Sending pallets requires correct labeling of said pallets.

The necessary format is called SSCC or NVE (German). AM.numbers is a service that generates these numbers to facilitate the labeling process for our customers.

Scope

External business clients who send large orders via Deutsche Post use this service. A customer who wants to utilize the service needs to be registered with AM and authorized for its use by the IT-CSP.

Using the API

This service lets our customers generate the SSCCs required for the labeling of pallets. You may create any number of SSCCs, from one to up to 10,000. Setting a zero count will check the technical availability of the service.

Example Use Case

If an order includes several pallets, you may generate the numbers required for labeling these via AM.numbers and attach them to the pallets. You will then have to enter the SSCCs you used when creating the corresponding order in AM.exchange.

Get Access

You must request credentials for any applications you develop.

To register your app and get your API subscription keys:

1. Click User Dashboard on the portal website and follow the instructions on the website to create a new app.
2. Fill out the form and make sure the information you provide is both complete and correct.
3. When you have completed the form, click the Add App (+) button.
4. In order to receive SSCC/NVE numbers with the API, you must also be activated for this in the AM backend. This activation takes place via the IT CSP (email: it-csp@deutschepost.de).
5. Once this process has been completed, you will receive access to the Sandbox environment for testing.
6. After successful testing you can get credentials for the Production environment.
7. You‘re good to go! Simply create your API request, using a valid Access Token as described below.

Note: The Sandbox environment is accessible directly from this documentation page, where you can leverage the predefined test requests in the reference section.

Authentication

Get Access Token 

The Get Access Token API call provides OAuth 2.0 bearer token with authorization scope, assigned to your client id, which grants you an access to the Deutsche Post AM.numbers API.

The API operation is secured by HTTP Basic authentication, therefore you have to provide client_id and client_secret as a username and password, when calling the API.

To view your API subscription keys:

1. From the My Apps screen, click on the name of your app.
   The Details screen appears. 
2. If you have access to more than one API, click the name of the relevant API. 
   Note: The APIs are listed under the “Credentials” section. 
3. Click the Show link below the asterisks that is hiding the Consumer Key. 
   The Consumer Key appears.    

Environments

The addressable API base URL/URI environments are:  

When passing the client_id and client_secret via HTTPS request, using HTTP Basic Authentication, you will need to populate the HTTP Header Authorization in the following format.

Note: client_id and client_secret have to be encoded to base64-encoding. There is a space character between Basic and the base64-encoded string. There is a : (colon) character between the client_id and client_secret, when encoded in base64.

Authorization: Basic base64-encoded(client_id:client_secret)
Authorization: Basic Yzk2YjQ5YmItYzM3OC00YTE1LWIyZTMtODQyYTk4NTBiMjNkOmJlNDRhZjBhLTc0ZjktNDM4ZS1hM2FjLWUzZTIxZDg0MjU5Zg==

API Call POST https://api-sandbox.dhl.com/auth/v1/token?response_type=access_token&grant_type=client_credentials

Note: You can test the Get Access Token API directly from the documentation page. The Authorization HTTP Header is populated for you in the Console View on the right side of the screen.

You will receive the following response in the JSON format.  

{"access_token":"MqPtBTmEsKTAmRBzZ90tmIRZRFiE","token_type":"Bearer","expires_in":1799}

The response fields: access_token: Contains Access Token string for the  API authentication and authorization.

• token_type: type of the OAuth 2.0 Access Token. Default value is "Bearer".
• expires_in: time to live of the Access Token. Default value is 1799 seconds (30 minutes). After this time the token expires.

Access Token Info 

The Get Access Token Info API call provides information about the issued token.

Rate Limits

Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.

The table below details the main request limits:

When the limit is reached, you will receive an HTTP status code: 

429: Too many requests.