Developer Guide - XPress
On this page you will find an overview of the available XPress APIs and the different options offered via each API next to a description of the involved authentication method used in the APIs.
API: Rate & Service
Request quotes and service options based on agreed tariff rates.
Supported transport modes: XPress
The Rate & Service API offers one method to receive quote and services options:
Rate & Service (receive a quote based on agreed tariff rates)
Feature: Request quotes based on agreed tariff rates, and list the available services matching your criteria.
This API will not submit bookings to DSV.
API: Booking
Submit bookings to DSV via DSV’s Booking API.
Supported transport modes: XPress
The Booking API offers four methods to submit and maintain a booking:
Submit draft booking (submit a draft booking to DSV – booking is NOT sent to carrier)
Feature: Submit a draft transport booking to DSV to move a package from A to B. Bookings sent via this method are not processed by DSV.
Upload transport related documents
Feature: Upload transport related documents against the draft booking (e.g. packing list, dangerous goods certificates, commercial invoice, export declaration etc.)
Note: Some Documents are mandatory when shipping outside Europe or from/to a Restricted country.
Mandatory documents have to be uploaded prior to confirming the final booking.
List of mandatory documents per country can be found in the section XPress booking process.
Confirm draft booking and download package label(s)
Feature: Confirm draft booking and download package label(s).
This method will confirm the draft booking and send the booking instruction to the final carrier.With the booking confirmation, the call will respond with the package label which can be downloaded either in a ZPL or PDF format.
Cancel booking (within allowed cancellation window)
Feature: Cancel a confirmed booking within the allowed cancellation window.
The cancellation window is subject to specific restrictions according to your agreement with DSV. The API will instantly provide either a confirmation response in case the cancellation request was accepted by DSV or an error message in case the cancellation of a specific booking is not possible.
Booking types
The number of involved process steps for submitting a final XPress booking depends on the type of shipment as described in the following:
Simple booking shipped Domestic or within Europe will require 2 API requests:
Submit Draft Booking
Confirm draft booking and download package labels
Complex booking shipped outside Europe will require 3 API requests:
Submit Draft Booking
Upload transport related documents
Confirm draft booking and download package labels
Detailed information about complex bookings (countries) and mandatory documents can be found in the section XPress booking process.
Note: To move to production environment, the certification process must be passed for the XPress Booking API. Please refer to the Certification tests section for a detailed explanation of the involved steps.
API: Tracking
Track the status and latest events of your XPress shipments moved by DSV.
Supported transport modes: XPress.
The tracking API offers four methods to obtain shipment information:
Shipment details (by DSV XPress Shipment ID – e.g. 10123456)
Features: Retrieve detailed shipment data for a specific shipment, by searching by the DSV XPress Shipment ID received from API booking or through the DSV XPress online portal.
Data elements: DSV Shipment ID, DSV Booking ID, Booked By, Address details, Transport mode, Shipment Status, ETA, Cargo details, estimated or actual charges etc.
Shipment events (by DSV XPress Shipment ID – e.g. 10123456)
Features: Retrieve actual events for a specific shipment by searching for the DSV XPress shipment id.
Data elements: Actual pickup, departure, arrival, delivery date/time, exception description.
Shipment events (by AWB number – e.g. 40170726203663178132)
Features: Retrieve actual events for a specific shipment by searching for the AWB number.
Data elements: Actual pickup, departure, arrival, delivery date/time, exception description etc.
Shipment events (by Carrier tracking ID – e.g. 921541696551)
Features: Retrieve actual events for a specific shipment by searching for the Carrier tracking id
Data elements: Actual pickup, departure, arrival, delivery date/time, exception description.
Authentication and login credentials
The available XPress APIs are using a combination of authentication methods to ensure a secure connection to DSV.
You will need to provide an API key, an Authorization key and a Personal Access Token in the HTTP header for every request submitted to XPress APIs.
The authentication details are linked to specific environments (test and production). When moving to the production environment a new set of authentication details will be provided.
The involved authentication methods and credentials for the online portals are briefly described in the following:
Authentication methods
API key
Goal : Security to access for DSV Developer Portal
HTTP header : DSV-Subscription-Key
When is it provided :
This key is obtained by subscribing to the API as described in the ‘Developer Guide’. It will be active once your subscription is approved by DSV.
Other keys will be provided when your 'go-live' request will be validated.
Where is it available : The key can be found in the DSV Developer portal profile page but will only be active once the subscription request is approved by DSV. This key is common to all DSV APIs.
What does it look like : 2 keys are allocated per subscribed product, a “primary key” and a “secondary key”.
Only one key, either primary key or secondary key, should be used in the HTTP header “DSV-Subscription-Key”.Sample key structure: b5c09b92fbf24d62a17caad22227c470
Authorization key
Goal : For security reasons, you will have to pass along a valid service authorization key in the request header for the given XPress API endpoint.
HTTP header : DSV-Service-Auth
When is it provided :
You can access it once you receive your credentials for DSV XPress demo portal. These credentials will be sent to you in a separate email once the subscription request is approved by DSV.
You will have access to a new authorization key when your request for go-live will be accepted.
Where is it available :
The key for the test can be found on the XPress demo portal in the profile page. Be careful to select the key that belong to the desired XPress API product (Booking, Tracking or Rate & Services) if you have subscribed to several products.
The key for the production can be found on the XPress production portal in the profile page. Be careful to select the key that belong to the desired XPress API product (Booking, Tracking or Rate & Services) if you have subscribed to several products.
What does it look like : 2 keys are allocated per subscribed product, a “primary key” and a “secondary key”.
Only one key, either primary key or secondary key, should be used in the HTTP header “DSV-Service-Auth”.Sample key structure: e4e5a4d.f1fbc48e1a0848b4d64e7bf23
XPress Personal Access Token (HTTP header: x-pat)
Goal : For security reasons, you will have to pass along a valid Personal Access Token in the request header. It is common to all XPress products.
HTTP header : x-pat
When is it provided :
Same as for the authorization keys, once you receive your credentials for XPress demo portal, you will be able to access it.
You will receive a new token when your request for go-live will be accepted.
Where is it available :
The token for the test environment can be found on the XPress demo portal in the profile page.
The token for the production environment can be found on the XPress production portal in the profile page.
What does it look like : 1 token is allocated per user for all XPress API products.
Sample key structure: bbmiPcs2uFY3fN9R0lju
Login credentials for online portals
When developing against the XPress APIs, several online portals are made available supporting different parts of the development process.
DSV Developer portal
Main portal for DSV’s APIs covering the API catalogue, technical documentation, developer guides and subscriptions for the different APIs.
The API key (HTTP header: DSV-Subscription-Key) is found on this portal.
Login credentials are selected by the user when signing up to the portal.
XPress demo portal
Online booking and tracking portal where bookings submitted via the test XPress booking API are visible. It is recommended to use the portal to verify if the information submitted via the APIs are correctly received by DSV.
The Authorization key (HTTP header: DSV-Service-Auth) and XPress Personal Access Token (HTTP header: x-pat) are found on this portal in the profile page.
Login credentials are provided via email once the subscription request made on the DSV Developer portal is approved by DSV.
Login credentials are the same for both the XPress demo portal and API validation portal.
API validation portal
Online portal used for the Certification test process which is mandatory when developing against the XPress booking API.
Login credentials are provided via email once the subscription request made on the DSV Developer portal is approved by DSV.
Login credentials are the same for both the API validation portal and the XPress demo portal.
Certification Tests
The XPress Booking API requires you to pass a certification process, as a prerequisite for moving to Production.
Note: The XPress Booking API can only be moved to production once all tests has been passed successfully. The certification test is only required for the XPress Booking API.
The involved test steps are described in the following:
1. Access the API VALIDATION PORTAL and login with the credentials provided with the approval of the subscription request.
2. View and familiarize yourself with the required certification tests list on the page.
3. Add the HTTP header ‘x-cert-id’ to each test call:
Header: ‘x-cert-id’
Value (ID of the certification test): TCx (e.g. TC1)
4. Execute the test case in one of the following ways:
Online via Certification page on the API VALIDATION PORTAL
Certification tests can be executed directly from the Certification Page on the API validation portal after logging into the portal.
On the certification tests page, you will be prompted to specify valid request parameters and payloads. The validation tool will ensure that the proper credentials and Certification ID are passed along with the test calls.
Online via the ‘Try-It’ feature on the DSV DEVELOPER PORTAL
Another option to execute the certification tests is by using the ‘Try-It’ feature on the DSV Developer portal.
• Click at the API Product and REST method you want to test.
• Click the ‘Try-It’ button and fill out the request parameters and payloads.
• Populate the Headers with your credentials (mentioned in the section Authentication).
• Add the "x-cert-id" http header and populate with the certification test case identifier (e.g. TC1).
• Click the Send button and inspect the result.
Execute Certification Tests using cURL
As a third option, you can execute the certification tests from your API client with cURL or any other programming language.
For each REST method, examples of cURL commands and samples in other programming languages are displayed at the bottom of the documentation page.Simply add the "x-cert-id" http header and populate with the certification test case identifier (e.g. TC1).
5. Review the response for each test case.
When executing a certification test, the API will respond with the following headers:
Note: All required certification tests for the XPress Booking API must have been passed prior requesting Go-live. The progress of the tests can be viewed in the API validation portal.
XPress booking process (complex bookings)
The XPress Booking API requires specific documents to be upload against the booking for selective trade lanes, package types and commodity. These types of bookings are referred to as Complex bookings.
The following table provides an overview of the mandatory documents per trade lane, package type, commodity:
Postman
To facilitate easy development and testing Postman collections for each endpoint have been created: