Intro to SOAP messages
TraceLink communicates with certain operating systems or programs of choice through SOAP (XML-based messaging protocol) integration. As indicated in the diagram below, the TraceLink applications that use the SOAP API are Serialized Operations Manager, Serial Number Exchange, and Product Track.
For example, if an internal system needs serial numbers, the SerialNumberRequest SOAP call is sent from that internal system to TraceLink's SOAP API endpoint, which is the main request-response communication hub. The endpoint simply extracts the XML from the SerialNumberRequest call and passes it to the TraceLink platform (the Serial Number Exchange app, in this example). Serial Number Exchange waits for the XML response containing the requested serial numbers, sends the serial number data back through the endpoint where the SOAP response generates, and sends the response back to the original system. This response also confirms whether the operation is successful or if it fails.
Development platform installation is required prior to integration.
Authentication
A valid TraceLink Network username and password for HTTP basic authentication validation is needed, as well as a user and app look-up to ensure proper validation of a given request.
To enforce strong security in the TraceLink Track & Trace Services, username:password in plain text is not accepted. To successfully send SOAP calls to TraceLink, Base64 encoding must be used for the username:password and sent in the HTTP Authorization header to conform with the IETF basic authorization standard (https://tools.ietf.org/html/rfc7617).
An HTTP 401 Unauthorized client error status response code occurs in the following scenarios:
- A non-Base64 encoded username:password is sent in the HTTP Authorization header.
- A Base64-encoded or plain text username:password is sent in the Username header.
- The Username header is sent.
App-specific authentication
- Serial Number Exchange requires basic authentication.
- Serialized Operations Manager requires basic authentication. TraceLink also allows the caller to pass a username (possibly a different username from the one used to authenticate), a location type, and location value for the purpose of executing a Serialized Operations Manager call. If these values are not provided, TraceLink executes the call at the company level.
Header Usage Sample Value Required User Use to identify a user making the request (for Audit purposes). User email or GUID. Example: snxpubco1-mem1@tracelink.com No. Value defaults to user used in authentication (basic authentication). LocationType Use to identify location type executing the call. SGLN No. If excluded, call is made at the Company level. LocationValue Use to identify location value executing the call. 12345.678.10 No, unless LocationType is specified. - Compliance Reporting requires basic authentication.
WSDL access
Access to the Web Services Description Language (WSDL), where the XSDs reside along with other functionality information, is needed for integration. The URL for the WSDL contains the name of the TraceLink environment being accessed, followed by a specified app path. The following are itest WSDL examples by application:
- Serial Number Exchange: https://itestapi.tracelink.com/soap/snx/snrequest?wsdl
- Serialized Operations Manager: https://itestapi.tracelink.com/soap/som?wsdl
Ensure authentication success before attempting to access the WSDL.SOAP API call limits
Before configuring data, query limitations should be noted. The table below outlines the query limitation details for TraceLink SOAP messages:
| API Call | Limit | Description of Limit |
| Serial Number Exchange Messages | ||
| serialNumberRequestResponse | 500,000 | The maximum quantity of serial numbers that can be requested is 500,000. |
| Serialized Operations Manager Messages | ||
| Commission | 50 | The maximum amount of serial numbers that can be commissioned is 50. |
| Decommission | 500 | The maximum amount of serial numbers that can be decommissioned is 500. |
| GetSerialNumberHierarchy | 100000 | A maximum of 100,000 serial numbers can be returned with a GetSerialNumberHierarchy request. |
| SetSerialNumberStatus | 500 | The serial number status can be set for a maximum of 500 serial numbers. |
