Shippinglabel API
Welcome to the documentation of our Shippinglabel API.
This guide explains REST request and response mechanics including sample requests and responses.
It also provides other information that you'll need as you write applications with the API.
If you have some questions or if you find any errors, please feel free to contact us. If you need assistance with the implementation of the API, then we will of course also be happy to help:
Get Started
The Shippinglabel API follows the REST design, uses the JSON format for reqeusts and reponses and uses standard HTTP response codes.
To make requests to the API, you must create an application on Shippinglabel. There you will receive your ClientID and the ClientSecret, which you need to obtain the access token.
Endpoints
The following API endpoints are available:
| URL | Application | |
|---|---|---|
| Sandbox | https://api.dev.shippinglabel.de/v2 |
Shippinglabel (dev) |
| Production | https://api.shippinglabel.de/v2 |
Shippinglabel (live) |
SDK
For the Shippinglabel API we offer the following SKDs:
General
Sample JSON
{
"id": 1,
"name": "Shippinglabel",
"amount": 200.48,
"created": "2022-08-08T11:36:24Z",
"isDefault": true,
"string": "",
"integer": 0,
"float": 0.0,
"boolean": false,
"object": null,
"array": null
}
The example above is output as follows
{
"id": 1,
"name": "Shippinglabel",
"amount": 200.48,
"created": "2022-08-08T11:36:24Z",
"isDefault": true
}
JSONis used for the request and response, unless otherwise describedCamelCaseis used for field names (e.g.firstName)Datesare returned in ISO8601 format:YYYY-MM-DDTHH:mm:ss- Blank fields are omitted in the response
| Type | Sample | Omitted value |
|---|---|---|
| string | "Shippinglabel" | "" |
| integer | 400 | 0 |
| float | 2.45 | 0 |
| boolean | true or false | false |
| datetime | "2022-08-08T11:36:24Z" | null |
| object | {} | null |
| array | [] | null |
Localization
Sample Header
Accept-Language: de
Sample Query Parameter
[GET] https://api.shippinglabel.de/v2/shipments?locale=en
Error messages and texts in the applications can be output in English or German. Users can select one of the two languages that affects the response body texts in the settings on Shippinglabel. You can also select the language via the Accept-Language header or via the query parameter locale. The available values are en or de.
The language is selected with the following prioritization:
- User settings
- Query parameter: locale
- Header: Accept-Language
Errors
Sample Error
[400] - Bad Request
{
"message": "Bitte wählen Sie ein gültiges Sendungsdatum",
"code" : "DHL",
"messages": [
"Die von Ihnen genannte PLZ ist ungültig",
"Die von Ihnen genannte Straße ist ungültig"
]
}
Sample Error
[401] - Unauthorized
{
"message": "Authentication failed",
"code" : "UNAUTHORIZED"
}
Sample Error
[404] - Not Found
{
"message": "Path not found",
"code" : "NOT_FOUND"
}
Sample Error
[500] - Internal Server Error
{
"message": "Internal server error",
"code" : "SERVER_ERROR"
}
When an error occurs, you receive an 4xx HTTP status code along with a message and error code in the body of the response. The message is issued in the user's preferred language, while the code is designed as machine-readable codes that help applications understand the context of the error. If available, additional error messages are added.
ErrorModel
The ErrorModel is output in case of an error.
| Field | Type | Description |
|---|---|---|
| message | string | Main error message |
| code | string | Error code. If the code is named after the carrier (e.g DHL), then the error messages come directly from the carrier |
| messages | string[] | Further error messages |
HTTP Status Codes
After each HTTP Request, there is an HTTP Status Code, which indicates how the request was processed.
| Code | Text | Description |
|---|---|---|
| 200 | OK | The request has been successfully processed and the result of the request is transmitted in the response |
| 201 | Created | The request was processed successfully. The requested resource was created before sending the response |
| 204 | No Content | The request was successful, but the response does not contain any data |
| 207 | Multi-Status | The response contains several objects with different status codes |
| 400 | Bad Request | The request body was constructed incorrectly or the request could not be processed correctly |
| 401 | Unauthorized | The request cannot be performed without valid authentication |
| 403 | Forbidden | Authentication was correct, but the requester has no authorization |
| 404 | Not Found | The requested resource was not found |
| 405 | Method Not Allowed | The request may only be made using other HTTP methods |
| 500 | Internal Server Error | Unexpected server error |
| 503 | Service Unavailable | The server is temporarily unavailable |
Authentication
Sample Authorization Header
Authorization: Bearer ACCESS_TOKEN
The API use the OAuth2.0 protocol for application and user authorization. Authentication requires a valid access token to be included in the Authorization Header for each request.
The methods for creating access tokens are described below.
Client Credentials
Sample Request
[POST] /oauth2/tokenHeader
Authorization: Basic [encoded string]
Content-Type: application/x-www-form-urlencoded
Body
grant_type: client_credentials
Sample Response
[200] - OK
{
"accessToken": "ey123testaccesstokenforshippinglabel",
"expiresIn" : 300,
"refreshToken": "ey456testrefreshtokenforshippinglabel",
"refreshTokenExpiresIn" : 600,
"tokenType": "Bearer"
}
To get a token via Client Credentials, the HTTP Basic Authorization is required. The username used here is ClientID and the password is ClientSecret. With this method, you must also add the client_credentials grant type in the request body.
Authorization Code
The authorization code grant is used when an application exchanges an authorization code for an access token. After the user returns to the application through the redirect URL, the application obtains the authorization code from the URL and uses it to request an access token. This request is made to the /oauth2/token endpoint.
Get User Permission
Sample Request
[GET] /oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fshippinglabel.de&state=xcoiv33d4yw222vusuye3kchSample Response
[302] - Found
The user is redirected to Shippinglabel to get the user's authorization
After Authorization
[302] https://shippinglabel.de?code=e160c27218d571fec79787f63d682663&state=xcoiv33d4yw222vusuye3kchQuery parameters
code: e160c27218d571fec79787f63d682663
state: xcoiv33d4yw222vusuye3kch
[GET] /oauth2/authorize
Creates a session and redirects the user to the Shippinglabel application. There the user grants authorization and is connected to the application. After that, the user is redirected to the specified URL with the authorization code.
Query parameters
| Field | Description |
|---|---|
| response_type | Specifies the response type. For this flow, the value must be code |
| client_id | Your Client ID |
| redirect_uri | The URL to which the server will redirect the browser after the user grants authorization. The authorization code will be available in the URL parameter code |
| state | An opaque value used by the client to maintain state between the request and callback |
Exchange Code for an Access Token
Sample Request
[POST] /oauth2/tokenHeader
Authorization: Basic [encoded string]
Content-Type: application/x-www-form-urlencoded
Body
grant_type: authorization_code
code: e160c27218d571fec79787f63d682663
Sample Response
[200] - OK
{
"accessToken": "ey123testaccesstokenforshippinglabel",
"expiresIn" : 300,
"refreshToken": "ey456testrefreshtokenforshippinglabel",
"refreshTokenExpiresIn" : 600,
"tokenType": "Bearer"
}
After receiving the authorization code, it can be exchanged for an access token. To do this, it is entered in the code field in the body of the request. Also, the grant type authorization_code must be set and as with Client Credentials, HTTP Basic Authorization is required.
Refresh Token
Sample Request
[POST] /oauth2/tokenHeader
Authorization: Basic [encoded string]
Content-Type: application/x-www-form-urlencoded
Body
grant_type: refresh_token
refresh_token: REFRESH_TOKEN
Sample Response
[200] - OK
{
"accessToken": "ey123testaccesstokenforshippinglabel",
"expiresIn" : 300,
"refreshToken": "ey456testrefreshtokenforshippinglabel",
"refreshTokenExpiresIn" : 600,
"tokenType": "Bearer"
}
Refresh tokens are long-lived authentication tokens that can be used to replace expired access tokens without having to use any of the above methods. Refresh tokens are issued when an access token is requested.
When requesting an access token with a refresh token, you must use the refresh_token grant type and specify the refresh token in the body of the request. As with Client Credentials, HTTP Basic Authorization is required.
Generate Access Token
Sample Response
[200] - OK
{
"accessToken": "ey123testaccesstokenforshippinglabel",
"expiresIn" : 300,
"refreshToken": "ey456testrefreshtokenforshippinglabel",
"refreshTokenExpiresIn" : 600,
"tokenType": "Bearer"
}
You can use this path to generate an Access Token using one of the methods mentioned (Client Credentials, Authorization Code or Refresh Token).
[POST] /oauth2/token
| Field | Type | Description |
|---|---|---|
| accessToken | string | Access token |
| expiresIn | integer | Specifies the expiration time of the access token in seconds |
| refreshToken | string | Refresh token |
| refreshTokenExpiresIn | integer | Specifies the expiration time of the refresh token in seconds |
| tokenType | string | Specifies the token type (default: Bearer) |
Parcels
Use /parcels to create, update, delete and retrieve predefined parcels.
Parcel Models
ParcelModel
Sample ParcelModel
{
"id": 1,
"name": "Small default",
"description": "Small parcel",
"weight": 2,
"length": 40,
"width": 30,
"height": 15,
"reference": "Parcel reference",
"customFields": {
"parcelClass": "X"
},
"isDefault": true
}
Contains information about the package size, description and reference needed to create a shipment.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | ID of the parcel. Read only |
| name | string | Yes | Display name of the parcel |
| description | string | Yes* | Parcel description Required for the carrier DHL_EXPRESS |
| weight | float | Yes | Weight in kg |
| length | float | Yes* | Length in cm Required for the carrier DHL_EXPRESS |
| width | float | Yes* | Width in cm Required for the carrier DHL_EXPRESS |
| height | float | Yes* | Height in cm Required for the carrier DHL_EXPRESS |
| reference | string | No | The reference is printed on the label |
| customFields | object | No | Contains specific values for a carrier.HERMES: You can specify the parcel class with parcelClass: XS,S,M,L,X,XL |
| isDefault | boolean | No | Specifies the default parcel |
List Parcels
Sample Request
[GET] /parcelsSample Response
[200] - OK
[
{
"id": 1,
"name": "Small default",
"description": "Small parcel",
"weight": 2,
"length": 40,
"width": 30,
"height": 15,
"isDefault": true
},
{
"id": 2,
"name": "Large",
"description": "Large parcel",
"weight": 20,
"length": 60,
"width": 40,
"height": 40,
}
]
[GET] /parcels
Returns all available user parcels.
Create Parcel
Sample Request
[POST] /parcels
{
"name": "Small default",
"description": "Small parcel",
"weight": 2,
"length": 40,
"width": 30,
"height": 15,
"isDefault": true
}
Sample Response
[201] - Created
{
"id": 1,
"name": "Small default",
"description": "Small parcel",
"weight": 2,
"length": 40,
"width": 30,
"height": 15,
"isDefault": true
}
[POST] /parcels
Creates a parcel.
Get Parcel
Sample Request
[GET] /parcels/1Sample Response
[200] - OK
{
"id": 1,
"name": "Small default",
"description": "Small parcel",
"weight": 2,
"length": 40,
"width": 30,
"height": 15,
"isDefault": true
}
[GET] /parcels/{parcelId}
Shows details for a parcel.
Update Parcel
Sample Request
[PUT] /parcels/1
{
"name": "Small default",
"description": "Small parcel",
"weight": 2,
"length": 40,
"width": 30,
"height": 15,
"isDefault": true
}
Sample Response
[204] - No Content
[PUT] /parcels/{parcelId}
Updates a parcel.
Delete Parcel
Sample Request
[DELETE] /parcels/1Sample Response
[204] - No Content
[DELETE] /parcels/{parcelId}
Deletes a parcel.
Addresses
Use /addresses to create, update, delete and retrieve shipment addresses.
Address Models
AddressModel
Sample AddressModel
{
"id": 1,
"company": "Shippinglabel",
"firstName": "Shipping",
"lastName": "Label",
"street": "Maarweg",
"streetNumber": "62",
"addressAddition": "Apartment 123",
"postalCode": "50933",
"city": "Köln",
"country": "DE",
"state": "NRW",
"phone": "22112345678",
"mail": "label@shippinglabel.de",
"vatNumber": "DE1234423432",
"addressType": "SHIPPING"
}
Contains address data, which is needed for the management of shipments.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | ID of the address. Read only |
| company | string | Yes* | company, firstName or lastName must be set.Required for the carrier DHL_EXPRESS |
| firstName | string | Yes* | company, firstName or lastName must be set.Required For the carrier DHL_EXPRESS |
| lastName | string | Yes* | company, firstName or lastName must be set |
| street | string | Yes* | Can be ignored if the service SHOP_DELIVERY and carrier DHL has been selected |
| streetNumber | string | Yes* | Can be ignored if the service SHOP_DELIVERY and carrier DHL has been selected |
| addressAddition | string | No | |
| postalCode | string | Yes | |
| city | string | Yes | |
| country | CountryCode | Yes | ISO 3166-1 alpha-2 code |
| state | string | No | |
| string | No | ||
| phone | string | Yes* | Required for the carrier DHL_EXPRESS |
| vatNumber | string | No | |
| addressType | AddressTypeCode | Yes | Specifies the address type |
AddressTypeCode
The AddressTypeCode is an enum and specifies the address type.
| Value | Description |
|---|---|
| SHIPPING | This value indicates that this is a shipping address |
| RETURN | This value indicates that this is an address for returns |
List Addresses
Sample Request
[GET] /addressesSample Response
[200] - OK
[
{
"id": 1,
"firstName": "Shipping",
"lastName": "Label",
"street": "Maarweg",
"streetNumber": "62",
"postalCode": "50933",
"city": "Köln",
"country": "DE",
"state": "NRW",
"phone": "22112345678",
"mail": "label@shippinglabel.de",
"addressType": "SHIPPING"
},
{
"id": 2,
"company": "Shippinglabel",
"street": "Maarweg",
"streetNumber": "62",
"postalCode": "50933",
"city": "Köln",
"country": "DE",
"state": "NRW",
"phone": "22112345678",
"mail": "label@shippinglabel.de",
"addressType": "RETURN"
}
]
[GET] /addresses
Returns all available addresses.
Create Address
Sample Request
[POST] /addresses
{
"firstName": "Shipping",
"lastName": "Label",
"street": "Maarweg",
"streetNumber": "62",
"postalCode": "50933",
"city": "Köln",
"country": "DE",
"state": "NRW",
"phone": "22112345678",
"mail": "label@shippinglabel.de",
"addressType": "SHIPPING"
}
Sample Response
[201] - Created
{
"id": 1,
"firstName": "Shipping",
"lastName": "Label",
"street": "Maarweg",
"streetNumber": "62",
"postalCode": "50933",
"city": "Köln",
"country": "DE",
"state": "NRW",
"phone": "22112345678",
"mail": "label@shippinglabel.de",
"addressType": "SHIPPING"
}
[POST] /addresses
Creates an address.
Get Address
Sample Request
[GET] /addresses/1Sample Response
[200] - OK
{
"id": 1,
"firstName": "Shipping",
"lastName": "Label",
"street": "Maarweg",
"streetNumber": "62",
"postalCode": "50933",
"city": "Köln",
"country": "DE",
"state": "NRW",
"phone": "22112345678",
"mail": "label@shippinglabel.de",
"addressType": "SHIPPING"
}
[GET] /addresses/{addressId}
Shows details of an address.
Update Address
Sample Request
[PUT] /addresses/1
{
"firstName": "Shipping",
"lastName": "Label",
"street": "Maarweg",
"streetNumber": "62",
"postalCode": "50933",
"city": "Köln",
"country": "DE",
"state": "NRW",
"phone": "22112345678",
"vatNumber": "DE123456789",
"mail": "label@shippinglabel.de",
"addressType": "SHIPPING"
}
Sample Response
[204] - No Content
[PUT] /addresses/{addressId}
Updates an address.
Delete Address
Sample Request
[DELETE] /addresses/1Sample Response
[204] - No Content
[DELETE] /addresses/{addressId}
Deletes an address.
Metadata
Use /metadata to retrieve data from carriers, products and label formats.
Metadata Models
CarrierMetadataModel
Sample CarrierMetadataModel
{
"carrierCode": "DP",
"name": "Deutsche Post",
"products": [
{
"product": "1",
"name": "Standardbrief",
"annotation": "Die Länge muss mindestens das 1,4-fache der Breite betragen.",
"price": 0.85,
"isInternational": true,
"minWeight": 1,
"maxWeight": 20,
"minLength": 140,
"maxLength": 235,
"minWidth": 90,
"maxWidth": 125,
"minHeight": 5,
"maxHeight": 5
}
],
"labelFormats": [
{
"labelFormat": "1",
"name": "DIN A4 Normalpapier",
"hasAddressField": true,
"labelCountX": 2,
"labelCountY": 5
}
]
}
Contains information about the package size, description and reference needed to create a shipment.
| Field | Type | Description |
|---|---|---|
| carrierCode | CarrierCode | Carrier |
| name | string | Display name of the carrier |
| products | ProductModel[] | Available products |
| labelFormats | LabelFormatModel[] | Available label formats |
ProductModel
Model that contains the data of a carrier product.
| Field | Type | Carrier | Description |
|---|---|---|---|
| product | string | DHL, DP, DPD, GLS, UPS, HERMES, POST_AT, DHL_EXPRESS |
Value for the selection of the product in the shipment |
| name | string | DHL, DP, DPD, GLS, UPS, HERMES, POST_AT, DHL_EXPRESS |
Display name of product |
| annotation | string | DP |
Additional details about the product |
| price | float | DP |
Specifies the cost of the product, which will be charged when a label is created |
| isInternational | boolean | DP |
Indicates whether the product is for international shipping |
| minWeight | integer | DP |
Min weight of the product |
| maxWeight | integer | DP |
Max weight of the product |
| minLength | integer | DP |
Min length of the product |
| maxLength | integer | DP |
Max length of the product |
| minWidth | integer | DP |
Min width of the product |
| maxWidth | integer | DP |
Max width of the product |
| minHeight | integer | DP |
Min height of the product |
| maxHeight | integer | DP |
Max height of the product |
LabelFormatModel
Model that contains the data of a carrier label format.
| Field | Type | Carrier | Description |
|---|---|---|---|
| labelFormat | string | DHL, DP, DPD, GLS, UPS, HERMES, POST_AT, DHL_EXPRESS |
Value, which is required for the selection in the shipment |
| name | string | DHL, DP, DPD, GLS, UPS, HERMES, POST_AT, DHL_EXPRESS |
Display name of the label format |
| hasAddressField | boolean | DP |
If true, the label shows an address field |
| labelCountX | integer | DP |
Number of labels (horizontal) |
| labelCountY | integer | DP |
Number of labels (vertical) |
List All
Sample Request
[GET] /metadata/carriersSample Response
[200] - OK
[
{
"carrierCode": "DHL",
"name": "DHL",
"products": [
{
"product": "V01PAK",
"name": "DE - Paket National"
}
],
"labelFormats": [
{
"labelFormat": "910-300-300",
"name": "Common Label Laserdruck (Bogen A5) 105x148mm (910-300-300)"
}
]
},
{
"carrierCode": "DP",
"name": "Deutsche Post",
"products": [
{
"product": "1",
"name": "Standardbrief",
"annotation": "Die Länge muss mindestens das 1,4-fache der Breite betragen.",
"price": 0.85,
"maxWeight": 20,
"minLength": 140,
"maxLength": 235,
"minWidth": 90,
"maxWidth": 125,
"maxHeight": 5
}
],
"labelFormats": [
{
"labelFormat": "1",
"name": "DIN A4 Normalpapier",
"hasAddressField": true,
"labelCountX": 2,
"labelCountY": 5
}
]
},
{
"carrierCode": "DPD",
"name": "DPD",
"products": [
{
"product": "Classic",
"name": "Classic"
}
],
"labelFormats": [
{
"labelFormat": "PDF_A4",
"name": "PDF_A4"
}
]
},
{
"carrierCode": "GLS",
"name": "GLS"
},
{
"carrierCode": "UPS",
"name": "UPS"
},
{
"carrierCode": "HERMES",
"name": "Hermes"
},
{
"carrierCode": "POST_AT",
"name": "Österreichische Post"
},
{
"carrierCode": "DHL_EXPRESS",
"name": "DHL Express"
}
]
[GET] /metadata/carriers
Returns all available carriers including metadata.
DHL Metadata
List DHL Products
Sample Request
[GET] /metadata/carriers/dhl/productsSample Response
[200] - OK
[
{
"product": "V01PAK",
"name": "DE - Paket National"
},
{
"product": "V01PRIO",
"name": "DE - Paket Prio"
}
]
[GET] /metadata/carriers/dhl/products
Returns all DHL products.
List DHL Label Formats
Sample Request
[GET] /metadata/carriers/dhl/formatsSample Response
[200] - OK
[
{
"labelFormat": "910-300-300",
"name": "Common Label Laserdruck (Bogen A5) 105x148mm (910-300-300)"
},
{
"labelFormat": "910-300-300-oz",
"name": "Common Label Laserdruck (Bogen A5) 105x148mm (910-300-300) ohne Zusatzetiketten"
}
]
[GET] /metadata/carriers/dhl/formats
Returns all DHL label formats.
DP Metadata
List DP Products
Sample Request
[GET] /metadata/carriers/dp/productsSample Response
[200] - OK
[
{
"product": "1",
"name": "Standardbrief",
"annotation": "Die Länge muss mindestens das 1,4-fache der Breite betragen.",
"price": 0.85,
"minWeight": 2,
"maxWeight": 20,
"minLength": 140,
"maxLength": 235,
"minWidth": 90,
"maxWidth": 125,
"minHeight": 1,
"maxHeight": 5
},
{
"product": "10001",
"name": "Standardbrief Intern. GK",
"annotation": "Die Länge muss mindestens das 1,4-fache der Breite betragen.",
"price": 1.1,
"isInternational": true,
"maxWeight": 20,
"minLength": 140,
"maxLength": 235,
"minWidth": 90,
"maxWidth": 125,
"maxHeight": 5
}
]
[GET] /metadata/carriers/dp/products
Returns all Deutsche Post (DP) products.
List DP Label Formats
Sample Request
[GET] /metadata/carriers/dp/formatsSample Response
[200] - OK
[
{
"labelFormat": "1",
"name": "DIN A4 Normalpapier",
"hasAddressField": true,
"labelCountX": 2,
"labelCountY": 5
},
{
"labelFormat": "2",
"name": "Brief B5 176 x 250",
"hasAddressField": true,
"labelCountX": 1,
"labelCountY": 1
}
]
[GET] /metadata/carriers/dp/formats
Returns all Deutsche Post (DP) label formats.
DPD Metadata
List DPD Products
Sample Request
[GET] /metadata/carriers/dpd/productsSample Response
[200] - OK
[
{
"product": "Classic",
"name": "Classic"
}
]
[GET] /metadata/carriers/dpd/products
Returns all DPD products.
List DPD Label Formats
Sample Request
[GET] /metadata/carriers/dpd/formatsSample Response
[200] - OK
[
{
"labelFormat": "PDF_A4",
"name": "PDF_A4"
},
{
"labelFormat": "PDF_A6",
"name": "PDF_A6"
}
]
[GET] /metadata/carriers/dpd/formats
Returns all DPD label formats.
GLS Metadata
List GLS Products
Sample Request
[GET] /metadata/carriers/gls/productsSample Response
[200] - OK
[
{
"product": "PARCEL",
"name": "Parcel"
},
{
"product": "EXPRESS",
"name": "Express"
}
]
[GET] /metadata/carriers/gls/products
Returns all GLS products.
List GLS Label Formats
Sample Request
[GET] /metadata/carriers/gls/formatsSample Response
[200] - OK
[
{
"labelFormat": "PDF",
"name": "PDF"
}
]
[GET] /metadata/carriers/gls/formats
Returns all GLS label formats.
HERMES Metadata
List Hermes Products
Sample Request
[GET] /metadata/carriers/hermes/productsSample Response
[200] - OK
[
{
"product": "PARCEL",
"name": "Parcel"
},
{
"product": "LARGE_ITEM",
"name": "Large item"
},
]
[GET] /metadata/carriers/hermes/products
Returns all Hermes products.
List Hermes Label Formats
Sample Request
[GET] /metadata/carriers/hermes/formatsSample Response
[200] - OK
[
{
"labelFormat": "PDF",
"name": "PDF"
}
]
[GET] /metadata/carriers/hermes/formats
Returns all Hermes label formats.
UPS Metadata
List UPS Products
Sample Request
[GET] /metadata/carriers/ups/productsSample Response
[200] - OK
[
{
"product": "11",
"name": "UPS Standard"
},
{
"product": "07",
"name": "UPS Express"
},
{
"product": "74",
"name": "UPS Express 12:00"
}
]
[GET] /metadata/carriers/ups/products
Returns all UPS products.
List UPS Label Formats
Sample Request
[GET] /metadata/carriers/ups/formatsSample Response
[200] - OK
[
{
"labelFormat": "PDF",
"name": "PDF"
}
]
[GET] /metadata/carriers/ups/formats
Returns all UPS label formats.
POST_AT Metadata
List POST_AT Products
Sample Request
[GET] /metadata/carriers/post-at/productsSample Response
[200] - OK
[
{
"product": "10",
"name": "Paket Österreich"
},
{
"product": "45",
"name": "Paket Premium International"
}
]
[GET] /metadata/carriers/post-at/products
Returns all Österreichische Post (POST_AT) products.
List POST_AT Label Formats
Sample Request
[GET] /metadata/carriers/post-at/formatsSample Response
[200] - OK
[
{
"labelFormat": "A5",
"name": "A5"
},
{
"labelFormat": "A4",
"name": "A4"
},
{
"labelFormat": "2xA5inA4",
"name": "2 x A5 auf A4"
}
]
[GET] /metadata/carriers/post-at/formats
Returns all Österreichische Post (POST_AT) label formats.
DHL_EXPRESS Metadata
List DHL_EXPRESS Products
Sample Request
[GET] /metadata/carriers/dhl-express/productsSample Response
[200] - OK
[
{
"product": "N",
"name": "EXPRESS DOMESTIC"
},
{
"product": "I",
"name": "EXPRESS DOMESTIC 9:00"
}
]
Sample Request
[GET] /metadata/carriers/dhl-express/formatsSample Response
[200] - OK
[
{
"labelFormat": "PDF",
"name": "PDF"
}
]
[GET] /metadata/carriers/dhl-express/products
Returns all DHL Express products.
List DHL_EXPRESS Label Formats
[GET] /metadata/carriers/dhl-express/formats
Returns all DHL Express label formats.
Carriers
Use /carriers to create, update, delete and retrieve shipment carriers.
Carrier Models
CarrierModel
Sample CarrierModel
{
"carrierCode": "DHL",
"name": "DHL",
"isDefault": true,
"created": "2022-11-03T16:35:11Z",
"username": "DHL_USERNAME",
"userSecret": "DHL_PASSWORD",
"product": "V01PAK",
"labelFormat": "910-300-300",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
],
"parameters": {
"ekp": "2222222222",
"products": [
{
"id": 1,
"product": "V01PAK",
"userParticipation": "01",
"preferredNeighbour": true,
"preferredLocation": true,
"visualCheckOfAge": true,
"namedPersonOnly": true,
"identCheck": true,
"preferredDay": true,
"noNeighbourDelivery": true,
"additionalInsurance": true,
"bulkyGoods": true,
"cashOnDelivery": true,
"packagingReturn": true,
"parcelOutletRouting": true
}
]
}
}
The CarrierModel contains all data for a shipping carrier. Depending on the selection of the carrier, the entries are specified.
| Field | Type | Required | Description |
|---|---|---|---|
| carrierCode | CarrierCode | Yes | Selected carrier |
| name | string | No | Display name of the carrier. Read only |
| isDefault | boolean | No | Specifies the default carrier |
| created | datetime | No | Read only |
| username | string | Yes* | Username of the carrier service Required in /carriers |
| userSecret | string | Yes* | Secret of the carrier service Required in /carriers |
| product | string | Yes* | Selected product Used in /carriers to set the default productRequired in /shipments if no default product has been created |
| labelFormat | string | Yes* | Selected label format Used in /carriers to set the default formatRequired in /shipments if no default format has been created |
| services | CarrierServiceModel[] | No | Additional carrier services Used in /shipments |
| parameters | object | Yes* | Contains specific values for the carrier. For example, the value EKP for DHL. Depending on the carrier, different values are expected |
CarrierCode
The CarrierCode is an enum and specifies the shipping carrier.
| Value | Description |
|---|---|
| DHL | This value indicates the carrier DHL |
| DP | This value indicates the carrier Deutsche Post |
| DPD | This value indicates the carrier DPD |
| GLS | This value indicates the carrier GLS |
| HERMES | This value indicates the carrier Hermes |
| UPS | This value indicates the carrier UPS |
| POST_AT | This value indicates the carrier Österreichische Post |
| DHL_EXPRESS | This value indicates the carrier DHL Express |
CarrierServiceModel
Used to add additional Services in a shipment. Depending on which service is selected, further information is mandatory.
| Field | Type | Required | Description |
|---|---|---|---|
| service | CarrierServiceCode | Yes | Selected carrier service |
| parameters | object | *Yes | Mandatory depending on carrier and service |
CarrierServiceCode
The CarrierServiceCode is an enum and determines additional services offered by the carrier.
| Value | Description |
|---|---|
| PREFERRED_NEIGHBOUR | Your customers can specify a neighbor in their immediate vicinity. If the recipient is not at home at the time of delivery, the delivery agent attempts to deliver to this designated neighbor. |
| PREFERRED_LOCATION | Your customers specify a drop-off location on their premises (such as the garage) at which the shipment can be deposited. |
| VISUAL_CHECK_OF_AGE | Special care must be taken when sending adult-only goods (for example alcohol, tobacco products or media with a 16/18 age rating). |
| NAMED_PERSON_ONLY | Gifts, health products or erotic items: Some purchases call for particular discretion. "Named Person Only" service is an easy and cost-effective way to make sure your parcels are only released to the recipient in person. |
| IDENT_CHECK | For certain product groups such as high-value goods, it is extremely important that they are delivered to your customers in person. Use the Ident-Check service to make sure your parcels are only released to the recipient in person - after proof of identity and (where relevant) age are checked and documented. |
| PREFERRED_DAY | Service preferred day. |
| NO_NEIGHBOUR_DELIVERY | Protect your customers' privacy and deactivate delivery to neighbors in the case of sensitive shipment content such as adult entertainment or hygiene articles. |
| ADDITIONAL_INSURANCE | Use supplementary transport insurance to protect parcels with valuable contents. AdditionalInsuranceAmount enables you to insure your parcels against damage and loss beyond the EUR 500 liability cap - up to a maximum amount of EUR 25,000. |
| BULKY_GOODS | The bulky goods service makes it possible for business customers to send merchandise that does not conform to standard dimensions or has an unusual format, special packaging features or uses certain packaging materials. Items are processed individually to ensure your parcels are transported quickly and securely to their recipient. |
| CASH_ON_DELIVERY | With the Cash on delivery service, the parcel is only handed over to the customer once the outstanding sum has been paid. This means that, as the sender, you can be certain that you will get your money. The cash on delivery sum received will be transferred to your specified account. |
| PACKAGING_RETURN | Service for package return. For packagingReturn you also have to book a return label. |
| PARCEL_OUTLET_ROUTING | Undeliverable domestic shipment can be forwarded and held at retail store. Details can be an email-address, if not set receiver email will be used. |
| FLEX_DELIVERY | A service to offer recipients different delivery options |
| NEXT_DAY | Guaranteed delivery in the next working day |
| SHOP_RETURN | Service so that the customer can return the package to the shop |
| SHOP_DELIVERY | Parcel delivery to the carrier shop |
| IDENT_PIN | The recipient only receives the parcel after successfully entering the PIN |
| SATURDAY_DELIVERY | Permits delivery on a Saturday |
| NO_SHIPMENT_REDIRECTION | No forwarding of the parcel to a shop if the parcel could not be delivered |
| NO_SHOP_AUTHORIZATION | Exclusion of authorization to pickup an order at a parcel shop |
| HAZARDOUS_GOODS | Dangerous goods declaration service |
| FRAGILE | Marks the parcel as fragile |
| PREMIUM | The parcel is prioritised and always transported by the fastest route |
| PICKUP | The parcel is collected by the carrier |
| SIGNATURE | Signature on delivery |
DHLProductModel
Contains important information of the user, which is necessary for the use of a DHL product. If the user does not have this information, he cannot use the products. In addition, he can specify which DHL services are activated for him. This model is used in the CarrierModel for the value parameters.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | Product ID. Ready only |
| product | string | Yes | Specifies the DHL product |
| userParticipation | string | Yes | This value is required for the DHL account number. The account number is composed of your EKP, the procedure and the participation |
| procedure | string | No | This value is required for the DHL account number. The account number is composed of your EKP, the procedure and the participation |
List Carriers
Sample Request
[GET] /carriersSample Response
[200] - OK
[
{
"carrierCode": "DHL",
"name": "DHL",
"isDefault": true,
"product": "V01PAK",
"labelFormat": "910-300-300",
"created": "2022-10-17T12:58:11Z"
},
{
"carrierCode": "DP",
"name": "Deutsche Post",
"product": "1",
"labelFormat": "1",
"created": "2022-11-03T16:35:11Z"
},
{
"carrierCode": "DPD",
"name": "DPD",
"product": "Classic",
"labelFormat": "PDF_A4",
"created": "2022-11-08T00:00:00Z"
},
{
"carrierCode": "GLS",
"name": "GLS",
"product": "PARCEL",
"labelFormat": "PDF",
"created": "2022-11-08T00:00:00Z"
},
{
"carrierCode": "HERMES",
"name": "Hermes",
"product": "PARCEL",
"labelFormat": "PDF",
"created": "2022-11-08T00:00:00Z"
},
{
"carrierCode": "UPS",
"name": "UPS",
"product": "11",
"labelFormat": "PDF",
"created": "2022-11-08T00:00:00Z"
},
{
"carrierCode": "POST_AT",
"name": "Österreichische Post",
"product": "10",
"labelFormat": "A5",
"created": "2022-11-08T00:00:00Z"
},
{
"carrierCode": "DHL_EXPRESS",
"name": "DHL Express",
"product": "T",
"labelFormat": "PDF",
"created": "2022-11-08T00:00:00Z"
}
]
[GET] /carriers
Returns all carriers created by the user.
Create Carrier
[POST] /carriers
Creates a carrier.
DHL
Sample DHL Request
[POST] /carriers
{
"carrierCode": "DHL",
"username": "DHL_USERNAME",
"userSecret": "DHL_PASSWORD",
"product": "V01PAK",
"labelFormat": "910-300-300",
"parameters": {
"ekp": "2222222222",
"senderReference": "ShipperWithLogo",
"products": [
{
"product": "V01PAK",
"userParticipation": "01"
}
]
}
}
Sample DP Request
[POST] /carriers
{
"carrierCode": "DP",
"username": "DP_USERNAME",
"userSecret": "DP_PASSWORD",
"product": "1",
"labelFormat": "1"
}
Sample DPD Request
[POST] /carriers
{
"carrierCode": "DPD",
"username": "DPD_USERNAME",
"userSecret": "DPD_PASSWORD",
"product": "Classic",
"labelFormat": "PDF_A4"
}
Sample GLS Request
[POST] /carriers
{
"carrierCode": "GLS",
"username": "GLS_USERNAME",
"userSecret": "GLS_PASSWORD",
"product": "PARCEL",
"labelFormat": "PDF",
"parameters": {
"contactId": "12345678",
"serviceUrl": "https://shipit-wbm-de01.gls-group.eu"
}
}
Sample POST_AT Request
[POST] /carriers
{
"carrierCode": "POST_AT",
"username": "POST_ORG_UNIT_ID",
"userSecret": "POST_ORG_UNIT_GUID",
"product": "10",
"labelFormat": "A5",
"parameters": {
"clientId": "POST_CLIENT_ID",
}
}
Sample DHL_EXPRESS Request
[POST] /carriers
{
"carrierCode": "DHL_EXPRESS",
"username": "DHL_EXPRESS_USER_NAME",
"userSecret": "DHL_EXPRESS_PASSWORD",
"product": "T",
"labelFormat": "PDF",
"parameters": {
"accountNumber": "123456789",
}
}
Sample Response
[201] - Created
{
"carrierCode": "DHL",
"name": "DPD",
"product": "V01PAK",
"labelFormat": "910-300-300",
"created": "2022-11-08T00:00:00Z"
}
In addition to the input fields of the CarrierModel, the following values can be set in the parameters field for the carrier DHL.
| Field | Type | Required | Description |
|---|---|---|---|
| ekp | string | Yes | The EKP is a DHL customer number and consists of 10 characters |
| senderReference | string | No | When entering the value, the sender address stored in DHL is selected. This value must correspond exactly to the "sender reference" value from DHL |
| products | DHLProductModel[] | No | Array of DHL service products |
DP
No further entries in the parameters field necessary.
DPD
No further entries in the parameters field necessary.
GLS
In addition to the input fields of the CarrierModel, the following values can be set in the parameters field for the carrier GLS.
| Field | Type | Required | Description |
|---|---|---|---|
| contactId | string | Yes | Your shipper ID, which is assigned by GLS |
| serviceUrl | string | Yes | Your assigned API endpoint from GLS |
Hermes
UPS
POST_AT
In addition to the input fields of the CarrierModel, the following values can be set in the parameters field for the carrier POST_AT.
| Field | Type | Required | Description |
|---|---|---|---|
| clientId | string | Yes | Your client id which you have received from the Post AT for the web service |
DHL_EXPRESS
In addition to the input fields of the CarrierModel, the following values can be set in the parameters field for the carrier DHL_EXPRESS.
| Field | Type | Required | Description |
|---|---|---|---|
| accountNumber | string | Yes | Your DHL Express account number |
Get Carrier
Sample Request
[GET] /carriers/DHLSample Response
[200] - OK
{
"carrierCode": "DHL",
"name": "DHL",
"created": "2022-10-17T12:58:11Z",
"product": "V01PAK",
"labelFormat": "910-300-300",
"paramters": {
"ekp": "2222222222",
"products": [
{
"id": 1,
"product": "V01PAK",
"userParticipation": "01"
}
]
}
}
Sample Request
[GET] /carriers/DPSample Response
[200] - OK
{
"id": 2,
"carrierCode": "DP",
"name": "Deutsche Post",
"product": "1",
"labelFormat": "1",
"created": "2022-11-03T16:35:11Z"
}
Sample Request
[GET] /carriers/DPDSample Response
[200] - OK
{
"carrierCode": "DPD",
"name": "DPD",
"product": "Classic",
"labelFormat": "PDF_A4",
"created": "2022-11-08T00:00:00Z"
}
Sample Request
[GET] /carriers/GLSSample Response
[200] - OK
{
"carrierCode": "GLS",
"name": "GLS",
"product": "PARCEL",
"labelFormat": "PDF",
"created": "2022-11-08T00:00:00Z",
"parameters": {
"contactId": "12345678",
"serviceUrl": "https://shipit-wbm-de01.gls-group.eu"
}
}
Sample Request
[GET] /carriers/HERMESSample Response
[200] - OK
{
"carrierCode": "HERMES",
"name": "Hermes",
"product": "PARCEL",
"labelFormat": "PDF",
"created": "2022-11-08T00:00:00Z"
}
Sample Request
[GET] /carriers/UPSSample Response
[200] - OK
{
"carrierCode": "UPS",
"name": "UPS",
"product": "11",
"labelFormat": "PDF",
"parameters": {
"accountNumber": "UPS_ACCOUNT_NUMBER"
},
"created": "2022-11-08T00:00:00Z"
}
Sample Request
[GET] /carriers/POST_ATSample Response
[200] - OK
{
"carrierCode": "POST_AT",
"name": "Österreichische Post",
"product": "10",
"labelFormat": "A5",
"parameters": {
"clientId": "POST_CLIENT_ID"
},
"created": "2022-11-08T00:00:00Z"
}
Sample Request
[GET] /carriers/DHL_EXPRESSSample Response
[200] - OK
{
"carrierCode": "DHL_EXPRESS",
"name": "DHL Express",
"product": "T",
"labelFormat": "PDF",
"parameters": {
"accountNumber": "123456789"
},
"created": "2022-11-08T00:00:00Z"
}
[GET] /carriers/{carrierCode}
Shows details of a carrier.
Update Carrier
Sample Request
[PUT] /carriers/DHL
{
"carrierCode": "DHL",
"name": "DHL",
"product": "V01PAK",
"labelFormat": "910-300-300",
"paramters": {
"ekp": "2222222222"
}
}
Sample Response
[204] - No Content
[PUT] /carriers/{carrierCode}
Updates a carrier.
Update Credentials
Sample Request
[PUT] /carriers/DHL/credentials
{
"username": "DHL_USERNAME",
"userSecret": "DHL_PASSWORD"
}
Sample Response
[204] - No Content
[PUT] /carriers/{carrierCode}/credentials
Updates the credentials of the carrier.
Verify Credentials
Sample Request
[POST] /carriers/DHL/verifySample Response
[204] - No Content
[POST] /carriers/{carrierCode}/verify
Verifies the credentials of the carrier.
Delete Carrier
Sample Request
[DELETE] /carriers/DHLSample Response
[204] - No Content
[DELETE] /carriers/{carrierCode}
Deletes a carrier.
Manage Products
Sample Request
[POST] /carriers/DHL/products
{
"product": "V01PAK",
"userParticipation": "01"
}
Sample Response
[201] - Created
{
"id": 1,
"product": "V01PAK",
"userParticipation": "01"
}
For the carrier DHL the products have to be created additionally, because the userParticipation is needed. Furthermore he can specify which DHL services are activated for him.
Create Product
[POST] /carriers/DHL/products
Creates a DHL product
Update Product
Sample Request
[PUT] /carriers/DHL/products/1
{
"product": "V01PAK",
"userParticipation": "01"
}
Sample Response
[204] - No Content
[PUT] /carriers/DHL/products/{productId}
Updates a DHL product
Delete Product
Sample Request
[DELETE] /carriers/DHL/products/1Sample Response
[204] - No Content
[DELETE] /carriers/DHL/products/{productId}
Deletes a DHL product
Carrier Services
The services that can be used when creating a shipping label for the selected carrier are listed below.
DHL Services
Sample services for DHL
[
{
"service": "PREFERRED_NEIGHBOUR",
"parameters" : {
"value": "Shippinglabel"
}
},
{
"service": "PREFERRED_LOCATION",
"parameters" : {
"value": "Garage"
}
},
{
"service": "VISUAL_CHECK_OF_AGE",
"parameters" : {
"value": "A18"
}
},
{
"service": "NAMED_PERSON_ONLY"
},
{
"service": "BULKY_GOODS"
},
{
"service": "IDENT_CHECK",
"parameters" : {
"firstName": "Name",
"lastName": "LastName",
"birthDate": "2022-08-08T00:00:00Z"
}
},
{
"service": "PREFERRED_DAY",
"parameters" : {
"preferredDay": "2022-08-08T00:00:00Z"
}
},
{
"service": "NO_NEIGHBOUR_DELIVERY"
},
{
"service": "ADDITIONAL_INSURANCE",
"parameters" : {
"amount": 25000
}
},
{
"service": "CASH_ON_DELIVERY",
"parameters" : {
"amount": 200.50,
"accountOwner": "Shippinglabel Name",
"bankName": "Shippinglabel Bank",
"iban": "DE11111111111111111111",
"bic": "COLSDE33XXX",
"reference": "Reference 1",
"reference2": "Reference 2"
}
},
{
"service": "PACKAGING_RETURN"
},
{
"service": "PARCEL_OUTLET_ROUTING",
"parameters" : {
"value": "label@shippinglabel.de"
}
},
{
"service": "SHOP_DELIVERY",
"parameters": {
"destinationType": "SHOP",
"destinationId": "540",
"postNumber": "12345678"
}
},
{
"service": "SHOP_DELIVERY",
"parameters": {
"destinationType": "LOCKER",
"destinationId": "110",
"postNumber": "12345678"
}
},
{
"service": "PREMIUM"
}
]
The following services can be offered via DHL
| Service | Parameters |
|---|---|
| PREFERRED_NEIGHBOUR | value: The name / address of your preferred neighbour |
| PREFERRED_LOCATION | value: The preferred delivery location for the parcel (e.g. garage) |
| VISUAL_CHECK_OF_AGE | value: Accepted values:A16 -> Minimum age of receiver needs to be 16 yearsA18 -> Minimum age of the receiver needs to be 18 years |
| NAMED_PERSON_ONLY | - |
| IDENT_CHECK | firstName: First namelastName: Last namebirthDate: Date of birth |
| PREFERRED_DAY | preferredDay: The requested day must be at least 2 and at most 6 working days after the shipment date |
| NO_NEIGHBOUR_DELIVERY | - |
| ADDITIONAL_INSURANCE | amount: The insurance amount. Possible values are 2500 and 25000 |
| BULKY_GOODS | - |
| CASH_ON_DELIVERY | amount: Money amount to be collectedaccountOwner: Name of bank account ownerbankName: Name of Bankiban: IBAN code of bank account bic: Bank-Information-Code (BankCCL) of bank accountreference: Purpose of bank informationreference2: Purpose of bank information |
| PACKAGING_RETURN | - |
| PARCEL_OUTLET_ROUTING | value: E-mail address for notification in case of non-deliverability |
| SHOP_DELIVERY | destinationType: Indicates whether the delivery is to a shop or a Packstation (Locker). Possible values are: SHOP or LOCKERdestinationId: Indicates the ID of the shop or the PackstationpostNumber: Is the official account number a private DHL customer gets upon registration |
| PREMIUM | - |
GLS Services
Sample services for GLS
[
{
"service": "FLEX_DELIVERY"
},
{
"service": "PREFERRED_LOCATION",
"parameters" : {
"location": "Garage"
}
},
{
"service": "NEXT_DAY"
},
{
"service": "SHOP_RETURN"
},
{
"service": "SATURDAY_DELIVERY"
},
{
"service": "IDENT_CHECK",
"parameters" : {
"firstName": "Name",
"lastName": "LastName",
"birthDate": "2022-08-08T00:00:00Z"
}
},
{
"service": "IDENT_PIN",
"parameters" : {
"pin": "1234",
"birthDate": "2022-08-08T00:00:00Z"
}
},
{
"service": "ADDITIONAL_INSURANCE",
"parameters" : {
"amount": 5000
}
},
{
"service": "CASH_ON_DELIVERY",
"parameters" : {
"amount": 200.50,
"reference": "Reference"
}
},
{
"service": "PREFERRED_DAY",
"parameters" : {
"preferredDay": "2022-08-08T00:00:00Z"
}
}
]
The following services can be offered via GLS
| Service | Parameters |
|---|---|
| FLEX_DELIVERY | The mail field in the receiver address must be set |
| PREFERRED_LOCATION | location: The preferred delivery location for the parcel (e.g. garage) |
| NEXT_DAY | - |
| SHOP_RETURN | - |
| IDENT_CHECK | firstName: First namelastName: Last namebirthDate: Date of birth |
| IDENT_PIN | pin: 4-digit PIN code that the consignee needs to enterbirthDate: Date of birth |
| ADDITIONAL_INSURANCE | amount: The insurance amount |
| CASH_ON_DELIVERY | amount: Money amount to be collectedreference: Purpose of bank information |
| SATURDAY_DELIVERY | This service can only be booked on a Friday with the product EXPRESS |
Hermes Services
Sample services for Hermes
[
{
"service": "BULKY_GOODS"
},
{
"service": "NEXT_DAY"
},
{
"service": "SHOP_DELIVERY"
},
{
"service": "NO_NEIGHBOUR_DELIVERY"
},
{
"service": "NO_SHIPMENT_REDIRECTION"
},
{
"service": "NO_SHOP_AUTHORIZATION"
},
{
"service": "HAZARDOUS_GOODS"
},
{
"service": "CASH_ON_DELIVERY",
"parameters" : {
"amount": 200.50
}
},
{
"service": "IDENT_CHECK",
"parameters" : {
"identId": "12345678",
"birthDate": "2022-08-08T00:00:00Z"
}
},
{
"service": "VISUAL_CHECK_OF_AGE",
"parameters" : {
"value": "18"
}
}
]
The following services can be offered via Hermes
| Service | Parameters |
|---|---|
| BULKY_GOODS | - |
| NEXT_DAY | - |
| SHOP_DELIVERY | The mail field in the receiver address must be set |
| NO_NEIGHBOUR_DELIVERY | - |
| CASH_ON_DELIVERY | amount: Money amount to be collected |
| IDENT_CHECK | identId: Document ID for the IdentServicebirthDate: Date of birth |
| VISUAL_CHECK_OF_AGE | value: Accepted values:16 -> Minimum age of receiver needs to be 16 years18 -> Minimum age of the receiver needs to be 18 |
| NO_SHIPMENT_REDIRECTION | - |
| NO_SHOP_AUTHORIZATION | - |
| HAZARDOUS_GOODS | - |
| PREFERRED_DAY | preferredDay: The requested day must be at least 2 and at most 6 working days after the shipment date |
UPS Services
Sample services for UPS
[
{
"service": "SATURDAY_DELIVERY"
},
{
"service": "CASH_ON_DELIVERY",
"parameters" : {
"amount": 200.50
}
}
]
The following services can be offered via UPS
| Service | Parameters |
|---|---|
| SATURDAY_DELIVERY | - |
| CASH_ON_DELIVERY | amount: Money amount to be collected |
POST_AT Services
Sample services for POST_AT
[
{
"service": "SATURDAY_DELIVERY"
},
{
"service": "CASH_ON_DELIVERY",
"parameters" : {
"amount": 200.50,
"accountOwner": "Shippinglabel Name",
"iban": "DE11111111111111111111",
"bic": "COLSDE33XXX",
"reference": "Reference 1",
}
},
{
"service": "PREFERRED_LOCATION",
"parameters" : {
"location": "Letterbox"
}
},
{
"service": "ADDITIONAL_INSURANCE",
"parameters" : {
"amount": 2500
}
},
{
"service": "NEXT_DAY"
},
{
"service": "HAZARDOUS_GOODS"
},
{
"service": "NAMED_PERSON_ONLY"
},
{
"service": "FRAGILE"
},
{
"service": "PREFERRED_NEIGHBOUR",
"parameters" : {
"name": "BWS IT GmbH",
"address": "Maarweg 62"
}
},
{
"service": "SHOP_DELIVERY",
"parameters": {
"shop": "10060310126964100"
}
}
]
The following services can be offered via POST_AT
| Service | Parameters |
|---|---|
| SATURDAY_DELIVERY | - |
| CASH_ON_DELIVERY | amount: Money amount to be collectedaccountOwner: Name of bank account owneriban: IBAN code of bank account bic: Bank-Information-Code (BankCCL) of bank accountreference: Purpose of bank information |
| PREFERRED_LOCATION | location: The preferred delivery location for the parcel (e.g. letterbox) |
| ADDITIONAL_INSURANCE | amount: The insurance amount |
| NEXT_DAY | - |
| HAZARDOUS_GOODS | - |
| PREFERRED_NEIGHBOUR | name: Neighbour's nameaddress: Street & number |
| NAMED_PERSON_ONLY | - |
| FRAGILE | - |
| SHOP_DELIVERY | shop: Shop id (Branchkey) |
DHL_EXPRESS Services
Sample services for DHL_EXPRESS
[
{
"service": "SATURDAY_DELIVERY"
},
{
"service": "HAZARDOUS_GOODS"
},
{
"service": "SIGNATURE"
},
{
"service": "VISUAL_CHECK_OF_AGE"
},
{
"service": "ADDITIONAL_INSURANCE",
"parameters" : {
"amount": 2500
}
},
{
"service": "PICKUP",
"parameters" : {
"pickupTime": "18:00",
"location": "reception",
"pickupAddress": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"phone": "+49221123456789",
"country": "DE"
}
}
}
]
The following services can be offered via DHL_EXPRESS
| Service | Parameters |
|---|---|
| SATURDAY_DELIVERY | - |
| HAZARDOUS_GOODS | - |
| SIGNATURE | - |
| VISUAL_CHECK_OF_AGE | - |
| ADDITIONAL_INSURANCE | amount: The insurance amount |
| PICKUP | pickupTime: The latest time the location premises is available to dispatch the DHL Express shipmentlocation: Provides information on where the package should be picked uppickupAddress: Pickup address vom type: AddressModel |
Shipments
Use /shipments to create, update, delete and retrieve shipments.
Shipment Models
ShipmentModel
Sample ShipmentModel
{
"id": 1,
"shipmentNumber": "1234567890",
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
]
},
"parcels": [
{
"description": "Shippinglabel package",
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "BWS",
"streetNumber": "49",
"street": "Featherstone Street",
"city": "London",
"postalCode": "EC1Y 8SY",
"mail": "label@bws-dev.com",
"country": "UK"
},
"customs": {
"exportType": "COMMERCIAL_GOODS",
"exportDescription": "Shirts",
"shippingCosts": {
"value": 3,
"currency": "EUR"
},
"invoiceNumber": "RE-123-456-789",
"hasElectronicExportNotification": false,
"senderCustomsReference": "DE123456789",
"receiverCustomsReference": "GB123456789",
"items": [
{
"description": "T-Shirt",
"quantity": 5,
"hsCode": "123456",
"originCountry": "DE",
"unitValue": {
"value": 2.35,
"currency": "EUR"
},
"weight": 0.5
}
]
},
"reference": "ID-12345678",
"shipmentDate": "2022-12-15T15:13:00Z",
"created": "2022-12-15T20:59:12.816578Z",
"label": "JVBERi0xLjQKJeLjz9MKNSAwIG9iago8PC9GaWx0ZXIvRm....",
"status": {
"code": 400,
"error": {
"message": "Error sample"
}
}
}
The ShipmentModel contains all data for creating a shipping label.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | ID of the shipment. Read only |
| shipmentNumber | string | No | The shipment number returned for the carrier. Can be used for tracking |
| carrier | CarrierModel | Yes | Carrier details and services |
| parcels | ParcelModel[] | Yes | Array of Parcels. Currently only one parcel may be specified |
| sender | AddressModel | Yes* | Sender address Required if no address of type SHIPPING exists |
| receiver | AddressModel | Yes | Receiver address |
| customs | CustomsModel | No | Contains customs documents and information. Available for the carrier DHL and DHL_EXPRESS |
| reference | string | No | Reference for API requests. Will not be transmitted to the carrier |
| shipmentDate | datetime | No | If not set, today's date is automatically selected |
| created | datetime | No | Created time. Read only |
| label | string | No | Base64-encoded shipping label in PDF format |
| status | ShipmentStatusModel | No | Contains information about the result when creating multiple shipments or when using our queue function |
CustomsModel
Contains information on customs documents for international shipping.
| Field | Type | Required | Description |
|---|---|---|---|
| exportType | ExportTypeCode | Yes | The category type of the item in the package |
| exportDescription | string | Yes* | Description of the export type when exportType is OTHER |
| shippingCosts | AmountModel | Yes* | Specifies the shipping costs Required for the carrier DHL |
| invoiceNumber | string | Yes* | The invoice number of the package Required for the carrier DHL_EXPRESS |
| invoiceDate | string | Yes* | The invoice date in format YYYY-MM-DDRequired for the carrier DHL_EXPRESS |
| hasElectronicExportNotification | boolean | No | Indicator confirming whether an electronic record for the package has been made Available for the carrier DHL |
| senderCustomsReference | string | No | Reference from the sender (EORI number or VAT number) Available for the carrier DHL |
| receiverCustomsReference | string | No | Reference from the receiver (EORI number or VAT number) Available for the carrier DHL |
| items | CustomsItemModel[] | Yes | Contains the custom items |
CustomsItemModel
Contains information on the customs items.
| Field | Type | Required | Description |
|---|---|---|---|
| description | string | Yes | Description of the item |
| quantity | integer | Yes | Quantity of the item in the package |
| hsCode | string | No | The Harmonized Code referring to the item |
| originCountry | CountryCode | No | Where the item was manufactured |
| unitValue | AmountModel | Yes | Specifies the price of a single item |
| weight | float | Yes | Weight in kg of a single item |
ExportTypeCode
The ExportTypeCode is an enum and specifies the category for the customs item.
| Value | Description |
|---|---|
| COMMERCIAL_GOODS | This value indicates that the shipment contains commercial goods |
| RETURN_OF_GOODS | This value indicates the return of goods |
| DOCUMENT | This value indicates that the shipment contains documents |
| SAMPLE | This value indicates that the shipment includes samples |
| PRESENT | This value indicates the presence of a gift or present in the shipment. |
| OTHER | This value covers all other situations not falling into the above categories |
AmountModel
An AmountModel is used to represent monetary amounts.
| Field | Type | Required | Description |
|---|---|---|---|
| value | float | Yes | Numeric amount |
| currency | CurrencyCode | Yes | Specifies the currency code |
ShipmentStatusModel
Contains information about the result when creating multiple shipments.
| Field | Type | Description |
|---|---|---|
| code | integer (HTTP Status Code) | Returns the result of the shipment.201: Successfully created400: Check error for details |
| error | ErrorModel | Contains the error message, for a code above or equal 400 |
List Shipments
Sample Request
[GET] /shipments?page=0&page_size=2&order=ascSample Response
[200] - OKHeader
X-Total-Count: 1234
Body
[
{
"id": 1,
"shipmentNumber": "222201010023532108",
"carrier": {
"carrierCode": "DHL"
},
"parcels": [
{
"reference": "Parcel reference"
}
],
"receiver": {
"company": "Shippinglabel",
"street": "Maarweg",
"streetNumber": "62"
},
"reference": "API-INTERN-1",
"created": "2022-12-07T10:12:49Z"
},
{
"id": 2,
"shipmentNumber": "A0027BBE300000005261",
"carrier": {
"carrierCode": "DP"
},
"parcels": [
{
"reference": "Parcel reference"
}
],
"receiver": {
"firstName": "Shipping",
"lastName": "Label",
"street": "Maarweg",
"streetNumber": "62"
},
"reference": "API-INTERN-2",
"created": "2022-12-15T20:53:29Z"
}
]
[GET] /shipments
Returns all available shipments.
Query parameters
| Field | Description |
|---|---|
| page_size | The maximum number of shipments to return in the response. Must be an integer between 0 and 10000. Default: 10000 |
| page | The page number to retrieve for the list of shipments. For example page = 0 and page_size = 10 return the first 10 shipments. page = 1 and page_size=10 return the next shipments (11-20). Default: 0 |
| order | Specifies the order of shipments. Available values are asc or desc. Default: asc |
Validate Shipment
Sample Request
[POST] /shipments/validate
{
"carrier": {
"carrierCode": "DPD",
"product": "Classic",
"labelFormat": "PDF_A4"
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"shipmentDate": "2022-12-12T15:13:00Z",
"reference": "ID-12345678"
}
Sample Response
[204] - No Content
[POST] /shipments/validate
Validates a shipment.
Create Shipment
Sample Request
[POST] /shipments
{
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK",
"labelFormat": "910-300-300",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
]
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"shipmentDate": "2022-12-12T15:13:00Z",
"reference": "ID-12345678"
}
Sample Response
[201] - Created
{
"id": 1,
"shipmentNumber": "1234567890",
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK",
"labelFormat": "910-300-300",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
]
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"reference": "ID-12345678",
"shipmentDate": "2022-12-15T15:13:00Z",
"created": "2022-12-15T20:59:12.816578Z",
"label": "JVBERi0xLjQKJeLjz9MKNSAwIG9iago8PC9GaWx0ZXIvRm...."
}
[POST] /shipments
Creates a shipment.
Get Shipment
Sample Request
[GET] /shipments/1Sample Response
[200] - OK
{
"id": 1,
"shipmentNumber": "1234567890",
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK"
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"reference": "ID-12345678",
"shipmentDate": "2022-12-15T15:13:00Z",
"created": "2022-12-15T20:59:12.816578Z",
"label": "JVBERi0xLjQKJeLjz9MKNSAwIG9iago8PC9GaWx0ZXIvRm...."
}
[GET] /shipments/{shipmentId}
Shows details of a shipments.
Delete Shipment
Sample Request
[DELETE] /shipments/1Sample Response
[204] - No Content
[DELETE] /shipments/{shipmentId}
Deletes a shipment.
Create Shipments
Sample Request
[POST] /shipments
[
{
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK"
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"shipmentDate": "2022-12-12T15:13:00Z",
"reference": "ID-1"
},
{
"carrier": {
"carrierCode": "DP",
"product": "1"
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"reference": "ID-2"
}
]
Sample Response
[207] - Multi-Status
[
{
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK"
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"reference": "ID-1",
"shipmentDate": "2022-12-06T15:13:00Z",
"status": {
"code": 400,
"error": {
"message": "Bitte geben Sie ein gültiges Sendungsdatum an.",
"code": "DHL"
}
}
},
{
"id": 4,
"shipmentNumber": "A1121324341421421421",
"carrier": {
"carrierCode": "DP",
"product": "1",
"dpOrderId": "11111111"
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"reference": "ID-2",
"created": "2022-12-15T21:11:14.275372Z",
"status": {
"code": 201
}
}
]
[POST] /shipments/bulk
Creates multiple shipments.
Get Labels
Sample Request
[GET] /shipments/labels/1,2,3,4Sample Response
[200] - OKHeader
Content-Type: application/pdf
Content-Disposition: attachment;filename=sl_label_1.pdf
Content-Length: 1232134
Body
%PDF-1.4
%//&//$
5 0 obj
<</Filter/FlateDecode/Length 51>>stream
xX1+34r
as2P057Z31VSI//r...
[GET] /shipments/labels/{id1,id2,...,idn}
Returns one or more labels in PDF format.
Export CSV
Sample Request
[GET] /shipments/csv/1,2,3,4?profileId=1&compress=falseSample Response
[200] - OKHeader
Content-Type: text/csv
Content-Disposition: attachment;filename=sl_file.csv:
Content-Length: 1232134
Body
Carrier;Weight
DHL;5
HERMES;1
Sample Request
[GET] /shipments/csv/1,2,3,4?profileId=1&compress=trueSample Response
[200] - OKHeader
Content-Type: application/zip
Content-Disposition: attachment;filename=sl_file.zip:
Content-Length: 1232134
Body
ZIP_BINARY_DATA
[GET] /shipments/csv/{id1,id2,...,idn}
Export the selected shipments as a CSV file.
Query parameters
| Field | Description |
|---|---|
| profileId | Specifies the CSV profile. If not specified, the default profile is automatically selected. |
| compress | Set to true to receive the CSV data in a compressed ZIP file format, enhancing the efficiency of data transfer and storage. |
Queue
Use /shipments/queue to create, update, delete and retrieve shipments in the queue. Shipment in the queue can be prepared and then bundled and processed via a shipment job.
Queue Models
QueueItemModel
Sample QueueItemModel
{
"id": 1,
"shipment": {
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
]
},
"parcels": [
{
"description": "Shippinglabel package",
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "BWS",
"streetNumber": "49",
"street": "Featherstone Street",
"city": "London",
"postalCode": "EC1Y 8SY",
"mail": "label@bws-dev.com",
"country": "UK"
},
"customs": {
"exportType": "COMMERCIAL_GOODS",
"exportDescription": "Shirts",
"shippingCosts": {
"value": 3,
"currency": "EUR"
},
"invoiceNumber": "RE-123-456-789",
"hasElectronicExportNotification": false,
"senderCustomsReference": "DE123456789",
"receiverCustomsReference": "GB123456789",
"items": [
{
"description": "T-Shirt",
"quantity": 5,
"hsCode": "123456",
"originCountry": "DE",
"unitValue": {
"value": 2.35,
"currency": "EUR"
},
"weight": 0.5
}
]
},
"reference": "ID-12345678",
"shipmentDate": "2022-12-15T15:13:00Z",
"created": "2022-12-15T20:59:12.816578Z",
"status": {
"code": 201
}
},
"created": "2023-12-05T11:58:15Z"
}
The QueueItemModel defines the structure of a data object in a queuing system, specifying details such as the unique ID, associated shipment data, processing time, and creation time of each queue item.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | ID of the queue item. Read only |
| shipment | ShipmentModel | Yes | The shipment data of the queue item |
| processTime | datetime | No | The process time of the shipment. Read only |
| created | datetime | No | Created time. Read only |
List Queue Items
Sample Request
[GET] /shipments/queueSample Response
[200] - OK
[
{
"id": 1,
"shipment": {
"carrier": {
"carrierCode": "DHL",
"product": "WRONG_PRODUCT"
},
"receiver": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
},
"reference": "456",
"status": {
"code": 400,
"error": {
"message": "The selected product could not be found"
}
}
},
"created": "2023-12-05T11:58:15Z"
},
{
"id": 2,
"shipment": {
"id": 2519,
"carrier": {
"carrierCode": "DHL"
},
"receiver": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
},
"reference": "ID-12345678",
"status": {
"code": 201
}
},
"created": "2023-12-07T11:00:15Z"
}
]
[GET] /shipments/queue
Returns all available shipments in the queue.
Create Queue Item
Sample Request
[POST] /shipments/queue
{
"shipment": {
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
]
},
"parcels": [
{
"description": "Shippinglabel package",
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "BWS",
"streetNumber": "49",
"street": "Featherstone Street",
"city": "London",
"postalCode": "EC1Y 8SY",
"mail": "label@bws-dev.com",
"country": "UK"
},
"reference": "ID-12345678"
}
}
Sample Response
[201] - Created
{
"id": 1,
"shipment": {
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
]
},
"parcels": [
{
"description": "Shippinglabel package",
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "BWS",
"streetNumber": "49",
"street": "Featherstone Street",
"city": "London",
"postalCode": "EC1Y 8SY",
"mail": "label@bws-dev.com",
"country": "UK"
},
"reference": "ID-12345678"
},
"created": "2023-12-07T11:00:15Z"
}
[POST] /shipments/queue
Creates a shipment to the queue.
Get Queue Item
Sample Request
[GET] /shipments/queue/1Sample Response
[200] - OK
{
"id": 2,
"shipment": {
"id": 1,
"shipmentNumber": "1234567890",
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK"
},
"parcels": [
{
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "dewabit",
"streetNumber": "62",
"street": "Maarweg ",
"city": "Köln",
"postalCode": "50933",
"mail": "label@bws-dev.com",
"country": "DE"
},
"reference": "ID-12345678",
"shipmentDate": "2022-12-15T15:13:00Z",
"created": "2022-12-15T20:59:12.816578Z",
"status": {
"code": 201
}
},
"created": "2023-12-07T11:00:15Z"
}
[GET] /shipments/queue/{itemId}
Shows details for a shipment from the queue.
Update Queue Item
Sample Request
[PUT] /shipments/queue/1
{
"shipment": {
"carrier": {
"carrierCode": "DHL",
"product": "V01PAK",
"services": [
{
"service": "PREFERRED_LOCATION",
"parameters": {
"value": "Garage"
}
}
]
},
"parcels": [
{
"description": "Shippinglabel package",
"weight": 1.0,
"reference": "4711"
}
],
"sender": {
"company": "Shippinglabel",
"firstName": "first name",
"lastName": "last name",
"streetNumber": "62",
"street": "Maarweg",
"city": "Köln",
"postalCode": "50933",
"mail": "label@shippinglabel.de",
"country": "DE"
},
"receiver": {
"company": "BWS",
"streetNumber": "49",
"street": "Featherstone Street",
"city": "London",
"postalCode": "EC1Y 8SY",
"mail": "label@bws-dev.com",
"country": "UK"
},
"reference": "ID-12345678"
}
}
Sample Response
[204] - No Content
[PUT] /shipments/queue/{itemId}
Updates a shipment from the queue.
Delete Queue Item
Sample Request
[DELETE] /shipments/queue/1Sample Response
[204] - No Content
[DELETE] /shipments/queue/{itemId}
Deletes a shipment from the queue.
Upload CSV
Sample Request
[POST] /shipments/queue?profileId=1Header
Content-Type: text/csv
Body
Carrier;Weight
DHL;5
HERMES_WRONG;1
Sample Response
[201] - Created
[
{
"id": 1,
"shipment": {
"carrier": {
"code": "DHL"
},
"parcels": [
{
"weight": 5
}
],
},
"created": "2023-12-11T12:32:21.4932488Z"
},
{
"id": 2,
"shipment": {
"carrier": {
"code": "HERMES_WRONG"
},
"parcels": [
{
"weight": 1
}
],
"status": {
"code": 400,
"error": {
"message": "Der angegebene Dienstleister konnte nicht gefunden werden",
"code": "VALIDATE_CARRIER_CODE_NOT_FOUND"
}
}
},
"created": "2023-12-11T12:32:21.4932488Z"
}
]
[POST] /shipments/queue/csv
Use this endpoint to import a CSV file to transfer shipments to the queue.
Query parameters
| Field | Description |
|---|---|
| profileId | Specifies the CSV profile. If not specified, the default profile is automatically selected. |
Request Body
You can either specify the CSV directly as text in the HTTP request body or as form data (multipart/form-data). Use the key csvFile to attach you CSV file.
CSV
Use /csv/profiles for efficient management of CSV profiles, enabling the upload of CSV files to facilitate the creation of shipments within the queue.
CSV Models
CSVProfileModel
Sample CSVProfileModel
{
"id": 1,
"name": "CSV",
"delimiter": ";",
"dateFormat": "YYYY-MM-DDThh:mm:ssZ",
"encoding": "UTF-8",
"mapping": [
{
"headerField": "ShipmentNumber",
"valueId": "ShipmentNumber"
},
{
"headerField": "Carrier",
"valueId": "Carrier.Code"
}
],
"isDefault": true,
"created": "2023-12-02T12:50:29Z"
}
The CSVProfileModel defines the structure and settings for CSV file processing in shipment management, encompassing fields like profile ID, name, delimiter, date format, encoding, mapping to shipment data, default status, and creation time.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | ID of the CSV profile. Read only |
| name | string | Yes | Specified name of the profile |
| delimiter | string | Yes | Indicates the character used as a separator in the CSV file to distinguish between individual values. Please note that only a single character can be specified for this purpose. |
| dateFormat | CSVDateFormat | Yes | Specifies the date format |
| encoding | EncodingCode | Yes | Specifies the coding format |
| mapping | CSVMappingModel[] | Yes | Specifies the assignment of the CSV file with the shipment data |
| isDefault | boolean | No | Sets the default CSV profile |
| created | datetime | No | Created time. Read only |
EncodingCode
The EncodingCode is an enum and specifies the coding format for the CSV file.
| Value | Description |
|---|---|
| UTF-8 | A widely used character encoding that supports a large number of characters from various languages. It's compatible with ASCII and is commonly used for its versatility in handling diverse text data. |
| ISO-8859-1 | Also known as Latin-1, this encoding supports Western European languages. It's useful for texts containing characters from languages like English, French, German, and Spanish. |
| UTF-8-BOM | A variant of UTF-8 that includes a Byte Order Mark (BOM). This marker at the start of the text stream can help some software determine the file's encoding, language, and endianness. |
CSVMappingModel
The CSVMappingModel correlates CSV file header values with corresponding shipment data, ensuring accurate mapping and data integration.
| Field | Type | Required | Description |
|---|---|---|---|
| headerField | string | Yes | The header name of your CSV field |
| valueId | MappingCode | Yes | Specifies the shipment data |
MappingCode
The MappingCode is an enum and specifies the value in the shipment.
| Value | Description |
|---|---|
| ShipmentNumber | Tracking number of the shipment |
| ShipmentDate | Date of the shipment |
| Carrier.Code | Code of the carrier |
| Carrier.Product | Product type of the carrier |
| Carrier.Format | Format used by the carrier |
| Parcels.[0].Weight | Weight of the first parcel |
| Parcels.[0].Height | Height of the first parcel |
| Parcels.[0].Length | Length of the first parcel |
| Parcels.[0].Width | Width of the first parcel |
| Parcels.[0].Description | Description of the first parcel |
| Parcels.[0].Reference | Reference of the first parcel |
| Receiver.Company | Company name of the receiver |
| Receiver.FirstName | First name of the receiver |
| Receiver.LastName | Last name of the receiver |
| Receiver.Street | Street address of the receiver |
| Receiver.StreetNumber | Street number of the receiver |
| Receiver.AddressAddition | Additional address details of the receiver |
| Receiver.PostalCode | Postal code of the receiver |
| Receiver.City | City of the receiver |
| Receiver.Mail | Email address of the receiver |
| Receiver.Phone | Phone number of the receiver |
| Receiver.Country | Country of the receiver |
| Sender.Company | Company name of the sender |
| Sender.FirstName | First name of the sender |
| Sender.LastName | Last name of the sender |
| Sender.Street | Street address of the sender |
| Sender.StreetNumber | Street number of the sender |
| Sender.AddressAddition | Additional address details of the sender |
| Sender.PostalCode | Postal code of the sender |
| Sender.City | City of the sender |
| Sender.Mail | Email address of the sender |
| Sender.Phone | Phone number of the sender |
| Sender.Country | Country of the sender |
| Reference | Reference for the API request |
CSVDateFormat
You can use the CSVDateFormat to specify the date format to be used in the CSV file. The following values are available.
| Value | Description |
|---|---|
| YYYY | Year |
| MM | Month |
| DD | Day |
| hh | Hours |
| mm | Minutes |
| ss | Seconds |
| Z | Timezone |
For example, the date format YYYY-MM-DDThh:mm:ssZ is converted to 2023-12-02T12:50:29Z.
List CSV Profiles
Sample Request
[GET] /csv/profilesSample Response
[200] - OK
[
{
"id": 1,
"name": "CSV-Profile",
"isDefault": true,
"created": "2023-12-02T12:50:29Z"
},
{
"id": 2,
"name": "dewabit_Export",
"created": "2023-12-10T12:04:27Z"
}
]
[GET] /csv/profiles
Returns all available CSV profiles.
Create CSV Profile
Sample Request
[POST] /csv/profiles
{
"name": "CSV-Profile",
"delimiter": ";",
"dateFormat": "YYYY-MM-DD",
"encoding": "UTF-8",
"mapping": [
{
"headerField": "ShipmentNumber",
"valueId": "ShipmentNumber"
},
{
"headerField": "Carrier",
"valueId": "Carrier.Code"
}
],
"isDefault": true
}
Sample Response
[201] - Created
{
"id": 1,
"name": "CSV-Profile",
"delimiter": ";",
"dateFormat": "YYYY-MM-DD",
"encoding": "UTF-8",
"mapping": [
{
"headerField": "ShipmentNumber",
"valueId": "ShipmentNumber"
},
{
"headerField": "Carrier",
"valueId": "Carrier.Code"
}
],
"isDefault": true,
"created": "2023-12-10T12:04:27Z"
}
[POST] /csv/profiles
Creates a CSV profile.
Get CSV Profile
Sample Request
[GET] /csv/profiles/1Sample Response
[200] - OK
{
"id": 1,
"name": "CSV-Profile",
"delimiter": ";",
"dateFormat": "YYYY-MM-DD",
"encoding": "UTF-8",
"mapping": [
{
"headerField": "ShipmentNumber",
"valueId": "ShipmentNumber"
},
{
"headerField": "Carrier",
"valueId": "Carrier.Code"
}
],
"isDefault": true,
"created": "2023-12-10T12:04:27Z"
}
[GET] /csv/profiles/{profileId}
Shows details for a CSV profile.
Update CSV Profile
Sample Request
[PUT] /csv/profiles/1
{
"name": "CSV-Profile",
"delimiter": ",",
"dateFormat": "YYYY-MM-DD",
"encoding": "UTF-8",
"mapping": [
{
"headerField": "ShipmentNumber",
"valueId": "ShipmentNumber"
},
{
"headerField": "Carrier",
"valueId": "Carrier.Code"
},
{
"headerField": "APIReference",
"valueId": "Reference"
}
],
"isDefault": true
}
Sample Response
[204] - No Content
[PUT] /csv/profiles/{profileId}
Updates a CSV profile.
Delete CSV Profile
Sample Request
[DELETE] /csv/profiles/1Sample Response
[204] - No Content
[DELETE] /csv/profiles/{profileId}
Deletes a CSV profile.
Jobs (BETA)
Use the /shipment/jobs endpoint to effectively process selected shipments from the queue and create shipping labels.
Job Models
JobModel
Sample JobModel
{
"id": 1,
"status": "COMPLETED",
"executionTime": "2023-12-08T10:00:00Z",
"lastUpdate": "2023-12-08T10:21:42Z",
"created": "2023-12-06T07:24:05Z",
"queueItems": [
{
"id": 1,
"shipment": {
"carrier": {
"carrierCode": "DHL"
},
"reference": "456",
"status": {
"code": 201
}
},
"processTime": "2023-12-07T10:09:51Z",
"created": "2023-12-05T11:58:15Z"
}
],
"totalQueueItems": 1,
"processedQueueItems": 1
}
The JobModel defines the structure for creating a job that processes shipments from the queue to create shipping labels.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | No | ID of the job. Read only |
| status | JobStatusCode | No | Specified the job status. Read only |
| executionTime | datetime | No | If specified, the job is executed and processed at the specified time. Otherwise, the job is executed directly |
| lastUpdate | datetime | No | A timestamp indicating the last update of the job. Read only |
| created | datetime | No | Created time. Read only |
| queueItems | QueueItemModel[] | Yes | Specifies the coding format |
| totalQueueItems | integer | No | Specifies the number of items to be processed from the job. Read only |
| processedQueueItems | integer | No | Specifies the number of items already processed from the job. Read only |
JobStatusCode
The JobStatusCode is an enum and specifies the status of the job.
| Value | Description |
|---|---|
| CREATED | Specifies that the job has been created |
| RUNNING | Indicates that the job is currently running |
| CANCELLED | Specifies that the job was cancelled |
| COMPLETED | Specifies that the job has been completed |
List Jobs
Sample Request
[GET] /shipments/jobsSample Response
[200] - OK
[
{
"id": 1,
"status": "CANCELLED",
"lastUpdate": "2023-12-07T10:14:50Z",
"created": "2023-12-05T11:58:20Z",
"totalQueueItems": 1
},
{
"id": 2,
"status": "COMPLETED",
"lastUpdate": "2023-12-07T10:21:42Z",
"created": "2023-12-06T07:24:05Z",
"totalQueueItems": 1,
"processedQueueItems": 1
}
]
[GET] /shipments/jobs
Returns all available jobs.
Create Job
Sample Request
[POST] /shipments/jobs
{
"queueItems": [
{
"id": 1
},
{
"id": 2
}
],
"executionTime": "2023-12-24T12:00:00Z"
}
Sample Response
[201] - Created
{
"id": 1,
"status": "CREATED",
"executionTime": "2023-12-24T12:00:00Z",
"lastUpdate": "2023-12-11T12:24:14.9435367Z",
"created": "2023-12-11T12:24:14.9435367Z",
"queueItems": [
{
"id": 1
},
{
"id": 2
}
],
"totalQueueItems": 2
}
[POST] /shipments/jobs
Creates a job.
Get Job
Sample Request
[GET] /shipments/jobs/1Sample Response
[200] - OK
{
"id": 1,
"status": "COMPLETED",
"executionTime": "2023-12-20T15:04:05Z",
"lastUpdate": "2023-12-11T12:24:18Z",
"created": "2023-12-11T12:24:15Z",
"queueItems": [
{
"id": 2,
"shipment": {
"id": 1,
"carrier": {
"carrierCode": "DHL"
},
"reference": "ID-12345678",
"status": {
"code": 201
}
},
"created": "2023-12-07T11:00:15Z"
},
{
"id": 3,
"shipment": {
"carrier": {
"carrierCode": "DHL"
},
"status": {
"code": 400,
"error": {
"message": "Das ausgewählte Produkt konnte nicht gefunden werden"
}
}
},
"created": "2023-12-10T12:06:23Z"
}
],
"totalQueueItems": 2
}
[GET] /shipments/jobs/{jobId}
Shows details about a job.
Cancel Job
Sample Request
[POST] /shipments/jobs/1/cancelSample Response
[204] - No Content
[POST] /shipments/jobs/{jobId}/cancel
Cancels a job.
User
Use /user to retrieve data from a user.
User Models
UserModel
Sample UserModel
{
"email": "label@shippinglabel.de",
"language": "DE",
"balance": 149.1074,
"address": {
"company": "BWS",
"firstName": "Dennis",
"lastName": "W"
},
"shipmentStats": {
"total": 4,
"currentYear": 4,
"currentMonth": 4,
"today": 1
}
}
Contains information about the user.
| Field | Type | Required | Description |
|---|---|---|---|
| string | No | Mail address of the user | |
| language | LanguageCode | No | Specifies the preferred language |
| balance | float | No | Balance of the user |
| address | AddressModel | No | Includes the variables firstName and lastName |
| shipmentStats | StatsModel | No | Statistics about the number of created shipments |
LanguageCode
The LanguageCode is an enum and specifies the preferred language
| Value | Description |
|---|---|
| EN | English language |
| DE | German language |
StatsModel
Indicates statistical information
| Field | Type | Required | Description |
|---|---|---|---|
| total | int | No | Total number |
| currentYear | int | No | Total number of the year |
| currentMonth | int | No | Total number of the month |
| today | int | No | Total from today |
Get User
Sample Request
[GET] /userSample Response
[200] - OK
{
"email": "label@shippinglabel.de",
"language": "DE",
"balance": 149.1074,
"address": {
"firstName": "Dennis",
"lastName": "W"
},
"shipmentStats": {
"total": 4,
"currentYear": 4,
"currentMonth": 4,
"today": 1
}
}
[GET] /user
Returns information about the user.
Changelog
1.5.0
General
- Add carrier DHL_EXPRESS
- The output of error messages has been improved
- Add service
PREMIUMfor the carrier DHL - Add service
SIGNATURE - Add service
PICKUP
CSV
- CSV profiles can be created and managed
- Shipments can be imported into the queue via CSV
- Shipments can be exported as a CSV file
Queue Items
- Shipments can be created and managed in a queue
Jobs
- Create jobs for processing shipments in the queue
1.4.0
General
- Customs information has been added for the carrier
DHL - Postman Collection: Sample requests for each carrier to create labels, including the existing services, have been added
1.3.0
General
- Add carrier POST_AT
- Add new carrier service
FRAGILE - Add service
NO_SHIPMENT_REDIRECTIONfor the carrier HERMES - Add service
NO_SHOP_AUTHORIZATIONfor the carrier HERMES - Add service
HAZARDOUS_GOODSfor the carrier HERMES
1.2.0
General
- Add carrier Hermes
- Add carrier UPS
- Add field
AddressAdditionin the AddressModel - Removed update request for
/shipments - The creation of multiple shipments has been limited to a maximum of 30 shipments / request
- Migration to DHL API V2. Requests, such as sending multiple shipments, should now be faster
- Add service
SHOP_DELIVERYfor the carrier DHL - Add field
senderReferencefor the carrier DHL
1.1.1
General
1.1.0
General
- Add carrier GLS
1.0.0
General
- Release of the Shippinglabel API