Slik sender du flere sporingsnumre i én API-forespørsel (batchgrenser og delvise feil)
For å sende flere sporingsnumre i én API-forespørsel bruker du et Tracking API-endepunkt som uttrykkelig støtter batchbehandling, formaterer hver forsendelse i henhold til forespørselsskjemaet og deler større lister opp i batcher innenfor de dokumenterte grensene. Kontroller deretter både HTTP-responsen og resultatet for hver forsendelse: En vellykket HTTP-forespørsel betyr ikke nødvendigvis at alle sporingsnumrene ble godkjent. Prøv bare på nytt ved kvalifiserte feil, og avklar usikre resultater før du sender inn en hel batch på nytt.

Denne veiledningen er for utviklere som kobler forsendelsessporing til et ordrebehandlingssystem, en lagerplattform, en e-handelsapplikasjon eller et internt dashbord. Målet er ikke bare å sende færre forespørsler, men å ta hensyn til hver forsendelse uten å opprette dobbeltarbeid eller miste mislykkede poster.
Identifiser først hva batch-endepunktet faktisk gjør
En sporingsintegrasjon kan omfatte flere ulike operasjoner. Registrering av forsendelser, henting av den nyeste sporingsinformasjonen og mottak av senere oppdateringer er ikke det samme.
- Registrering: Send inn forsendelser slik at tjenesten kan starte eller opprettholde sporingen av dem.
- Oppslag: Be om sporingsinformasjon for forsendelser, i henhold til endepunktets regler for henting.
- Leveringsoppdatering: Motta senere endringer gjennom en støttet mekanisme, for eksempel webhooks, eller hent dem gjennom planlagte forespørsler.
Kontroller dokumentasjonen for den nøyaktige operasjonen du trenger. Et registreringsendepunkt som godtar flere poster, betyr ikke at et oppslagsendepunkt godtar samme antall, bruker samme skjema eller har samme hastighetsgrense.
For en 17TRACK-integrasjon kan du starte med produktsiden for Tracking API og bruke den offisielle API-dokumentasjonen for å bekrefte operasjonen, autentiseringsmetoden, forespørselsformatet og responsfeltene. Se på eksemplene nedenfor som implementasjonsmønstre, ikke som en erstatning for API-kontrakten.
Batchgrenser handler om mer enn maksimalt antall forsendelser
Det finnes ingen universell batchgrense for et Tracking API. Grensene kan variere etter leverandør, endepunkt, API-versjon og kontokonfigurasjon. Før du implementerer batchbehandling, bør du registrere disse begrensningene separat.
| Begrensning | Hva som må bekreftes | Konsekvens for implementeringen |
|---|---|---|
| Elementer per forespørsel | Maksimalt antall poster for den aktuelle operasjonen | Del inndatalisten før sending |
| Størrelse på forespørselsteksten | Eventuell dokumentert bytegrense | Ta hensyn til valgfrie felt og serialiseringsstørrelse |
| Forespørselsfrekvens | Tillatte forespørsler i et definert tidsintervall | Reguler forespørslene gjennom en felles begrenser |
| Samtidighet | Eventuelle begrensninger på samtidige forespørsler | Begrens antallet aktive arbeidere |
| Bruksberegning | Om bruken telles per forespørsel, forsendelse eller annen enhet | Beregn forbruk separat fra forespørselsvolumet |
Hvis et hypotetisk endepunkt for eksempel tillater 25 poster per forespørsel, krever 63 poster tre forespørsler med henholdsvis 25, 25 og 13 poster. Tallene illustrerer bare oppdeling; de er ikke oppgitte 17TRACK-grenser.
Ikke anta at batchbehandling reduserer fakturerbar bruk. Den kan redusere HTTP-overhead, men eventuell påvirkning på kostnader avhenger av leverandørens faktiske beregningsregler. En gyldig batchstørrelse gir heller ikke tillatelse til ubegrensede parallelle forespørsler.
Forbered poster før du bygger forespørselen
De fleste unngåelige batchfeil starter med forberedelsen av inndata. Valider hver forsendelse før du legger den til i en batch, men unngå regler som utilsiktet avviser legitime sporingsnumre fra ulike transportører.
- Bevar sporingsnumre som tekststrenger. Hvis du konverterer dem til tall, kan innledende nuller forsvinne eller lange identifikatorer bli endret.
- Fjern utilsiktede mellomrom rundt verdien. Ikke fjern interne tegn eller endre store og små bokstaver med mindre den relevante spesifikasjonen tillater slik normalisering.
- Valider obligatoriske felt. Noen arbeidsflyter kan kreve en transportør-ID eller ytterligere forsendelsesinformasjon. Bruk bare dokumenterte feltnavn og verdier.
- Velg et tydelig omfang for deduplisering. Et gjentatt sporingsnummer er ikke automatisk en duplikat på tvers av alle transportører, forhandlere eller historiske forsendelser.
- Behold en lokal forsendelses-ID. Lagre forbindelsen mellom det utgående elementet og ordre- eller forsendelsesposten, selv når API-et ikke godtar egendefinerte referansefelt.
Ved Carrier Tracking på tvers av flere nettverk bør du ikke utlede transportøren utelukkende fra lengden eller prefikset til et sporingsnummer, med mindre denne slutningen er pålitelig i den konkrete arbeidsflyten. Når API-et støtter identifisering av transportør, følger du den dokumenterte håndteringen av tvetydighet.
Illustrerende forespørselsstruktur
Følgende JSON viser konseptet med en batch-nyttelast. Wrapperen, egenskapsnavnene og identifikatorene er illustrerende, ikke et 17TRACK-forespørselsskjema. Noen API-er forventer en array på toppnivå i stedet for et objekt som inneholder en array.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Bygg nyttelasten gjennom en JSON-serialisering i stedet for å sette sammen strenger. Send autentiseringsopplysninger gjennom den dokumenterte mekanismen, og hold dem borte fra kildekontroll, kode som leveres til nettleseren og vanlige logger.
Behandle responsen på to nivåer
En batchforespørsel har et resultat på transportnivå og et resultat på applikasjonsnivå. Integrasjonen må evaluere begge.
Nivå 1: Mottok forespørselen et brukbart svar?
Start med HTTP-statusen, responsoverskriftene og responsen. Autentiseringsfeil, ugyldige forespørsler, hastighetsbegrensning og serverfeil kan hindre normal behandling av elementene. En nettverkstidsavbrudd er annerledes: Klienten vet kanskje ikke om serveren mottok eller behandlet forespørselen.
HTTP-semantikk er definert i RFC 9110. Leverandørens dokumentasjon avgjør imidlertid hvordan resultatfeltene på applikasjonsnivå knyttes til faktiske forsendelsesresultater.
Nivå 2: Hva skjedde med hver forsendelse?
Hvis responsen støtter resultater på elementnivå, klassifiserer du hver innsendte post. Ikke anta at HTTP 200 betyr at alle poster lyktes, eller at en resultatliste følger forespørselsrekkefølgen, med mindre kontrakten uttrykkelig garanterer dette.
- Godkjent: Operasjonen lyktes i henhold til endepunktets dokumenterte definisjon.
- Permanent inndatafeil: Rett opp eller undersøk posten før et nytt forsøk.
- Feil som kan prøves på nytt: Planlegg et nytt forsøk i henhold til leverandørens retningslinjer.
- Ukjent resultat: Responsen mangler, er ufullstendig eller kan ikke kobles sikkert til den innsendte posten.
Hold svar som «allerede registrert» eller andre duplikatrelaterte svar adskilt til du forstår den dokumenterte betydningen. De kan bety at ønsket tilstand allerede finnes, men skal ikke automatisk behandles som bekreftelse på eierskap, konfigurasjon eller abonnement.
Etter behandling av en respons skal hver inndatapost ha nøyaktig ett lokalt resultat. En nyttig avstemmingskontroll er: innsendte poster er lik godkjente poster pluss permanente feil pluss feil som kan prøves på nytt pluss ukjente resultater. Dette er en lokal regnskapsregel, ikke et påkrevd API-responsformat.
Håndter delvise feil uten å sende vellykkede poster på nytt
Anta at en illustrerende batch inneholder ti forsendelser: sju blir godkjent, to har ugyldige obligatoriske felt, og én får en dokumentert midlertidig feil. Lagre de sju vellykkede resultatene, send de to ugyldige postene til korrigering, og prøv bare den midlertidig mislykkede posten på nytt.
Hvis alle ti postene sendes på nytt, skapes unødvendig trafikk og duplikathåndteringen kan bli mer komplisert. Det blir også vanskeligere å skille et opprinnelig avslag fra et senere duplikatrelatert svar.
| Resultat | Anbefalt handling |
|---|---|
| Ugyldig felt eller verdi som ikke støttes | Rett opp inndataene; ikke prøv på nytt uten endringer |
| Autentiserings- eller tilgangsfeil | Sett berørt arbeid på pause og korriger legitimasjon eller tilgang |
| Hastighetsbegrensning | Vent i henhold til dokumenterte retningslinjer og relevante responsoverskrifter |
| Midlertidig feil på elementnivå | Prøv elementet på nytt med begrenset antall forsøk og gradvis lengre ventetid |
| Tidsavbrudd etter innsending | Marker som usikkert; avstem eller bruk dokumenterte garantier for trygg gjentakelse |
| Ukjent eller ufullstendig resultat | Behold bevis og undersøk i stedet for å anta at operasjonen lyktes |
HTTP 429 betyr for mange forespørsler, og responsen kan inneholde en Retry-After-overskrift, slik det beskrives i RFC 6585. Ikke anta at overskriften alltid finnes. Når ingen eksplisitt forsinkelse er oppgitt, bruker du en begrenset backoff-policy i samsvar med API-dokumentasjonen.
Legg til jitter for å spre nye forsøk fra flere arbeidere, angi et maksimalt antall forsøk eller en maksimal retry-alder, og send poster som har brukt opp forsøkene til en kontrollkø. Uendelige nye forsøk kan skjule et vedvarende konfigurasjonsproblem.
Hvorfor tidsavbrudd krever særskilt behandling
Et tidsavbrudd beviser ikke at forespørselen ble avvist. Serveren kan ha godtatt batchen før forbindelsen brøt. Automatisk gjentakelse av en forespørsel som endrer tilstand, kan derfor utføre arbeidet på nytt.
Hvis endepunktet støtter dokumenterte idempotency keys, følger du reglene for disse, inkludert omfang og oppbevaring. Ikke oppfinn en idempotency-header og anta at serveren respekterer den. Ellers bruker du et støttet oppslag eller en avstemmingsarbeidsflyt for å avgjøre om ønsket tilstand finnes før du sender inn på nytt. Lokal deduplisering hjelper med å koordinere egne arbeidere, men garanterer ikke idempotens på serversiden.
En praktisk arbeidsflyt for batchbehandling
Hold leverandørspesifikke detaljer i en adapter, slik at køen, planleggeren for nye forsøk og overvåkingslogikken ikke avhenger av rå responsfeltnavn.
valider poster og behold lokale forsendelses-ID-er
løs duplikater innenfor det tiltenkte forretningsomfanget
del poster ved hjelp av dokumenterte grenser for elementer og nyttelast
for hver batch gjennom en begrenset arbeiderpool:
lagre et forsøksregister før sending
vent på den felles hastighetsbegrenseren
send ved hjelp av den leverandørspesifikke adapteren
hvis resultatet er usikkert:
legg til avstemming i køen
fortsett
klassifiser resultater på forespørsels- og elementnivå
lagre ett resultat for hver innsendte post
planlegg bare kvalifiserte feil for nytt forsøk
send ugyldige poster eller poster som har brukt opp forsøkene til kontrollGjør lagring av resultater og planlegging av nye forsøk gjenopprettbar. En varig jobbpost eller et transaksjonelt kømønster kan for eksempel hindre at et prosesskrasj fører til at beslutningen om nytt forsøk går tapt. Når arbeidere starter på nytt, må de kunne skille mellom arbeid som ikke er sendt, og arbeid der det eksterne resultatet fortsatt er usikkert.
Bruk batchstørrelse som en konfigurerbar innstilling knyttet til det relevante endepunktet, ikke som en konstant spredt rundt i kodebasen. En mindre batch kan være nyttig ved feilsøking eller for å isolere problematiske poster; den største tillatte batchen er ikke automatisk den beste driftsstørrelsen.
Overvåk forsendelsesresultater, ikke bare HTTP-oppetid
API Monitoring bør vise om forsendelsene når ønsket tilstand. Et dashbord som bare rapporterer HTTP-suksessrate, kan overse delvise feil i ellers vellykkede svar.
- Elementgodkjenningsrate: Godkjente poster delt på innsendte poster, med en tydelig definisjon av hvordan nye forsøk behandles.
- Feilfordeling: Antall etter endepunkt, dokumentert feilkode og relevant transportørkontekst.
- Ukjente resultater: Ikke-avstemte poster og hvor lenge de har vært uavklarte.
- Kø for nye forsøk: Ventende nye forsøk, alder på det eldste forsøket og oppbrukte forsøk.
- Forespørselshelse: Ventetid, tidsavbrudd, hastighetsbegrensning og serverfeil.
- Aktualitet for sporing: Om godkjente forsendelser senere mottar brukbar sporingsinformasjon.
Godkjenning av registrering er ikke et bevis på en ny skanning fra transportøren. Hold API-behandlingsstatus adskilt fra forsendelsesbevegelse og dataenes aktualitet, slik at en integrasjonshendelse ikke forveksles med en leveringsforsinkelse.
Logg lokale batch-ID-er, forsendelsesreferanser, antall forsøk, dokumenterte feilkoder og leverandørens forespørsels-ID-er når de er tilgjengelige. Skjul legitimasjon og unødvendige personopplysninger. Bruk sporingsidentifikatorer bare når det er driftsmessig nødvendig, og unngå å plassere rå forsendelsesidentifikatorer i metrikktagger med høy kardinalitet.
Test disse tilfellene før produksjon
Bruk en dokumentert sandkasse eller et kontrollert testmiljø når det er tilgjengelig. Ikke anta at oppdiktede sporingsnumre gir forutsigbare produksjonssvar.
- Send inn en gyldig batch ved den dokumenterte elementgrensen, og test deretter hvordan klienten hindrer en for stor batch.
- Kontroller at sporingsnumre med innledende nuller overlever serialisering og lagring.
- Test en blanding av godkjente og avviste elementer uten å prøve vellykkede poster på nytt.
- Simuler hastighetsbegrensning og bekreft at flere arbeidere respekterer samme grense.
- Simuler et tidsavbrudd etter innsending og kontroller avstemmingsflyten.
- Start en arbeider på nytt mellom mottak av responsen og lokal lagring.
- Test manglende, ukjente eller elementresultater som ikke kan kobles til en post.
- Bekreft at ugyldige poster når en synlig korrigeringskø i stedet for å prøves på nytt for alltid.
En produksjonsklar integrasjon kan forklare tilstanden til hver innsendte forsendelse, også når resultatet midlertidig er ukjent. Det er nyttig å redusere antallet forespørsler, men det viktigste designmålet er å bevare denne sporbarheten.
Vanlige spørsmål
Hvor mange sporingsnumre kan jeg sende i én forespørsel?
Bruk grensen som er dokumentert for det nøyaktige endepunktet og API-versjonen. Kontroller også forespørselsstørrelse, hastighetsgrenser og eventuelle kontospesifikke begrensninger. Det finnes ikke ett trygt universelt antall som kan brukes på tvers av sporings-API-er eller ulike operasjoner i samme API.
Kan ett ugyldig sporingsnummer føre til at hele batchen mislykkes?
Ja, avhengig av endepunktets valideringsregler. Noen API-er returnerer individuelle avvisninger, mens andre kan avvise forespørselen før behandling av elementene. Kontroller både feil på forespørselsnivå og resultater på elementnivå; ikke anta at alle batch-endepunkter støtter delvis godkjenning.
Bør jeg prøve en batch på nytt når HTTP-responsen er vellykket?
Ikke automatisk. Analyser først den dokumenterte statusen på applikasjonsnivå og elementresultatene. Lagre vellykkede poster og prøv bare kvalifiserte feil på nytt. Hvis resultatet ikke kan tolkes på en trygg måte, klassifiser det som usikkert og undersøk saken.
Kan jeg blande transportører i samme batch?
Kun når endepunktet støtter denne forespørselsstrukturen. Bekreft om transportørinformasjon oppgis per forsendelse, om automatisk identifisering støttes, og hva som skjer når identifiseringen er tvetydig. En tjeneste med flere transportører fastslår ikke i seg selv batchreglene for hvert endepunkt.
Gjør batchbehandling at sporingsoppdateringer kommer raskere?
Batchbehandling kan redusere antallet forespørsler applikasjonen sender, men gjør ikke i seg selv at hendelser fra transportøren vises tidligere. Registrering, henting av data, tilgjengelighet av transportørskanninger og levering av oppdateringer er separate deler av arbeidsflyten.
Kilder
- 17TRACK Tracking API — offisiell produktside for utviklere som vurderer en sporingsintegrasjon.
- 17TRACK API-dokumentasjon — referanse for leverandørens endepunktkontrakt, grenser, autentisering og håndtering av svar.
- RFC 9110: HTTP Semantics — HTTP-statussemantikk, idempotens, automatiske nye forsøk og Retry-After.
- RFC 6585: Additional HTTP Status Codes — definisjon av HTTP 429 Too Many Requests og den valgfrie Retry-After-headeren.


