Sådan sender du flere sporingsnumre i én API-anmodning (batchgrænser og delvise fejl)
For at sende flere sporingsnumre i én API-anmodning skal du bruge et Tracking API-endpoint, der udtrykkeligt accepterer en batch, formatere hver forsendelse i henhold til dens request-schema og opdele større lister i batches inden for de dokumenterede grænser. Kontrollér derefter både HTTP-svaret og resultatet for hver forsendelse: En vellykket HTTP-anmodning betyder ikke nødvendigvis, at alle sporingsnumre blev accepteret. Gentag kun forsøg for berettigede fejl, og afstem usikre resultater, før du indsender en hel batch igen.

Denne vejledning er til udviklere, der forbinder forsendelsessporing med et ordreadministrationssystem, en lagerplatform, en e-handelsapplikation eller et internt dashboard. Målet er ikke blot at sende færre anmodninger. Det handler om at tage højde for hver forsendelse uden at skabe dobbeltarbejde eller miste fejlslagne poster.
Identificér først, hvad batch-endpointet faktisk gør
En sporingsintegration kan omfatte flere forskellige handlinger. Registrering af forsendelser, hentning af de seneste sporingsoplysninger og modtagelse af efterfølgende opdateringer kan ikke bruges som synonymer.
- Registrering: Indsend forsendelser, så tjenesten kan begynde eller fortsætte sporingen af dem.
- Opslag: Anmod om sporingsoplysninger for forsendelser i henhold til endpointets regler for hentning.
- Leveringsopdatering: Modtag senere ændringer via en understøttet mekanisme, f.eks. webhooks, eller hent dem gennem planlagte anmodninger.
Kontrollér dokumentationen for den præcise handling, du har brug for. Et registrerings-endpoint, der accepterer flere poster, betyder ikke, at et opslag-endpoint accepterer det samme antal, bruger det samme schema eller har den samme hastighedsgrænse.
For en 17TRACK-integration skal du begynde på produktsiden for Tracking API og bruge den officielle API-dokumentation til at bekræfte handlingen, godkendelsesmetoden, anmodningsformatet og svarfelterne. Betragt eksemplerne nedenfor som implementeringsmønstre og ikke som en erstatning for API-kontrakten.
Batchgrænser handler om mere end det maksimale antal forsendelser
Der findes ingen universel batchgrænse for et Tracking API. Grænserne kan variere efter udbyder, endpoint, API-version og kontokonfiguration. Før du implementerer batching, skal du registrere disse begrænsninger separat.
| Begrænsning | Hvad skal bekræftes | Konsekvens for implementeringen |
|---|---|---|
| Elementer pr. anmodning | Maksimalt antal poster for den specifikke handling | Opdel inputlisten, før den sendes |
| Størrelse på anmodningens body | Eventuel dokumenteret bytegrænse | Tag højde for valgfrie felter og serialiseringsstørrelse |
| Anmodningshastighed | Tilladte anmodninger i et defineret interval | Regulér anmodninger gennem en fælles begrænser |
| Samtidighed | Eventuelle begrænsninger for samtidige anmodninger | Begræns antallet af aktive workers |
| Forbrugsregistrering | Om forbruget tælles pr. anmodning, forsendelse eller en anden enhed | Estimér forbruget separat fra antallet af anmodninger |
Hvis et hypotetisk endpoint f.eks. tillader 25 poster pr. anmodning, kræver 63 poster tre anmodninger med henholdsvis 25, 25 og 13 poster. Disse tal illustrerer kun opdeling i blokke; de er ikke angivne 17TRACK-grænser.
Antag ikke, at batching reducerer fakturerbart forbrug. Det kan reducere overhead fra HTTP-anmodninger, men enhver effekt på omkostningerne afhænger af udbyderens faktiske regler for registrering af forbrug. På samme måde giver en gyldig batchstørrelse ikke tilladelse til ubegrænsede parallelle anmodninger.
Forbered poster, før du opbygger anmodningen
De fleste batchfejl, der kan undgås, begynder med forberedelsen af input. Validér hver forsendelse, før du føjer den til en batch, men undgå regler, der ved et uheld afviser legitime sporingsnumre fra forskellige transportører.
- Bevar sporingsnumre som strenge. Hvis du konverterer dem til tal, kan indledende nuller blive fjernet, eller lange identifikatorer kan blive ændret.
- Fjern utilsigtede mellemrum omkring værdien. Fjern ikke interne tegn, og ændr ikke store og små bogstaver, medmindre den relevante specifikation tillader denne normalisering.
- Validér obligatoriske felter. Nogle arbejdsgange kan kræve en transportøridentifikator eller yderligere forsendelsesoplysninger. Brug kun dokumenterede feltnavne og værdier.
- Vælg et eksplicit omfang for deduplikering. Et gentaget sporingsnummer er ikke automatisk en dublet på tværs af alle transportører, forhandlere eller historiske forsendelser.
- Bevar en lokal forsendelsesidentifikator. Gem relationen mellem det udgående element og din ordre- eller forsendelsespost, også når API'et ikke accepterer brugerdefinerede referencefelter.
Ved Carrier Tracking på tværs af flere netværk må du ikke udlede transportøren udelukkende ud fra et sporingsnummers længde eller præfiks, medmindre denne slutning er pålidelig i netop din arbejdsgang. Når API'et understøtter transportøridentifikation, skal du følge den dokumenterede håndtering af tvetydighed.
Illustrativ anmodningsstruktur
Følgende JSON viser princippet i en batch-payload. Wrapperen, egenskabsnavnene og identifikatorerne er illustrative og udgør ikke et 17TRACK-request-schema. Nogle API'er forventer et array på øverste niveau i stedet for et objekt, der indeholder et array.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Opbyg payloaden gennem en JSON-serialiser i stedet for at sammenkæde strenge. Send godkendelsesoplysninger via den dokumenterede mekanisme, og hold dem ude af kildekontrol, browserleveret kode og almindelige logs.
Behandl svaret på to niveauer
En batch-anmodning har et resultat på transportniveau og et resultat på applikationsniveau. Din integration skal evaluere begge.
Niveau 1: Modtog anmodningen et brugbart svar?
Begynd med HTTP-status, svarheaders og svarbody. Godkendelsesfejl, forkert udformede anmodninger, hastighedsbegrænsning og serverfejl kan forhindre normal behandling af elementer. En netværkstimeout er anderledes: Klienten ved muligvis ikke, om serveren modtog eller behandlede anmodningen.
HTTP-semantik er defineret i RFC 9110. Udbyderens dokumentation bestemmer dog, hvordan dens resultatfelter på applikationsniveau skal knyttes til de faktiske resultater for forsendelserne.
Niveau 2: Hvad skete der med hver forsendelse?
Hvis svaret understøtter resultater på elementniveau, skal du kategorisere hver indsendt post. Antag ikke, at HTTP 200 betyder, at alle poster lykkedes, eller at en resultatliste bevarer rækkefølgen fra anmodningen, medmindre kontrakten udtrykkeligt garanterer det.
- Accepteret: Handlingen lykkedes i henhold til endpointets dokumenterede definition.
- Permanent inputfejl: Ret eller undersøg posten, før du forsøger igen.
- Fejl, der kan forsøges igen: Planlæg et nyt forsøg i henhold til udbyderens vejledning om gentagne forsøg.
- Ukendt resultat: Svaret mangler, er ufuldstændigt eller kan ikke knyttes sikkert til den indsendte post.
Hold svar som “already registered” eller lignende dubletrelaterede svar adskilt, indtil du forstår deres dokumenterede betydning. De kan indikere, at den ønskede tilstand allerede findes, men de bør ikke automatisk behandles som bekræftelse af ejerskab, konfiguration eller abonnement.
Efter behandling af et svar skal hver inputpost have præcis ét lokalt resultat. En nyttig afstemningskontrol er: indsendte poster er lig med accepterede poster plus permanente fejl plus fejl, der kan forsøges igen, plus ukendte resultater. Dette er en lokal regnskabsregel og ikke et påkrævet format for API-svaret.
Håndtér delvise fejl uden at afspille vellykkede poster igen
Antag, at en illustrativ batch indeholder ti forsendelser: syv accepteres, to har ugyldige obligatoriske felter, og én rammes af en dokumenteret midlertidig fejl. Gem de syv vellykkede resultater, send de to ugyldige poster til rettelse, og gentag kun forsøget for den midlertidige fejl.
Hvis alle ti poster afspilles igen, skabes unødvendig trafik, og håndteringen af dubletter kan blive mere kompliceret. Det bliver også sværere at skelne mellem en oprindelig afvisning og et senere dubletrelateret svar.
| Resultat | Anbefalet handling |
|---|---|
| Ugyldigt felt eller ikke-understøttet værdi | Ret inputtet; gentag ikke forsøget uændret |
| Godkendelses- eller tilladelsesfejl | Sæt det berørte arbejde på pause, og ret legitimationsoplysninger eller adgang |
| Svar om hastighedsbegrænsning | Vent i henhold til den dokumenterede vejledning og relevante svarheaders |
| Midlertidig fejl på elementniveau | Gentag forsøget for elementet med et begrænset antal forsøg og backoff |
| Timeout efter indsendelse | Markér resultatet som usikkert; afstem det, eller brug dokumenterede garantier for sikker gentagelse |
| Ukendt eller ufuldstændigt resultat | Bevar dokumentationen, og undersøg i stedet for at antage succes |
HTTP 429 betyder for mange anmodninger, og svaret kan indeholde en Retry-After-header som beskrevet i RFC 6585. Antag ikke, at headeren altid er til stede. Når der ikke angives en eksplicit forsinkelse, skal du bruge en begrænset backoff-politik, der stemmer overens med API-dokumentationen.
Tilføj jitter for at sprede gentagne forsøg fra flere workers, angiv et maksimalt antal forsøg eller en maksimal retry-alder, og send poster, hvor forsøgene er opbrugt, til en gennemgangskø. Uendelige gentagne forsøg kan skjule et vedvarende konfigurationsproblem.
Hvorfor timeouts kræver særlig behandling
En timeout beviser ikke en afvisning. Serveren kan have accepteret batchen, før forbindelsen blev afbrudt. Automatisk gentagelse af en tilstandsændrende anmodning kan derfor udføre arbejdet igen.
Hvis endpointet understøtter dokumenterede idempotency keys, skal du følge dets regler, herunder nøglens omfang og opbevaring. Opfind ikke en idempotency-header og antag, at serveren respekterer den. Brug ellers et understøttet opslag eller en afstemningsarbejdsgang til at afgøre, om den ønskede tilstand findes, før du indsender igen. Lokal deduplikering hjælper med at koordinere dine egne workers, men garanterer ikke idempotens på serversiden.
En praktisk arbejdsgang til batchbehandling
Hold udbyderspecifikke detaljer i en adapter, så køen, planlægningen af gentagne forsøg og overvågningslogikken ikke afhænger af rå svarfeltnavne.
validér poster, og bevar lokale forsendelses-ID'er
løs dubletter inden for det tilsigtede forretningsomfang
opdel poster ved hjælp af dokumenterede grænser for elementer og payload
for hver batch gennem en begrænset worker-pulje:
gem et forsøgsrecord før afsendelse
vent på den fælles hastighedsbegrænser
send via den udbyderspecifikke adapter
hvis resultatet er usikkert:
læg afstemning i kø
fortsæt
kategorisér resultater på anmodnings- og elementniveau
gem ét resultat for hver indsendt post
planlæg kun berettigede fejl til nyt forsøg
send ugyldige eller udtømte poster til gennemgang
Gør lagring af resultater og planlægning af gentagne forsøg genoprettelig. Et permanent jobrecord eller et transaktionelt kømønster kan f.eks. forhindre, at et procesnedbrud mister beslutningen om et nyt forsøg. Når workers genstarter, skal de kunne skelne mellem ikke-afsendt arbejde og arbejde, hvis fjernresultat stadig er usikkert.
Gør batchstørrelsen til en konfigurerbar indstilling, der er knyttet til det relevante endpoint, i stedet for en konstant, der er spredt i hele kodebasen. En mindre batch kan være nyttig ved fejlfinding eller isolering af problematiske poster; den største tilladte batch er ikke automatisk den bedste driftsstørrelse.
Overvåg resultater for forsendelser, ikke kun HTTP-oppetid
API Monitoring skal vise, om forsendelserne når den ønskede tilstand. Et dashboard, der kun rapporterer HTTP-succesrater, kan overse delvise fejl i svar, der ellers lykkes.
- Acceptprocent på elementniveau: Accepterede poster divideret med indsendte poster, med en tydeligt defineret behandling af gentagne forsøg.
- Fordeling af fejl: Antal efter endpoint, dokumenteret fejlkode og relevant transportørkontekst.
- Ukendte resultater: Ikke-afstemte poster, og hvor længe de har været uafklarede.
- Retry-efterslæb: Afventende gentagne forsøg, højeste alder for et forsøg og opbrugte forsøg.
- Anmodningstilstand: Svartid, timeouts, hastighedsbegrænsning og serverfejl.
- Aktualitet for sporing: Om accepterede forsendelser efterfølgende modtager brugbare sporingsoplysninger.
Accept af registrering er ikke bevis på en ny scanning hos transportøren. Hold API-behandlingsstatus adskilt fra forsendelsens bevægelse og dataaktualitet, så en integrationshændelse ikke forveksles med en leveringsforsinkelse.
Log lokale batch-ID'er, forsendelsesreferencer, antal forsøg, dokumenterede fejlkoder og udbyderens request-ID'er, når de er tilgængelige. Redigér legitimationsoplysninger og unødvendige personlige oplysninger. Brug kun sporingsidentifikatorer, hvor det er nødvendigt af driftsmæssige årsager, og undgå at placere rå forsendelsesidentifikatorer i metric-labels med høj kardinalitet.
Test disse tilfælde før produktion
Brug en dokumenteret sandbox eller et kontrolleret testmiljø, hvor det er muligt. Antag ikke, at opfundne sporingsnumre giver forudsigelige produktionssvar.
- Indsend en gyldig batch ved den dokumenterede elementgrænse, og test derefter, hvordan klienten forhindrer en for stor batch.
- Kontrollér, at sporingsnumre med indledende nuller overlever serialisering og lagring.
- Test blandede accepterede og afviste elementer uden at gentage forsøget for vellykkede poster.
- Simulér hastighedsbegrænsning, og bekræft, at flere workers respekterer den samme grænse.
- Simulér en timeout efter indsendelse, og kontrollér afstemningsforløbet.
- Genstart en worker mellem modtagelse af svaret og lokal lagring.
- Test manglende, ukendte eller ikke-matchbare resultater på elementniveau.
- Bekræft, at ugyldige poster når en synlig korrektionskø i stedet for at blive forsøgt igen for evigt.
En produktionsklar integration kan forklare tilstanden for hver indsendt forsendelse, inklusive dem hvis resultat midlertidigt er ukendt. Det er nyttigt at reducere antallet af anmodninger; det vigtigere designmål er at bevare denne ansvarlighed.
FAQ
Hvor mange sporingsnumre kan jeg sende i én anmodning?
Brug den grænse, der er dokumenteret for det præcise endpoint og den præcise API-version. Kontrollér også anmodningsstørrelse, hastighedsgrænser og eventuelle kontospecifikke begrænsninger. Der findes ikke et sikkert universelt antal, der kan anvendes på tværs af Tracking API'er eller forskellige handlinger i ét API.
Kan ét ugyldigt sporingsnummer få hele batchen til at mislykkes?
Ja, afhængigt af endpointets valideringsregler. Nogle API'er returnerer individuelle afvisninger, mens andre kan afvise en anmodning, før elementerne behandles. Kontrollér både fejl på anmodningsniveau og resultater på elementniveau; antag ikke, at alle batch-endpoints understøtter delvis accept.
Skal jeg gentage en batch, når HTTP-svaret lykkes?
Ikke automatisk. Fortolk først den dokumenterede status på applikationsniveau og resultaterne for de enkelte elementer. Gem vellykkede poster, og gentag kun forsøget for berettigede fejl. Hvis resultatet ikke kan fortolkes sikkert, skal du klassificere det som usikkert og undersøge det.
Kan jeg blande transportører i den samme batch?
Kun når endpointet understøtter denne anmodningsstruktur. Bekræft, om transportøroplysninger leveres pr. forsendelse, om automatisk identifikation understøttes, og hvad der sker, når identifikationen er tvetydig. En multi-carrier-tjeneste fastlægger ikke i sig selv batching-reglerne for hvert endpoint.
Gør batching, at sporingsopdateringer ankommer hurtigere?
Batching kan reducere antallet af anmodninger, som din applikation sender, men det får ikke i sig selv transportørhændelser til at blive synlige hurtigere. Registrering, hentning af data, tilgængelighed af transportørscanninger og levering af opdateringer er separate dele af arbejdsgangen.
Kilder
- 17TRACK Tracking API — officiel produktindgang for udviklere, der evaluerer en sporingsintegration.
- 17TRACK API documentation — reference for den udbyderspecifikke endpoint-kontrakt, grænser, godkendelse og svarhåndtering.
- RFC 9110: HTTP Semantics — HTTP-statussemantik, idempotens, automatiske gentagne forsøg og Retry-After.
- RFC 6585: Additional HTTP Status Codes — definition af HTTP 429 Too Many Requests og den valgfri Retry-After-header.


