1. Was ist Logistik-Tracking?

Logistik-Tracking ist ein wichtiges Tool zur Überwachung des Transportprozesses, mit dem Benutzer Transportrouten, Ausnahmen und wichtige Statusänderungen verfolgen können.

Zu den Hauptfunktionen der Tracking-API gehören:

• Automatische Überwachung: Sobald eine Tracking-Nummer registriert ist, wird sie automatisch überwacht und Abfrageergebnisse werden ohne zusätzliche Kontingente weitergegeben. Hinweis: Diese Funktion arbeitet asynchron und ist nicht für Front-End-Webseiten, Miniprogramme oder Apps geeignet.
• Kapazität auf Unternehmensebene: Die Tracking-API bietet Datenverarbeitungsfunktionen auf Unternehmensebene und ermöglicht die Registrierung von 400.000 Tracking-Nummern pro Stunde.
• Integration globaler Spediteure: Die Tracking-API unterstützt die Integration mit über 2000 globalen Spediteuren und bietet einheitliche Anrufmethoden, Antwortstrukturen und Statusknoten, wodurch die Entwicklungskosten effektiv gesenkt werden.
• Best Practices für die Datenverwaltung: Es wird dringend empfohlen, Logistikinformationen auf Ihrem Server oder Speicherdienst zu speichern.
• Eindeutige Datenidentifikation: Jedes Datenelement wird durch die Kombination aus Tracking-Nummer + Spediteur eindeutig identifiziert.
• Übersicht über den Betriebsablauf: Der Betriebsablauf umfasst Sendungsabonnement > regelmäßiges Tracking > Prüfung von Änderungen des Sendungsstatus > Ergebnis-Pushing.

2. Vor der Verwendung

2.1 Erstellen Sie ein 17TRACK-Konto

API-Konten sind nicht umgebungsspezifisch. Es wird empfohlen, separate API-Konten für Test- und Produktionsumgebungen zu verwalten, um umgebungsspezifische Konfigurationen und Datenintegrität sicherzustellen. Bitte besuchen Sie 17TRACK-Api, um ein Konto zu eröffnen.

 

2.2 Sendungsnummer und Spediteurcode

• Besuchen Sie 17TRACK, um die Verfügbarkeit der vorbereiteten Sendungsnummer zu überprüfen.
• Besuchen Sie Spediteure, um die unterstützten Spediteure zu überprüfen.
• Was ist ein Spediteurcode? Der Spediteurcode ist eine Parameterspezifikation, die speziell für die Verwendung mit der Tracking-API entwickelt wurde. Weitere Informationen finden Sie unter Spediteurcode. Der Spediteurcode für USPS lautet beispielsweise 21051.

3. Integrationshandbuch

3.1 Integration von Systemen anderer Anbieter

Zielbenutzer

Die folgende Integrationsanleitung richtet sich speziell an führende Logistikanbieter, Händler, Dienstleister und Systemanbieter, die über eigene proprietäre Systeme und IT-Entwicklungsteams verfügen.

Schritt 1

(Für einen schnellen Test können Sie das Pushen über https://webhook.site überprüfen)

1. Stellen Sie sicher, dass Ihr Server vom öffentlichen Netzwerk aus zugänglich ist, um Tracking-Updates zu erhalten. Dies kann eine Anpassung Ihrer Firewall- und Gateway-Konfigurationen erfordern, um eingehende Verbindungen von den Servern von 17TRACK zuzulassen.
2. Entwickeln Sie eine Schnittstelle, die Tracking-Informationen empfangen kann, und stellen Sie sicher, dass sie mehrere gleichzeitige Anfragen verarbeiten kann. Es ist ratsam, Daten mithilfe unabhängiger Dienste wie Warteschlangen oder Caches zu verteilen, um die Skalierbarkeit zu verbessern.
3. Implementieren Sie eine Signaturüberprüfung in Ihrer Informationsempfangsschnittstelle, um die Authentizität und Integrität der von 17TRACK empfangenen Daten zu bestätigen. Weitere Informationen finden Sie unter „Überprüfen der Signatur“. Beispielcode finden Sie unten:

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

    String src = requestText + "/" + key;

    MessageDigest md = MessageDigest.getInstance("SHA-256");
    byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

    BigInteger number = new BigInteger(1, hash);
    StringBuilder hexString = new StringBuilder(number.toString(16));
    while (hexString.length() < 64) {
        hexString.insert(0, '0');
    }
    return hexString.toString();
}

 

Schritt 2

1. Erhalten Sie den API-Schlüssel, indem Sie sich anmelden und die API-Einstellungsseite unter API-Einstellungen aufrufen.
2. Um die Schnittstelle zum Empfangen von Daten einzurichten, melden Sie sich an und rufen Sie die API-Einstellungsseite unter API-Einstellungen auf. Geben Sie dann die Schnittstellen-URL im Abschnitt WebHook ein.

Schritt 3

1. Rufen Sie die Registrierungsschnittstelle (/register) auf, um Trackingnummern zu abonnieren. Es wird empfohlen, die Daten-ID im Geschäftssystem über ein Tag zu übergeben, um die zukünftige Verwendung von Push-Ergebnissen zu erleichtern. (Schnittstellenreferenz: Trackingnummer registrieren)

Schritt 4

1. Überwachen Sie den Vorgang der Informationsempfangsschnittstelle. Um sicherzustellen, dass Tracking-Ergebnisse vom Geschäftsende effektiv und zeitnah verwendet werden, beachten Sie bitte: dass Daten kontinuierlich in gleichzeitigen Zuständen gepusht werden können, wobei jeder Push den vollständigen Datensatz enthält. Wenn der normale Empfang fehlschlägt und ein temporärer Statuscode ungleich 200 zurückgegeben wird, bietet 17TRACK kompensierende Pushes, wie hier beschrieben: Wie funktioniert der Push?
   

Wenn keine Tracking-Ergebnisse gefunden werden können, kann dies folgende Gründe haben:

• Das Tracking läuft. (Unter normalen Umständen sollten die ersten Tracking-Ergebnisse innerhalb von 1 Minute verfügbar sein, wobei das nachfolgende Tracking bis zur Zustellung 3 bis 4 Mal alle 24 Stunden durchgeführt wird.)
• Falsche Tracking-Nummer. Rufen Sie in diesem Fall die Schnittstelle zum Löschen von Trackings (/deletetrack) auf und abonnieren Sie dann erneut.
• Falscher Spediteur. Rufen Sie in diesem Fall die Schnittstelle zum Ändern von Spediteuren (/changecarrier) auf, um den Spediteur zu aktualisieren.
• Eine Anomalie in der Schnittstelle des Spediteurs.
• Spediteure haben die Tracking-Daten nicht aktualisiert.
• Zusätzliche Tracking-Parameter fehlen. Beim Abonnieren müssen für bestimmte Spediteure zusätzliche Tracking-Parameter angegeben werden, z. B. Handynummern und Postleitzahlen.
• Spediteure haben ihre Daten 30 Tage in Folge nicht aktualisiert. In diesem Fall stoppt 17TRACK das Tracking automatisch.

3.2 Integration von Drittsystemen

Zielbenutzer

Die folgende Integrationsanleitung richtet sich an kleine bis mittelgroße Logistikanbieter und mittelgroße Händler, die ERP-, TMS-, WMS- und CRM-Systeme von Drittanbietern nutzen

Schritt 1

(Wenn auch nur für einen schnellen Test, können Sie das Pushen über https://webhook.site überprüfen)

1. Bitte bestätigen Sie mit dem Systemanbieter, ob das aktuelle System den Empfang von Push-Tracking-Daten über die Webhook-Methode unterstützt. [Unterschiedlich zu selbst entwickelten Systemen]
2. Bitte bestätigen Sie mit dem Systemanbieter, ob eine alternative Lösung verfügbar ist, falls Push nicht unterstützt wird: Rufen Sie die gettrackinfo-Schnittstelle (/gettrackinfo) auf, um die Daten in regelmäßigen Abständen abzurufen. (Hinweis: Diese Methode kann nicht die gleiche Effizienz bei der Datenrückgabe wie die Push-Methode garantieren und wird von 17TRACK auch nicht empfohlen.) [Unterschiedlich zu selbst entwickelten Systemen]
3. Bitte bestätigen Sie mit dem Systemanbieter, ob der 17TRACK-API-Zugriff unterstützt wird. Wenn dies unterstützt wird, bestätigen Sie, ob die aktuelle integrierte Version den Geschäftsanforderungen entspricht. Wenn nicht, verhandeln Sie bitte mit dem Systemanbieter, um eine andere Version zu integrieren. [Unterschiedlich zu selbst entwickelten Systemen]
4. Wenn Push unterstützt wird, vervollständigen Sie die Signaturüberprüfungslogik in der Informationsempfangsschnittstelle, um sicherzustellen, dass die Informationsquelle sicher und gültig ist. Bitte lesen Sie „Signatur überprüfen“, Beispielcode ist wie folgt:

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

   String src = requestText + "/" + key;

   MessageDigest md = MessageDigest.getInstance("SHA-256");
   byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

   BigInteger number = new BigInteger(1, hash);
   StringBuilder hexString = new StringBuilder(number.toString(16));
   while (hexString.length() < 64) {
       hexString.insert(0, '0');
   }
   return hexString.toString();
}

Schritt 2

1. API-Schlüssel abrufen: Melden Sie sich bei der API-Konsole an, rufen Sie den Schlüssel auf der Seite „Einstellungen“ ab und geben Sie ihn an den für die Integration zuständigen Systemanbieter weiter. (Siehe API-Einstellungen)
2. Überspringen Sie diesen Schritt, wenn der Systemanbieter die Push-Methode nicht unterstützt. Wenn dies der Fall ist, wenden Sie sich an den Systemanbieter, um die URL der Push-Schnittstelle anzugeben. (Siehe API-Einstellungen)

Schritt 3

1. Rufen Sie die Registrierungsschnittstelle (/register) auf, um Trackingnummern zu abonnieren. Es wird empfohlen, dass der Systemanbieter die Daten-ID im Geschäftssystem über ein Tag weitergibt, um die zukünftige Verwendung von Push-Ergebnissen zu erleichtern. (Schnittstellenreferenz: Trackingnummer registrieren)

Schritt 4

1. Bitte melden Sie sich bei dem von Ihnen verwendeten System an und überprüfen Sie die Ergebnisse im Tracking-Modul. Wenden Sie sich bei Bedarf an den Kundendienst des Systemanbieters und lassen Sie sich beraten.
2. Überwachen Sie den Betrieb der Schnittstelle zum Empfang von Informationen. Um sicherzustellen, dass die Tracking-Ergebnisse zeitnah und effektiv vom Unternehmen genutzt werden, beachten Sie bitte: dass Daten kontinuierlich in gleichzeitigen Zuständen gepusht werden können, wobei jeder Push den vollständigen Datensatz enthält. In Fällen, in denen der normale Empfang fehlschlägt und ein temporärer Statuscode ungleich 200 zurückgegeben wird, bietet 17TRACK kompensierende Pushes an, wie hier beschrieben: Wie funktioniert der Push?

Wenn keine Tracking-Ergebnisse gefunden werden können, kann dies folgende Gründe haben:

• Das Tracking läuft. (Unter normalen Umständen sollten die ersten Tracking-Ergebnisse innerhalb von 1 Minute verfügbar sein, wobei das nachfolgende Tracking bis zur Zustellung 3 bis 4 Mal alle 24 Stunden durchgeführt wird.)
• Falsche Tracking-Nummer. Rufen Sie in diesem Fall die Schnittstelle zum Löschen von Trackings (/deletetrack) auf und abonnieren Sie dann erneut.
• Falscher Spediteur. Rufen Sie in diesem Fall die Schnittstelle zum Ändern von Spediteuren (/changecarrier) auf, um den Spediteur zu aktualisieren.
• Eine Anomalie in der Schnittstelle des Spediteurs.
• Spediteure haben die Tracking-Daten nicht aktualisiert.
• Zusätzliche Tracking-Parameter fehlen. Beim Abonnieren müssen für bestimmte Spediteure zusätzliche Tracking-Parameter angegeben werden, z. B. Handynummern und Postleitzahlen.
• Spediteure haben ihre Daten 30 Tage in Folge nicht aktualisiert. In diesem Fall stoppt 17TRACK das Tracking automatisch.

4. Versionen

Hauptversionen

Difference	V1.0	V2.0 (May 2022)
Request Address	https://api.17track.net/track/v1	https://api.17track.net/track/v2
Registration interface (/register) simplifies auto-recognition operations	{ carrier : null , auto_detection : true }	{ carrier : null }
Simplified signature verification	TRACKING_STOPPED/ {"number":"RM101474005CN", "carrier":3011,"tag":""} /6A8D7CFC3F7A41149E0A4EE8ABD0DD8A	{"event":"TRACKING_UPDATED", "data":{"number":"RR123456789CN", "carrier":3011,"tag":null}} /123456ABCDEF
Response structuring + node semantics	Not supported	Supported
Independent query additional parameters	Used in conjunction with a tracking number	Independent parameter
Origin and Destination	Not supported	Supported
Timeliness information	Not supported	Supported
Status	7 status	9 main status, 27 sub-status
Attachment Information	Not supported	Weight, volume, etc. (if supported by the carrier).
Carrier information	Not supported	Name, alias, official phone number, official website, etc.
Translation of events	Not supported	8 languages supported

Unterversionen

v2.1 (Aktualisiert im August 2023):

1. 3 Freigabe-Unterzustände hinzugefügt.
2. Ereignisstatusknoten hinzugefügt.
3. Die Registrierungsschnittstelle unterstützt Bestellnummer- und Notizparameter.
4. Bestellnummer, Zeitlimit und andere Informationen zur Gettracklist-Schnittstelle hinzugefügt.

v2.2 (Aktualisiert im Oktober 2023):

1. Die Rohinformationsstruktur für den Zeitpunkt des Logistikereignisses integrieren.