This BlueX Freight Commerce Platform (FCP) API document describes our various product offerings via API integrations. The API supports carrier port pairs, schedules, and spot rates, and enables users to search for rates and book via a Deep Link provided by the API.

We are actively working on supporting further carrier API integrations, along with more new features, such as inventory management, instant booking, and many more.

BlueX presents data via an HTTP API using JSON serialization and is protected with JWT. Please first click "Getting Started" to get onboarded and collect your API key.

Please use https://api.bluextrade.com for production and https://sandbox-api.bluextrade.com for sandbox API calls.

All notable changes to this project will be documented in this section.

Added

• Surcharge Code List

Updated

• Add annotation to spot rate booking.

Added

• /v2/bookings/{carrier}/{applicationNumber} for booking amendment.

Removed

• /v1/auth for getting Token V1

Changed

• Use UN/LOCODE in location related parameters. {"unlocode":"XXXXX","name":"YY"} format is deprecated.
• Remove prefix from service type, e.g. FCL_FCL instead of SERVICE_FCL_FCL.

Added

• Add applicationType in webhookEventObject.

Changed

• Obsolete webhookEventType in webhook APIs.

Added

• /v3/auth for getting Token V3

Added

• Inventory of 40GP and 40HQ.
• Show depot free times if data is available.

Added

• /v2/auth for getting Token V2
• /v2/rates for querying rates with Token V2

Added

• Show price commodity: GDSM, GARMENT and FURNITURE.

Added

• Surcharge charge types: PREPAID and COLLECT.

Added

• Pricing transparency fields, e.g. surcharges, tieredSurcharges, includedSurcharges, and notApplicableSurcharges.

Changed

• Storing price in string type instead of float for better accuracy.
• Move freeTime from containerPrice to offer.

Before using the BlueX FCP API, please first register as a developer on our registration page. The BlueX team will review your application, and once your registration is confirmed, you will receive an API key and onboarding information for your developers.

This document contains a glossary with an alphabetical list with definitions related to APIs.

• APIs (Application Programming Interfaces) enable secure access to enterprise data assets and processes. They are usually in the form of REST web services. APIs are the building blocks for app creation integrations.
• JSON (JavaScript Object Notation), much like XML, is a way to transport and store data. JSON is smaller than XML and easier to parse. For more information on JSON, see here.
• JWT (JSON Web Token) is an open, industry standard RFC 7519 method for representing claims to be transferred between two parties.
• REST (REpresentational State Transfer) is a stateless architecture that generally runs over HTTP. The REST style is resource based (nouns) which have their own unique URI, and operations on those resources are limited to HTTP verbs (GET, POST, PUT, and DELETE). For example, consider a resource called Account. You would do an HTTP GET to retrieve information about that Account, and an HTTP POST to update the Account. REST style APIs are considered by many to be easier to understand and consume, especially for mobile development.
• XML (Extensible Markup Language) is a way to transport and store data, with tags that say what the data is.

Our API is accessible over HTTPs and returns JSON responses, and can only be accessed through BlueX provided API keys and tokens. When customers or third-party service providers access the BlueX FCP services via APIs, they are required to provide their API keys during the onboarding process.

Before accessing the API, clients must have an API key. The API key is obtained offline and identifies who the client is.

This section's Token V2 will be obsolete soon. Please use Token V3 instead.

Token V2 introduces a mechanism to allow users to act on behalf of their customers. Users may use Token V2 to search for schedules and query rates through APIs similarly to how customers did so on the CarrierX platform (the CarrierX platform is the white-label software solution developed by BlueX Trade, which provides digitalized container solution and trade services).

To use Token V2, customers need to generate a Carrier API key (including the API key ID and the API Secret) from the CarrierX platform (or the service agent like BlueX) and send/delegate the Carrier API key to API users.

The client calls HTTP POST /v2/auth with a valid API key, a valid referral user string and delegated carrier API keys. The token is then returned in the token field of the response.

$ curl -fsSL \
 --header 'Content-Type: application/json' \
 --request POST \
 --data '{"api_key":"API_KEY","referral_user":"USER-XYZ","user_carrier_api_key":[{"carrier":"EGLV","id":"CARRIER_API_KEY_ID","secret":"CARRIER_API_SECRET"},{"service_agent":"BLUX","id":"CARRIER_API_KEY_ID","secret":"CARRIER_API_SECRET"}]}' \
 "https://sandbox-api.bluextrade.com/v2/auth"

{"token":"eyJhbGciOiJIUz...BbBJBXY"}

The token is a JWT token. To access all APIs (except /v2/auth), the client must place the token in the HTTP header. Here is an example:

Authorization: Bearer eyJhbGciOiJIUz...BbBJBXY

The system will verify if the token is issued by the system or if the token was expired. The client request will be rejected if the token does not pass the verification process.

Token Refresh

Tokens issued by the system will expire automatically. A token will expire one day after it is issued. The client can obtain a new token by calling /v2/auth with the API key or calling HTTP GET /v1/refresh_token. The response of /v1/refresh_token is the same as /v2/auth.

Token V3 introduces a mechanism to allow users to act on behalf of their customers. Token V3 enables users to search for schedules and query rates through APIs similarly to how customers do so on the CarrierX platform (the CarrierX platform is the white-label e-Commerce software solution developed by BlueX Trade).

To use Token V3, API users need to obtain a further User API key from BlueX. The User API Key* is associated with a real username on the CarrierX platform. Please contact your BlueX sales representative for the User API Key.

The client calls HTTP GET /v3/auth?api-key=[api key]&user-api-key=[user api key]&referral-user=[referral user] with a valid API key, a valid User API key and a referral user string. The referral user is a string can identify the user who invokes /v3/auth/. All three fields - api-key, user-api-key and referral-user - are required. /v3/auth will return a JSON response. The token is in the "token" field of the response.

Here is an example of the response:

$ curl -fsSL \
 --header 'Content-Type: application/json' \
 "https://sandbox-api.bluextrade.com/v3/auth?api-key=API-KEY&user-api-key=USER-API-KEY&referral-user=USER-XYZ"

{
  "token": "eyJhbGciOiJI...fmhK81dsg"
}

The token is a JWT token. To access all APIs (except /v3/auth), the client must put the token in the HTTP header. Here is an example:

Authorization: Bearer eyJhbGciOiJI...fmhK81dsg

The system will verify if the token is issued by the system or if the token is expired. The client request will be rejected if the token does not pass the verification process.

Token Refresh

The tokens issued by the system will be expired automatically. A token will expire one day after it is issued. The client can obtain a new token by calling /v3/auth with the API key or calling HTTP GET /v1/refresh_token. The response of /v1/refresh_token is the same as /v3/auth.

To authenticate in the JWT bearer flow, you will need to obtain a JWT containing data on the authentication request, before exchanging it for an access token.

The "Bookings" API provides features for customers to create bookings, cancel bookings, update bookings and query bookings.