Picture

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.

  • 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. The involved authentication methods and credentials for the online portals are briefly described in the following: 

Authentication methods 

  • API key (HTTP header: dsv-subscription-key) 

    • This key is obtained by subscribing to the API as described in the ‘Developer Guide’. 

    • The key can be found in the DSV Developer portal profile page once the subscription request is approved by DSV. 

    • 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 (HTTP header: dsv-service-auth) 

    • For security reasons, you will have to pass along a valid service authorization key in the request header for the given XPress API. 

    • The key can be found on the XPress demo portal in the profile page. Login credentials to the XPress demo portal will be send to you via email once the subscription request is approved by DSV. 

    • 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) 

    • The XPress APIs are requiring a Personal Access Token to be passed in the request HTTP header “x-pat”. 

    • The Personal Access Token can be found on the XPress demo portal in the profile page. Login credentials to the XPress demo portal will be send to you via email once the subscription request is approved by DSV. 

      Sample key structure: bbmiPcs2uFY3fN9R0lju 

Note: the authentication details are linked to the specific environment (test and production). When moving to the production environment a new set of authentication details will be provided. 

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:

Picture


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:

Picture