Skip to main content
HomeBlogGidsenMeerdere trackingnummers verzenden in één API-verzoek (batchlimieten en gedeeltelijke fouten)

Meerdere trackingnummers verzenden in één API-verzoek (batchlimieten en gedeeltelijke fouten)

17TRACK

Om meerdere trackingnummers in één API-aanvraag te verzenden, gebruikt u een Tracking API-eindpunt dat expliciet batches accepteert, formatteert u elke zending volgens het bijbehorende aanvraagschema en splitst u grotere lijsten op in batches binnen de gedocumenteerde limieten. Controleer vervolgens zowel de HTTP-respons als het resultaat van elke zending: een geslaagde HTTP-aanvraag betekent niet noodzakelijk dat elk trackingnummer is geaccepteerd. Probeer alleen daarvoor in aanmerking komende fouten opnieuw en verifieer onzekere uitkomsten voordat u een volledige batch opnieuw verzendt.

Meerdere trackingnummers verzenden in één API-aanvraag

Deze handleiding is bedoeld voor ontwikkelaars die zendingtracking koppelen aan een orderbeheersysteem, magazijnplatform, e-commerceapplicatie of intern dashboard. Het doel is niet alleen om minder aanvragen te verzenden. Het gaat erom elke zending te verwerken zonder dubbel werk te creëren of mislukte records kwijt te raken.

Identificeer eerst wat het batch-eindpunt daadwerkelijk doet

Een trackingintegratie kan verschillende afzonderlijke bewerkingen omvatten. Zendingen registreren, de meest recente trackinginformatie ophalen en latere updates ontvangen zijn niet uitwisselbaar.

  • Registratie: Dien zendingen in zodat de service de tracking ervoor kan starten of onderhouden.
  • Opzoeken: Vraag trackinginformatie voor zendingen op, afhankelijk van de ophaalregels van het eindpunt.
  • Bezorging bijwerken: Ontvang latere wijzigingen via een ondersteund mechanisme, zoals webhooks, of haal ze op via geplande aanvragen.

Controleer de documentatie voor de exacte bewerking die u nodig hebt. Een registratie-eindpunt dat meerdere records accepteert, betekent niet dat een opzoek-eindpunt hetzelfde aantal accepteert, hetzelfde schema gebruikt of dezelfde snelheidslimiet hanteert.

Begin voor een 17TRACK-integratie met de productpagina van de Tracking API en gebruik de officiële API-documentatie om de bewerking, authenticatiemethode, aanvraagindeling en responsvelden te bevestigen. Beschouw de onderstaande voorbeelden als implementatiepatronen, niet als vervanging van het API-contract.

Batchlimieten zijn meer dan alleen een maximumaantal zendingen

Er bestaat geen universele batchlimiet voor een Tracking API. Limieten kunnen verschillen per provider, eindpunt, API-versie en accountconfiguratie. Leg deze beperkingen afzonderlijk vast voordat u batching implementeert.

BeperkingWat moet worden bevestigdGevolg voor de implementatie
Items per aanvraagMaximumaantal records voor de specifieke bewerkingSplits de invoerlijst vóór verzending
Grootte van de aanvraagbodyElke gedocumenteerde limiet in bytesHoud rekening met optionele velden en serialisatiegrootte
AanvraagsnelheidToegestane aanvragen binnen een bepaald intervalDoseer aanvragen via een gedeelde limiter
GelijktijdigheidElke beperking op gelijktijdige aanvragenBeperk het aantal actieve workers
GebruiksregistratieOf gebruik wordt geteld per aanvraag, zending of andere eenheidSchat het verbruik afzonderlijk van het aantal aanvragen

Als een hypothetisch eindpunt bijvoorbeeld 25 records per aanvraag toestaat, vereisen 63 records drie aanvragen met respectievelijk 25, 25 en 13 records. Deze aantallen illustreren alleen het opdelen in delen; het zijn geen vermelde 17TRACK-limieten.

Ga er niet van uit dat batching het factureerbare gebruik vermindert. Het kan HTTP-overhead verminderen, maar het effect op kosten hangt af van de daadwerkelijke registratieregels van de provider. Evenzo geeft een geldige batchgrootte geen toestemming voor onbeperkte parallelle aanvragen.

Bereid records voor voordat u de aanvraag opbouwt

De meeste vermijdbare batchfouten beginnen bij de invoervoorbereiding. Valideer elke zending voordat u deze aan een batch toevoegt, maar vermijd regels die legitieme trackingnummers van verschillende vervoerders per ongeluk afwijzen.

  1. Behoud trackingnummers als tekenreeksen. Door ze naar getallen om te zetten kunnen voorloopnullen verdwijnen of lange identificatoren worden gewijzigd.
  2. Verwijder onbedoelde omringende witruimte. Verwijder geen interne tekens en wijzig de hoofdlettergebruik niet, tenzij de relevante specificatie die normalisatie toestaat.
  3. Valideer verplichte velden. Sommige workflows vereisen mogelijk een vervoerder-ID of aanvullende verzendinformatie. Gebruik uitsluitend gedocumenteerde veldnamen en waarden.
  4. Kies een expliciete deduplicatiescope. Een herhaald trackingnummer is niet automatisch een duplicaat bij elke vervoerder, handelaar of historische zending.
  5. Bewaar een lokale zending-ID. Sla de relatie op tussen het uitgaande item en uw order- of zendingrecord, ook wanneer de API geen aangepaste referentievelden accepteert.

Leid bij Carrier Tracking over meerdere netwerken de vervoerder niet uitsluitend af uit de lengte of prefix van een trackingnummer, tenzij die afleiding betrouwbaar is voor uw specifieke workflow. Als de API identificatie van de vervoerder ondersteunt, volgt u het gedocumenteerde gedrag voor het afhandelen van ambiguïteit.

Illustratieve aanvraagstructuur

De volgende JSON toont het concept van een batchpayload. De wrapper, eigenschapsnamen en identificatoren zijn illustratief en vormen geen 17TRACK-aanvraagschema. Sommige API's verwachten een array op het hoogste niveau in plaats van een object dat een array bevat.

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

Bouw de payload op via een JSON-serializer in plaats van tekenreeksen aan elkaar te plakken. Verstuur authenticatiegegevens via het gedocumenteerde mechanisme en houd ze buiten bronbeheer, code die naar browsers wordt gestuurd en routinematige logs.

Verwerk de respons op twee niveaus

Een batchaanvraag heeft een resultaat op transportniveau en een resultaat op applicatieniveau. Uw integratie moet beide beoordelen.

Niveau 1: Heeft de aanvraag een bruikbare respons ontvangen?

Begin met de HTTP-status, responsheaders en responsebody. Authenticatiefouten, verkeerd gevormde aanvragen, snelheidsbeperkingen en serverfouten kunnen normale itemverwerking verhinderen. Een netwerktime-out is anders: de client weet mogelijk niet of de server de aanvraag heeft ontvangen of verwerkt.

HTTP-semantiek is gedefinieerd in RFC 9110. De documentatie van de provider bepaalt echter hoe de resultaatvelden op applicatieniveau worden gekoppeld aan daadwerkelijke verzendingsuitkomsten.

Niveau 2: Wat is er met elke zending gebeurd?

Als de respons resultaten op itemniveau ondersteunt, classificeert u elk ingediend record. Ga er niet van uit dat HTTP 200 betekent dat elk record is geslaagd, of dat een resultatenlijst de volgorde van de aanvraag behoudt, tenzij het contract dit expliciet garandeert.

  • Geaccepteerd: De bewerking is geslaagd volgens de gedocumenteerde definitie van het eindpunt.
  • Permanente invoerfout: Corrigeer of onderzoek het record vóór een nieuwe poging.
  • Opnieuw te proberen fout: Plan een nieuwe poging volgens de retry-richtlijnen van de provider.
  • Onbekende uitkomst: De respons ontbreekt, is onvolledig of kan niet veilig aan het ingediende record worden gekoppeld.

Houd antwoorden zoals “al geregistreerd” of vergelijkbare duplicaatgerelateerde antwoorden afzonderlijk totdat u de gedocumenteerde betekenis ervan begrijpt. Ze kunnen aangeven dat de gewenste toestand al bestaat, maar mogen niet automatisch worden behandeld als bevestiging van succesvol eigenaarschap, configuratie of abonnement.

Na het verwerken van een respons moet elk invoerrecord precies één lokale uitkomst hebben. Een nuttige reconciliatiecontrole is: ingediende records zijn gelijk aan geaccepteerde records plus permanente fouten plus opnieuw te proberen fouten plus onbekende uitkomsten. Dit is een lokale boekhoudregel, geen vereist API-responsformaat.

Behandel gedeeltelijke fouten zonder geslaagde records opnieuw af te spelen

Stel dat een illustratieve batch tien zendingen bevat: zeven worden geaccepteerd, twee hebben ongeldige verplichte velden en één krijgt te maken met een gedocumenteerde tijdelijke fout. Sla de zeven geslaagde uitkomsten op, stuur de twee ongeldige records ter correctie door en probeer alleen de tijdelijke fout opnieuw.

Alle tien records opnieuw afspelen creëert onnodig verkeer en kan de afhandeling van duplicaten bemoeilijken. Het maakt het ook moeilijker om een oorspronkelijke afwijzing te onderscheiden van een later duplicaatgerelateerd antwoord.

UitkomstAanbevolen actie
Ongeldig veld of niet-ondersteunde waardeCorrigeer de invoer; probeer niet ongewijzigd opnieuw
Authenticatie- of autorisatiefoutPauzeer het betrokken werk en herstel referenties of toegang
Reactie wegens snelheidsbeperkingWacht volgens de gedocumenteerde richtlijnen en toepasselijke responsheaders
Tijdelijke fout op itemniveauProbeer dat item opnieuw met begrensde pogingen en back-off
Time-out na verzendingMarkeer als onzeker; verifieer of gebruik gedocumenteerde garanties voor veilig opnieuw proberen
Niet-herkende of onvolledige uitkomstBewaar bewijs en onderzoek in plaats van succes te veronderstellen

HTTP 429 staat voor te veel aanvragen en de respons kan een Retry-After-header bevatten, zoals beschreven in RFC 6585. Ga er niet van uit dat die header altijd aanwezig is. Wanneer geen expliciete retryvertraging wordt opgegeven, gebruikt u een begrensd back-offbeleid dat overeenkomt met de documentatie van de API.

Voeg jitter toe om retries van meerdere workers te spreiden, stel een maximumaantal pogingen of een maximale retryduur in en stuur uitgeputte records naar een beoordelingswachtrij. Eindeloos opnieuw proberen kan een blijvend configuratieprobleem verbergen.

Waarom time-outs speciale behandeling vereisen

Een time-out bewijst geen afwijzing. De server kan de batch hebben geaccepteerd voordat de verbinding wegviel. Een state-changing request automatisch opnieuw afspelen kan daardoor werk herhalen.

Als het eindpunt gedocumenteerde idempotentiesleutels ondersteunt, volgt u de bijbehorende regels, inclusief sleutelbereik en bewaartermijn. Bedenk geen idempotency-header en neem niet aan dat de server deze respecteert. Gebruik anders een ondersteunde opzoek- of reconciliatieworkflow om te bepalen of de gewenste toestand bestaat voordat u opnieuw verzendt. Lokale deduplicatie helpt uw eigen workers te coördineren, maar garandeert geen idempotentie aan serverzijde.

Een praktische workflow voor batchverwerking

Houd provider-specifieke details in een adapter, zodat de wachtrij, retryplanner en monitoringlogica niet afhankelijk zijn van onbewerkte responsveldnamen.

valideer records en behoud lokale zending-ID's
los duplicaten op binnen de bedoelde bedrijfscontext
splits records volgens gedocumenteerde item- en payloadlimieten

voor elke batch via een begrensde workerpool:
    sla vóór verzending een pogingrecord op
    wacht op de gedeelde snelheidslimiter
    verzend via de provider-specifieke adapter

    als de uitkomst onzeker is:
        voeg reconciliatie toe aan de wachtrij
        ga verder

    classificeer uitkomsten op aanvraag- en itemniveau
    sla één uitkomst op voor elk ingediend record
    plan alleen daarvoor in aanmerking komende fouten voor opnieuw proberen
    stuur ongeldige of uitgeputte records ter beoordeling door

Zorg ervoor dat het opslaan van uitkomsten en het plannen van retries herstelbaar is. Een duurzaam jobrecord of transactioneel wachtrijpatroon kan bijvoorbeeld voorkomen dat een procescrash de retrybeslissing verloren laat gaan. Wanneer workers opnieuw starten, moeten ze niet-verzonden werk kunnen onderscheiden van werk waarvan de externe uitkomst nog onzeker is.

Maak de batchgrootte configureerbaar en koppel deze aan het relevante eindpunt, in plaats van een constante door de hele codebase te verspreiden. Een kleinere batch kan nuttig zijn bij probleemoplossing of het isoleren van problematische records; de maximaal toegestane batch is niet automatisch de beste operationele grootte.

Monitor zendinguitkomsten, niet alleen HTTP-beschikbaarheid

API Monitoring moet laten zien of zendingen de beoogde toestand bereiken. Een dashboard dat alleen HTTP-succespercentages rapporteert, kan gedeeltelijke fouten binnen verder geslaagde responses missen.

  • Acceptatiegraad op itemniveau: Geaccepteerde records gedeeld door ingediende records, met een duidelijk gedefinieerde behandeling van retries.
  • Foutverdeling: Aantallen per eindpunt, gedocumenteerde foutcode en relevante vervoerderscontext.
  • Onbekende uitkomsten: Niet-gereconcilieerde records en hoelang ze onopgelost zijn gebleven.
  • Retryachterstand: Geplande retries, ouderdom van de oudste retry en uitgeputte pogingen.
  • Aanvraagstatus: Latentie, time-outs, snelheidsbeperkingen en serverfouten.
  • Actualiteit van tracking: Of geaccepteerde zendingen vervolgens bruikbare trackinginformatie ontvangen.

Acceptatie van een registratie is geen bewijs van een nieuwe scan door de vervoerder. Houd de verwerkingsstatus van de API gescheiden van de verplaatsing van zendingen en de actualiteit van gegevens, zodat een integratie-incident niet wordt verward met een vertraging in de bezorging.

Log lokale batch-ID's, zendreferenties, aantallen pogingen, gedocumenteerde foutcodes en provider-request-ID's wanneer deze beschikbaar zijn. Redigeer referenties en onnodige persoonsgegevens. Gebruik trackingidentificatoren alleen waar dit operationeel noodzakelijk is en plaats ruwe zendingidentificatoren niet in metriclabels met hoge cardinaliteit.

Test deze gevallen vóór productie

Gebruik waar beschikbaar een gedocumenteerde sandbox of gecontroleerde testomgeving. Ga er niet van uit dat zelfbedachte trackingnummers voorspelbare productieresponses opleveren.

  1. Dien een geldige batch in op de gedocumenteerde itemlimiet en test vervolgens hoe uw client een te grote batch voorkomt.
  2. Controleer of trackingnummers met voorloopnullen behouden blijven tijdens serialisatie en opslag.
  3. Test gemengde geaccepteerde en afgewezen items zonder geslaagde records opnieuw te proberen.
  4. Simuleer snelheidsbeperking en bevestig dat meerdere workers dezelfde limiet respecteren.
  5. Simuleer een time-out na verzending en controleer het reconciliatiepad.
  6. Herstart een worker tussen het ontvangen van de respons en lokale persistentie.
  7. Test ontbrekende, onbekende of niet-koppelbare itemresultaten.
  8. Bevestig dat ongeldige records een zichtbare correctiewachtrij bereiken in plaats van eindeloos opnieuw te worden geprobeerd.

Een productierijpe integratie kan de toestand van elke ingediende zending verklaren, ook wanneer de uitkomst tijdelijk onbekend is. Het verminderen van het aantal aanvragen is nuttig; het behouden van die verantwoordingsplicht is het belangrijkere ontwerpdoel.

Veelgestelde vragen

Hoeveel trackingnummers kan ik in één aanvraag verzenden?

Gebruik de limiet die is gedocumenteerd voor het exacte eindpunt en de exacte API-versie. Controleer ook de aanvraaggrootte, snelheidslimieten en eventuele accountspecifieke beperkingen. Er bestaat geen veilig universeel aantal dat u kunt toepassen op alle tracking-API's of op verschillende bewerkingen binnen één API.

Kan één ongeldig trackingnummer ervoor zorgen dat de hele batch mislukt?

Ja, afhankelijk van de validatieregels van het eindpunt. Sommige API's retourneren afzonderlijke afwijzingen, terwijl andere een aanvraag kunnen afwijzen voordat items worden verwerkt. Controleer zowel fouten op aanvraagniveau als resultaten op itemniveau; ga er niet van uit dat elk batch-eindpunt gedeeltelijke acceptatie ondersteunt.

Moet ik een batch opnieuw proberen wanneer de HTTP-respons geslaagd is?

Niet automatisch. Analyseer eerst de gedocumenteerde status op applicatieniveau en de itemresultaten. Sla geslaagde records op en probeer alleen daarvoor in aanmerking komende fouten opnieuw. Als de uitkomst niet veilig kan worden geïnterpreteerd, classificeert u deze als onzeker en onderzoekt u dit.

Kan ik vervoerders in dezelfde batch combineren?

Alleen wanneer het eindpunt die aanvraagstructuur ondersteunt. Bevestig of vervoerdersinformatie per zending wordt aangeleverd, of automatische identificatie wordt ondersteund en wat er gebeurt wanneer de identificatie ambigu is. Een service voor meerdere vervoerders bepaalt op zichzelf niet de batchregels van elk eindpunt.

Zorgt batching ervoor dat trackingupdates sneller aankomen?

Batching kan het aantal aanvragen dat uw applicatie verzendt verminderen, maar zorgt er op zichzelf niet voor dat gebeurtenissen van vervoerders eerder verschijnen. Registratie, het ophalen van gegevens, de beschikbaarheid van scans door vervoerders en de levering van updates zijn afzonderlijke onderdelen van de workflow.

Bronnen