Welcome to the CheapCargo API documentation. This comprehensive guide will help you integrate our shipping services into your application for seamless logistics management.
The API supports both XML and JSON. Set the headers Accept and Content-Type to application/xml or application/json accordingly. The JSON format is a direct translation of the XML structure, where the XML root element becomes the top-level key in the JSON object.
XML attributes are represented as @attributeName fields in JSON. For example:
<shipment pay="false" id="E-1887"> <reference>ORDER-001</reference> </shipment>
{
"shipment": {
"@pay": false,
"@id": "E-1887",
"reference": "ORDER-001"
}
}
Array elements such as shipment and colli are always represented as JSON arrays, even when there is only one item.
- š° Rate Requests: Get competitive shipping rates for your packages
- š¦ Create Shipments: Book shipments with trusted carriers
- š Track Shipments: Real-time monitoring and status updates
- š·ļø Manage Labels: Download and print shipping labels
- āļø Cancel Shipments: Modify or cancel bookings when needed
- š¤ Manage Accounts: Create and manage user accounts
To access our API, each request must include an authentication token and user credentials. The authentication process ensures that only authorized users can interact with the API. Ensure that the hashes in authentication and password are correctly generated and match the expected format to successfully authenticate with the API.
The authentication information will typically look as follows in the request body:
<authentication>317ad2da332f65569b172c77b9565bda</authentication> <user> <email>user@example.com</email> <password>51f740668efd21ab9ec1d0d382d9746e</password> </user>
Or in JSON:
{
"authentication": "317ad2da332f65569b172c77b9565bda",
"user": {
"email": "user@example.com",
"password": "51f740668efd21ab9ec1d0d382d9746e"
}
}
Authentication token (
authentication):- The authentication token is generated by creating an MD5 hash of the user's API key followed by the current date and hour in the format
YYYYMMDDHH. - The time part
HHis based on a 24-hour format with a 2-hour margin. The time should be expressed in the time zone of the Netherlands (CET/CEST). For example, if the request is made between 13:00 and 17:59 on 15 December 2023, the time portion would be15, resulting in a date and time format of2023121515. So if the user's API key isVlp3RxUvRF9xDzoX, thenVlp3RxUvRF9xDzoX2023121515would hash to317ad2da332f65569b172c77b9565bda.
- The authentication token is generated by creating an MD5 hash of the user's API key followed by the current date and hour in the format
User email address (
email):- This is the email address associated with the user's account, used for logging in.
Password hash (
password):- The password should be hashed using the MD5 algorithm.
CheapCargowould hash to51f740668efd21ab9ec1d0d382d9746e.
- The password should be hashed using the MD5 algorithm.
User account number (
accountNumber):- Instead of providing the user email address, the user account number can also be provided.
The API also supports performing requests on behalf of another user. This allows authorized partners or administrators to execute operations for other accounts without requiring their direct credentials. To do this, include an onBehalfOf element in the request body after the user element, specifying either the user's email address or account number. For example:
<onBehalfOf> <email>different_user@example.com</email> </onBehalfOf>
or
<onBehalfOf> <accountNumber>260001337</accountNumber> </onBehalfOf>
In JSON:
{
"onBehalfOf": {
"email": "different_user@example.com"
}
}
or
{
"onBehalfOf": {
"accountNumber": "260001337"
}
}
This functionality only works if the target user has explicitly authorized you to act on their behalf. Without this authorization, the API will reject the request with an authentication error.
It is recommended to use the account number instead of the email address whenever possible, because account numbers are permanent identifiers, while users can change their email addresses at any time.
To ensure optimal compatibility with our API, each request should include the version number your system is using. This versioning helps prevent issues when we make changes to the message structure or functionality of the API. By specifying the version number, your system can continue to function correctly even if updates are made on our end.
The version number is applied on a per-method basis, meaning different methods in your system may use different version numbers.
If no version number is provided, the API will assume you are using the latest version. However, if CheapCargo introduces changes and a new version becomes available that differs from the previous one, this could lead to errors. Therefore, we strongly recommend always including the version number in your requests to ensure consistent operation.