Versions Compared

Old Version 3

changes.mady.by.user Michael.Landwehr

Saved on

compared with

New Version Current

changes.mady.by.user Michael.Landwehr

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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:

Code Block
languagejson
{
    "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

Table of Contents
minLevel1
maxLevel7

2   Anfrage per POST

2.1   Aufbau der Url

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

Info

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

Note

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

Required

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

Code Block
languagejson
{
	"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

Expand
titleClick here to expand
Code Block
languagejson
{
	"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

Code Block
languagejson
{
	"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

Expand
titleClick to expand
Code Block
{
	"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

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

4   Frachtführerkürzel

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

Include Page
Freight carrier shortcuts
Freight carrier shortcuts