1 Allgemein

1.1 Änderungshistorie

Rev. Nr	Datum	Firma	Mitarbeiter	Beschreibung der Änderung
1.0	14.04.2021	Ecovium	LK	Erstellung des Dokuments

1.2 Einführung

Nachfolgend finden Sie eine Beschreibung der Schnittstelle, die der Shiptrack.com-Dienst bietet. Alle Abfragen erfolgen über HTTPS. Die in der folgenden Tabelle aufgeführten HTTP-Header müssen mit den aufgeführten Werten festgelegt werden. Der Anrufer wird an der Schnittstelle mit einem zuvor definierten Benutzernamen und Passwort unter Verwendung der HTTP Basic Authentication Method (siehe RFC2617) authentifiziert.

HTTP-Header	Value
Content-Type	application/json

1.3 Fehlerbehandlung

Um sicherzustellen, dass der Aufrufer eine aussagekräftige Fehlermeldung erhält, wenn ein Fehler in der Schnittstelle auftritt, sendet die Schnittstelle eine Antwort mit einem HTTP-Statuscode, der den Fehler darstellt. Außerdem wird eine Nachricht zurückgegeben, die detaillierte Informationen zum Fehler enthält. Beispielsweise wird für den Fehler, dass die Kundenummer, welche in der URL verwendet wurde, nicht existiert, der HTTP-Statuscode 404 zurückgegeben. Die entsprechende Detailfehlermeldung sieht so aus:

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

Der Standardfehlercode für undefinierte Fehler ist der HTTP-Statuscode 505. Nachfolgend finden Sie eine Tabelle mit allen bekannten Shiptrack.com-spezifischen Fehlercodes.

HTTP-Status	Beschreibung
400	Ein Pflichtfeld wurde nicht angegeben
404	Ressource nicht gefunden. Wird zurückgesendet, wenn eine Client-ID nicht existiert oder wenn für den angeforderten Spediteur keine Rücksendekonfiguration gefunden werden kann.
409	VLOG-Schnittstellenfehler
500	Bad request

2 Anfrage per POST

2.1 Aufbau der Url

Um ein Retourenlabel anzufordern, muss die Endpunkt-URL die folgende Struktur haben:

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

2.2 Request body

Field name	Data type	Description	Required
frachtfuehrer	string	Frachtführerkürzel, mit dem die Retoure transportiert werden soll (siehe Punkt 4)	X
send_referenznr_01	string	Referenz 1 auf Sendungsebene	X
send_referenznr_02	string	Referenz 2 auf Sendungsebene
send_referenznr_03	string	Referenz 3 auf Sendungsebene
send_referenznr_04	string	Referenz 4 auf Sendungsebene
send_referenznr_05	string	Referenz 5 auf Sendungsebene
sender	sender	Adressdaten des Absenders	X
receiver	receiver	Adressdaten des Empfängers	X
package	package[]	Array vom Paketen
settings	settings	Settings Objekt

2.2.1 Sender

Field name	Data type	Description	Required
abs_adr_01	string	Erste Adresszeile des Absenders	X
abs_adr_02	string	Zweite Adresszeile des Absenders
abs_adr_03	string	Dritte Adresszeile des Absenders	X
abs_strasse	string	Straße des Absenders	X
abs_hnr	string	Hausnummer des Absenders	X
abs_plz	string	Postleitzahl des Absenders	X
abs_ort	string	Ort des Absenders	X
abs_land_kurz	string	Zweistelliger Ländercode des Absenders (ISO 3166-1 Alpha 2)	X
abs_mail	string	Mailadresse des Absenders
abs_tel	string	Telefonnummer des Absenders

2.2.2 Receiver

Field name	Data type	Description	Required
return_adr_01	string	Empfänger Firmenname	X
return_adr_02	string	Erste Adresszeile des Empfängers
return_adr_03	string	Zweite Adresszeile des Empfängers
return_adr_04	string	Titel des Empfängers
return_adr_05	string	Kontakt des Empfängers
return_anrede	string	Anrede des Empfängers
return_fax	string	Faxnummer des Empfängers
return_hnr	string	Hausnummer des Empfängers	X
return_iso	string	Empfänger-ISO-Code (numerisch), z. „276“ für Deutschland
return_kdnr	string	Kundennummer des Empfängers
return_id	string	Empfängercode (DHL Parcel Empfänger-ID, kann anstelle einer Absenderadresse übermittelt werden)	X (only for DHL shipments)
return_land	string	Ländername des Empfängers
return_land_kurz	string	Ländercode des Empfängers (alphanumerisch), z. "DE" für Deutschland	X
return_mail	string	E-Mail-Adresse des Empfängers
return_mobile	string	Mobiltelefonnummer des Empfängers
return_ort	string	Empfängerstadt	X
return_plz	string	Postleitzahl des Empfängers	X
return_postfach	string	Postfach des Empfängers
return_region	string	Empfängerregion
return_staat	string	Empfängerzustand
return_strasse	string	Empfängerstraße	X
return_tel	string	Telefonnummer des Empfängers

2.2.3 Package

Bitte beachten Sie, dass aktuell pro Retouren-Anfrage nur ein Label zurückgemeldet wird, auch wenn mehrere Pakete in der Anfrage enthalten sind. Wenn Sie also zwei Label benötigen, bitte zwei separate Anfragen schicken.

Field name	Data type	Description
send_referenznr_06	string	Referenz 6 auf Paketebene
send_referenznr_07	string	Referenz 7 auf Paketebene
send_referenznr_08	string	Referenz 8 auf Paketebene
send_referenznr_09	string	Referenz 9 auf Paketebene
send_referenznr_10	string	Referenz 10 auf Paketebene
send_gewichteinzel	string	Paketgewicht in kg
send_hoehe	string	Pakethöhe in cm
send_laenge	string	Paketlänge in cm
send_breite	string	Paketbreite in cm

2.2.4 Settings

Field name	Data type	Description	Required
create_shipment	Boolean	Wenn auf „true“ gesetzt, erstellt der Shiptrack-Service die Retourensendung
test	Boolean	Wenn auf true gesetzt, wird nur ein Testetikett erstellt. Die Validierung der Pflichtfelder ist davon nicht betroffen

2.3 Beispiele

2.3.1 DPD

2.3.1.1 Nur Pflichtfelder

{
	"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 Alle möglichen Felder

Click here to expand

{
	"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 Nur Pflichtfelder

{
	"frachtfuehrer": "DHL",
	"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_id": "deu"
	}
}

2.3.2.2 Alle möglichen Felder

Click to expand

{
	"frachtfuehrer": "DHL",
	"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_id": "deu"
	},
	"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
	}
}

3 Antwort

Wenn die Erstellung des Retourenlabels erfolgreich war, erhalten Sie das Etikett als base64-codierten String in der Antwort.

Field name	Data type	Description
send_referenznr_01	string	Referenz 1 auf Sendungsebene (aus Ihrer Anfrage)
shipment_tracking_id	string	Carrier TrackingID generiert über VLOG
return_label	string	Label als Base64-String

{
	"send_refernznr_01": "123456",
	"shipment_tracking_id": "123456789",
	"return_label": "iVBORw0KGgoAAAANSUhEUgAABJ0AAAbs...."
}

4 Frachtführerkürzel

Nachfolgend werden alle derzeit bekannten Frachtführerkürzel aufgelistet.

Shortcut	Carrier name
ABCLOGISTIK	ABC-Logistik GmbH
AMM	AMM Spedition
APAEXPRESS	DHL Parcel Austria
DPDAT	DPD Österreich / Prime Time
ASR	DB Schenker Österreich
ATP	Österreichische Post (AG)
BDP	Belgische Post (Bpost)
BLM	Bleckmann Niederlande
BOOS	Boos Logistik Service
BRT	Bartolini Italien
BURSPED	Bursped Speditions-G.m.b.H. & Co.
CAM	Camion Transport AG.
CES	City Express Serbia
CEV	CEVA Logistics
CHC	Swiss Post Cargo
CHE	Schweizer Post Express
CHP	Schweizer Post (CH)
CHPFREIGHT	Schweizer Post Fracht (CH)
COLISSIMO	Colissimo FR
COU	Coureon Logistics GmbH
CPL	Planzer Transport AG (Schweiz)
CTT	Correios de Portugal
CQP	Quickpac
DAO	Dansk Avis Omdeling
DCH	Dachser Intelligent Logistics
DHC	DHL Parcel Connect
DHL	DHL Paket
DHB	DHL Benelux
DHLEXPRESS	DHL Express
DHM	DHL Home Delivery 2-Mann-Handling
DHN	DHL Parcel Netherland
DKS	Logwin Holding Aschaffenburg GmbH
DPB	Deutsche Post AG (DV-Freimachung von Briefsendungen)
DPD	Dynamic Parcel Distribution - Geopost
DPDUK	Dynamic Parcel Distribution United Kingdom
DSV	DSV Air & Sea Germany GmbH
DSW	SwipBox
DTL	Deutsche Textil Logistik
DZS	DHL Freight (Danzas)
EAK	Azkar, Dachser Spanien
ECB	Camel24
ECS	Correos ES . Public
EMS	Emons Spedition GmbH
ESR	SEUR (E)
ETS	TIP SA Spain
FCP	Colis Privé
FCR	Chronopost Frankreich
FDE	Delivengo
FDX	FedEx
FMR	Mondial Relay Distribution FR
FNT	TNT Express Frankreich
FPD	DPD Frankreich
FRP	La Poste (FR)
FSR	DB Schenker Frankreich
GEFCO	Groupages express de Franche-Comté
GEL	Express Logistik
GLS	General Logistic Systems
GLSFR	General Logistic Systems France
GLSHU	General Logistic Systems Hungary
GLSRO	General Logistic Systems Romania
GLSSL	General Logistic Systems Slovenia
GLSCRO	General Logistic Systems Croatia
GON	General Overnight (GO!) Express & Logistics
GPC	Geis Parcel Slovakia CZ
GRM	Royal Mail
GSM	The Delivery Group (Secured Mail)
GWW	Gebrüder Weiss Gesellschaft m.b.H.
HEPPNER	Spedition Heppner
HES	Hermes 2 Man Handling
HHUBER	Heinz Huber Internationale Spedition
HVS	Hermes Versand Service
HWL	Hellmann Worldwide Logistics
IDSGEIS	Hans Geis
IDSKUN	Kühne & Nagel
IDSSCHMID	Spedition Andreas Schmid Logistik AG
INNIGHTBENELUX	Nox Nachtexpress NL, BE
INNIGHTDEAT	Nox Nachtexpress DE, AT
INS	Intersoft
JENTSCH	Jentsch Logistik
KIA	Kiala
KNUBBEN	Spedition Knubben (OSL)
KIESSLING	Spedition Kiessling
KLEINE	Spedition Kleine
KOEHA	Köster & Hapke Internationale Spedition
LAGERMAX	Spedition Lagermax
NBR	Bring Parcel Norway
NCT	Neutral Carrier Tracking (by ecovium)
NELLENQUACK	Nellen & Quack Spedition und Logistik
NGL	GLS Netherlands
NOERPEL	Spedition Noerpel
NOLIMIT	No Limits Trans GmbH Polen
NOTHEGGER	Nothegger Transport Logistik GmbH
NSE	Night Star Express
NTGLOGISTICS	NTG Logistik
NTS	National Transport Service GmbH
OETJEN	Spedition Oetjen
ONTIME	Ontime Logistics
OPL	Opal
PDK	Post Denmark
PHL	DHL Parcel Poland
PON	Post Nord
QUEHENBERGER	Quehenberger Logistics
PIP	Inpost Poland
PIT	Poste Italiane
PKT	Packeta
PLP	Poczta Polska
PPL	Professional Parcel Logistic
RABEN	Raben Group
RHE	Rhenus Logistics
RKL	Rieck Logistik-Gruppe
RUEDINGER	Rüdinger Spedition
SCHAEF	Schäflein Spedition GmbH
SDG	7Days Logistics
SEVENSENDERS	Seven Senders GmbH
SKP	Slovenská pošta
SKR	Schenker Deutschland AG
STRECK	Streck Transport Spedition
SWL	SkyNet Worldwide Express
TCS	TCS Sterne
THIJS	Thijs Logistiek
TMD	Transmed Transportmanagement
TML	TM Logistik & Services
TNT	Thomas Nationwide Transport
TOF	Trans-o-flex
TPG	Post (Niederlande)
TPO	Česká pošta
TRANSLAND	Transland Spedition GmbH
UFP	FOXPOST
UKM	DHL Parcel UK Mail
UPS	United Parcel Service
WLS	WLS Spedition GmbH
YDL	Yodel Delivery Network Limited
ZOBEL	Gebr. Zobel & Co. Speditions GmbH

Return REST API - deutsch