Intro to APIs

The OPUS accepts all APIs through one exposed /api/events endpoint per environment using the POST HTTP method regardless of the operation being performed or the object being operated upon. This is unlike a traditional RESTful Web service, which exposes multiple endpoints where users can perform operations with HTTP methods (e.g. GET, POST, PUT, etc.). The app that handles the request and the objects affected by the request are determined based on the contents of the header section of the request body.These event-driven APIs can be used to integrate the TraceLink app with your company's internal systems (e.g. enterprise resource planning system, warehouse management system).

Request header

The request header includes the Authorization OAuth token required to authenticate and access the Serial Number Provision API.

Request body

The request body used to generate the API key and API secret includes the following header and payload elements:

• header – Contains information required to process the request:
  • headerVersion – The header version. Valid value is 1.
  • eventName – The event associated with the API credential-generation response. Valid value is [app-name]:[event-name]:[version] (e.g. authorization-manager:generate-apiKeyCredentials:v1).
  • ownerId – The identifier for the company that is providing the app.
  • appName – The application that owns the event (e.g. user-admin).
  • dataspace – The dataspace within the environment that the request call is being made. Valid value is default.
• payload – Includes the contents of the request.
  • data – The dataspace within the environment that the request call is being made. Valid value is default.
  • description – A description used to identify the generated API credentials.

Request example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "header": {
        "headerVersion": 1,
        "eventName": "authorization-manager:generate-apiKeyCredentials:v1",
        "ownerId": "00000000-0000-0000-0000-000000000000",
        "appName": "user-admin",
        "dataspace": "default"
    },
    "payload": {
        "data": {
            "description": "description"
        }
    }
}

Response body

The response contains the following header and payload elements:

• header – Contains information about the API credential-generation response. This must include the following parameters:
  • headerVersion – The header version. Valid value is 1.
  • eventName – The event associated with the API credential-generation response. Valid value is [app-name]:[event-name]:[version] (e.g. authorization-manager:generate-apiKeyCredentials-response:v1).
  • ownerId – The identifier for the company that is providing the app.
  • isErr – Indicates whether an error occurred while processing the request.
  • errCode – The response status code.
  • licensePlate – The identifier associated with the request.
• payload– Includes the contents of the request.
  • apiKey – The generated API key.
  • apiSecret – The generated API secret. The API key and API secret are used to obtain an OAuth token.

Response example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "header": {
        "headerVersion": 1,
        "eventName": "authorization-manager:generate-apiKeyCredentials-response:v1",
        "ownerId": "00000000-0000-0000-0000-000000000000",
        "isErr": false,
        "errCode": "200_OK",
        "licensePlate": "zgCmz4-sj1"
    },
    "payload": {
        "apiKey": "a9d632bd-4ee9-403b-8dad-14ecda6ef92a",
        "apiSecret": "ObvyJ5RqU1k0w9QhduOGqZj360oy58pc"
    }
}

Serialized Number Exchange roles determine the functions and APIs that users can access. The following table lists the available roles and their associated permissions.

A guidelines table contains element requirements for a message:

Element

This column indicates the source/element name included in the API call.

Type

This column indicates the element's data format type (e.g. String, Integer, Boolean, Date, or Time).

Description

This column 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, etc.).

Hover over a footnote to display the data input sample for that Data Element. If using the printed version of the document, refer to the matching footnote at the bottom of the table.

Class 1

Class 1 errors are Map In errors.

Class 2

Class 2 errors are data translation Processing Failed errors.

Class 3 Errors

Class 3 errors occur when data translation to a third party (i.e. the Partner receiving the message) fails due to an internal server error. Class 3 errors are rare, though they can also occur due to missing or incorrect information in master data. If a message returns a class 3 error, check master data first, add missing information or edit incorrect data, and resubmit the message. If the class 3 error continues to occur when master data is definitely correct, contact TraceLink Support.

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

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.

   There is a known issue in the documentation where the example might have extra spaces or quotation marks added if copied through a Chromium-based browser (e.g. Google Chrome, Microsoft Edge). This issue will be fixed in a future revision. For now, if this problem results in a validation error, either:

   • Manually copy the example by highlighting the full text, right-clicking, and selecting Copy.

     or

   • Use a non-Chromium-based browser (e.g. Mozilla Firefox, Apple Safari) to copy the example.