Så skickar du flera spårningsnummer i en API-begäran (batchgränser och partiella fel)
För att skicka flera spårningsnummer i en API-begäran använder du en Tracking API-slutpunkt som uttryckligen accepterar batchar, formaterar varje försändelse enligt dess begärandeschema och delar upp större listor i batchar inom de dokumenterade gränserna. Kontrollera sedan både HTTP-svaret och resultatet för varje försändelse: en lyckad HTTP-begäran innebär inte nödvändigtvis att alla spårningsnummer accepterades. Försök endast igen med berättigade fel och stäm av osäkra resultat innan du skickar om en hel batch.

Den här guiden är avsedd för utvecklare som ansluter försändelsespårning till ett orderhanteringssystem, en lagerplattform, en e-handelsapplikation eller en intern instrumentpanel. Målet är inte bara att skicka färre begäranden. Det handlar om att redovisa varje försändelse utan att skapa dubbelarbete eller förlora misslyckade poster.
Identifiera först vad batch-slutpunkten faktiskt gör
En spårningsintegration kan omfatta flera olika åtgärder. Registrering av försändelser, hämtning av deras senaste spårningsinformation och mottagande av efterföljande uppdateringar är inte utbytbara.
- Registrering: Skicka in försändelser så att tjänsten kan börja spåra dem eller fortsätta spåra dem.
- Uppslagning: Begär spårningsinformation för försändelser, i enlighet med slutpunktens regler för hämtning.
- Uppdatering av leverans: Ta emot senare ändringar genom en stödd mekanism, till exempel webhooks, eller hämta dem genom schemalagda begäranden.
Kontrollera dokumentationen för den exakta åtgärd du behöver. Att en registreringsslutpunkt accepterar flera poster innebär inte att en uppslagningsslutpunkt accepterar samma antal, använder samma schema eller har samma hastighetsgräns.
För en 17TRACK-integration börjar du på produktsidan för Tracking API och använder den officiella API-dokumentationen för att bekräfta åtgärden, autentiseringsmetoden, begärandeformatet och svarsfälten. Betrakta exemplen nedan som implementeringsmönster, inte som en ersättning för det API-avtalet.
Batchgränser handlar om mer än det maximala antalet försändelser
Det finns ingen universell batchgräns för ett Tracking API. Gränserna kan skilja sig åt beroende på leverantör, slutpunkt, API-version och kontokonfiguration. Innan du implementerar batchhantering bör du registrera dessa begränsningar separat.
| Begränsning | Vad som ska bekräftas | Konsekvens för implementeringen |
|---|---|---|
| Poster per begäran | Maximalt antal poster för den specifika åtgärden | Dela upp indatalistan innan den skickas |
| Storlek på begärandetext | Eventuell dokumenterad bytegräns | Ta hänsyn till valfria fält och serialiseringsstorlek |
| Begärandefrekvens | Tillåtna begäranden under ett definierat intervall | Håll rätt takt på begäranden genom en gemensam begränsare |
| Samtidighet | Eventuell begränsning av samtidiga begäranden | Begränsa antalet aktiva arbetare |
| Användningsredovisning | Om användningen räknas per begäran, försändelse eller annan enhet | Beräkna förbrukningen separat från begärandevolymen |
Om en hypotetisk slutpunkt till exempel tillåter 25 poster per begäran kräver 63 poster tre begäranden med 25, 25 respektive 13 poster. Dessa siffror illustrerar endast uppdelning; de är inte angivna 17TRACK-gränser.
Anta inte att batchhantering minskar den debiterbara användningen. Den kan minska omkostnaderna för HTTP-begäranden, men eventuell påverkan på kostnaderna beror på leverantörens faktiska redovisningsregler. På samma sätt innebär en giltig batchstorlek inte att ett obegränsat antal parallella begäranden är tillåtna.
Förbered posterna innan du bygger begäran
De flesta undvikbara batchfel börjar med förberedelsen av indata. Validera varje försändelse innan du lägger till den i en batch, men undvik regler som oavsiktligt avvisar legitima spårningsnummer från olika transportörer.
- Bevara spårningsnummer som strängar. Om du konverterar dem till tal kan inledande nollor försvinna eller långa identifierare ändras.
- Ta bort oavsiktliga omgivande blanksteg. Ta inte bort interna tecken eller ändra skiftläge om inte den relevanta specifikationen tillåter sådan normalisering.
- Validera obligatoriska fält. Vissa arbetsflöden kan kräva en transportörsidentifierare eller ytterligare försändelseinformation. Använd endast dokumenterade fältnamn och värden.
- Välj ett uttryckligt omfång för deduplicering. Ett upprepat spårningsnummer är inte automatiskt en dubblett för alla transportörer, handlare eller historiska försändelser.
- Behåll en lokal försändelseidentifierare. Lagra relationen mellan den utgående posten och din order- eller försändelsepost, även när API:t inte accepterar anpassade referensfält.
För Carrier Tracking över flera nätverk ska du inte enbart härleda transportören från ett spårningsnummers längd eller prefix om den slutsatsen inte är tillförlitlig för ditt specifika arbetsflöde. När API:t stöder transportörsidentifiering ska du följa dess dokumenterade hantering av tvetydigheter.
Illustrativ begärandestruktur
Följande JSON visar konceptet för en batchnyttolast. Omslaget, egenskapsnamnen och identifierarna är illustrativa och utgör inte ett 17TRACK-begärandeschema. Vissa API:er förväntar sig en array på toppnivå i stället för ett objekt som innehåller en array.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Bygg nyttolasten genom en JSON-serialiserare i stället för att sammanfoga strängar. Skicka autentiseringsuppgifter genom den dokumenterade mekanismen och håll dem borta från källkodshantering, kod som levereras till webbläsare och rutinloggar.
Bearbeta svaret på två nivåer
En batchbegäran har ett resultat på transportnivå och ett resultat på applikationsnivå. Din integration måste utvärdera båda.
Nivå 1: Tog begäran emot ett användbart svar?
Börja med HTTP-statusen, svarshuvudena och svarstexten. Autentiseringsfel, felaktigt formaterade begäranden, hastighetsbegränsning och serverfel kan förhindra normal bearbetning av poster. En timeout i nätverket är annorlunda: klienten kanske inte vet om servern tog emot eller bearbetade begäran.
HTTP-semantik definieras i RFC 9110. Leverantörens dokumentation avgör dock hur dess resultatfält på applikationsnivå motsvarar faktiska försändelseresultat.
Nivå 2: Vad hände med varje försändelse?
Om svaret stöder resultat på postnivå ska du klassificera varje inskickad post. Anta inte att HTTP 200 innebär att varje post lyckades eller att en resultatlista bevarar begärandeordningen, såvida avtalet inte uttryckligen garanterar detta.
- Accepterad: Åtgärden lyckades enligt slutpunktens dokumenterade definition.
- Permanent indataproblem: Korrigera eller undersök posten innan ett nytt försök.
- Försöksbart fel: Schemalägg ett nytt försök enligt leverantörens riktlinjer för nya försök.
- Okänt resultat: Svaret saknas, är ofullständigt eller kan inte säkert kopplas till den inskickade posten.
Håll svar som ”redan registrerad” eller liknande dubblettrelaterade svar åtskilda tills du förstår deras dokumenterade innebörd. De kan innebära att det önskade tillståndet redan finns, men ska inte automatiskt behandlas som en bekräftelse på ägarskap, konfiguration eller prenumeration.
Efter att ett svar har bearbetats ska varje indatapost ha exakt ett lokalt resultat. En användbar avstämningskontroll är: inskickade poster är lika med accepterade poster plus permanenta fel plus försöksbara fel plus okända resultat. Detta är en lokal redovisningsregel och inte ett obligatoriskt API-svarsformat.
Hantera partiella fel utan att spela upp lyckade poster igen
Anta att en illustrativ batch innehåller tio försändelser: sju accepteras, två har ogiltiga obligatoriska fält och en drabbas av ett dokumenterat tillfälligt fel. Spara de sju lyckade resultaten, skicka de två ogiltiga posterna för korrigering och försök endast igen med det tillfälliga felet.
Att skicka om alla tio poster skapar onödig trafik och kan försvåra hanteringen av dubbletter. Det gör det också svårare att skilja ett ursprungligt avvisande från ett senare dubblettrelaterat svar.
| Resultat | Rekommenderad åtgärd |
|---|---|
| Ogiltigt fält eller värde som inte stöds | Korrigera indata; försök inte igen utan ändringar |
| Autentiserings- eller behörighetsfel | Pausa berört arbete och åtgärda autentiseringsuppgifter eller åtkomst |
| Svar om hastighetsbegränsning | Vänta enligt dokumenterade riktlinjer och tillämpliga svarshuvuden |
| Tillfälligt fel på postnivå | Försök igen med posten med ett begränsat antal försök och backoff |
| Timeout efter inskickning | Markera som osäkert; stäm av eller använd dokumenterade garantier för säker återförsökning |
| Oigenkännbart eller ofullständigt resultat | Bevara bevis och undersök i stället för att anta att det lyckades |
HTTP 429 betyder för många begäranden och svaret kan innehålla ett Retry-After-huvud, enligt beskrivningen i RFC 6585. Anta inte att detta huvud alltid finns. När ingen uttrycklig väntetid för nya försök anges ska du använda en begränsad backoff-policy som överensstämmer med API-dokumentationen.
Lägg till jitter för att sprida nya försök från flera arbetare, ange ett maximalt antal försök eller en maximal försöksålder och skicka poster där försöken uttömts till en granskningskö. Oändliga nya försök kan dölja ett bestående konfigurationsproblem.
Varför timeouts kräver särskild hantering
En timeout bevisar inte att begäran avvisades. Servern kan ha accepterat batchen innan anslutningen bröts. Att automatiskt spela upp en tillståndsändrande begäran igen kan därför upprepa arbetet.
Om slutpunkten stöder dokumenterade idempotensnycklar ska du följa dess regler, inklusive nyckelns omfång och lagringstid. Hitta inte på ett idempotenshuvud och anta att servern respekterar det. Använd annars en stödd uppslagnings- eller avstämningsprocess för att avgöra om det önskade tillståndet finns innan du skickar om begäran. Lokal deduplicering hjälper till att samordna dina egna arbetare men garanterar inte idempotens på serversidan.
Ett praktiskt arbetsflöde för batchbearbetning
Håll leverantörsspecifika detaljer i en adapter så att kön, schemaläggaren för nya försök och övervakningslogiken inte är beroende av råa svarsfältnamn.
validate records and retain local shipment IDs
resolve duplicates within the intended business scope
split records using documented item and payload limits
for each batch through a bounded worker pool:
persist an attempt record before sending
wait for the shared rate limiter
send using the provider-specific adapter
if the outcome is uncertain:
enqueue reconciliation
continue
classify request-level and item-level outcomes
persist one outcome for every submitted record
schedule only eligible failures for retry
route invalid or exhausted records for review
Gör lagringen av resultat och schemaläggningen av nya försök återställningsbara. Till exempel kan en beständig jobbpost eller ett transaktionellt kömönster förhindra att en processkrasch gör att beslutet om ett nytt försök går förlorat. När arbetare startas om ska de kunna skilja oskickat arbete från arbete vars fjärrresultat fortfarande är osäkert.
Använd batchstorlek som en konfigurerbar inställning kopplad till den relevanta slutpunkten, inte som en konstant som är utspridd i kodbasen. En mindre batch kan vara användbar vid felsökning eller för att isolera problematiska poster; den största tillåtna batchen är inte automatiskt den bästa driftstorleken.
Övervaka försändelseresultat, inte bara HTTP-driftstid
API Monitoring ska visa om försändelser når det avsedda tillståndet. En instrumentpanel som endast rapporterar HTTP-framgångsfrekvenser kan missa partiella fel i annars lyckade svar.
- Acceptansgrad på postnivå: Accepterade poster dividerat med inskickade poster, med en tydligt definierad hantering av nya försök.
- Felfördelning: Antal per slutpunkt, dokumenterad felkod och relevant transportörskontext.
- Okända resultat: Ej avstämda poster och hur länge de har förblivit olösta.
- Backlogg för nya försök: Väntande nya försök, ålder på det äldsta nya försöket och uttömda försök.
- Begärandehälsa: Fördröjning, timeouts, hastighetsbegränsning och serverfel.
- Spårningsaktualitet: Om accepterade försändelser senare får användbar spårningsinformation.
Acceptans av registrering är inte ett bevis på en ny transportörsskanning. Håll API-bearbetningsstatus åtskild från försändelsens förflyttning och datans aktualitet, så att en integrationsincident inte förväxlas med en leveransförsening.
Logga lokala batch-ID:n, försändelsereferenser, antal försök, dokumenterade felkoder och leverantörens begärande-ID:n när sådana finns. Maskera autentiseringsuppgifter och onödig personlig information. Använd spårningsidentifierare endast där det behövs i verksamheten och undvik att placera råa försändelseidentifierare i etiketter för mätvärden med hög kardinalitet.
Testa dessa fall före produktion
Använd en dokumenterad sandlåda eller kontrollerad testmiljö när sådan finns. Anta inte att påhittade spårningsnummer ger förutsägbara produktionssvar.
- Skicka in en giltig batch vid den dokumenterade postgränsen och testa sedan hur klienten förhindrar en för stor batch.
- Verifiera att spårningsnummer med inledande nollor överlever serialisering och lagring.
- Testa blandade accepterade och avvisade poster utan att försöka igen med lyckade poster.
- Simulera hastighetsbegränsning och bekräfta att flera arbetare respekterar samma gräns.
- Simulera en timeout efter inskickning och verifiera avstämningsvägen.
- Starta om en arbetare mellan mottagandet av svaret och den lokala lagringen.
- Testa saknade, okända eller omatchningsbara resultat på postnivå.
- Bekräfta att ogiltiga poster når en synlig korrigeringskö i stället för att försöka igen för evigt.
En produktionsklar integration kan förklara tillståndet för varje inskickad försändelse, inklusive sådana vars resultat tillfälligt är okänt. Att minska antalet begäranden är användbart; att bevara denna ansvarsskyldighet är det viktigare designmålet.
Vanliga frågor
Hur många spårningsnummer kan jag skicka i en begäran?
Använd gränsen som dokumenterats för den exakta slutpunkten och API-versionen. Kontrollera även begärandestorlek, hastighetsgränser och eventuella kontospecifika begränsningar. Det finns inget säkert universellt antal som kan tillämpas på alla spårnings-API:er eller på olika åtgärder inom ett och samma API.
Kan ett ogiltigt spårningsnummer få hela batchen att misslyckas?
Ja, beroende på slutpunktens valideringsregler. Vissa API:er returnerar individuella avvisanden, medan andra kan avvisa en begäran innan posterna bearbetas. Kontrollera både fel på begärandenivå och resultat på postnivå; anta inte att alla batch-slutpunkter stöder partiell acceptans.
Bör jag försöka igen med en batch när HTTP-svaret är lyckat?
Inte automatiskt. Tolka först den dokumenterade statusen på applikationsnivå och resultaten för posterna. Spara lyckade poster och försök endast igen med berättigade fel. Om resultatet inte kan tolkas säkert ska du klassificera det som osäkert och undersöka saken.
Kan jag blanda transportörer i samma batch?
Endast när slutpunkten stöder den begärandestrukturen. Bekräfta om transportörsinformation anges per försändelse, om automatisk identifiering stöds och vad som händer när identifieringen är tvetydig. En tjänst med flera transportörer fastställer inte i sig reglerna för batchhantering i varje slutpunkt.
Gör batchhantering att spårningsuppdateringar kommer snabbare?
Batchhantering kan minska antalet begäranden som din applikation skickar, men gör inte i sig att transportörshändelser visas tidigare. Registrering, datahämtning, tillgänglighet av transportörsskanningar och leverans av uppdateringar är separata delar av arbetsflödet.
Källor
- 17TRACK Tracking API — officiell produktingång för utvecklare som utvärderar en spårningsintegration.
- 17TRACK API-dokumentation — referens för leverantörens specifika slutpunktsavtal, begränsningar, autentisering och svarshantering.
- RFC 9110: HTTP Semantics — HTTP-statussemantik, idempotens, automatiska nya försök och Retry-After.
- RFC 6585: Additional HTTP Status Codes — definition av HTTP 429 Too Many Requests och dess valfria Retry-After-huvud.


