Intro to SOAP APIs

SOAP APIs allow Owners and Partners to synchronously integrate their internal systems (e.g. warehouse management systems, enterprise resource planning systems) with certain TraceLink apps. These SOAP APIs are useful for making real-time updates to the company's data in TraceLink or quickly receiving information from their trade partner's systems through TraceLink.

The SOAP API endpoint extracts the XML data from the SOAP API request, and passes the XML to TraceLink. TraceLink then sends a confirmation of success and the requested information or a confirmation of failure and the error codes in XML format to the SOAP API endpoint, where the SOAP API response is generated and sent back to the company that made the request.

Owners and Partners must install a development platform before they can integrate with TraceLink through SOAP APIs.

SOAP APIs

SOAP APIs require a valid TraceLink user name and password for HTTP basic authorization validation, as well as a user and app lookup.

The user name and password must be encoded using Base64 and set in the HTTP Authorization header to conform with the IETF basic authorization standard.

An HTTP 401 Unauthorized client error status code occurs if:

  • A non-Base64 encoded user name and password is sent in the HTTP Authorization header.
  • Any information is sent in the Username header.

IT system administrators and developers must access the Web Services Description Language file (WSDL) for each app they integrate through SOAP. The WSDLs contain the XSDs along with other functionality information.

The URL for the WSDL contains the name of the TraceLink environment being accessed, followed by an app path. To access the Serial Number Exchange WSDL, go to https://itestapi.tracelink.com/soap/snx/snrequest?wsdl

TraceLink employs rate limits for SOAP and REST APIs, but Owners and Partners sending API requests through their normal business processes should rarely hit those limits. If the company's internal systems do hit a rate limit for some reason, TraceLink responds with a RATE_LIMIT_EXCEEDED error code. The company should pause their API requests at that time, typically for only a few seconds, before trying again.

TraceLink APIs use standard response codes to indicate whether an HTTP request was successful. Response status codes may include, but are not limited to, the following:

Successful response

200 OK. The request was successful.

Redirect message

307 Temporary Redirect. The client must get the requested resource at another URI with the same HTTP method that was used in the prior request.

Client error status codes

400 Bad Request. The server could not understand the request due to invalid syntax.
401 Unauthorized. The client is unauthenticated, not allowed access, and should re-request credentials.
403 Forbidden. The request is valid and the client is authenticated, but the client is not allowed access rights to the content for any reason.
404 Not Found. The server cannot find the requested item. This can also mean that the endpoint is valid but the resource does not exist.

Server error status codes

500 Internal Server Error. The server has encountered an unknown error.
502 Bad Gateway. The server is working as a gateway to handle the request and received an invalid response.
503 Service Unavailable. The server is not ready to handle the request.
504 Gateway Timeout. The server is acting as a gateway and cannot get a response in time.

How to use this guide

A guidelines table contains element requirements for a message.

  • Element – The source or element name included in the API.
  • Type – The element's data format type (e.g. String, Integer, Boolean, Date, Time).
  • Description – Indicates whether the element is required for the message and provides a brief description of the element, including any relevant notes (e.g. country requirements, formatting notes).
Element Type Description
soapenv:Envelope - Required. The envelope for the SOAP API.
  soapenv:Header - The header of the SOAP API, which TraceLink does not use.
  soapenv:Body - Required. The body of the SOAP API.
    urn:serialNumbersRequest - Required. The payload of the SOAP API.
      SendingSystem String Required. The identifier of the line management system requesting serial numbers (e.g. SYSTEM-100001). This value must match the configured value for the requesting system in the Serial Number Exchange configuration. This value is the ReceivingSystem in the response message.
      ReceivingSystem String Required. The identifier of the app or system that must respond to the serial number request (e.g. 0060354701201). This value must match the configured value for the app in the Serial Number Manager configuration. This value is the SendingSystem in the response message.

  1. Navigate to the guidelines table for the message you want to export.
  2. Select the Download icon.
  3. The file downloads locally.

In the Excel output of the API Guidelines:

  • When you open the file in Excel, the following dialog box might display: "The file format and extension of [file name] don't match. The file could be corrupted or unsafe. Unless you trust its source, don't open it. Do you want to open it anyway?" This message is expected. Select Yes to open the file.
  • The Occurs and Length values will be enclosed by square brackets (i.e. [1...1] or [1/20]). These brackets do not change the value of the data and are present to prevent Excel from interpreting the Occurs and Length values as dates or fractions.

API examples can be easily copied and pasted into a text editor by selecting Copy.

  1. Create a blank text file and save it locally.
  2. Navigate to the API example that you want to copy.
  3. Select Copy.
  4. Navigate to the first row of the saved text file, right-click, and select Paste.

    The API example's structure is maintained.

    Syntax highlights will not reflect unless enabled in the file editor.