1. Purpose of this document

xChange connect enables members to integrate their shipping software with xChange. At a glance you will, when integrated, profit from these benefits:

• Create one-way leasing supplies & requirements seamlessly
• Sell containers automatically on the trading platform
• Get better matches and offers on xChange
• Get event-based container tracking data from all carriers
• Get aggregated movement-reports from all depots

All of these points can lead to a reduction of overtyping, increase of fleet utilization and boost of economic success on xChange. Read more details about the features and benefits here.

Further in this document, all possible ways to push to and receive data from xChange are described and specified in terms of data standards, authentication and endpoints.

2. General information

Send data to xChange

xChange Solutions offers a REST API to receive data. The xChange API allows xChange members to work with xChange out of their own software.

Authentication

To authenticate with xChange’s servers it is necessary to authenticate. All API requests that are submitted to the API endpoints obey the following constraints. xChange uses API Tokens to authenticate an incoming API calls and to assign the call to the correct member. To authenticate, the header of the API request may have the given API Token as parameter in the URL.

Example:

https://integration.container-xchange.com/connect/rest/api/v1/inventory?api_token=<API Token>

To obtain the token please contact connect@container-xchange.com.

Payload encoding

All payloads may be encoded as JSON object.

Example:

[  
  {  
    "booking_id": "your_internal_id_12345",  
    "deal_id": "",  
    "pickup_location": "CST Hamburg",  
    "pickup_unlocode": "DEHAM"  
   },  
  {  
    "booking_id": "your_internal_id_98765",  
    "deal_id": "1234-1",  
    "pickup_location": "Depot XY",  
    "pickup_unlocode": "CNSHG"  
   }  
]

Error handling

Upon receiving your data, the API service checks whether all mandatory fields are existing. If all mandatory fields exist, an HTTP response with code 200 will be sent. Otherwise, the response will contain details about the error, e.g. listing the missing or erroneous fields.

For further response code explanations, please see the table below.

Last update timestamp

For xChange to process your containers fast and efficiently, a timestamp, which indicates the date and time, a line in the sent object got changed. This applies to every container in the inventory and every reservation in the reservations-payload.

"last_update":"2020-11-30T08:11+2"

Testing environment

We are happy to provide you with a robust testing environment based in a swagger.io instance running on our servers.

Receive data from xChange

As per now the supported ways of sending data to xChange’s integrated members (you) are

• REST API
• Webhook endpoints
  • You can register your webhook endpoint urls (CREATE, UPDATE, DELETE) by texting to connect@container-xchange.com

Please provide us details how to connect with you.

Authentication

To authenticate outgoing communication from xChange to the members’ backend, xChange must authenticate accordingly. Please provide us with the corresponding credentials and documentation.

Payload encoding

When receiving data from xChange, the payload will be encoded as an JSON object. See the example above.

Error handling

Please follow standard HTTP response codes described in the following chapter. Furthermore, please include, if possible, a brief error description in that case.

3. Response codes

4. xChange data standards

Please follow the below stated standards for seamless data transmissions:

Date and time convention

Date and time must follow ISO 8601 specifications:

Format: 2020-07-01 09:00:22 UTC+5 translates to 2020-07-01T09:00+5

Note: For the following parameters use YYYY-MM-DD without time:

• val_date
• ready_for_pickup_date
• eta

Container number

The container number must follow ISO 6346 specifications:

Example: ABCU1234567

Locations

xChange follows the UN/LOCODE convention. UN/LOCODEs are 5-character codes for almost every city or point of interest in the world. You can look up UN/LOCODEs at http://www.unece.org/cefact/locode/service/location.html. Otherwise, we can provide you with an according list.

Hamburg would translate to DEHAM

Container equipment type

We provide you with the different container types and their naming conventions as soon as you get in touch with us.

Container conditions

We provide you with the different container conditions and their naming conventions as soon as you get in touch with us.

A. Supply and use-data on xChange

Availabilities are the basis to creating offers on the trading platform and requirements on the one-way platform. To profit from automatically created availabilities on xChange, two types of data must be sent on a regular basis from the integrated member to xChange: Inventories and bookings.

Synchronizing the inventory solely allows you to enable your fleet to be tracked by xChange’s tracking engine.

A.1. Inventory synchronization

xChange needs to know which individual containers are, in principle, available to offer on xChange. If you are interested in tracking your whole fleet, this is how you submit the list of containers to be tracked.

This API endpoint can be called based on a schedule, e.g. every hour, or event based and must contain all containers from the inventory, not just the changed ones.

URL Structure

https://integration.container-xchange.com/connect/rest/api/v1/inventory?api_token=<api token>

Parameters

Example:

curl -X POST "https://integration.container-xchange.com/connect/rest/api/v1/inventory?api_token=<API TOKEN>" 
        -H  "accept: */*" 
        -H  "Content-Type: application/json" 
        -d <payload>

[
  {
    "container_number": "ABCU1234567",
    "container_type": "20HC",
    "status": "inventory",
    "current_depot": "CST Hamburg",
    "current_unlocode": "DEHAM",
    "pickup_depot": "",
    "pickup_unlocode": "",
    "dropoff_depot": "",
    "dropoff_unlocode": "",
    "condition": "CARGO_WORTHY",
    "color": "Red",
    "ready_for_pickup_date": "",
    "eta": "",
    "ref_out": "",
    "ow_flag": 1,
    "sale_flag": 1,
    "tracking_flag": 1,
    "partner": "Maersk Lines",
    "year_of_manufacturing": 2010,
    "target_price": "",
    "last_update": "2020-10-12T15:27+2"
  },
  {
    "container_number": "XYZU7654321",
    "container_type": "40HC",
    "status": "leased",
    "current_depot": "",
    "current_unlocode": "",
    "pickup_depot": "CST Hamburg",
    "pickup_unlocode": "DEHAM",
    "dropoff_depot": "Depot Xy",
    "dropoff_unlocode": "CNSHG",
    "condition": "BRAND_NEW",
    "color": "",
    "ready_for_pickup_date": "2020-10-01T12:00+2",
    "eta": "2020-10-31",
    "ref_out": "ref12345",
    "ow_flag": 1,
    "sale_flag": 1,
    "tracking_flag": 1,
    "partner": "Maersk Lines",
    "year_of_manufacturing": 2010,
    "target_price": "",
    "last_update": "2020-10-12T15:27+2"
  }
]

A.2. Reservations

Reservations refer to groups of containers, sharing the same condition, type and location, that are expected to be picked up in the near future. To calculate the right amount available per availability, xChange needs no know how many containers are “blocked”. As soon as all containers of a booking have been picked up, the reservation is not needed anymore.

This API endpoint can be called based on a schedule, e.g. every hour, or event based and must contain all reservations of a given group of containers, not just the changed ones.

URL Structure

https://integration.container-xchange.com/connect/rest/api/v1/reservations?api_token=<api token>

Parameters

Example:

curl -X POST "https://integration.container-xchange.com/connect/rest/api/v1/reservations?api_token=<API TOKEN>" 
        -H  "accept: */*" 
        -H  "Content-Type: application/json" 
        -d <payload>

Payload example:

[
  {
    "booking_id": "your_internal_id_12345",
    "deal_id": "",
    "pickup_location": "CST Hamburg",
    "pickup_unlocode": "DEHAM",
    "container_type": "45HC",
    "condition": "CARGO_WORTHY",
    "ref_out": "release_1234",
    "amount_booking": 10,
    "amount_picked_up": 5,
    "last_update": "2020-10-12T16:06+2"
  },
  {
    "booking_id": "your_internal_id_98765",
    "deal_id": "123-1",
    "pickup_location": "DIT Duisburg",
    "pickup_unlocode": "DEDUI",
    "container_type": "40HC",
    "condition": "BRAND_NEW",
    "ref_out": "release_9876",
    "amount_booking": 5,
    "amount_picked_up": 0,
    "last_update": "2020-10-12T16:06+2"
  }
]

A.3. Stocklist synchronization

If you have a stocklist, hence groups of containers that share the same container pickup location, type, condition and price, you can provide them directly.

Please note that the combination of location, type, conditon and price (even if it is null) must be unique.

URL Structure

https://integration.container-xchange.com/connect/rest/api/v1/availabilities?api_token=<api token>

Parameters

Example:

curl -X POST "https://integration.container-xchange.com/connect/rest/api/v1/availabilities?api_token=<API TOKEN>" 
        -H  "accept: */*" 
        -H  "Content-Type: application/json" 
        -d <payload>

[
{
"container_type": "T75",
"container_condition": "CARGO_WORTHY",
"location_unlocode": "BEANR",
"price": 2760,
"avail_amount_ow": 0,
"avail_amount_trading": 10,
"avail_amount_depot": 10,
"total_amount_depot": 10,
"yom_from": 2001,
"yom_to": 2011,
"colors": null,
"capacity": 22000,
"grade": "chemical"
},
{
"container_type": "20DC",
"container_condition": "CARGO_WORTHY",
"location_unlocode": "DEHAM",
"price": 2995,
"avail_amount_ow": 0,
"avail_amount_trading": 8,
"avail_amount_depot": 8,
"total_amount_depot": 8,
"yom_from": 2000,
"yom_to": 2011,
"colors": "RAL 1100, Green",
"capacity": null,
"grade": null
}
]

https://integration.container-xchange.com/connect/rest/api/v1/requirements?api_token=<api token>

curl -X POST "https://integration.container-xchange.com/connect/rest/api/v1/requirements?api_token=<API TOKEN>" 
        -H  "accept: */*" 
        -H  "Content-Type: application/json" 
        -d <payload>

[
{
"pickup_location": "CNFZH",
"dropoff_location": "DEHAM",
"direction": "Using",
"equipment_type": "75T",
"condition": "CARGO_WORTHY",
"equipment_count": null,
"free_days": null,
"per_diem": null,
"pickup_charge": null,
"damage_protection_plan": null,
"residual_value": null,
"depreciation_rate": null,
"replacement_value": null,
"grade": "Chemical",
"capacity": 22000
},
{
"pickup_location": "CNFZH",
"dropoff_location": "DEHAM",
"direction": "Supplying",
"equipment_type": "40HC",
"condition": "CARGO_WORTHY",
"equipment_count": 8,
"free_days": 60,
"per_diem": 1,
"pickup_charge": 50,
"damage_protection_plan": 100,
"residual_value": 3000,
"depreciation_rate": 5,
"replacement_value": 50,
"grade": "",
"capacity": null
}
]

B. Leaning up your processes

This chapter specifies two ways of speeding up your processes while working with xChange.

B.1. Accepted deal details

Here the payload is defined, that allows xChange to push details about an accepted deal to your software, being, after a successful negotiation at the trading- or one-way-leasing-platform.

Please design your endpoints following the below defined parameters.

Container trading negotiation was successful

When a negotiation on the trading platform ends successfully by one of the two parties closing the deal, the below stated payload will be sent to integrated customers. This can result for the supplying party in the automatic reservation of the right amount of containers.

Payload example:

[
  {
    "trading_id": "123-1",
    "trading_role": "buyer",
    "container_type": "20HC",
    "condition": "BRAND_NEW",
    "color": "Green",
    "yom_from": 2018,
    "yom_to": 2020,
    "amount": 3,
    "pickup_depot": null,
    "pickup_unlocode": "DEHAM",
    "partner": "Trader xyz",
    "price": 2500,
    "freedays": 20,
    "daily_storage_charge": 10,
    "payment_handling": true
  }
]

One-way-leasing deal is accepted

When a negotiation on the one-way-leasing platform ends successfully by one of the two parties closing the deal, the below stated payload will be sent to integrated customers.

This can result for the supplying party in the automatic reservation of the right amount of containers.

Payload example:

[
  {
    "request_id": "12345",
    "request_role": "supplier",
    "partner": "xChange Member 10",
    "container_type": "45HC",
    "condition": "CARGO_WORTHY",
    "amount": 10,
    "pickup_depot": "CST Hamburg",
    "pickup_unlocode": "DEHAM",
    "dropoff_depot": "CNSHG",
    "dropoff_unlocode": "Depot Xi",
    "freedays": 30,
    "per_diem": 1.5,
    "pickup_charge": 0.5,
    "damage_protection_plan": 200,
    "discounted_residual_value": 700,
    "damage_protection_insurance": 1000
  }
]

B.2. Release creation

If you are the supplier of containers withing a trading- or one-way-leasing-deal you can create release documents automatically out of your software. This will make the release document available to download for the other party on xChange instantly.

This API Endpoint should be called after reserving the right amounts of containers and asigning the reservation a release number.

URL Structure

https://integration.container-xchange.com/connect/rest/api/v1/create-release?api_token=<api token>

Payload

Example:

curl -X POST "https://integration.container-xchange.com/connect/rest/api/v1/create-release?api_token=<API TOKEN>" 
        -H  "accept: */*" 
        -H  "Content-Type: application/json" 
        -d <payload>

Payload example:

[
  {
    "request_id": "X12345",
    "trading_id": "",
    "ref_out": "ABC-XYZ99999",
    "val_date": "2020-10-15",
    "container_type": "20DC",
    "condition": "CARGO_WORTHY",
    "amount": 10,
    "pickup_depot": "CST Hamburg",
    "pickup_unlocode": "DEHAM",
    "depot_address_1": "Industriestrasse 55",
    "depot_address_2": "",
    "depot_zip": "21107",
    "depot_phone": "+49 40 74119066",
    "depot_email": "info@cst-container.com",
    "additional_info": "Please make sure you advise your hauler to pick cargo worthy units as the release is ex-stack.\nKindly contact depot prior to sending trucks for collection."
  }
]

C. Track your containers

This chapter specifies the payloads of tracking related events, like gate-in and -out movements of containers or more detailed tracking informations from determined by the MyFleet Tracking Engine. To enable your fleet for tracking, please refer to A.1. Inventory synchronization.

C.1. Receive tracking events

Tracking events are sent to you event based. This means that if xChange tracking engine registers a new event of one of your containers in your inventory, we call your API or webhook endpoints with the event data.

Please design your endpoints following the below defined parameters.

{
  'container_number':'ABCU1234567',
  'event_date':'2020-10-28',
  'event_name':'Empty Returned (Off-hired)'
  'event_location':'DEHAM',
  'transport_mode':'M.S. Tina',
  'voyage':'V. 125'
  'eta': false
}

{
  'container_number':'ABCU1234567',
  'event_date':'2021-02-28',
  'event_name':'Empty Returned (Off-hired)'
  'event_location':'DEHAM',
  'transport_mode':'',
  'voyage':''
  'eta': true
}

C.2. Gate-movements

Gate-movements can be both pushed to your backend as well as being provided to xChange.

Get gate-movements from xChange

As soon as a gate-in or -out movement is registered by xChange we push integrated customers these movements directly into their software.

Please design your endpoints following the below defined parameters.

Payload example:

[
  {
    "container_number": "ABCU1234567",
    "ref_out": "REFxyz-123",
    "event": "in",
    "depot_name": "CST Hamburg",
    "depot_unlocode": "DEHAM"
  }
]

or

[
  {
    "container_number": "ABCU1234567",
    "ref_out": "REFxyz-123",
    "event": "out",
    "depot_name": "CST Hamburg",
    "depot_unlocode": "DEHAM"
  }
]

Send gate-movements to xChange

Send gate-movements to xChange when they are entered manually to xChange, so that your partner gets this info faster and billing based on used days is seamless.

URL Structure:

https://integration.container-xchange.com/connect/rest/api/v1/gate-movement?api_token=<api token>

Example:

curl -X POST "https://integration.container-xchange.com/connect/rest/api/v1/gate-movement?api_token=<api token>" 
   -H  "accept: */*" 
   -H  "Content-Type: application/json" 
   -d "<payload>

Payload example:

[
  {
    "container_number": "ABCU1234567",
    "ref_out": "REFxyz-123",
    "event": "in",
    "depot_name": "CST Hamburg",
    "depot_unlocode": "DEHAM"
  }
]

or

[
  {
    "container_number": "ABCU1234567",
    "ref_out": "REFxyz-123",
    "event": "out",
    "depot_name": "CST Hamburg",
    "depot_unlocode": "DEHAM"
  }
]

D. Depot integrations

xChange offers different ways for depots to send gate movements to xChange for their customers. However, before sending customer related details to xChange as a third party, an information processing agreement must be signed by the customer to authorize the depot to send the data.

D.1. EDI

xChange supports EDIFACT/CODECO standard to receive and process gate movements. EDI messages can be saved on a dedicated SFTP-Server or sent to an e-mail inbox serving that purpose. Please get in touch with connect@container-xchange.com for more details.

D.2. API calls

You can provide us with event-based gate movements via a dedicated API endpoint. Please refer to section C.2. for more details on that.

D.3. ODBC

We can access a part of your database securely over ODBC. Please get in touch with us for more information on that topic.

Version 1.6 – Last revision: 10.08.2021
In case of any questions please use the contact form below.