Tracelink University ## Breadcrumb 1. [Home](/) 2. [Resources](/resources/resource-center) 3. [TraceLink University](/resources/tracelink-university) # Intro to event-driven APIs - [Download PDF](/node/628741/pdf) - [Share](#) - [ LinkedIn ](https://www.linkedin.com/shareArticle?mini=true&url=https://www.tracelink.com/resources/tracelink-university/intro-event-driven-apis&title=Intro to event-driven APIs&summary=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.&source=TraceLink "LinkedIn") - [ Facebook ](https://www.facebook.com/share.php?u=https://www.tracelink.com/resources/tracelink-university/intro-event-driven-apis&t=Intro to event-driven APIs "Facebook") - [ Mail ](mailto:?subject=Intro to event-driven APIs+|+TraceLink&body=https://www.tracelink.com/resources/tracelink-university/intro-event-driven-apis "Mail") - [ Twitter ](https://twitter.com/intent/tweet?text=Intro to event-driven APIs https://www.tracelink.com/resources/tracelink-university/intro-event-driven-apis&via=TraceLink "Twitter") #### Table of contents 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. ## 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). [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)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. [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)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`. - **payload**– Includes the contents of the request. [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)Authorization](#)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. [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)](#)[HTTP response status code](#)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 [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)Read the guidelines table](#)A guidelines table contains element requirements for a message: Element Type Description Header **Required.** The request header. headerVersion Integer **Required.Required.** The version identifier for the request. Valid value is`1`. eventName String **Required.** The fully qualified name of the request event. Valid value is NEED INFO ownerId String **Required.** The identifier for the Owner company associated with the request. isErr String **Required.** Indicates whether the request was successful. Valid values: - `true` – The call was successful. - `false` – The call was not successful. The **errCode** and **errMsg** fields provide error information for troubleshooting. errCode String **Required.** The status code of the response. errMsg String **Conditionally required** if the call is unsuccessful. The message associated with the error code (e.g. `"Process Type is required."`). licensePlate String **Required.** The unique identifier for the message instance. exceptionName String (missing or bad snippet) Payload – **Required.** The request body. commentId String **Conditionally required** if the call is successful. The identifier for the added comment. [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)Element](#)This column indicates the source/element name included in the API call. [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)Type](#)This column indicates the element's data format type (e.g. String, Integer, Boolean, Date, or Time). [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)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.). ![](../../../../tl_global_hc/Content/Resources/Images/global_images/note_tip.png)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. [![Closed](/sites/default/files/tech_comms/masterdata/Skins/Default/Stylesheets/Images/transparent.gif)Read the message example](#)Sample requests and responses, where relevant, are provided for each message. Below is a Copy Direct Supplier Incident request example: ```xml { "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 } } ``` #### Table of contents ##### Related Content [ ![Related content](https://www.tracelink.com/sites/default/files/2024-09/chat-bubble-question.svg) ](/resources/tracelink-university/modify-your-account) ##### Modify your account Modify your profile, define app settings, and enable inbox messages and notifications. [View More](/resources/tracelink-university/modify-your-account) [ ![Related content](https://www.tracelink.com/sites/default/files/2024-09/chat-bubble-question.svg) ](/resources/tracelink-university/switch-companies-or-environments) ##### Switch companies or environments The OPUS Ensemble user experience allows you to switch between companies or environments that you have access to with the same user account (identified by an email) without logging into a separate URL. [View More](/resources/tracelink-university/switch-companies-or-environments) [ ![Related content](https://www.tracelink.com/sites/default/files/2024-09/chat-bubble-question.svg) ](/resources/tracelink-university/navigate-help-documentation-and-support) ##### Navigate to help documentation and support Select the Help Center icon in the header to access the one-stop-shop help center for everything related to the network you are currently within (e.g. [View More](/resources/tracelink-university/navigate-help-documentation-and-support)