So senden Sie mehrere Sendungsnummern in einer API-Anfrage (Batch-Limits und teilweise Fehler)
Um mehrere Sendungsnummern in einer API-Anfrage zu senden, verwenden Sie einen Tracking-API-Endpunkt, der ausdrücklich Batch-Anfragen akzeptiert, formatieren Sie jede Sendung gemäß dem jeweiligen Anfrage-Schema und teilen Sie größere Listen in Batches innerhalb der dokumentierten Grenzen auf. Prüfen Sie anschließend sowohl die HTTP-Antwort als auch das Ergebnis jeder Sendung: Eine erfolgreiche HTTP-Anfrage bedeutet nicht zwangsläufig, dass jede Sendungsnummer akzeptiert wurde. Wiederholen Sie nur zulässige Fehler und gleichen Sie unklare Ergebnisse ab, bevor Sie einen gesamten Batch erneut senden.

Dieser Leitfaden richtet sich an Entwickler, die die Sendungsverfolgung mit einem Auftragsverwaltungssystem, einer Lagerplattform, einer E-Commerce-Anwendung oder einem internen Dashboard verbinden. Ziel ist nicht einfach, weniger Anfragen zu senden. Vielmehr soll jede Sendung berücksichtigt werden, ohne doppelte Arbeit zu erzeugen oder fehlgeschlagene Datensätze zu verlieren.
Ermitteln Sie zunächst, was der Batch-Endpunkt tatsächlich tut
Eine Tracking-Integration kann mehrere unterschiedliche Vorgänge umfassen. Das Registrieren von Sendungen, das Abrufen der neuesten Tracking-Informationen und der Empfang späterer Aktualisierungen sind nicht austauschbar.
- Registrierung: Senden Sie Sendungen ein, damit der Dienst deren Verfolgung starten oder fortsetzen kann.
- Abfrage: Fordern Sie Tracking-Informationen für Sendungen an, vorbehaltlich der Abrufregeln des Endpunkts.
- Zustellung aktualisieren: Empfangen Sie spätere Änderungen über einen unterstützten Mechanismus wie Webhooks oder rufen Sie sie über geplante Anfragen ab.
Prüfen Sie in der Dokumentation den genauen Vorgang, den Sie benötigen. Ein Registrierung Endpunkt, der mehrere Datensätze akzeptiert, bedeutet nicht, dass ein Abfrage-Endpunkt dieselbe Anzahl akzeptiert, dasselbe Schema verwendet oder dasselbe Ratenlimit besitzt.
Beginnen Sie bei einer 17TRACK-Integration mit der Produktseite der Tracking API und verwenden Sie die offizielle API-Dokumentation, um Vorgang, Authentifizierungsmethode, Anfrageformat und Antwortfelder zu bestätigen. Betrachten Sie die folgenden Beispiele als Implementierungsmuster und nicht als Ersatz für den API-Vertrag.
Batch-Limits sind mehr als eine maximale Anzahl von Sendungen
Für eine Tracking API gibt es kein universelles Batch-Limit. Die Grenzen können je nach Anbieter, Endpunkt, API-Version und Kontokonfiguration variieren. Erfassen Sie diese Einschränkungen vor der Implementierung von Batches separat.
| Einschränkung | Was zu bestätigen ist | Folge für die Implementierung |
|---|---|---|
| Elemente pro Anfrage | Maximale Datensatzanzahl für den jeweiligen Vorgang | Eingabeliste vor dem Senden aufteilen |
| Größe des Anfrage-Bodys | Dokumentiertes Byte-Limit | Optionale Felder und Serialisierungsgröße berücksichtigen |
| Anfragerate | Zulässige Anfragen innerhalb eines definierten Zeitraums | Anfragen über einen gemeinsamen Begrenzer takten |
| Parallelität | Beschränkung gleichzeitiger Anfragen | Anzahl aktiver Worker begrenzen |
| Nutzungsabrechnung | Ob die Nutzung nach Anfrage, Sendung oder einer anderen Einheit gezählt wird | Verbrauch unabhängig vom Anfragevolumen schätzen |
Wenn ein hypothetischer Endpunkt beispielsweise 25 Datensätze pro Anfrage erlaubt, erfordern 63 Datensätze drei Anfragen mit 25, 25 und 13 Datensätzen. Diese Zahlen veranschaulichen lediglich die Aufteilung in Teilmengen; sie stellen keine 17TRACK-Limits dar.
Gehen Sie nicht davon aus, dass Batching die abrechenbare Nutzung reduziert. Es kann den HTTP-Anfrageaufwand verringern, aber die Auswirkungen auf die Kosten hängen von den tatsächlichen Abrechnungsregeln des Anbieters ab. Ebenso berechtigt eine gültige Batch-Größe nicht zu unbegrenzt vielen parallelen Anfragen.
Datensätze vor dem Erstellen der Anfrage vorbereiten
Die meisten vermeidbaren Batch-Fehler beginnen bei der Eingabevorbereitung. Validieren Sie jede Sendung, bevor Sie sie einem Batch hinzufügen, vermeiden Sie jedoch Regeln, die gültige Sendungsnummern verschiedener Versanddienstleister versehentlich ablehnen.
- Sendungsnummern als Zeichenfolgen beibehalten. Eine Umwandlung in Zahlen kann führende Nullen entfernen oder lange Identifikatoren verändern.
- Versehentliche Leerzeichen am Anfang und Ende entfernen. Entfernen Sie keine internen Zeichen und ändern Sie die Groß-/Kleinschreibung nicht, sofern die entsprechende Spezifikation diese Normalisierung nicht erlaubt.
- Erforderliche Felder validieren. Einige Abläufe können eine Versanddienstleister-ID oder zusätzliche Sendungsinformationen erfordern. Verwenden Sie ausschließlich dokumentierte Feldnamen und Werte.
- Einen eindeutigen Deduplizierungsbereich festlegen. Eine wiederholte Sendungsnummer ist nicht automatisch über jeden Versanddienstleister, Händler oder jede frühere Sendung hinweg ein Duplikat.
- Eine lokale Sendungs-ID speichern. Speichern Sie die Beziehung zwischen dem ausgehenden Element und Ihrem Auftrags- oder Sendungsdatensatz, auch wenn die API keine benutzerdefinierten Referenzfelder akzeptiert.
Leiten Sie bei der Carrier Tracking über mehrere Netzwerke den Versanddienstleister nicht allein aus der Länge oder dem Präfix einer Sendungsnummer ab, es sei denn, diese Schlussfolgerung ist für Ihren konkreten Ablauf zuverlässig. Wenn die API die Identifizierung des Versanddienstleisters unterstützt, befolgen Sie deren dokumentiertes Verhalten bei Mehrdeutigkeiten.
Beispielhafte Anfrage-Struktur
Das folgende JSON zeigt das Konzept einer Batch-Nutzlast. Wrapper, Eigenschaftsnamen und Identifikatoren sind beispielhaft und stellen kein 17TRACK-Anfrage-Schema dar. Einige APIs erwarten anstelle eines Objekts mit einem Array ein Array auf oberster Ebene.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Erstellen Sie die Nutzlast über einen JSON-Serializer, statt Zeichenfolgen zusammenzusetzen. Senden Sie Authentifizierungsdaten über den dokumentierten Mechanismus und halten Sie sie aus der Versionsverwaltung, aus an den Browser ausgeliefertem Code und aus routinemäßigen Protokollen heraus.
Antwort auf zwei Ebenen verarbeiten
Eine Batch-Anfrage hat ein Ergebnis auf Transportebene und ein Ergebnis auf Anwendungsebene. Ihre Integration muss beide bewerten.
Ebene 1: Hat die Anfrage eine verwertbare Antwort erhalten?
Beginnen Sie mit HTTP-Status, Antwort-Headern und Antworttext. Authentifizierungsfehler, fehlerhafte Anfragen, Ratenbegrenzung und Serverfehler können die normale Verarbeitung von Elementen verhindern. Ein Netzwerk-Timeout ist etwas anderes: Der Client weiß möglicherweise nicht, ob der Server die Anfrage empfangen oder verarbeitet hat.
Die HTTP-Semantik ist in RFC 9110 definiert. Die Dokumentation des Anbieters bestimmt jedoch, wie dessen Ergebnisse auf Anwendungsebene den tatsächlichen Sendungsergebnissen zugeordnet werden.
Ebene 2: Was ist mit jeder Sendung passiert?
Wenn die Antwort Ergebnisse auf Elementebene unterstützt, klassifizieren Sie jeden eingereichten Datensatz. Gehen Sie nicht davon aus, dass HTTP 200 bedeutet, dass jeder Datensatz erfolgreich war, oder dass eine Ergebnisliste die Reihenfolge der Anfrage beibehält, sofern der Vertrag dies nicht ausdrücklich garantiert.
- Akzeptiert: Der Vorgang war gemäß der dokumentierten Definition des Endpunkts erfolgreich.
- Permanenter Eingabefehler: Korrigieren oder untersuchen Sie den Datensatz vor einem weiteren Versuch.
- Wiederholbarer Fehler: Planen Sie gemäß den Wiederholungsrichtlinien des Anbieters einen weiteren Versuch.
- Unbekanntes Ergebnis: Die Antwort fehlt, ist unvollständig oder kann dem eingereichten Datensatz nicht sicher zugeordnet werden.
Behalten Sie Antworten wie „bereits registriert“ oder ähnliche duplikatbezogene Antworten separat, bis Sie ihre dokumentierte Bedeutung verstehen. Sie können darauf hinweisen, dass der gewünschte Zustand bereits besteht, sollten jedoch nicht automatisch als Bestätigung von Besitz, Konfiguration oder Abonnement behandelt werden.
Nach der Verarbeitung einer Antwort sollte jeder Eingabedatensatz genau ein lokales Ergebnis besitzen. Eine nützliche Abgleichprüfung lautet: Eingereichte Datensätze entsprechen akzeptierten Datensätzen plus permanenten Fehlern plus wiederholbaren Fehlern plus unbekannten Ergebnissen. Dies ist eine lokale Abrechnungsregel und kein vorgeschriebenes API-Antwortformat.
Teilfehler behandeln, ohne erfolgreiche Datensätze erneut abzuspielen
Angenommen, ein beispielhafter Batch enthält zehn Sendungen: Sieben werden akzeptiert, zwei enthalten ungültige Pflichtfelder und bei einer tritt ein dokumentierter vorübergehender Fehler auf. Speichern Sie die sieben erfolgreichen Ergebnisse, leiten Sie die zwei ungültigen Datensätze zur Korrektur weiter und wiederholen Sie nur den vorübergehend fehlgeschlagenen Datensatz.
Das erneute Senden aller zehn Datensätze erzeugt unnötigen Datenverkehr und kann die Behandlung von Duplikaten erschweren. Außerdem wird es schwieriger, eine ursprüngliche Ablehnung von einer späteren duplikatbezogenen Antwort zu unterscheiden.
| Ergebnis | Empfohlene Maßnahme |
|---|---|
| Ungültiges Feld oder nicht unterstützter Wert | Eingabe korrigieren; unverändert nicht erneut senden |
| Authentifizierungs- oder Berechtigungsfehler | Betroffene Arbeit anhalten und Zugangsdaten oder Berechtigungen korrigieren |
| Antwort wegen Ratenbegrenzung | Gemäß dokumentierten Richtlinien und relevanten Antwort-Headern warten |
| Vorübergehender Fehler auf Elementebene | Dieses Element mit begrenzten Versuchen und Backoff erneut senden |
| Timeout nach dem Senden | Als unklar markieren; abgleichen oder dokumentierte Wiederholungssicherheitsgarantien verwenden |
| Nicht erkanntes oder unvollständiges Ergebnis | Belege aufbewahren und untersuchen, statt Erfolg anzunehmen |
HTTP 429 bezeichnet zu viele Anfragen; die Antwort kann einen Retry-After-Header enthalten, wie in RFC 6585 beschrieben. Gehen Sie nicht davon aus, dass dieser Header immer vorhanden ist. Wenn keine ausdrückliche Wartezeit angegeben wird, verwenden Sie eine begrenzte Backoff-Richtlinie im Einklang mit der API-Dokumentation.
Fügen Sie Jitter hinzu, um Wiederholungen mehrerer Worker zu verteilen, legen Sie eine maximale Anzahl von Versuchen oder ein maximales Wiederholungsalter fest und senden Sie ausgeschöpfte Datensätze an eine Prüfwarteschlange. Unbegrenzte Wiederholungen können ein dauerhaftes Konfigurationsproblem verdecken.
Warum Timeouts besondere Behandlung erfordern
Ein Timeout beweist keine Ablehnung. Der Server kann den Batch akzeptiert haben, bevor die Verbindung fehlgeschlagen ist. Das automatische erneute Senden einer zustandsändernden Anfrage kann daher Arbeit wiederholen.
Wenn der Endpunkt dokumentierte Idempotenzschlüssel unterstützt, befolgen Sie dessen Regeln einschließlich Schlüsselbereich und Aufbewahrung. Erfinden Sie keinen Idempotenz-Header und nehmen Sie nicht an, dass der Server ihn berücksichtigt. Verwenden Sie andernfalls einen unterstützten Abruf- oder Abgleichsablauf, um vor dem erneuten Senden festzustellen, ob der gewünschte Zustand vorhanden ist. Lokale Deduplizierung hilft bei der Koordination eigener Worker, garantiert jedoch keine serverseitige Idempotenz.
Praktischer Ablauf zur Batch-Verarbeitung
Halten Sie anbieterspezifische Details in einem Adapter, damit Warteschlange, Wiederholungsplaner und Überwachungslogik nicht von rohen Antwortfeldnamen abhängen.
Datensätze validieren und lokale Sendungs-IDs beibehalten
duplikate innerhalb des vorgesehenen Geschäftsumfangs auflösen
Datensätze anhand dokumentierter Element- und Nutzlastlimits aufteilen
für jeden Batch über einen begrenzten Worker-Pool:
Versuchsdaten vor dem Senden speichern
auf den gemeinsamen Ratenbegrenzer warten
über den anbieterspezifischen Adapter senden
wenn das Ergebnis unklar ist:
Abgleich einreihen
fortfahren
Ergebnisse auf Anfrage- und Elementebene klassifizieren
für jeden eingereichten Datensatz genau ein Ergebnis speichern
nur zulässige Fehler zur Wiederholung einplanen
ungültige oder ausgeschöpfte Datensätze zur Prüfung weiterleiten
Speichern Sie Ergebnisse und planen Sie Wiederholungen so, dass sie wiederherstellbar sind. Ein dauerhafter Jobdatensatz oder ein transaktionales Warteschlangen-Muster kann beispielsweise verhindern, dass ein Prozessabsturz die Wiederholungsentscheidung verliert. Nach einem Neustart müssen Worker nicht gesendete Arbeit von Arbeit unterscheiden können, deren Ergebnis beim entfernten Dienst noch unklar ist.
Machen Sie die Batch-Größe zu einer konfigurierbaren Einstellung, die an den relevanten Endpunkt gebunden ist, statt sie als Konstante über die Codebasis zu verteilen. Ein kleinerer Batch kann bei der Fehlersuche oder beim Isolieren problematischer Datensätze hilfreich sein; der größtmögliche zulässige Batch ist nicht automatisch die beste Betriebsgröße.
Sendungsergebnisse überwachen, nicht nur die HTTP-Verfügbarkeit
API Monitoring sollte zeigen, ob Sendungen den vorgesehenen Zustand erreichen. Ein Dashboard, das nur HTTP-Erfolgsraten meldet, kann Teilfehler innerhalb ansonsten erfolgreicher Antworten übersehen.
- Akzeptanzrate auf Elementebene: Akzeptierte Datensätze geteilt durch eingereichte Datensätze, mit klar definierter Behandlung von Wiederholungen.
- Fehlerverteilung: Anzahl nach Endpunkt, dokumentiertem Fehlercode und relevantem Versanddienstleisterkontext.
- Unbekannte Ergebnisse: Nicht abgeglichene Datensätze und die Dauer, seit der sie ungelöst sind.
- Wiederholungsrückstand: Ausstehende Wiederholungen, Alter der ältesten Wiederholung und ausgeschöpfte Versuche.
- Anfragezustand: Latenz, Timeouts, Ratenbegrenzung und Serverfehler.
- Aktualität der Sendungsverfolgung: Ob akzeptierte Sendungen anschließend verwertbare Tracking-Informationen erhalten.
Die Annahme einer Registrierung ist kein Beweis für einen neuen Scan des Versanddienstleisters. Halten Sie den Status der API-Verarbeitung von der Bewegung der Sendung und der Aktualität der Daten getrennt, damit ein Integrationsvorfall nicht mit einer Lieferverzögerung verwechselt wird.
Protokollieren Sie lokale Batch-IDs, Sendungsreferenzen, Versuchszahlen, dokumentierte Fehlercodes und, sofern verfügbar, Anfrage-IDs des Anbieters. Schwärzen Sie Zugangsdaten und nicht erforderliche personenbezogene Daten. Verwenden Sie Tracking-Identifikatoren nur, wenn dies betrieblich erforderlich ist, und vermeiden Sie rohe Sendungsidentifikatoren in Metriklabels mit hoher Kardinalität.
Diese Fälle vor dem Produktionsbetrieb testen
Verwenden Sie, sofern verfügbar, eine dokumentierte Sandbox oder eine kontrollierte Testumgebung. Gehen Sie nicht davon aus, dass erfundene Sendungsnummern vorhersehbare Antworten in der Produktion erzeugen.
- Senden Sie einen gültigen Batch am dokumentierten Elementlimit und testen Sie anschließend, wie Ihr Client einen zu großen Batch verhindert.
- Stellen Sie sicher, dass Sendungsnummern mit führenden Nullen die Serialisierung und Speicherung überstehen.
- Testen Sie gemischte akzeptierte und abgelehnte Elemente, ohne erfolgreiche Datensätze erneut zu senden.
- Simulieren Sie eine Ratenbegrenzung und bestätigen Sie, dass mehrere Worker dasselbe Limit einhalten.
- Simulieren Sie einen Timeout nach dem Senden und überprüfen Sie den Abgleichsweg.
- Starten Sie einen Worker zwischen dem Empfang der Antwort und der lokalen Speicherung neu.
- Testen Sie fehlende, unbekannte oder nicht zuordenbare Elementergebnisse.
- Bestätigen Sie, dass ungültige Datensätze eine sichtbare Korrekturwarteschlange erreichen, anstatt endlos wiederholt zu werden.
Eine produktionsreife Integration kann den Zustand jeder eingereichten Sendung erklären, einschließlich derjenigen, deren Ergebnis vorübergehend unbekannt ist. Die Anzahl der Anfragen zu reduzieren ist nützlich; diese Nachvollziehbarkeit zu bewahren ist jedoch das wichtigere Designziel.
FAQ
Wie viele Sendungsnummern kann ich in einer Anfrage senden?
Verwenden Sie das für den genauen Endpunkt und die API-Version dokumentierte Limit. Prüfen Sie außerdem Anfragegröße, Ratenlimits und kontospezifische Einschränkungen. Es gibt keine sichere universelle Zahl, die auf alle Tracking-APIs oder auf verschiedene Vorgänge innerhalb einer API angewendet werden kann.
Kann eine ungültige Sendungsnummer dazu führen, dass der gesamte Batch fehlschlägt?
Ja, abhängig von den Validierungsregeln des Endpunkts. Einige APIs geben einzelne Ablehnungen zurück, während andere eine Anfrage vor der Elementverarbeitung ablehnen können. Prüfen Sie sowohl Fehler auf Anfrageebene als auch Ergebnisse auf Elementebene; gehen Sie nicht davon aus, dass jeder Batch-Endpunkt eine teilweise Annahme unterstützt.
Soll ich einen Batch erneut senden, wenn die HTTP-Antwort erfolgreich ist?
Nicht automatisch. Analysieren Sie zuerst den dokumentierten Status auf Anwendungsebene und die Elementergebnisse. Speichern Sie erfolgreiche Datensätze und wiederholen Sie nur zulässige Fehler. Wenn das Ergebnis nicht sicher interpretiert werden kann, klassifizieren Sie es als unklar und untersuchen Sie es.
Kann ich Versanddienstleister im selben Batch mischen?
Nur wenn der Endpunkt diese Anfragestruktur unterstützt. Bestätigen Sie, ob die Informationen zum Versanddienstleister pro Sendung angegeben werden, ob eine automatische Identifizierung unterstützt wird und was bei einer mehrdeutigen Identifizierung geschieht. Ein Multi-Carrier-Dienst legt nicht automatisch die Batch-Regeln jedes Endpunkts fest.
Werden Tracking-Aktualisierungen durch Batching schneller zugestellt?
Batching kann die Anzahl der von Ihrer Anwendung gesendeten Anfragen reduzieren, lässt Ereignisse des Versanddienstleisters jedoch nicht automatisch früher erscheinen. Registrierung, Datenabruf, Verfügbarkeit von Scans des Versanddienstleisters und Zustellung von Aktualisierungen sind getrennte Teile des Ablaufs.
Quellen
- 17TRACK Tracking API — offizieller Produkteinstiegspunkt für Entwickler, die eine Tracking-Integration bewerten.
- 17TRACK API-Dokumentation — Referenz für den anbieterspezifischen Endpunktvertrag, Limits, Authentifizierung und Antwortverarbeitung.
- RFC 9110: HTTP Semantics — HTTP-Statussemantik, Idempotenz, automatische Wiederholungen und Retry-After.
- RFC 6585: Additional HTTP Status Codes — Definition von HTTP 429 Too Many Requests und seinem optionalen Retry-After-Header.


