Intro to APIs

The context diagrams below illustrate the relevant APIs and typical flow for Producers and Consumers.

Producers add product records and serial number information to Product Information Manager

Producers can use Product Information Exchangeto integrate with Master Data Exchange and Serialized Operations Manager to sync product master data and serial number information as they go about their standard operations. Producers can also call the Product Information Exchange API to directly to manually add product records and serial number information to the TraceLink-owned network application Product Information Manager.

Consumers verify against the product records and serial number information provided by Producers to confirm the validity of products before reselling them. In addition to adding and maintaining the product information against which Consumers verify, Producers also set the rules that determine which information is returned in verification requests for their products.

Consumers verify product information provided by Producers in Product Information Manager

Consumers configure their ERP system to call the Smart Event Manager API to verify against the product directory records and serial number information provided by Producers (Pharmaceutical Manufacturers, Repackagers) in Product Information Manager. They can also view verification histories through Product Information Exchange. The US DSCSA requires Consumers to verify that returned products are still valid, according to the Producers who manufactured the products, before these products can be resold.

Additionally, Consumers can also send requests directly to Product Information Exchange to download Producers' product master data records.

TraceLink REST APIs use Basic Authentication for secure validation of a given request, which verifies the identity of a user.

Header key-value pairs

• Content-Type – The media type for the message. Valid value is application/json.
• Authorization – The Administrator's username and password, encoded using Base64. The Administrator uses a basic token for Basic Authentication.
  If the message is sent through Postman, select Basic Auth on the Authorization tab to enter the Administrator's username and password. These credentials are encrypted and added to the header.

TraceLink REST 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. For GET, this means that the resource has been fetched.

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.

The relevant Message Type (e.g. SOM_DESTROY_EVENT) and Info Exchange Display Name (e.g. Destroy Event) are included above each Guidelines Table. The Message Type is used when setting up B2B connections. Use the Info Exchange Display Name in Info Exchange to monitor and troubleshoot messages exchanged with Partners. See the Info Exchange Online Help for additional information.

How the Message Type is used depends on the type of B2B connection:

• AS2: The Message Type is in the AS2 header (e.g. SOM_DESTROY_EVENT).
• HTTP Post: The Message Type is part of the URL (e.g. https://prodb2b.tracelink.com:5443/server?request=send&directory=inbox/SOM_DESTROY_EVENT&filename=<filename>).
• SSTP: The Message Type is the folder in which the message is saved.

In Info Exchange Profiles, the Message Type is included in the "transaction" column of the Transactional Maps CSV file.

The Errors table displays all potential errors that may be encountered for a message. In the "Description" column, the term "source" is used to refer to the specific element in question. For example, in the description for the cmn:PartnerId element below, "source" refers to cmn:ParterId itself. No value has been provided for this element, therefore triggering the error message.

A Guidelines Table contains field/element requirements for a message:

Data Element

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

Occurs/Length

This column indicates the minimum and maximum amount of times that the particular element can occur within the API call (note that repeating elements are indicated in the "Description" column). In the example above, the urn:serialNumbersRequest element must occur a minimum of once and can only occur up to once for the maximum occurrence as indicated by the "1...1". If "*" is indicated, the element has an unbounded maximum occurrence.

Format

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.

1. Navigate to a message in the appropriate API Guide and open the Guidelines table.
2. Click the Download icon ().
3. The file downloads locally.

Sample requests and responses, where relevant, are provided for each message.

Below is a Download Product Master Data Request example:

{
    "t": {
        "v": 1,
        "m": "pie--consumer-download-mds--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "records": [
            { "packagingCode": "10312345678910", "packagingCodeType": "GTIN-14" },
            { "packagingCode": "00312345678913", "packagingCodeType": "GTIN-14" }
        ]
    }
}

Message examples can be easily copied and pasted into a text editor by selecting the Copy to Clipboard icon ().

1. Create a blank text file and it save locally.
2. Navigate to the message sample within the appropriate API Guide.
3. Select the Copy to Clipboard icon ().

   The Copied to Clipboard icon () displays for 2 seconds, indicating that the copy is successful.

4. Navigate to the first row of the saved text file and select Paste.

   The message example's structure is maintained.

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