Best for:
- Business customers of Post & Parcel Germany
- Create and manage shipment labes for domestic and international Parcels
You are on the documentation page of the DHL Parcel DE Shipping API of Post & Parcel Germany. In the following chapters we offer you:
- An Overview of the business functions covered via the API
- The technical documentation of the API
- The User Guide contains topics of connection and authentication
- Postman Collection
- Open API Specification and code examples in Reference Docs
- Find further Use Cases, FAQ and Support Contact in section Additional Information
- Latest Release Notes
Scope
The DHL Parcel DE Shipping API permits the management of shipments and the online purchase of postage and is typically aimed at senders with a volume of more than 200 shipments per year. For DHL business customers who do not have a DHL business customer account (EKP) and who have a shipping volume of less than 200 shipments per year, shipping documents are created via the DHL private customer shipping API.
Using the API
The DHL Parcel DE Shipping API takes care of:
- The preparation of shipping documents for national and international shipping
- Creation of export documents
- Retrieval of labels
General basics
To connect the DHL Parcel DE Shipping API to your systems, we would like to give you an overview on shipping of goods with Deutsche Post DHL for business customers.
To create business customer shipments, you (or your customer) need(s) a business customer contract and access to the Post & DHL Business Customer Portal (GKP). The DHL Parcel DE Shipping API must be set up precisely for these contractually agreed products and services. In addition, the user access data to the GKP, all used billing numbers, sender and return addresses and bank account data must be implemented as configurable attributes.
There are two types of users: system users and personal users. System users can be used for system connections or webservices only. Logging in to the GKP interface is not possible with them. Personal users, on the other hand, are created for the usage in the GKP GUI.
The access data to the GKP consists of a username and a password. The username can, for example, consist of first and last names and may only contain lowercase letters and certain special characters.
The password must comply with the Post & DHL Business Customer Portal guidelines in order to meet certain security criteria: It must be at least 8 characters and no more than 20 characters long, contain at least one special character (!,$,/,(,),=,#,*,+), at least one letter and at least one number. Be sure to use the correct upper- and lower-case spelling when entering the password.
Password validity is 365 days for system users and 90 days for personal users. Users will be informed by e-mail before a password expires and will also receive a link to assign a new password in this e-mail. If the link in the e-mail has expired or if a user has not received an e-mail, they can use the "Forgot Password?" function on the GKP login page (https://geschaeftskunden.dhl.de/) to assign a new password.
EKP: The EKP is a "uniform customer and product number" and thus the key to using Deutsche Post DHL products. It consists of ten digits and is created and assigned by the DHL sales team. Each customer can be uniquely identified via this EKP. It is required for all system connections and must always be transferred.
Contract Procedure: The products used for shipping are referred to as contract procedure. You can find more information about the products here.
Contract Participation: The so-called contract participation is a two-digit numeric (00 to 99) or alphanumeric (AA to ZZ) character string. It is assigned by the DHL sales team. For each product (so-called contract procedure) a customer can use one or more contract participations. It is therefore recommended to keep the number of contract participations variable when configuring the interface. The contract participations enable a subdivision, for example, according to locations, seasonal business or different conditions. In addition, certain services, such as environmentally friendly shipping with GoGreen, are also stored as separate contract participations.
Bank account data: Bank data is only required if the cash on delivery service is enabled. Details of IBAN, BIC, payee, bank name and reason for payment must be entered here.
Contract Billing Number: The billing number is a 14-character string. It consists of the EKP, the contract procedure (=product) and the contract participation. The correct spelling is without spaces or special characters (all 14 characters directly one after the other).
Example:
| 1234567890 | 53 | 01 |
| EKP | Contract Procedure | Contract Participation |
Label format and printing
The DHL Parcel DE Shipping API offers all label formats, which are also available in the Post & DHL Business Customer Portal. We would like to point out that scaling of the label is not permitted, as this no longer guarantees the legibility of the label. Shipments for which machine readability is not possible will be invoiced to the sender with an additional charge for the required manual post-processing.
The following label formats are currently available (printFormat):
- "A4" Common Label laser printing A4 plain paper
- "910-300-700" Common Label laser printing (sheet A5) 105x208mm (910-300-700)
- "910-300-700-oz" Common Label laser printing (sheet A5) 105x208mm, without additional labels (910-300-700)
- "910-300-710" Common Label laser printing105x209mm (910-300-710)
- "910-300-600" Common Label thermal print (folding tape labels) 103x199mm (910-300-600)
- "910-300-610" Common Label thermal print (roll) 103x199mm (910-300-610)
- "910-300-400" Common Label thermal print (folding tape labels) 103x150mm (910-300-400)
- "910-300-410" Common Label thermal print (roll) 103x150mm (910-300-410)
- "910-300-300" Common Label laser printing (sheet A5) 105x148mm (910-300-300)
- "910-300-300-oz" Common Label laser printing (sheet A5) 105x148mm, without additional labels (910-300-300)
Additionally, the label format 100 x 70 mm can be used, but exclusively for the products Warenpost and Warenpost International. Please note that some information cannot be printed on this label due to its smaller size. The following rules therefore apply to address data on this label format:
- Sender: Name 2 and Name 3 are not printed
- For German consignee addresses, Name 3 is is not printed
- For international addresses, 6 lines are printed, with the last line always being the consignee country.
Label printing with a thermal printer corresponds to a resolution of 203dpi. We ask you to take this into account accordingly so that a smooth production run is possible.
Products and services via the web service interface
Products
Shipments can be created using the API function POST "/orders". All products are handed over in the web service attribute "product" and validated by the "contract procedure" in the contract billing number. The contract procedures and product codes to be used can be found in the following overview:
Services
Details and combinatoric
The following table contains an overview of the minimum and maximum dimensions and weights per product. The parameters for creating shipments must be within these limits. The listed parameters are standard values.
Available services per product
In the following table you will find all available services per product. They are divided into three service groups for the sake of clarity only. These groups are not part of the webservice requests.
The following provides an overview on how to get access to the API.
- Technical details on the API calls can be found here: "API Specification".
- Further hints on API usage are given in the sections "Support" and "FAQ".
Get Access
How to register your DHL Parcel DE Shipping API and get your API subscription keys:
- Click Get Access Button on top of this page and the create App form will open with the sandbox environment of the API being pre-selected.
-
- When you have completed the form, click the Create App button.
- You will now find your App under My Apps.
- From the My Apps screen, click on the name of your app.
The Details screen appears. - 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. - Click the Show link below the asterisks that are hiding the Consumer Key.
The Consumer Key appears.
Every call to the API requires a consumer key. This key needs to be specified in the request header (dhl-api-key).
Please note that different keys are required for sandbox respectively production environment. Both can be requested via above procedure and copied from the API credentials section.
Alternatively to "get access" you can go to My Apps on the portal website and click the + Create App button:
- The "Create App" form appears.
- Complete the Create App form and select the "DHL Parcel DE Shipping API".
- You will find two entries of the API in the list: one for Sandbox, one for Production use.
Authentication
Sandbox
To create labels in the sandbox, you have the option of using our testsuite with the following user data:
- Username: "sandy_sandbox"
- Password: "pass"
- EKP: "3333333333"
- Above given username and password must be provided via basic authentication (Basic Auth). Please refer the sample calls below in section authentication details.
A detailed description of the DHL Parcel DE Shipping API can be found in the "Open API Specification".
You can download the "Open API Specification" here.
Following billing numbers and services are available in the sandbox:
Production
To use the "DHL Parcel DE Shipping API", you will first need an application created including the API in production mode.
In addition, the following access data for the webservice (API) must be specified:
- User: "User from Post & DHL Business Customer Portal".
- Password: "Password of above user".
- Your active business customers user and password values must be provided via basic authentication (Basic Auth). Please refer the sample calls below in section authentication details.
When selecting the respective user, please also consider the duration of the validity of passwords:
- the password validity of a "user" is" 90 days
- the password validity of a "system user" is" 365 days
It is not possible to log on to the Post & DHL Business Customer Portal with a "system user".
Important: DHL contract customers receive the access data for access to production from the Post & DHL Business Customer Portal via DHL Paket sales.
Environments
The addressable API base URL/URI environments are:
Authentication Details
This section summarizes preconditions for access and provides background.
| Technical Artefact | Sandbox | Production | Comment |
|
API KEY |
Obtained via Get Access! (app creation) and manually approved by DHL. | Obtained via Get Access! (app creation) and manually approved by DHL. |
Key is a hexadecimal string like below. Provide a HTTP Header parameter like in sample curl call which can be used for validation:
-H "dhl-api-key: ${KEY}" https://api-sandbox.dhl.com/parcel/de/shipping/v2/
Sample key: 7eelE1paJtbWvAKw0ROgVNLZak6rvEoD |
|
GKP Credentials (username + password for https://www.dhl-geschaeftskundenportal.de/ ) |
gkpuser=sandy_sandbox For the sandbox, please use the above credentials. |
gkpuser=YOUR_USERNAME For production, you must be an active business customer. You need to contact DHL. |
GKP username and password must be provided via basic authentication. Curl example below.
curl
|
Next Steps
Once you have obtained an API key for at least the sandbox:
-
Try out basic access by querying the API version:
curl --H "accept: application/json" -H "dhl-api-key: ${KEY}" https://api-sandbox.dhl.com/parcel/de/shipping/v2/ -
Try out to validate a shipment against the sandbox (which you have stored in my_request.json)
curl -X POST -H "dhl-api-key: ${KEY}" --H "accept: application/json" -H "Content-Type: application/json" -u sandy_sandbox:pass -d @my_request.json https://api-sandbox.dhl.com/parcel/de/shipping/v2/orders?validate=True
Note that you can use your credentials to try out several calls directly in the API description under "Reference Information". You will also see more complete curl examples and request documents there. Next, you can actually create a shipping label, retrieve it, and more.
We recommend using the Postman software to test our APIs. Postman is a collaboration platform for API development and testing. Post & DHL Germany provides you a comprehensive Postman collection for every single API. You can download the complete API collection, import it into your Postman work space and get started quickly on your integration with our APIs.
The following steps must be performed to test the API beforehand:
You must request access to the sandbox environment to obtain an API key (dhl-api-key).
You can find detailed instructions on how to do this under Get Access.
Setting up the Postman Test Collection
- Download the Postman test collection from the download section.
- Import the Postman Test Collection (see official documentation of the Postman learning platform)
- Replace the value of the variable "dhl-api-key" with your personal API key.
Please also see our step-by-step instructions on how to use the Postman Test Collection.
The following table creates transparency about the deprecation dates of previous API versions. To clarify the terms, please see the explanations below.
| API Version | Status | Deprecation Date | Sunset Date |
|---|---|---|---|
| GKV 1.x (SOAP) | Deprecated | 01.11.2023 | 31.05.2024 |
| GKV 2.x (SOAP) | Superseded | 01.11.2024 | 31.05.2025 |
| GKV 3.x (SOAP) | Superseded | 01.04.2025 | 31.05.2026 |
| Parcel DE Shipping V1 | Superseded | 01.04.2025 | 31.05.2026 |
| Parcel DE Shipping V2 | Active |
Terms and conditions:
Status "Active": Using this API Version is recommended.
Status "Superseded": The API has been replaced by a new API Version. The API is still supported without limitation. It is recommended to switch to the "Active" API Version.
Status: "Deprecated": The service has been ended (with or without a replacement becoming available). Support for this service is limited to bug fixes only.
"Deprecation Date": From this date on, the API will be in status "Deprecated". Further development will be only based on security updates and bug fixing.
"Sunset Date": The API is no longer available from this date on.
Known Issues
A list of known issues in the current version of Parcel DE Shipping API. We will endeavor to rectify this in the coming releases:
- Shipper phone number is not printed on the customs declaration field “Contact details of sender”
- Identification number for customs purposes is not printed on customs declaration
- GET /orders call for international shipments sometimes leads to errors
- Attributes name2 and name3 are not printed on the return label when using a return address
- Shipper's contact person is not printed on the shipping label when a sender reference is used
- Recipient email address is not displayed in shipping details
- For some attributes, a warning is given regarding the field length, even though the field length is within the given limits, the attribute is processed correctly and the shipping label is successfully created.
- For some technical errors, the structure of the error message deviates from the structure described in the YAML.
- Inconsistent designations for HTTP Status Code in the webservice response
- GET /manifest call with return type URL leads to error when calling the URL
Workaround: Return as Base64-encoded PDF (includeDocs=include)
-
The attribute shipmentRefNo is not returned in the response for multiple shipments within one request and the option validate=true
Notes
If the request contains a multi element array (e.g. multiple shipments), then the order of the items in the response corresponds to the order of the items in the request. For consistency, if the request contains only one item then the response contains a single element array.
Access, Authentication, and Autorisation
Where can I find the documentation of the old Business Customer Shipping API (SOAP)?
The documentation of the old Business Customer Shipping API (SOAP) is available in the download area of the Group API Developer Portal.
Please raise a support ticket to get access. It is recommended to switch to the latest DHL Parcel Shipping API.
How to find the Download Area in the Group API Developer Portal: Navigate to your private settings via the person symbol at the top right and then activate the "Downloads" tab. You will then find the "Documentation Developer Portal" area after approval.
Where can I find samples for authentication?
Please refer to the section on authentication at the User Guide .This also has a curl example.
What authentication is needed for the "Try now!" function?
Two factors are needed. You need a valid API key (it looks like 7eelE1paJtbWvAKw0ROgVNLZak6rvEoD). For the basic auth part, you need Post & DHL Business Customer Portal user and password. For try-out, use the known sandbox credentials (user: sandy_sandbox, password: pass).
My setup works for getVersion() but I get HTTP 401 for all other calls.
Please check the GKP credentials (they are provided via basic auth header). getVersion() (GET call on API URI) does not require those, but all other calls do.
I requested access and did not hear back for 48 hours or more.
Please reach out via contact form Help Center.. Approval is not automatic as long as we are in Early Access or Beta.
Label Formatting and Printing
Can I modify the side margin when printing ZPL label?
A client reported successfully using the following: Before sending the received ZPL file to the printer: “I add on the fly a ZPL command (^LS-30) just after the beginning of ZPL Data (^XA command).”
Request Document
Do you support multi-piece shipments?
Not fully. There is limited support for that via the "costCenter" attribute if you need to group shipments.
ShipperRef attribute -- how to use
You need to set the reference to a shipper (address details) in the business customer portal under “Parcel & goods -> Ship -> Address book -> Sender” and may then refer to this shipper via the shipperRef attribute. In that case, no shipper details are needed. If both are provided, the explicit information will be applied. A hard validation error with HTTP 400 occurs if the shipper reference is unknown.
Weight
Shipment weight is important for billing. This is a mandatory attribute. You can provide shipment weight in either kg or g unit. If shipping internationally and needing customs data: Similar rules apply for individual item weights.
Dimensions
Providing dimensions (length, width, height) are optional. Adherance to product limitations will be checked by DHL. If you choose to provide that data, all attributs (unit of measure, length, height, width) are required.
Packstation Addresses
Please refer to sample included in the API specification. A packstation destination is identified by providing the lockerID attribute.
additionalAddressInformation1 and additionalAddressInformation2 elements of the consignee address
Please check the API specification. Those elements are not printed for most labels. Exceptions include Parcel International labels for selected countries.
Label Download
How long are the labels available for download via /labels URL?
Via the GET /orders call, labels can be retrieved again up to three days after manifesting. A specific shipment number must be added to the call.
Services
I set premium=false but PREMIUM is still printed on the label?
This is country-specific. Most EU countries do not offer economy products, so premium=true is applied. Other countries (CH) offer both.
COD (cash on delivery) - cannot provide the full bank account data
Depending on the GKP account privileges you may be required to create the account in the business customer portal and refer to it via AccountReference attribute in the API.
Retoure international
This is NOT supported on this API. Please check the Parcel DE Returns API. You can create return labels for standard domestic parcels.
Retoure Services
This is a popular service, please refer to the samples included in the technical API spec and/or postman collection.
Customs Information
When providing customs information, do I need to provide it for each item I plan to ship?
Yes.
Will I need to provide customs information?
Depends on origin and destination address. Whenever shipping internationally and not covered differently. (E.g., You don't need it when shipping within the European customs union).
Northern Ireland is part of the European customs union. Therefore, shipments to UK containing postal codes starting with “BT” do not require customs information.
Manifest
Get / manifest appears slow on the sandbox
The sandbox accounts are heavily shared. All customers with a sandbox account can create shipments on the sandbox environment. The manifest-all call may apply to a large number of shipments and therefore, the call might take longer.
Please note: The production behavior is different since your manifests are exclusively related to your shipments.
Can I get a manifest for each billing number?
GET /manifests currently only supports one big combined manifest per EKP (customer number). The only parameter available is the manifesting date (if not provided, today's date is used). The manifest contains multiple sections and is sorted by billing number.
It is planned to enhance the functionality of manifesting to allow more flexible retrieval.
When is Manifest done? Do I have to do it?
It is done automatically at a pre-agreed time, usually the end of your working day. Afterwards shipments cannot be changed and labels (unless cached) cannot be downloaded. You can trigger manifesting explicitly via API as well (POST /manifest).
Version
Do I need to call this?
This helps you as a quick connectivity check and also tells you the current version number. Part of the response is like "version": "v2.0.2" - the version of the API. Updates in the last component -- patch level -- will not be announced, they are guaranteed to be compatible.
Errors
General Hints
PLEASE use the validation switch available for POST /orders. It will tell you if you are missing required elements, mistyped an attribute name and more. Please also use the postman collection (it does have samples for common requests). Please also note that the Swagger (OAS) descriptions contains working samples for most products (available via choice box when trying out a post).
I get an error message complaining
"property": "customs",
"validationMessage" : "Specifiying this line is not possible."
"validationState": "Error"
Likely you are getting the error message when sending an Europaket V54EPAK with more than one goods categories per packet. This product allows only a single goods category (defined by the attribute “hsCode”).
I get an error message complaining
"property": "customs.exportType",
"validationMessage" : "Please enter the type of shipment."
"validationState": "Error"
Likely you are getting the error message when sending a Parcel International and you are missing required customs data.
I get an error message complaining
"property": "billingNumber",
"validationMessage" : "The selected billing number is invalid."
"validationState": "Error"
Likely you are getting the error message when requesting a service which is either not known (check with validate=true please) or your account number + billing number information is not enabled for the service (e.g., Retoure). In that case, please reach out to your DHL contact to check that.
I got an HTTP 500 error downloading a label from the URL returned by the POST call
Likely you are attempting to download a label after it has expired. Before manifesting has been done there is also an alternative obtaining a label through the authenticated GET /orders call. This will also allow to obtain the label directly in the response plus many other options.
Warnings
I get an warning message complaining
"property": "consignee",
"validationMessage" : "The street entered could not be found."
"validationState": "Warning"
The address data could not be validated. You can use that label but DHL may incur extra charges (please check with your sales representative) to correct the address during processing. This also is indicated by a routing code on the label ending with six or more zeroes. To avoid this, please set the query parameter mustEncode=true..
Other
I see there is also a dedicated Retoure API. What's the difference?
The DHL Parcel DE Shipping API allows you as business customer to already provide a return label as part of the original outbound shipment. The Parcel DE Returns API scope is different. Please refer do the documentation of the DHL Parcel DE Returns API.
I see German error messages, is English also available?
Yes, English error messages are available. You can define the accept language in the header parameter of the request.
Currencies can be specified in the request, what can I use?
Please use EUR as currency for cash on delivery (COD). The customs form allows for any other currency as defined in ISO-4217.
Go-Live
I am an Easylog customer and want to migrate to REST. What do I need to know?
You should speak with your DHL sales representative. Likely you will need new billing numbers to avoid clashing number ranges between your Easylog shipments and shipments generated via API.
How long does the activation take to use the production environment?
You should have received the activation of the production API within 1-3 working days.
Will I use the same key for PROD and SANDBOX?
If you have requested access to both sandbox and production products in the same app, the same key will typically be enabled for both PROD and SANDBOX. We can set you up based on your preferences. We can also add PROD access if you had originally only requested sandbox access.
You can request support in our Help Center. You can raise a ticket that allows you to request direct support from DHL Support. Please describe your enquiry in as much detail as possible and also send us reproducible extracts from the web service communication. We will try to help you with your problem as soon as possible during following times:
IT Customer Support & Integration Parcel
Business hours: Mo-Fr 8 a.m. to 16 p.m.
Specific Terms for the use of and/or access to the "DHL Parcel DE Shipping API"
To register for the use of DHL Parcel DE Shipping API You and/or the legal entity you are authorized to represent (hereinafter "You"/"Your") need to have an active customer account with Post & DHL Business Customer Portal (hereinafter referred to as "DHL"). An API Productive Key and access details will be provided to You subject to a successful validation of Your credentials by DHL. If You engage an external developer, or other IT services provider to develop Your Application or any other third party to access and/or use the DHL Parcel DE Shipping API on Your behalf, You remain fully liable for any acts or omissions of such Third Parties in connection with the access to and/or usage of the DHL Parcel DE Shipping API.
These Legal Terms do not replace and/or modify the applicable "General Terms and Conditions of DHL Parcel for business customers", available at https://www.dhl.de/en/geschaeftskunden/paket/rund-um-den-versand/agb.html or any other shipment services agreement, which govern Your parcel shipments.
In case You act as a third party software, vendor, marketplace or otherwise as commercial agent on DHL's and/or its affiliates' behalf, i.e. with DHL's and/or its affiliates' consent, You are obliged to refer the customer (i.e. the sender of the shipments) to the applicable terms and conditions for shipment.
You shall use the services and/or data that You receive via the DHL Parcel DE Shipping API only for the legitimate contractual purposes and only in connection with Your or the shipping customers DHL shipments.
The following prerequisites and/or restrictions apply for the usage of and/or access to the DHL Parcel DE Shipping API:
- The DHL Parcel DE Shipping API provides the possibility to create and print shipping labels and to book shipments. Please be aware that the booking of the shipment within DHL Parcel DE Shipping API does not constitute the contract of carriage. The contract of carriage will only be concluded when the shipment is handed over or picked up and accepted by DHL.
- Please note that the DHL Parcel DE Shipping API only facilitates shipments from Germany to Germany and from Germany to other countries. Creating shipping documents from abroad to Germany and from abroad to abroad is not possible via the DHL Parcel DE Shipping API .
- Please note, that the standard implementation of the functionality "Print Label and Export Documents" (createShipmentOrder) is as PDF label; an implementation according to the" Common Label specification" requires a separate approval by DHL.
- You need to configure your Post & DHL business customer portal (account number or "EKP", procedures, products, services etc.) according to the necessities of the DHL Parcel DE Shipping API. If you act as a third party vendor or marketplace, these configurations need to be implemented for each shipping customer (merchant) individually.
- Credentials (user / password) for the Post & DHL business customer portal need to be delivered/shared within the XML Request.
- When using the service "cash-on-delivery" ("Nachnahme") bank details (incl. BIC and IBAN data for national and international transfers) need to be delivered/shared within the XML Request.
- You shall implement the functionality "Cancel Shipment" (deleteShipmentOrder) within your Application.
- For all products value for the weight must necessarily be delivered. This value may have a predefined default value (only for contractually agreed fixed prices in procedure 01 ("Verfahren 01")) or consist of the specific weight of the shipment. Accordingly, the detection / default must be displayed in the e-shop or marketplace.
- You need to implement the functionality to cancel incorrect labels and have them generated correctly again.
- Non-codable shipments will result in extra charges per shipment (according to procedure 01 ("Verfahren 01")). Accordingly, the procedure must be clarified internally (Accept label without encodable address or cancellation and reprint after correction) and , if applicable, your customer/merchant needs to be informed.
- TThe delivery of shipments to a "Packstation" or "Postfiliale Direkt" needs to be be implemented. For these services a 6-10 digit postal number ("PostNummer") is provided. Specific types of addresses have been defined for the recipient: "Packstation" and "Postfiliale".
- If you act as a third party vendor or marketplace a documentation of the interface is mandatory.
Please note the following additional guidance and recommendations:
- For one DHL product multiple billing numbers or participations ("Teilnahmen") can exist e.g. to distinguish locations, clients or promotions or to use on "GoGreen". If you act as a third party vendor or marketplace we recommend to provide multiple fields for the entry of billing numbers or participations ("Teilnahmen").
- If you act as a third party vendor or marketplace and do not wish to integrate all DHL products and services via the DHL Parcel DE Shipping API, we recommend that you additionally integrate a shortcut link to DHL's business customer portal. Your customers / merchants can then create shipping documents for non-integrated products directly or edit shipping documents created in your Application.
- Each package is exactly one (1) shipment. Please consider this shipping multiple items in multiple packages to one (1) recipient.
2.1.8
The Movement Reference Number (MRN) can now be transferred as an optional parameter in the request when ordering an international shipment.
In the customs declaration, up to 99 goods items can now be transferred in the request.
Correction of enum values of attribute “printFormat” of the objects “Document” and “GetManifestData”.
2.1.7
The service „shipping confirmation” has been removed from the section “value added services” (VAS). Please use DHL Parcel Notification instead.
The documentation of the “BadRequest” response object has been corrected.
2.1.6
The service shipping confirmation is deprecated and no longer supported. Please use DHL Parcel Notification instead.
2.1.5
In the new fields "shipperCustomsRef" and "consigneeCustomsRef" the identification numbers of the shipper and consignee can now be transferred for customs purposes.
The fields "permitNo" and "attestionNo" are now printed correctly on the customs documents.
2.1.4
- Correction of "Shipper" model for successful JSON schema validation when using a shipper reference
2.1.3
- Correction of the documentation for the schema objects: ServiceInformation, POBox, shipDate, dateOfBirth, preferredDay
- Correction of the status code for the endpoint /manifests: If there are no shipments for the daily closing, error code 200 is returned.
- Correction for service DHL return shipment: The shipment number of the return shipment is now included in the response attribute “returnShipmentNo”.
2.1.2
- The successful delivery of a DHL parcel to your front door is generally documented through the signature of our DHL courier. If you additionally need the signature of the recipient, you can order the service “Signed for by recipient” for individual shipments as of July 1, 2023. The service is already available in the sandbox.
2.1.1
- Documentation fixes for schema objects: servers, b64 property of object document and property hsCode minlength
- Ordering of shipping labels via a sender reference now possible again
2.1.0
- A daily manifest can now be performed for all shipments of a certain billing number (operation POST /manifest).
- When a daily manifest list is retrieved, the sheet numbers associated with the billing numbers and shipment numbers are now returned in the response (operation GET /manifest).
2.0.2
- Initial Release
Coming from the original Parcel Business Customer Shipping API (SOAP) including the following operations (SOAP API calls):
- getVersion: With this operation the latest version available on the web can be queried.
- validateShipment: With this operation the data for a shipment can be validated before a shipment label and tracking number will be created.
- createShipmentOrder: This operation creates shipments for DHL Paket including the relevant shipping documents.
- updateShipmentOrder: With this operation shipping documents are updated for previously created shipments. The update automatically performs a cancellation and creating of a shipment.
- deleteShipmentOrder: This operation cancels earlier created shipments.
- getLabel: This operation hands back the shipping label for previously created shipments.
- getExportDoc: This operation hands back export documents for previously created shipments.
- doManifest: With this operation a end-of-day closing for up to 30 previously created shipments can be carried out.
- getManifest: With this operation end-of-day reports are available for a specific day or period.
This API provides equivalent REST endpoints, and attempts to closely replicate the original functionality.
Naming of API resources
The API is following URL naming conventions based on this scheme: https://api${environment}.dhl.com/${business_unit}/${domain_name}/${version_id}/${resource}/
For this API, this means:
https://api-eu.dhl.com/parcel/de/shipping/v2/orders/ andhttps://api-eu.dhl.com/parcel/de/shipping/v2/manifests/
Endpoints
The new API endpoints for the above mentioned old SOAP API calls are:
//orders/manifests/labels
Please have a detailed look at the mapping:
| Resource | Operation | Maps to | comments |
|---|---|---|---|
| / | GET | getVersion | API version and health check |
| /orders | GET | getLabel and getExportDoc | retrieve documents (label, returnlabel and customs documentation) |
| - | POST | createShipmentOrder | Validation or creation of new shipments. This is the primary function of the shipping API. |
| - | DELETE | deleteShipmentOrder | Delete an existing shipment. |
| /manifests | POST | doManifest | Close out the daily processing for selected shipments. |
| - | GET | getManifest | Download the manifesting document. |
| /labels | GET | downloadLabel | Abrufen der PDF-Etiketten von einer öffentlichen URL. Die URL ist Teil der Antwort auf den Aufruf von POST /orders |