Intro to APIs
Before referring to the API portion of this guide, users that might integrate via API should work with their TraceLink implementation team to help configure their system and receive the appropriate endpoints and authentication information.
Learn the basics about integrating with the Opus Platform through TraceLink's event-driven APIs:
Event-driven APIs
The Opus Platform 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 contains the metadata associated with the API request. All API calls to the Opus Platform must include the following key-value pairs in the request header:
- Content-Type – The media type for the message. Valid value is
application/json
. - Authorization – The authorization token required to connect to the platform and environment.
Request body
The request body contains the message routing and handler information as well as the contents of the request. All API requests submitted to the Opus Platform must include the following header
and payload
elements:
- header – Specifies the event type of the request and the app that will receive the request. This must include the following parameters:
- headerVersion –The header version. Valid value is
1
. - eventName – The fully qualified name of the event that will be triggered by the request. This is typically formatted as
[app-name]:[event-name]:[version]
(e.g.agile-process-teams:add-incident:v1
). - appName – The application that owns the event (e.g.
agile-process-teams
). - ownerId – The identifier for the company that is providing the app.
- dataspace – The dataspace within the environment that the request call is being made. Valid value is
default
.
- headerVersion –The header version. Valid value is
- payload– Includes the contents of the request.
Users are granted authorization to the Opus Platform through an API token. The users need to generate an API token prior to sending an API request in order to identify a username (an API key) and password (an API secret). A valid username and password must be included in the headers to process the API request successfully. This username and password does not expire, and it can be used in all API calls.
Code | Description |
---|---|
200 | OK. The request was successful. |
Code | Description |
---|---|
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. |
Code | Description |
---|---|
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. |
Code | Description |
---|---|
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.
- Occurs | Length – Occurs indicates the minimum and maximum amount of times that the particular element can occur within the message. Length indicates the length of the value for the given element. An asterisk (*) indicates that an unlimited number of the element can occur or there is no limit on the length of the value. Additional information about the number of occurrences and the length can also be included in the Description column.
- 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 | |
---|---|---|---|
Header |
Required. The response header. |
||
headerVersion | Integer | Required. The version identifier for the request. | |
eventName | String | Required. The fully qualified name of the response event. | |
ownerId | String | Required. The identifier for the Owner company associated with the request. | |
isErr | String |
Required. Indicates whether the request was successful. Valid values:
|
|
errCode | String |
Required. The status code of the request. |
|
errMsg | String | Conditionally required if the call is unsuccessful. The message associated with the error code. | |
licensePlate | String | Required. The unique identifier for the request and response instance. | |
Payload | – |
Required. The response payload. |
|
commentId | String | Conditionally required if the call is successful. The identifier for the added comment. |
Element | Occurs Length |
Type | Description | |||
---|---|---|---|---|---|---|
epcis:EPCISDocument | - |
1…1- | Required. The EPCIS message root element. | |||
@schemaVersion | 0/* |
1…1Decimal | Required. The version of the EPCIS schema used to populate the EPCIS document elements. Valid value is 1.2 . |
|||
@creationDate | 1/* |
1…1DateTime |
Required. The date and time of the Standard Business Document's creation (i.e. the GMT create date and time for the EPCIS message). The system expects the Z to be appended; however, if the Z is not included, the system assumes that the time is GMT and therefore appends the Z (e.g. 2021-12-18T22:08:02Z). |
|||
EPCISHeader | - |
0…1- |
Required. The XML file control header. This message supports the following use cases:
|
|||
sbdh:StandardBusinessDocumentHeader | - |
1…1- | Required. The business header information, including the EPCIS header version, sender and receiver information, and the document identification. | |||
sbdh:HeaderVersion |
0/* |
1…1String | Required. The version of the Standard Business Document Header (SBDH). Valid value is 1.0 . |
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. |
- Navigate to the guidelines table for the message you want to export.
- Select the Download icon.
- 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 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.
Sample requests and responses, where relevant, are provided for each message.
Below is a Copy Direct Supplier Incident request example:
{
"header": {
"headerVersion": 1,
"eventName": "agile-process-teams:copy-direct-supplier-incident:v2",
"ownerId": "94f94f37-2772-4b39-8041-9c2dcfcfff82",
"processNetworkId": "945feb8e-09a7-4fef-9a8a-b3c5b56f87d",
"appName": "agile-process-teams",
"dataspace": "default"
},
"payload": {
"id": "fd04dd70-c162-43ef-8118-539ca01de471",
"createdByPartner": false,
"aptBusinessObjectSummary": "Shipment Damage",
"copyGeneralInfo": true,
"copyPartnerInfo": false,
"copyMaterialInfo": true,
"copyImpactInfo": false,
"copyReferenceIds": false,
"copyRelatedProcesses": true
}
}
Sample requests and responses, where relevant, are provided for each message.
API examples can be easily copied and pasted into a text editor by selecting
.- Create a blank text file and save it locally.
- Navigate to the API example that you want to copy.
- Select .
- Navigate to the first row of the saved text file, right-click, and select
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
or
. - Use a non-Chromium-based browser (e.g. Apple Safari) to copy the example.
. - Manually copy the example by highlighting the full text, right-clicking, and selecting