1 General

1.1 Introduction

Below is a description of the interface that the Shiptrack.com service offers. All queries are made via HTTPS. The HTTP headers listed in the table below must be set with the values listed. The caller is authenticated at the interface using a previously defined username and password using the HTTP Basic Authentication Method (refer to RFC2617).

HTTP-Header	Value
Content-Type	application/json

1.3 Error handling

To ensure that the caller receives a meaningful error message when an error occurs in the interface, the interface sends a response with an HTTP status code that represents the error. In addition, a message is returned that contains detailed information about the error. For example, for the error that a customer is specified as parameter that does not exist, the HTTP status code 404 is returned. The corresponding detail error message looks like this:

{
    "error": {
        "code": "404",
        "message": "The requested client with Id '<Client-Id>' does not exist."
    }
}

The default error code for undefined errors is HTTP status code 505. Below is a table with all known Shiptrack.com specific error codes.

HTTP-Status	Description
400	A mandatory field was not provided
404	Resource not found. Will be returned in a clientId does not exist or if no return-configuration can be found for the requested carrier.
409	VLOG interface error
500	Bad request

1 1 General
- 1.1 1.1 Introduction
- 1.2 1.3 Error handling
2 2 Request via POST
- 2.1 2.1 Endpoint path structure
- 2.2 2.2 Request body
  - 2.2.1 2.2.1 Sender
  - 2.2.2 2.2.2 Receiver
  - 2.2.3 2.2.3 Package
  - 2.2.4 2.2.4 Settings
- 2.3 2.3 Examples
  - 2.3.1 2.3.1 DPD
    - 2.3.1.1 2.3.1.1 Only mandatory fields
    - 2.3.1.2 2.3.1.2 All possible fields
  - 2.3.2 2.3.2 DHL
    - 2.3.2.1 2.3.2.1 Only mandatory fields
    - 2.3.2.2 2.3.2.2 All possible fields
3 3 Response
4 4 Carrier abbreviation

2 Request via POST

2.1 Endpoint path structure

To request a return label, the endpoint url must have the following structure:

https://service.shiptrack.com/clients/<Client-Id>/return

2.2 Request body

Field name	Data type	Description	Required
frachtfuehrer	string	Carrier short name, with whom the inbound shipment should be transported (see 4 Carrier Abbreviation)	X
send_referenznr_01	string	Reference 1 on shipment level	X
send_referenznr_02	string	Reference 2 on shipment level
send_referenznr_03	string	Reference 3 on shipment level
send_referenznr_04	string	Reference 4 on shipment level
send_referenznr_05	string	Reference 5 on shipment level
sender	sender	Sender address data	X
receiver	receiver	Receiver address data	X
package	package[]	Array of packages
settings	settings	Settings object

2.2.1 Sender

Field name	Data type	Description	Required
abs_adr_01	string	First address line of the sender	X
abs_adr_02	string	Second address line of the sender
abs_adr_03	string	Third address line of the sender	X
abs_strasse	string	Sender street	X
abs_hnr	string	Sender house number	X
abs_plz	string	Sender zip code	X
abs_ort	string	Sender city	X
abs_land_kurz	string	Sender double-digit country code (ISO 3166-1 alpha 2)	X
abs_mail	string	Mail address of the sender
abs_tel	string	Phone number of the sender

2.2.2 Receiver

Field name	Data type	Description	Required
return_adr_01	string	Receiver company name	X
return_adr_02	string	Receiver first name
return_adr_03	string	Receiver last name
return_adr_04	string	Receiver title
return_adr_05	string	Receiver contact person
return_anrede	string	Receiver form of address (Dr./Mr./Mrs. etc.)
return_fax	string	Receiver fax
return_hnr	string	Receiver house number	X
return_iso	string	Receiver iso code (numeric), e.g. "276" for Germany
return_kdnr	string	Receiver customer number
return_id	string	Receiver code (DHL Parcel receiver ID, can be transferred instead of a return address)	X (only for DHL shipments)
return_land	string	Receiver country name
return_land_kurz	string	Receiver country code (alphanumeric), e.g. "DE" for Germany	X
return_mail	string	Receiver email address
return_mobile	string	Receiver mobile phone number
return_ort	string	Receiver city	X
return_plz	string	Receiver zip code	X
return_postfach	string	Receiver post office box
return_region	string	Receiver region
return_staat	string	Receiver state
return_strasse	string	Receiver street	X
return_tel	string	Receiver phone number

2.2.3 Package

Please note that currently only one label is reported per return request, even if several packages are included in the request. So if you need two labels, please send two separate requests.

Field name	Data type	Description
send_referenznr_06	string	Reference 6 on package level
send_referenznr_07	string	Reference 7 on package level
send_referenznr_08	string	Reference 8 on package level
send_referenznr_09	string	Reference 9 on package level
send_referenznr_10	string	Reference 10 on package level
send_gewichteinzel	string	Package weight in kg
send_hoehe	string	Package height in cm
send_laenge	string	Package length in cm
send_breite	string	Package width in cm

2.2.4 Settings

Field name	Data type	Description	Required
create_shipment	Boolean	If set to true, the shiptrack service creates the inbound shipment
test	Boolean	If set to true, only a test label is produced. The validation of the mandatory fields is not affected

2.3 Examples

2.3.1 DPD

2.3.1.1 Only mandatory fields

{
	"frachtfuehrer": "DPD",
	"send_referenznr_01": "123456",
	"sender": {
		"abs_adr_01": "Max Mustermann",
		"abs_strasse": "Tüschenbroicher Str.",
		"abs_hnr": "11",
		"abs_plz": "41844",
		"abs_ort": "Wegberg",
		"abs_land_kurz": "DE"
	},
	"receiver": {
		"return_adr_01": "Ecovium Demounternehmen",
		"return_hnr": "3",
		"return_land_kurz": "DE",
		"return_ort": "Neustadt am Rübenberge",
		"return_plz": "31535",
		"return_strasse": "Justus-von-Liebig-Str."
	}
}

2.3.1.2 All possible fields

{
	"frachtfuehrer": "DPD",
	"send_referenznr_01": "123456",
	"send_referenznr_02": "456789",
	"send_referenznr_03": "ABC-123",
	"send_referenznr_04": "Test",
	"send_referenznr_05": "00110001",
	"sender": {
		"abs_adr_01": "Musterfirma",
		"abs_adr_02": "3. OG",
		"abs_adr_03": "z.H. Max Mustermann",
		"abs_strasse": "Tüschenbroicher Str.",
		"abs_hnr": "11",
		"abs_plz": "41844",
		"abs_ort": "Wegberg",
		"abs_land_kurz": "DE",
		"abs_mail": "max@muster.de",
		"abs_tel": "0123456789"
	},
	"receiver": {
		"return_adr_01": "Ecovium Demounternehmen",
		"return_adr_02": "Rainer",
		"return_adr_03": "Zufall",
		"return_adr_04": "Buchhaltung",
		"return_adr_05": "Hr. Zufall",
		"return_anrede": "Mr.",
		"return_fax": "0123456789",
		"return_hnr": "3",
		"return_iso": "276",
		"return_kdnr": "123456789",
		"return_land": "Deutschland",
		"return_land_kurz": "DE",
		"return_mail": "helpdesk@mhp-net.de",
		"return_mobile": "0321654987",
		"return_ort": "Neustadt am Rübenberge",
		"return_plz": "31535",
		"return_region": "Region Hannover",
		"return_staat": "Niedersachsen",
		"return_strasse": "Justus-von-Liebig-Str.",
		"return_tel": "49 5032 9656 0"
	},
	"package": [
		{
			"send_referenznr_06": "36201961660329005965",
			"send_referenznr_07": "IR3WRAK7UT",
			"send_referenznr_08": "260701237113069",
			"send_referenznr_09": "020766183535359",
			"send_referenznr_10": "281663369004144",
			"send_gewichteinzel": "10",
			"send_hoehe": "5",
			"send_laenge": "15",
			"send_breite": "10"
		}
	],
	"settings": {
		"create_shipment": false,
		"test": true
	}
}

2.3.2 DHL

2.3.2.1 Only mandatory fields

2.3.2.2 All possible fields

3 Response

If the creation of the return label was successful, you will receive the label as a base64 encoded string in the response.

Field name	Data type	Description
send_referenznr_01	string	Reference 1 on shipment level (from your request)
shipment_tracking_id	string	Carrier TrackingID generated via VLOG
return_label	string	Return label as base64 string

4 Carrier abbreviation

All currently known carrier abbreviations are listed below.

Interfaces

REST API - Returns