CargoChain’s API is 100% accessible over a set of HTTPS REST calls using the widespread JSON format, making CargoChain open to any other Internet-capable technology.

In order to simplify the integration of your applications with CargoChain, we provide an Enterprise SDK in different development languages.

Installation

The JS SDK client is available as a NPM package.

$ npm i @cargochain/sdk-js
$ npm i --save @cargochain/sdk-js

Usage

The main object is CargoChainClient singleton. You have to specify the URL of the CargoChain API by using the setUrl() function. See the CargoChain locations.

The CargoChainClient instance has two properties that allow to interact with the CargoChain API:

• profile: exposes the functions for manipulating profiles (create profiles, search profiles, add events, set metadata, etc). See the CargoChain API for profiles.
• referenceData: exposes the functions for getting all reference data natively provided by CargoChain (Countries, Currencies, HS Codes, UN/LOCODE, etc).

API Result

The result of each API call has the following format:

{
    isSuccess,          // true / false if the call is success
    message,            // if isSuccess if false, this property contains an error message
    statusCode,         // the HTTP status code
    data,               // the data returns by the CargoChain API
    page                // the information for the pagination (https://github.com/CargoChain/doc/wiki/V2-API#pagination) if the endpoint supports it
}

Security

You have to specify an Access Token to the CargoChainClient instance in order to perform the calls to the CargoChain API. For more details, see the API Authentication.

To set the Access Token to the CargoChainClient instance, you have to use the setAccessToken() function.

If the CargoChain API returns an authentication error, you can handle it by using the setOnAccessTokenExpiredHandler() function. The handler that you have to specify by calling this function should ask for a new Access Token (typically by calling the CargoChain Portal) and set again the Access Token by using the setAccessToken() function.

Example

// Load the CargoChainClient
const CargoChainClient = require('@cargochain/sdk-js');

// Get the instance
const client = CargoChainClient.instance;
// Set the CargoChain API Url 
client.setUrl('https://api2-tests.cargochain.com');
// Set your access token
client.setAccessToken('[MY ACCESS TOKEN]');

client.setOnAccessTokenExpiredHandler(() => {
    // Here you should call the CargoChain Portal in order to get a new access token
    const token = "[MY NEW ACCESS TOKEN]";
    client.setAccessToken(token);
});

client.referenceData.getCountries().then((res) => {
    // Display the number of countries
    console.log(res.data.length);
});

client.profile.getAllProfiles(5).then((res) => {
    // ...
});