Skip to content

API User Guide

Copyright IBM Corporation and GTD Solution Inc. 2020

Overview

The purpose of this document is to provide a detailed understanding of how to work with the TradeLens APIs. The target audience is a software developer familiar with REST APIs and JSON. With that knowledge, the Swagger API Documentation will be the best place to start experimenting with the features available.

Notes:

  • Before downloading and opening any documents, attachments, or sample code, ensure that you have antivirus protection per your company policy with the latest virus definitions.

  • For convenience, this document contains several direct links to Swagger pages (Event Publish, Trade Object, Platform Constants, Event Subscription, Document Sharing, and Actionable Flows) that resolve to "platform-sandbox" as the first part of the URL. If you have been onboarded onto a different stack than "platform", replace "platform" with your stack name, for example "maersk", in the URLs to work with the Swagger for your organization.

When building integrations with TradeLens APIs, the first step is authentication. API calls without a valid token will result in an error. Swagger provides an interface where the user can follow a link to log in, but application (system) code requires a programmatic path to acquire the secure token necessary to call the APIs.  Find details about how to authenticate in Authentication and Token Generation for API usage.

It is worth noting that the TradeLens UI leverages many of the APIs. Prior to building automation to do configuration related tasks like setting up subscriptions or business partner relationships, consider using the UI. It should simply your efforts.  

All production level applications must handle error conditions. This document contains several sections describing potential errors and a path to resolution. However, in cases where progress cannot be made or unknown errors occur, take the steps outlined in the Get Support section.

Swagger API Documentation

The TradeLens API documentation leverages Swagger, a popular format for documenting REST APIs. It goes beyond text descriptions and allows a developer to experiment with the APIs live from the Swagger UI prior to writing any integration code. Before starting your work with TradeLens, you should familiarize yourself with Swagger (if necessary), at https://swagger.io. Updates to the TradeLens APIs are documented in the API Release Notes.

Swagger URLs

There is Swagger for the Sandbox and Production zones.

Note: If you have been onboarded onto a different stack than "platform", replace "platform" with your stack name, for example "maersk", in the URLs below.

Sandbox Swagger: https://platform-sandbox.tradelens.com/documentation/swagger/ Production Swagger: https://platform.tradelens.com/documentation/swagger/

There are several sets of APIs (some are available based on your organization's role): Event Publish, Event Subscription, Trade Object, Document Sharing, Actionable Flows, Business Partners, Platform Constants, etc. The steps below will help you understand how to work with Swagger and the APIs.

  1. Become familiar with the REST APIs: Start reviewing the documentation by expanding the API definitions in Swagger. You can read the specification and submit test events from the APIs in the Sandbox environment. This will help you understand the APIs prior to writing any code. You can find the different API specifications for the platform by selecting them from the top right area Select a definition. Each page represents a set of related APIs. Each Swagger page includes subgroups of related APIs. Click on the group to expand and collapse the group. You might notice some APIs with a line through them. This is how Swagger renders deprecated APIs. In these cases, you should be able to find a better, more suitable API. With a group of APIs displayed, click on an API to see the details and read its description.

  2. Authenticate in Swagger: Authentication is required for Swagger to use the APIs. If you are not already logged in, click on Login, at the top of the API page in the Swagger, and log in with your TradeLens credentials (ID and password). If you have not been provisioned to TradeLens yet, or if you receive a message that you are not a registered user, contact your TradeLens onboarding lead.

  3. Test in Swagger: To test an API in Swagger, click on Try it out, modify the sample event body with your test data, and click on Execute to run the API. Check the response code and response body that is returned. In cases where an API requires an HTTP body to be configured, an Example Value is shown by default, but you can click the Model link to see the JSON schema showing the full details of all available fields and descriptions. Note that there are some limitations on the Production Swagger in order to prevent potential test or fake data from entering the production system.  

  4. Develop client code for calling the APIs: Once you become familiar with the Swagger REST API specification, you can write your client code using any language. Note that publishing events directly from your client code requires using your system ID and the JSON Web Token (JWT) or "bearer" token. Three headers are required on the HTTPS request: Accept, Content-Type, and Authorization. See the Authentication and Token Generation for API usage section for more details.

API Change Management

TradeLens delivers new features frequently, as often as every two weeks. As they are delivered, the following indicators can help you stay informed.

  • Notifications of new releases are posted to https://status.tradelens.com/. You can subscribe for email notifications there too.
  • At the top of each swagger page is a version field. That version will only change if an API on that page has changed. APIs are always backward compatible, so these changes would only be optional features appended to existing APIs or new APIs altogether.
  • The Release Notes section of the documentation includes the details of what has changed.

Deprecation Policy

As with any evolving product, there are times when APIs must be deprecated in favor of a new version. In this case, the indicators above can keep you informed, but it is important that action be taken to move off of deprecated APIs. Once an API is deprecated, it is on a path to be removed from the product. If you have not moved off a deprecated API at that point, your integrated application will fail. Below is the staged policy TradeLens uses for deprecation.

  1. When releasing a new set of features, an API will be deprecated. This is communicated in the release notes documentation as well as in Swagger where a line will be drawn through the API and a note will be added to the description indicating the end of service date. A deprecated API will stay in this state for 180 days.
  2. After the 180 days, the API will be removed from Swagger completely and will be out of service.

Event Publish and Query APIs

Given the volume of world trade and applicable events, TradeLens receives millions of events per day. This section will provide guidance when developing systems that submit these events. In Swagger, the Event Publish API enables TradeLens network members (ocean carriers, ports, authorities, etc.) to publish various types of events, recording everything from a new container being in use to a party being granted access to a consignment. The Trade Object API enables TradeLens network members to query visibility granted trade objects like Consignment, Transport Equipment, Shipment, and events associated with them. 

Rate Limiting

In order to keep the system healthy so it can handle such a large volume of events, and to protect it from any potential denial of service attack, TradeLens has applied a rate limit on the event publishing APIs and a few other APIs on the platform. This rate limit defines how many API calls an individual organization can make per second. The value is system wide and subject to change. Recent values are as follows:

Zone Events Published (per second) Trade Object Queries (per second)
Production 400  200
Sandbox 40 200

If an organization exceeds the rate threshold, their application will get an HTTP 429 "Too Many Requests" error until enough time has passed for their average rate to fall back below the limit. Applications sending events to TradeLens should look for the 429 response and pause for a second before republishing the event or publishing additional events, especially for those submitting large volumes. Similar comments apply to the query related APIs. Customer applications may be multi-threaded, submitting many events in parallel; this is another case where extra care should be taken.

Asynchronous Event Handling

When events are published to TradeLens, a successful (2xx) response does not imply the event has been fully applied to the platform. Events get processed asynchronously, often within seconds, but not necessarily. At various times, some event publishers might send bursts of events that might take additional time to process. In addition, not all events take the same amount of time to process.  Some events need to only be associated with a consignment for example, while more complicated events can trigger a lot more processing.

In many cases, event publishers can "fire and forget". That is, there is no immediate need for an event to be considered processed before moving forward. In cases where the publishing application requires confirmation, there are several options. Each option requires the sender to keep track of the response from sending the event. It includes a unique event transaction id (eventTransactionId) used for correlation.

  • Validate by Subscription: If an event subscription has been set up, the logic in the associated webhook application can detect when the matching event transaction id has been received, representing that the event processing is complete.

  • Validate by Query: Several query APIs in the Trade Object API return matching events, typically based on input identifiers such as a carrier booking number or equipment number.  Those APIs could be polled and checked for the inclusion of the event with the matching event transaction id, representing that the event processing is complete.

  • Validate by UI: While this will not apply to programmatic validation, events visible in the UI (associated with their target trade object) also indicate that the processing is complete.

Error Handling

When publishing events or calling any REST APIs, a variety of errors might occur. Some result from client-side problems like incorrect syntax or authentication. Others indicate a problem in the service being called. See General HTTP Status Codes in the Error Code Reference section for the common list of HTTP status error codes as well as suggestions for resolution.

In some cases, an event might pass schema validation and authorization, but once TradeLens is applying it to a trade object (shipment, consignment, or transport equipment), problems can be detected that will either delay or prevent an event from being processed. The next two sections cover how those scenarios get handled.

Orphaned Events

TradeLens needs to handle events from many network members in any order. That often results in events arriving for a trade object that does not exist yet. For example, an ocean carrier might not have created the transport equipment yet, but a trucking company might send a related event for the transport equipment. That event will have an equipment number that is unknown to TradeLens. In cases like this, the event will not be lost. Rather, it will be set aside temporarily in something called the event orphanage. As the name implies, these events have no "parent" trade object.  

As new trade objects get created, TradeLens scans the orphanage for events matching the trade object identifiers. Upon detecting a match, the event gets removed from the orphanage and associated (adopted) to the trade object. At this point, the event will be pushed out to subscribers and be available in the query APIs.

The orphanage keeps events available for 30 days before removing them from the system. Events orphaned this long imply an error in the data from the sender. Access to orphaned events is available using the GET .../unassociatedEvents - Fetch unassociated events API in the Trade Object API.

Homeless Events

Different from orphaned events, homeless events are those that will never match a trade object. Therefore, they will never be processed by TradeLens and will never be accessible through the query API or subscription. Homeless events pass schema validation, but are considered errant events. Integration efforts in the Sandbox (pre-production) zone should provide the testing necessary to prevent publishing events that will be considered homeless. Here are a couple of examples, but there are others.

  • Unauthorized Party Add Event: A party added event from an organization that does not have authority to add parties to the given trade object or to apply the given roles.
  • Ambiguous Admin Event: An administrative event for a trade object that maps to more than one trade object, maybe because the only identifier provided was the carrier booking number that could match several consignments.  

Events falling into this category get stored in an internal homeless events database. They are kept around for 30 days, but only as a reference for the event publisher to track down a missing event. Access to homeless events is available using the GET .../unassociatedEvents - Fetch unassociated events in the Trade Object API.

Event Subscriptions

TradeLens enables organizations to set up subscriptions in the form of a webhook application. The platform will publish events (for which the organization has visibility) to the webhook. The webhook application can look for specific events to trigger applicable business integration.  

If you are new to webhooks or just want to see how this works quickly without writing a new application, try an online webhook site like https://webhook.site/.  It will create a new dynamic webhook URL for you and will display any events or data sent to it. Use the Sandbox environment and configure a new TradeLens subscription pointing to your dynamically generated webhook URL. Once in place, you can log in and use the Event Publish API to submit events (like creating a new consignment or transport equipment) and watch the event get delivered to your online webhook. Note that some events require a certain organization type in order to be submitted. See the Swagger description for the event, and the Data Sharing Specification topic.

Once you are familiar with how subscriptions work, you are ready to start building your own webhook application. While you can do this in any programming language, below are a couple of sample projects on GitHub to get you started.

As events arrive to your webhook application, first acknowledge that you have received the event with an HTTPS response and then parse it to determine if action is required. The events are in JSON format. Depending on the programming language involved, several libraries are likely available for consuming this JSON data automatically, enabling you to walk through the data model to find what you need. The initial data element to find is "eventType". For example:

{
   "eventType": "plannedGateIn"
}

When building your webhook application to parse the event fields, be sure it is not sensitive to new fields. As TradeLens builds additional features, new fields are added all the time. For example, if you are using the ObjectMapper class in Java to map a JSON event into your Java class, be sure to set the following property:

new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

The full set of event types is available in the Platform Constants API using the GET ​...​/eventTypes - Get all event types. Once you have detected an event type of interest, you can parse the event JSON further to find fields of interest. The available field names will align with the schema defined for each event type in the Event Publish API.

We highly recommend that you read the Setting up Subscriptions topic, and especially the Webhook and Shared Secret section. In addition, if you are interested in the APIs specific to creating and managing subscriptions, see the Event Subscription API.

IP Allowlist

To enable your human users and system users to access TradeLens, ensure that your organization's firewalls are configured with the proper IP Allowlist as described below.

Client applications to Tradelens APIs:

The following API lists all IP addresses used by the IBM Cloud Internet Services (CIS) proxy. This list includes all IP addresses to be added to your Allowlist for communicating with TradeLens API endpoints: https://api.cis.cloud.ibm.com/v1/ips

Document Sharing and Actionable Flows APIs

In Swagger, the Document Sharing API and Actionable Flows API can be used for the management of documents in TradeLens. See the Document Sharing and Actionable Doc Flows topics for more information on working with documents and actionable doc flows.

Asynchronous Document Handling

When uploading documents, quite a bit of processing takes place within the platform. Aside from initial API schema and authorization validation, the files get securely stored in a database and audit records get saved in the blockchain. Given these activities often take more than a few seconds, the upload APIs quickly return a transaction id that should be used to check the status of the request with following query APIs: 

Error Handling

See the Error Code Reference section for details on how to interpret errors when calling the APIs as well as insight on resolution.  

Data Sharing Specification

The TradeLens platform, through a robust authorization and permission model, enables or restricts access to that data by other participants. The model both promotes secure and fast access to supply chain information and ensures that no commercially sensitive information is available to competitors or other unauthorized parties. Find more details in the TradeLens Data Sharing Specification topic.

The APIs for uploading and fetching documents abide by that specification. Therefore, you might get an error when attempting to upload a document because your organization does not have authorization. Similarly, when searching for documents, you will only have access to those documents for which you have been granted access. 

Platform Constants APIs

In Swagger, the Platform Constants API has a collection of helper APIs that you can use to fetch data that can be supplied in other APIs. Some of these include fetching UN/Locode, country types, event types, etc.

Retrying Upon Error

TradeLens reports API errors in several ways, sometimes depending on the API involved.

  • The HTTP status has an error code (4xx, 5xx).
  • The HTTP payload includes an error status "code" in the JSON.
  • Querying the status of a transaction id (Document Sharing and Actionable Flows) results in a failure status.

In some cases, the root cause of the problem is temporary. For example, there could be unexpected volatility in the network connection or a race condition within TradeLens service logic. Some errors (HTTP 429, HTTP 5xx, failed transactions) might be addressed by calling the same API again. Pause between retries for a 2-3 seconds. If failures persist after a couple of retries, take the steps outlined in the Get Support section.

Note: Retrying in case of HTTP 5xx errors for a POST/PUT API might result in the document version being incremented. This can happen in scenarios when the document got uploaded successfully but the API failed while returning the response or while handling other dependencies. 

Error Code Reference

General HTTP Status Codes

TradeLens APIs are all based on REST, and therefore HTTP. Use the table below to look up HTTP status error codes you receive when calling the APIs. The status and description align with the HTTP standard, but the details column gives additional insight into what could be wrong or how to work around the problem.

HTTP Status Description Details 
400 Bad Request The provided JSON schema is not correct.  See the Swagger documentation for the required fields and their type.  This may also result from poorly formatted JSON, like a missing comma or brace character.
401 Unauthorized The user does not have an acceptable authentication token. It may be missing or have expired.  Get a fresh token and try again.
403 Forbidden The user is authenticated, but not allowed access to the requested data.
429 Too Many Requests Rate limiting has been applied. Too many requests per second were received from the same organization.  Reduce the API calls or, in case of an unexpected spike, retry the request.
500 Internal Server Error An unexpected error occurred on the origin server.  In case of a race condition, try again. If the problem persists, check for any potential maintenance windows. If that is not the case, open a support ticket.
502 Bad Gateway This indicates that a proxy was not able to get a valid or any response from the origin server. In case of a race condition, try again. If the problem persists, check for any potential maintenance windows. If that is not the case, open a support ticket.
504 Gateway Timeout This indicates that your request did not get a timely response.  Several conditions can lead to this including network infrastructure. In case of a race condition, try again. If the problem persists, check for any potential maintenance windows. If that is not the case, open a support ticket.

Document Sharing Error Codes

Beyond the HTTP status codes above, the Document Sharing APIs provide additional details about errors in the "code" field of the JSON response. The JSON response schema looks like the following:

{
  "code": "string",
  "message": "string",
  "timestamp": "string"
}

The list below contains details for several of these error codes.

Error Code HTTP Code Description
DBK_400 401 Authentication Token not provided.
DBK_401 401 Authentication Failed.
DBK_403 401 User is not authorized.
DBK_404 401 User is not authorized to view the transaction of different organization.
DBK_405 401 User is not authorized to perform this operation.
DBK_971 401 Token about to expire. Please generate a new one and retry.
DBK_1020 401 Token validation failed. Please generate a new one and retry.
DBK_402 403 User is not authorized for delete api.
DBK_482 403 User is not allowed to update schema with this organization id.
DBK_993 403 User is not authorized to access the supplied trade object identifiers.
DBK_958 403 User is not authorized to perform this operation.
DBK_1100 403 User not authorized for bill of lading verifier search api.
DBK_433 404 Document can not be accessed as it is marked for deletion.
DBK_468 404 Document schema for requested version not found.
DBK_470 404 Document not found.
DBK_471 404 Document schema not found for the given id.
DBK_485 404 Document content cannot be retrieved as the document resides in external location.
DBK_613 404 Printable copy is not available for the requested documentId and version.
DBK_700 404 No channel found for the trade object.
DBK_920 404 No documents found.
DBK_963 404 Consignment not found. Please check if this is a valid consignment.
DBK_964 404 Transport equipment not found. Please check if this is a valid transport equipment.
DBK_965 404 Document not found. Please check if this is a valid document.
DBK_966 404 Shipment not found. Please check if this is a valid shipment.
DBK_992 404 No trade object found for the supplied trade object external identifiers.
DBK_1027 404 No document found for the given payload.
DBK_1102 404 No document found matching the the organization id and bill of lading number.
DBK_1106 404 No document found matching the input parameters for bill of lading verifier search api.
DBK_1112 404 No document found matching the organization id.

API Payload Size Restriction

In order to prevent TradeLens from misuse and denial of service attacks, there is a limit on the payload size of 20 megabytes when calling any API. Most APIs involve significantly less data, especially given small JSON schemas. However, the Document Sharing and Actionable Flows APIs involve file uploads. Callers should be sure to keep their files under the 20 megabyte limit for TradeLens to accept them.  

Get Support

Follow the steps below if you are hitting unexpected errors for which there is no workaround.