This BlueX Freight Commerce Platform (FCP) API document explains our various product offerings through 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.
surcharges
, tieredSurcharges
, includedSurcharges
, and notApplicableSurcharges
.string
type instead of float
for better accuracy.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.
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
will be obsolete soon. Please use Token V2 instead.
The client calls HTTP GET /v1/auth?api-key=[api key]&referral-user=[referral user] with a valid API key and a referral user string. The referral user is a string can identify the user who invokes /v1/auth/ with the API key. Both the api-key and referral-user are required. /v1/auth will return a JSON response. The token is in the "token" field of the response.
This is an example of the response:
{
"token": "eyJhbGciOiJI...W0ossH6uE"
}
The token is a JWT token. To access all APIs (except /v1/auth), the client must put the token in the HTTP header. Here is an example.
Authorization: Bearer eyJhbGciOiJI...W0ossH6uE
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.
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 /v1/auth with the API key or calling HTTP GET /v1/refresh_token. The response of /v1/refresh_token is the same as /v1/auth.
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 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":"USER_API_KEY","referral_user":"XYZ","user_carrier_api_key":[{"carrier":"EGLV","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.
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.
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.
Get a new access token
api-key required | string |
referral-user required | string |
{- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
{- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Get a new access token
api_key required | string |
referral_user required | string |
Array of objects |
{- "api_key": "string",
- "referral_user": "string",
- "user_carrier_api_key": [
- {
- "carrier": "string",
- "id": "string",
- "secret": "string"
}
]
}
{- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
The "Rates" API supports features for customers to receive container information and spot rates. Customers can also receive information from ocean carriers about service routes, vessel/voyage, and container types.
List available rates
scac required | string Example: scac=EGLV The brand SCAC code of the carrier to list rates |
por required | string Example: por=CNSHA Set to filter results to match UN/LOCODE of origin location. |
fnd required | string Example: fnd=USLAX Set to filter results to match UN/LOCODE of destination location. |
departureFrom required | string Example: departureFrom=2020-02-13 Earliest departure date for requested rates in ISO Date Format |
departureTo | string Example: departureTo=2020-03-21 Latest departure date for requested rates in ISO Date Format |
containers | Array of strings Example: containers=2x20SD&containers=3x40HQ Container amounts and types for the request in |
commodities | Array of strings Items Enum: "GDSM" "GARMENT" "FURNITURE" Example: commodities=GDSM&commodities=GARMENT Commodity Code of the content in the containers |
porServiceMode | string Value: "CY" Example: porServiceMode=CY Specify service mode for origin, Merchant haulage (CY) or Carrier haulage (SD) |
fndServiceMode | string Value: "CY" Example: fndServiceMode=CY Specify service mode for destination, Merchant haulage (CY) or Carrier haulage (SD) |
sort | Array of strings Items Enum: "price" "price:asc" "price:desc" "etd" "etd:asc" "etd:desc" "tt" "tt:asc" "tt:desc" Example: sort=etd:asc&sort=tt:desc Sorting is determined through the use of the |
{- "offers": [
- {
- "id": "quote-01",
- "brandScac": "EGLV",
- "productCode": "AS1234",
- "schedule": {
- "id": "schedule-01",
- "brandScac": "EGLV",
- "from": {
- "location": {
- "code": "CNSHA",
- "unlocode": "CNSHA"
}, - "etd": 1591574400
}, - "to": {
- "location": {
- "code": "USLAX",
- "unlocode": "USLAX"
}, - "eta": 1592784000
}, - "firstLoadingPort": {
- "location": {
- "code": "CNSHA",
- "unlocode": "CNSHA",
- "name": "Shanghai",
- "fullName": "Shanghai"
}, - "etd": 1591574400
}, - "lastDischargePort": {
- "location": {
- "code": "USLAX",
- "unlocode": "USLAX"
}, - "eta": 1592784000
}, - "vessel": {
- "name": "EVER LEADER"
}, - "voyageNumber": "0911-046E",
- "transitTime": 14,
- "legs": [
- {
- "from": {
- "location": {
- "code": "CNSHA",
- "unlocode": "CNSHA"
}, - "etd": 1591574400
}, - "to": {
- "location": {
- "code": "USLAX",
- "unlocode": "USLAX"
}, - "eta": 1592784000
}, - "transportMode": "VESSEL",
- "tradeLane": "CPS",
- "vessel": {
- "name": "EVER LEADER"
}, - "voyageNumber": "0911-046E",
- "transitTime": 14
}
]
}, - "price": {
- "containerPrices": [
- {
- "containerType": "20SD",
- "bas": {
- "currency": "USD",
- "rate": "2010",
- "qty": 2,
- "amount": "4020",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_WITH_FREIGHT",
- "chargeCode": "BAS",
- "chargeDescription": "Basic Ocean Freight"
}, - "surcharges": [
- {
- "currency": "USD",
- "rate": "500",
- "qty": 2,
- "amount": "1000",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_AT_ORIGIN",
- "chargeType": "PREPAID",
- "chargeCode": "CSC",
- "chargeDescription": "Container Service Charge"
}, - {
- "currency": "TWD",
- "rate": "100",
- "qty": 2,
- "amount": "200",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_AT_DESTINATION",
- "chargeType": "COLLECT",
- "chargeCode": "THC/D",
- "chargeDescription": "Terminal Handling Charge at Destination"
}
]
}, - {
- "containerType": "40SD",
- "bas": {
- "currency": "USD",
- "rate": "2200",
- "qty": 8,
- "amount": "17600",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_WITH_FREIGHT",
- "chargeCode": "BAS",
- "chargeDescription": "Basic Ocean Freight"
}, - "surcharges": [
- {
- "currency": "USD",
- "rate": "500",
- "qty": 8,
- "amount": "4000",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_AT_ORIGIN",
- "chargeType": "PREPAID",
- "chargeCode": "CSC",
- "chargeDescription": "Container Service Charge"
}, - {
- "currency": "TWD",
- "rate": "120",
- "qty": 8,
- "amount": "960",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_AT_DESTINATION",
- "chargeType": "COLLECT",
- "chargeCode": "THC/D",
- "chargeDescription": "Terminal Handling Charge at Destination"
}
], - "tieredSurcharges": [
- {
- "currency": "USD",
- "rate": "10",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_AT_ORIGIN",
- "chargeType": "PREPAID",
- "chargeCode": "HWCS",
- "chargeDescription": "Heavy Weight Container Surcharge",
- "tierType": "G.W.(Ton)",
- "from": "18.001",
- "to": "22"
}, - {
- "currency": "USD",
- "rate": "15",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_AT_ORIGIN",
- "chargeType": "PREPAID",
- "chargeCode": "HWCS",
- "chargeDescription": "Heavy Weight Container Surcharge",
- "tierType": "G.W.(Ton)",
- "from": "22.001",
- "to": "30"
}, - {
- "currency": "USD",
- "rate": "20",
- "rateBasis": "PER_CONTAINER",
- "rateType": "PAID_AT_ORIGIN",
- "chargeType": "PREPAID",
- "chargeCode": "HWCS",