Vilka data bör ett spårnings-API returnera? 12 fält utöver aktuell status?
A tracking API bör returnera mer än en etikett som ”Under transport”. Utöver den aktuella statusen bör du leta efter försändelseidentifierare, transportörens identitet, detaljerad statusinformation, transportörens ursprungliga meddelanden, händelsehistorik, tidsstämplar för händelser, platser, leveransprognoser, undantag, överlämningar mellan transportörer, leveransdetaljer och metadata om informationens aktualitet. Tillsammans hjälper dessa 12 datagrupper utvecklare att bygga tillförlitliga arbetsflöden och ger driftteamen tillräckligt med sammanhang för att agera.

Detta är ett rekommenderat svarsavtal för utvecklare, tekniska inköpare och e-handels- och driftteam – inte ett påstående om att varje transportör eller API tillhandahåller varje fält. Vissa värden kommer legitimt att saknas. En bättre utformning gör dessa luckor tydliga i stället för att fylla dem med antaganden.
Vad gör spårningsdata användbar?
En aktuell status besvarar en enda avgränsad fråga: vilket sammanfattat tillstånd har försändelsen? Den förklarar inte nödvändigtvis vad som hände, när det hände, om informationen är aktuell eller vad någon bör göra härnäst.
Två försändelser kan till exempel båda visa ”Under transport” men kräva olika åtgärder. Den ena kan ha en nylig skanning på en anläggning och inga rapporterade problem. Den andra kan ha ett olöst adressproblem registrerat i sin händelsehistorik. En applikation som endast läser huvudstatusen kan missa den skillnaden.
Utvärdera svaret mot tre praktiska uppgifter: att koppla försändelsen till rätt order, att förklara dess förlopp korrekt och att avgöra om en åtgärd är motiverad. Följande fält stöder dessa uppgifter. Fältnamnen är illustrativa; de utgör ingen universell standard eller ett specifikt schema från en leverantör.
12 fält att utvärdera utöver den aktuella statusen
1. Försändelse- och spårningsidentifierare
Svaret bör identifiera den försändelse som beskrivs. Användbara värden omfattar det inskickade spårningsnumret, API:ets identifierare för spårningsposten och en kundreferens som ditt system kan koppla till en leverans- eller paketpost.
Utgå inte från att en order motsvarar en försändelse. En order kan delas upp på flera paket och en ersättningsleverans kan skapa en annan försändelse. Lagra spårningsposter på paket- eller leveransnivå och koppla dem sedan till ordern. Bevara spårningsnummer som strängar så att formatering och inledande nollor inte går förlorade.
2. Transportörens identitet
Leta efter en stabil transportörsidentifierare tillsammans med ett läsbart transportörsnamn. När det är möjligt bör svaret skilja mellan en transportör som uttryckligen angetts av din applikation och en som valts genom automatisk identifiering.
Transportörens sammanhang är viktigt när ett spårningsnummer och dess händelser ska tolkas. Om identifieringen är tvetydig bör din integration kunna lösa detta i stället för att tyst presentera en osäker matchning som bekräftad. Håll information om servicenivå separat: ett transportörsnamn visar inte i sig om en försändelse använder express-, post- eller någon annan tjänst.
3. Normaliserad statusdetalj
Be om en dokumenterad detaljkod eller delstatus bredvid huvudstatusen. En bred kategori kan beskriva en försändelse som ett undantag, medan detaljen identifierar ett misslyckat leveransförsök, ett adressproblem eller ett tullrelaterat stopp.
Använd stabila koder för affärslogik och läsbara etiketter för presentation. Kontrollera hur leverantören mappar transportörens händelser till dessa koder, inklusive hur okända eller omappade händelser hanteras. En normaliserad etikett gör olika transportörsflöden enklare att använda, men den bör inte sudda ut skillnader som supportteamet behöver.
4. Transportörens ursprungliga meddelanden och koder
Behåll den ursprungliga händelsebeskrivningen och transportörens händelsekod när de tillhandahålls. Dessa värden ger supportmedarbetare sammanhang som kan saknas i en normaliserad status, särskilt när en transportör använder ett specifikt operativt uttryck.
Håll originaltexten åtskild från översatta eller omformulerade beskrivningar. Annars kan en kundinriktad förklaring misstas för transportörens exakta formulering. Behandla transportörens text som otillförlitlig indata när den visas: escape:a den på lämpligt sätt och rendera den inte som körbar HTML.
5. Historik över spårningshändelser
Ett användbart svar bör visa försändelsens tidslinje, inte bara den senaste händelsen. Varje händelse bör helst innehålla en identifierare, status eller kod, beskrivning, tidsstämpel och tillgänglig platsinformation.
Kontrollera om API:et returnerar hela historiken, ett begränsat tidsfönster eller paginerade resultat. Fastställ också hur korrigeringar och dubbla observationer representeras. Din applikation bör inte anta att det första objektet alltid är det nyaste om inte svarsavtalet uttryckligen garanterar den ordningen.
6. Tidsstämplar för händelser och tidszonsinformation
Tiden då en händelse inträffade skiljer sig från tiden då API:et tog emot eller returnerade den. Bevara båda när de finns tillgängliga. Skillnaden hjälper till att förklara varför en nyss mottagen uppdatering kan beskriva något som inträffade tidigare.
Begär tidsstämplar med uttryckliga UTC-förskjutningar eller UTC-notation. RFC 3339 definierar ett tidsstämpelformat som lämpar sig för internetprotokoll, inklusive numeriska tidsförskjutningar. Om en källa endast anger lokal tid utan känd förskjutning ska du bevara osäkerheten i stället för att tyst behandla den som UTC. Antyd aldrig precision på sekundnivå när den underliggande källan endast tillhandahåller ett datum.
7. Händelseplatser och försändelsens geografi
Leta efter strukturerade platskomponenter som stad, region, land och postnummer när de tillhandahålls. Bevara även en rå platssträng om en omvandling till strukturerade fält kan leda till att betydelse går förlorad.
En skanningsplats är inte nödvändigtvis paketets aktuella position. På samma sätt är den senast rapporterade anläggningen inget bevis på att paketet fortfarande finns där. Kundinriktade sidor bör beskriva den som den senast rapporterade platsen. Undvik att härleda koordinater eller en exakt leveransadress från ofullständig skanningstext.
8. Beräknat leveransdatum eller leveransintervall
Ett fält för beräknad leverans bör ange om det innehåller ett enskilt datum eller ett intervall, vem som skapade det och när det senast uppdaterades. En uppskattning från transportören och en separat beräknad prognos bör kunna särskiljas.
Omvandla inte en uppskattning som endast innehåller ett datum till en exakt ankomsttid. Din integration bör också kunna hantera reviderade eller återkallade uppskattningar utan att behålla ett föråldrat löfte på spårningssidan. Om ingen uppskattning finns ska du visa att den saknas i stället för att beräkna en utifrån ett obestyrkt antagande.
9. Orsak till undantag och nödvändig åtgärd
Information om undantag bör förklara problemet och, när källan stöder det, ange en åtgärd, ansvarig part eller tidsfrist. Ett allmänt förseningsmeddelande skiljer sig operativt från en begäran om mottagaruppgifter.
Håll rapporterade fakta åtskilda från dina egna arbetsflödesbeslut. Ditt företag kan till exempel skapa en supportuppgift efter en konfigurerad period utan uppdatering. Det är en intern eskaleringsregel, inte ett bevis på att transportören har deklarerat paketet som förlorat. Skapa inte betalningsinstruktioner eller begäranden om känslig information utifrån tvetydig spårningstext.
10. Överlämningar mellan transportörer och relaterade spårningsnummer
När en försändelse flyttas mellan operatörer omfattar användbara uppgifter nästa transportör, ett tillhörande spårningsnummer och relationen mellan de ursprungliga och efterföljande posterna. Detta kan bidra till kontinuitet när leveranssträckan använder en annan identifierare.
Behandla en rapporterad överlämning som en relation i stället för att skriva över den ursprungliga transportören. Slå inte ihop poster enbart för att deras destinationer eller spårningsnummer ser lika ut. Om relationen inte tillhandahålls eller på annat sätt bekräftas ska den förbli olöst i stället för att du hittar på en sammanhängande resa.
11. Leveransresultat och referenser till leveransbevis
När en leverans rapporteras bör svaret ange den registrerade leveranstiden och alla tillgängliga leveransdetaljer, exempelvis en beskrivning av en säker plats eller en mottagarkategori. En referens till leveransbevis kan också vara användbar när transportören och tjänsten gör den tillgänglig.
En status som ”Levererad” bör inte behandlas som bevis på att den avsedda mottagaren personligen tog emot paketet. Signaturer, fotografier, namn och exakta platser kan innehålla personuppgifter. Begränsa åtkomsten, undvik att exponera dessa uppgifter på offentliga spårningssidor och bekräfta eventuella krav på behörighet eller giltighetstid för bevislänkar.
12. Aktualitet, hämtningsstatus och svarsmetadata
Begär tillräckligt med metadata för att skilja den senaste försändelsehändelsen från den senaste lyckade datahämtningen. Användbara värden omfattar den senaste lyckade kontrollen, det senaste misslyckade försöket, tidpunkten då svaret skapades och om returnerade data är cachade eller ofullständiga.
En lyckad API-begäran fastställer inte i sig att transportören har publicerat en ny skanning. HTTP-svarssemantik beskriver resultatet av begäran; försändelsens förlopp hör hemma i applikationsdata. Bevara hämtningsfel separat från försändelseundantag så att ett tillfälligt anslutningsproblem inte blir en falsk leveransavisering.
Saknade uppgifter behöver en definierad betydelse
Fältets förekomst är bara en del av avtalet. Ditt team behöver också förstå vad ett frånvarande värde betyder. En leveransprognos kan saknas i källan, ännu inte ha hämtats eller vara irrelevant efter leverans. Dessa situationer bör inte automatiskt leda till samma kundmeddelande.
- Okänt: Värdet har inte fastställts.
- Inte tillhandahållet: Källan tillhandahöll inte värdet i de hämtade uppgifterna.
- Inte tillämpligt: Fältet gäller inte för denna post eller detta tillstånd.
- Hämtningen misslyckades: Systemet kunde inte slutföra den relevanta hämtningen.
Detta är rekommenderade skillnader, inte obligatoriska bokstavliga värden. Oavsett vilken representation du väljer ska du dokumentera den. Undvik platshållardatum, tomma objekt som liknar giltiga poster och standardkoordinater som kan misstas för verkliga platser.
Så testar du svaret innan integration
Utvärdera faktiska nyttolaster från de transportörer, tjänster och fraktrutter som ditt företag använder. Ett schema kan lista ett valfritt fält utan att garantera att varje underliggande källa fyller i det. För en 17TRACK-integration använder du den officiella dokumentationen för Tracking API för att kontrollera svarsavtalet i stället för att behandla de konceptuella fältnamnen i denna guide som färdiga parametrar.
- Skapa ett representativt urval. Ta med nyligen registrerade försändelser, aktiva försändelser, leveransförsök, slutförda leveranser och tillgängliga fall av överlämning.
- Spåra fälten tillbaka till händelserna. Bekräfta att den visade statusen, den senaste händelsen och leveransdetaljerna beskriver en konsekvent post. Undersök avvikelser i stället för att dölja dem.
- Testa fördröjda och upprepade uppdateringar. Bearbeta samma nyttolast igen och ta emot en äldre händelse efter en nyare. Bekräfta att inget av fallen skapar dubbla aviseringar eller felaktigt återställer den visade statusen.
- Testa saknade och felaktigt formaterade värden. Ta med saknade uppskattningar, okända platser, obekanta statuskoder och ofullständiga tidsstämplar. Applikationen ska förbli användbar utan att hitta på ersättningar.
- Separera transportfel från spårningsresultat. Ett autentiseringsfel, en timeout eller ett felaktigt svar ska gå till en integrationsfelväg, inte till ett arbetsflöde för försändelseundantag.
- Validera kundvyn. Kontrollera att interna referenser, råa diagnostikdetaljer och personuppgifter inte läcker till offentliga sidor eller aviseringar.
För webhook-baserade uppdateringar bör du även kontrollera leveransidentifierare, autentisering, återförsöksbeteende och hantering av upprepningar i leverantörens dokumentation. Detta är integrationskrav snarare än försändelsefakta. Din mottagare bör behandla upprepade leveranser säkert och inte anta att ankomstordningen är samma som händelseordningen.
Acceptanskriteriet bör vara praktiskt: kan din applikation förklara försändelsen utan att göra obestyrkta påståenden, och kan driftteamet identifiera nästa motiverade åtgärd? En mindre, väldefinierad nyttolast kan vara mer användbar än ett större svar fullt av oförklarade valfria värden.
Vanliga frågor
Måste alla 12 datagrupper vara ifyllda för varje försändelse?
Nej. Leveransbevis, efterföljande spårningsnummer och beräknade leveransdatum kanske inte är tillgängliga eller tillämpliga. Kräv tydliga fältdefinitioner och förutsägbart beteende för saknade värden i stället för att kräva att alla fält alltid är ifyllda. Kontrollera de viktigaste fälten mot den faktiska blandningen av frakter.
Bör vi lagra råsvaret eller endast normaliserade fält?
Lagra normaliserade fält för applikationslogik. Att behålla relevanta källnyttolaster kan också hjälpa vid felsökning och ändringar i mappningen, med hänsyn till dina krav på integritet, säkerhet, avtal och lagring. Begränsa åtkomsten och behåll inte känsligt innehåll enbart för att det förekommer i ett svar.
Vilken tidsstämpel bör avgöra den senaste händelsen?
Använd dokumenterad händelsekronologi och leverantörens ordningsregler med hänsyn till tidszoner och korrigeringar. Mottagningstiden anger när ditt system fick kännedom om en händelse, inte nödvändigtvis när den inträffade. Om tidsstämplarna är ofullständiga eller motstridiga ska du bevara tvetydigheten i stället för att hävda en exakt sekvens.
Kan ett tracking-API bekräfta att ett paket är förlorat?
Behandla endast en förlust som rapporterad av transportören när källan uttryckligen stöder den tolkningen. En lång period utan skanningar kan motivera en utredning enligt dina operativa regler, men tystnad fastställer inte i sig att paketet är förlorat. Håll ”inaktuell spårning” och ”rapporterat förlorat” som separata begrepp.
Räcker statusen ”Levererad” för att avsluta ett kundklagomål?
Inte automatiskt. Den fastställer det rapporterade spårningsresultatet, men behöver inte lösa mottagarens tvist. Granska tillgängliga leveransdetaljer, kundens konto och din supportprocess. Behandla inte en statusetikett som ett substitut för att undersöka motstridig information.
Källor
- 17TRACK Tracking API documentation — den produktspecifika referensen för att kontrollera en integrations dokumenterade fält och beteende; de 12 grupperna ovan är redaktionella rekommendationer och inte en återgivning av dess schema.
- RFC 3339: Date and Time on the Internet: Timestamps — representation av tidsstämplar och konventioner för tidsförskjutningar.
- RFC 9110: HTTP Semantics — HTTP-svarssemantik, åtskild från försändelsens affärsstatus.


