Hvilke data bør en tracking-API returnere? 12 felter ud over den aktuelle status?
En tracking-API bør returnere mere end en etiket som "Undervejs". Ud over den aktuelle status bør du se efter forsendelsesidentifikatorer, transportørens identitet, detaljerede statusoplysninger, transportørens oprindelige meddelelser, hændelseshistorik, tidsstempler for hændelser, lokationer, forventede leveringstidspunkter, undtagelser, overdragelser mellem transportører, leveringsdetaljer og metadata om dataenes aktualitet. Tilsammen hjælper disse 12 datagrupper udviklere med at opbygge pålidelige arbejdsgange og giver driftsteams tilstrækkelig kontekst til at handle.

Dette er en anbefalet svarkontrakt for udviklere, tekniske indkøbere og e-handelsdriftsteams – ikke en påstand om, at alle transportører eller API'er leverer hvert felt. Nogle værdier vil legitimt være utilgængelige. Et bedre design gør disse mangler tydelige i stedet for at udfylde dem med antagelser.
Hvad gør trackingdata nyttige?
En aktuel status besvarer ét snævert spørgsmål: Hvad er forsendelsens sammenfattede tilstand? Den forklarer ikke nødvendigvis, hvad der skete, hvornår det skete, om oplysningerne er aktuelle, eller hvad nogen bør gøre som det næste.
To forsendelser kan for eksempel begge vise "Undervejs", men kræve forskellige svar. Den ene kan have en nylig scanning på et anlæg og ingen rapporterede problemer. Den anden kan have et uafklaret adresseproblem registreret i sin hændelseshistorik. En applikation, der kun læser den overordnede status, kan overse denne forskel.
Evaluer svaret ud fra tre praktiske opgaver: at knytte forsendelsen til den korrekte ordre, forklare dens forløb præcist og afgøre, om en handling er berettiget. De følgende felter understøtter disse opgaver. Feltnavnene er illustrative; de er ikke en universel standard eller en bestemt udbyders skema.
12 felter, der bør evalueres ud over den aktuelle status
1. Forsendelses- og trackingidentifikatorer
Svaret bør identificere den beskrevne forsendelse. Nyttige værdier omfatter det indsendte trackingnummer, API'ens identifikator for trackingposten og en klientreference, som dit system kan knytte til en ordre- eller pakkepost.
Antag ikke, at én ordre er lig med én forsendelse. En ordre kan være opdelt på flere pakker, og en erstatningsvare kan oprette en ny forsendelse. Gem trackingposter på pakke- eller ordreopfyldelsesniveau, og knyt dem derefter til ordren. Gem trackingnumre som strenge, så formatering og indledende nuller ikke går tabt.
2. Transportørens identitet
Se efter en stabil transportøridentifikator sammen med et læsbart transportørnavn. Hvor det er muligt, bør svaret skelne mellem en transportør, der udtrykkeligt er angivet af din applikation, og en transportør, der er valgt via automatisk registrering.
Transportørens kontekst er vigtig, når et trackingnummer og dets hændelser skal fortolkes. Hvis registreringen er tvetydig, bør din integration kunne afklare den i stedet for stiltiende at vise et usikkert match som bekræftet. Hold oplysninger om serviceniveau adskilt: Et transportørnavn alene fastslår ikke, om en forsendelse bruger en ekspres-, post- eller anden service.
3. Normaliserede statusdetaljer
Bed ud over hovedstatussen om en dokumenteret detaljekode eller delstatus. En bred kategori kan beskrive en forsendelse som en undtagelse, mens detaljen identificerer et leveringsforsøg, et adresseproblem eller en toldrelateret tilbageholdelse.
Brug stabile koder til forretningslogik og læsbare etiketter til visning. Bekræft, hvordan udbyderen knytter transportørhændelser til disse koder, herunder hvordan ukendte eller ikke-knyttede hændelser håndteres. En normaliseret etiket gør forskellige transportørfeeds lettere at bruge, men den bør ikke udviske de forskelle, som dit supportteam har brug for.
4. Transportørens oprindelige meddelelser og koder
Bevar den oprindelige hændelsesbeskrivelse og transportørens hændelseskode, når de leveres. Disse værdier giver supportmedarbejdere kontekst, som kan mangle i en normaliseret status, især når en transportør bruger en specifik operationel formulering.
Hold den oprindelige tekst adskilt fra oversatte eller omskrevne beskrivelser. Ellers kan en forklaring til kunden forveksles med transportørens nøjagtige formulering. Behandl transportørtekst som upålideligt input, når den vises: Escap den korrekt, og gengiv den ikke som eksekverbar HTML.
5. Historik over trackinghændelser
Et nyttigt svar bør vise forsendelsens tidslinje, ikke kun den seneste hændelse. Hver hændelse bør ideelt indeholde en identifikator, status eller kode, beskrivelse, tidsstempel og tilgængelige lokationsoplysninger.
Kontroller, om API'en returnerer den fulde historik, et begrænset udsnit eller sideopdelte resultater. Fastlæg også, hvordan rettelser og dublerede observationer repræsenteres. Din applikation bør ikke antage, at det første element altid er det nyeste, medmindre svarkontrakten udtrykkeligt garanterer denne rækkefølge.
6. Tidsstempler for hændelser og oplysninger om tidszone
Tidspunktet, hvor en hændelse fandt sted, er forskelligt fra det tidspunkt, hvor API'en modtog eller returnerede den. Bevar begge, når de er tilgængelige. Denne forskel hjælper med at forklare, hvorfor en netop modtaget opdatering kan beskrive noget, der skete tidligere.
Bed om tidsstempler med eksplicitte UTC-forskydninger eller UTC-notation. RFC 3339 definerer et tidsstempelformat, der egner sig til internetprotokoller, herunder numeriske tidsforskydninger. Hvis en kilde kun leverer lokal tid uden en kendt forskydning, skal du bevare denne usikkerhed i stedet for stiltiende at behandle den som UTC. Giv aldrig indtryk af præcision på sekundniveau, når den underliggende kilde kun leverer en dato.
7. Hændelseslokationer og forsendelsens geografi
Se efter strukturerede lokationskomponenter som by, region, land og postnummer, når de leveres. Bevar også en rå lokationsstreng, hvis en konvertering til strukturerede felter kan medføre betydningstab.
En scanningslokation er ikke nødvendigvis pakkens aktuelle position. Den senest rapporterede terminal er heller ikke et bevis på, at pakken stadig befinder sig der. Kundevendte sider bør beskrive den som den senest rapporterede lokation. Undgå at udlede koordinater eller en nøjagtig leveringsadresse fra ufuldstændig scanningstekst.
8. Forventet leveringsdato eller -interval
Et felt for forventet levering bør angive, om det indeholder en enkelt dato eller et interval, hvem der har oprettet det, og hvornår det sidst blev opdateret. Et estimat fra transportøren og en separat beregnet prognose bør kunne skelnes fra hinanden.
Konvertér ikke et estimat, der kun indeholder en dato, til et præcist ankomsttidspunkt. Din integration bør også håndtere reviderede eller tilbagetrukne estimater uden at fastholde et forældet løfte på trackingsiden. Hvis der ikke findes et estimat, skal du vise, at det ikke er tilgængeligt, i stedet for at beregne et ud fra en udokumenteret antagelse.
9. Årsag til undtagelse og påkrævet handling
Oplysninger om undtagelser bør forklare problemet og, hvor kilden understøtter det, identificere en handling, ansvarlig part eller frist. En generel meddelelse om forsinkelse er operationelt forskellig fra en anmodning om oplysninger fra modtageren.
Hold rapporterede fakta adskilt fra dine egne arbejdsgangsbeslutninger. Din virksomhed kan for eksempel oprette en supportsag efter en konfigureret periode uden opdatering. Det er en intern eskaleringsregel, ikke et bevis på, at transportøren har erklæret pakken bortkommet. Generér ikke betalingsinstruktioner eller anmodninger om følsomme oplysninger ud fra tvetydig trackingtekst.
10. Overdragelser mellem transportører og relaterede trackingnumre
Når en forsendelse flyttes mellem operatører, omfatter nyttige data den næste transportør, et tilknyttet trackingnummer og relationen mellem de oprindelige og efterfølgende poster. Det kan hjælpe med at bevare kontinuiteten, når leveringsstrækningen bruger en anden identifikator.
Behandl en rapporteret overdragelse som en relation i stedet for at overskrive den oprindelige transportør. Flet ikke poster blot fordi deres destinationer eller trackingnumre ser ens ud. Hvis relationen ikke er leveret eller på anden måde bekræftet, skal den forblive uafklaret i stedet for at opfinde en sammenhængende rejse.
11. Leveringsresultat og referencer til leveringsbevis
Når levering rapporteres, bør svaret indeholde det registrerede leveringstidspunkt og alle tilgængelige leveringsdetaljer, såsom en beskrivelse af et sikkert afleveringssted eller en modtagerkategori. En reference til leveringsbevis kan også være nyttig, hvor transportøren og servicen gør den tilgængelig.
En leveret-status bør ikke behandles som bevis på, at den tilsigtede modtager personligt accepterede pakken. Underskrifter, fotografier, navne og præcise lokationer kan indeholde personoplysninger. Begræns adgangen, undgå at vise disse oplysninger på offentlige trackingsider, og bekræft eventuelle krav om autorisation eller udløb for bevislinks.
12. Aktualitet, hentestatus og metadata for svar
Bed om tilstrækkelige metadata til at skelne mellem den seneste forsendelseshændelse og den seneste vellykkede datahentning. Nyttige værdier omfatter seneste vellykkede kontrol, seneste mislykkede forsøg, tidspunktet for generering af svaret og om de returnerede data er cachede eller delvise.
En vellykket API-anmodning fastslår ikke i sig selv, at transportøren har offentliggjort en ny scanning. HTTP-svarsemantik beskriver resultatet af anmodningen; forsendelsens fremdrift hører hjemme i applikationsdataene. Bevar hentefejl adskilt fra forsendelsesundtagelser, så et midlertidigt forbindelsesproblem ikke bliver til en falsk leveringsadvarsel.
Manglende data kræver en entydig betydning
Tilstedeværelsen af et felt er kun en del af kontrakten. Dit team skal også forstå, hvad en manglende værdi betyder. Et leveringestimat kan være utilgængeligt fra kilden, endnu ikke hentet eller ikke relevant efter levering. Disse situationer bør ikke automatisk udløse den samme kundemeddelelse.
- Ukendt: Værdien er ikke fastlagt.
- Ikke leveret: Kilden leverede ikke værdien i de hentede data.
- Ikke relevant: Feltet gælder ikke for denne post eller tilstand.
- Hentning mislykkedes: Systemet kunne ikke gennemføre det relevante opslag.
Dette er anbefalede skelnen, ikke obligatoriske bogstavelige værdier. Uanset hvilken repræsentation du vælger, skal du dokumentere den. Undgå pladsholderdatoer, tomme objekter, der ligner gyldige poster, og standardkoordinater, der kan forveksles med virkelige lokationer.
Sådan tester du svaret før integration
Evaluer faktiske payloads fra de transportører, services og transportruter, som din virksomhed bruger. Et skema kan angive et valgfrit felt uden at garantere, at alle underliggende kilder udfylder det. Ved en 17TRACK-integration skal du bruge den officielle Tracking API-dokumentation til at kontrollere svarkontrakten i stedet for at behandle de konceptuelle feltnavne i denne vejledning som parametre, der kan kopieres direkte.
- Opbyg et repræsentativt udsnit. Medtag nyregistrerede forsendelser, aktive forsendelser, leveringsforsøg, gennemførte leveringer og tilgængelige tilfælde af overdragelse.
- Spor felterne tilbage til hændelserne. Bekræft, at den viste status, seneste hændelse og leveringsdetaljer beskriver en sammenhængende post. Undersøg uoverensstemmelser i stedet for at skjule dem.
- Test forsinkede og gentagne opdateringer. Behandl den samme payload igen, og modtag en ældre hændelse efter en nyere. Bekræft, at ingen af tilfældene opretter dublerede notifikationer eller fejlagtigt ruller den viste tilstand tilbage.
- Test manglende og ugyldige værdier. Medtag manglende estimater, ukendte lokationer, ukendte statuskoder og ufuldstændige tidsstempler. Applikationen bør forblive brugbar uden at opfinde erstatninger.
- Adskil transportfejl fra trackingresultater. En godkendelsesfejl, timeout eller forkert formateret svar bør gå til en integrationsfejlsti, ikke til en arbejdsgang for forsendelsesundtagelser.
- Valider kundevisningen. Kontrollér, at interne referencer, rå diagnostiske detaljer og personoplysninger ikke lækker til offentlige sider eller notifikationer.
For webhook-baserede opdateringer skal du også kontrollere leveringsidentifikatorer, godkendelse, genforsøgsadfærd og håndtering af afspilning i udbyderens dokumentation. Dette er integrationskrav snarere end forsendelsesfakta. Din modtager bør behandle gentagne leveringer sikkert og bør ikke antage, at modtagelsesrækkefølgen er lig med hændelsesrækkefølgen.
Acceptkriteriet bør være praktisk: Kan din applikation forklare forsendelsen uden at fremsætte udokumenterede påstande, og kan dit driftsteam identificere den næste berettigede handling? En mindre, veldefineret payload kan være mere nyttig end et større svar fyldt med uforklarede valgfrie værdier.
Ofte stillede spørgsmål
Skal alle 12 datagrupper være udfyldt for hver forsendelse?
Nej. Leveringsbevis, efterfølgende trackingnumre og forventede leveringsdatoer er muligvis ikke tilgængelige eller relevante. Kræv tydelige feltdefinitioner og forudsigelig håndtering af manglende værdier i stedet for, at alle felter altid skal være udfyldt. Kontrollér de vigtigste felter i forhold til din faktiske forsendelsesmiks.
Bør vi gemme det rå svar eller kun normaliserede felter?
Gem normaliserede felter til applikationslogik. Bevaring af relevante kildepayloads kan også hjælpe med fejlfinding og håndtering af ændringer i mapping, under hensyntagen til dine krav til privatliv, sikkerhed, kontrakter og opbevaring. Begræns adgangen, og gem ikke følsomt indhold blot fordi det optræder i et svar.
Hvilket tidsstempel bør afgøre, hvad den seneste hændelse er?
Brug dokumenteret hændelsesforløb og udbyderens regler for rækkefølge, og tag højde for tidszoner og rettelser. Modtagelsestidspunktet fortæller, hvornår dit system fik kendskab til en hændelse, ikke nødvendigvis hvornår den fandt sted. Hvis tidsstemplerne er ufuldstændige eller modstridende, skal du bevare tvetydigheden i stedet for at hævde en præcis rækkefølge.
Kan en tracking-API bekræfte, at en pakke er bortkommet?
Betragt kun en pakke som rapporteret bortkommet af transportøren, når kilden udtrykkeligt understøtter denne fortolkning. En lang periode uden scanninger kan berettige en undersøgelse efter dine driftsregler, men tavshed alene fastslår ikke, at pakken er bortkommet. Hold "forældet tracking" og "rapporteret bortkommet" som separate begreber.
Er en leveret-status nok til at lukke en kundeklage?
Ikke automatisk. Den fastslår det rapporterede trackingresultat, men løser muligvis ikke modtagerens indsigelse. Gennemgå de tilgængelige leveringsdetaljer, kundens konto og din supportproces. Undgå at behandle en statusetiket som en erstatning for at undersøge modstridende oplysninger.
Kilder
- 17TRACK Tracking API-dokumentation — den produktspecifikke reference til kontrol af en integrations dokumenterede felter og adfærd; de 12 grupper ovenfor er redaktionelle anbefalinger og ikke en gengivelse af dens skema.
- RFC 3339: Date and Time on the Internet: Timestamps — repræsentation af tidsstempler og konventioner for tidsforskydninger.
- RFC 9110: HTTP Semantics — HTTP-svarsemantik, som adskiller sig fra forretningsstatus på forsendelsesniveau.


