Skip to main content
HemBloggGuiderSå skickar du flera spårningsnummer i en API-begäran (batchgränser och partiella fel)

Så skickar du flera spårningsnummer i en API-begäran (batchgränser och partiella fel)

17TRACK

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.

Så skickar du flera spårningsnummer i en API-begäran

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änsningVad som ska bekräftasKonsekvens för implementeringen
Poster per begäranMaximalt antal poster för den specifika åtgärdenDela upp indatalistan innan den skickas
Storlek på begärandetextEventuell dokumenterad bytegränsTa hänsyn till valfria fält och serialiseringsstorlek
BegärandefrekvensTillåtna begäranden under ett definierat intervallHåll rätt takt på begäranden genom en gemensam begränsare
SamtidighetEventuell begränsning av samtidiga begärandenBegränsa antalet aktiva arbetare
AnvändningsredovisningOm användningen räknas per begäran, försändelse eller annan enhetBerä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.

  1. Bevara spårningsnummer som strängar. Om du konverterar dem till tal kan inledande nollor försvinna eller långa identifierare ändras.
  2. Ta bort oavsiktliga omgivande blanksteg. Ta inte bort interna tecken eller ändra skiftläge om inte den relevanta specifikationen tillåter sådan normalisering.
  3. 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.
  4. 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.
  5. 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.

ResultatRekommenderad åtgärd
Ogiltigt fält eller värde som inte stödsKorrigera indata; försök inte igen utan ändringar
Autentiserings- eller behörighetsfelPausa berört arbete och åtgärda autentiseringsuppgifter eller åtkomst
Svar om hastighetsbegränsningVä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 inskickningMarkera som osäkert; stäm av eller använd dokumenterade garantier för säker återförsökning
Oigenkännbart eller ofullständigt resultatBevara 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.

  1. Skicka in en giltig batch vid den dokumenterade postgränsen och testa sedan hur klienten förhindrar en för stor batch.
  2. Verifiera att spårningsnummer med inledande nollor överlever serialisering och lagring.
  3. Testa blandade accepterade och avvisade poster utan att försöka igen med lyckade poster.
  4. Simulera hastighetsbegränsning och bekräfta att flera arbetare respekterar samma gräns.
  5. Simulera en timeout efter inskickning och verifiera avstämningsvägen.
  6. Starta om en arbetare mellan mottagandet av svaret och den lokala lagringen.
  7. Testa saknade, okända eller omatchningsbara resultat på postnivå.
  8. 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