Skip to main content
HjemBloggVeiledningerHvilke data bør et sporings-API returnere? 12 felt utover gjeldende status?

Hvilke data bør et sporings-API returnere? 12 felt utover gjeldende status?

17TRACK

Et sporings-API bør returnere mer enn en etikett som «Underveis». I tillegg til gjeldende status bør du se etter forsendelsesidentifikatorer, transportørens identitet, detaljert statusinformasjon, transportørens originale meldinger, hendelseshistorikk, tidspunkter for hendelser, steder, leveringsestimater, avvik, overleveringer mellom transportører, leveringsdetaljer og metadata om dataenes aktualitet. Til sammen hjelper disse 12 datagruppene utviklere med å bygge pålitelige arbeidsflyter og gir driftsteam nok kontekst til å handle.

Hvilke data bør et sporings-API returnere – 12 felt utover status

Dette er en anbefalt responskontrakt for utviklere, tekniske innkjøpere og driftsteam innen netthandel – ikke en påstand om at alle transportører eller API-er leverer hvert felt. Noen verdier vil helt legitimt være utilgjengelige. Et bedre design gjør disse manglene tydelige i stedet for å fylle dem med antakelser.

Hva gjør sporingsdata nyttige?

En gjeldende status besvarer ett snevert spørsmål: Hva er forsendelsens oppsummerte tilstand? Den forklarer ikke nødvendigvis hva som skjedde, når det skjedde, om informasjonen er oppdatert, eller hva noen bør gjøre videre.

For eksempel kan to forsendelser begge vise «Underveis», samtidig som de krever ulike tiltak. Den ene kan ha en nylig skanning på et anlegg og ingen rapporterte problemer. Den andre kan ha et uløst adresseproblem registrert i hendelseshistorikken. En applikasjon som bare leser hovedstatusen, kan overse denne forskjellen.

Vurder responsen opp mot tre praktiske oppgaver: å koble forsendelsen til riktig ordre, forklare fremdriften nøyaktig og avgjøre om et tiltak er berettiget. Feltene nedenfor støtter disse oppgavene. Feltnavnene er illustrative; de er ikke en universell standard eller en bestemt leverandørs skjema.

12 felt som bør vurderes utover gjeldende status

1. Forsendelses- og sporingsidentifikatorer

Responsen bør identifisere forsendelsen som beskrives. Nyttige verdier omfatter det innsendte sporingsnummeret, API-ets identifikator for sporingsposten og en klientreferanse som systemet ditt kan koble til en oppfyllelses- eller pakkepost.

Ikke anta at én ordre tilsvarer én forsendelse. En ordre kan deles opp i flere pakker, og en erstatning kan opprette en ny forsendelse. Lagre sporingsposter på pakke- eller oppfyllelsesnivå, og knytt dem deretter til ordren. Bevar sporingsnumre som strenger slik at formatering og innledende nuller ikke går tapt.

2. Transportørens identitet

Se etter en stabil transportøridentifikator sammen med et lesbart transportørnavn. Når det er tilgjengelig, bør responsen skille mellom en transportør som applikasjonen din har oppgitt uttrykkelig, og en som er valgt gjennom automatisk gjenkjenning.

Transportørkontekst er viktig når et sporingsnummer og hendelsene knyttet til det skal tolkes. Hvis gjenkjenningen er tvetydig, bør integrasjonen ha en måte å avklare dette på, i stedet for å presentere en usikker samsvaring som bekreftet. Hold informasjon om tjenestenivå separat: Et transportørnavn alene fastslår ikke om en forsendelse bruker ekspress-, post- eller en annen tjeneste.

3. Normaliserte statusdetaljer

Be om en dokumentert detaljkode eller understatus sammen med hovedstatusen. En bred kategori kan beskrive en forsendelse som et avvik, mens detaljen identifiserer et leveringsforsøk, et adresseproblem eller en tollrelatert tilbakeholdelse.

Bruk stabile koder for forretningslogikk og lesbare etiketter for presentasjon. Bekreft hvordan leverandøren mapper transportørhendelser til disse kodene, inkludert hvordan ukjente eller ikke-mappede hendelser håndteres. En normalisert etikett gjør ulike transportørdata enklere å bruke, men den bør ikke viske ut forskjeller supportteamet trenger.

4. Transportørens originale meldinger og koder

Ta vare på den originale hendelsesbeskrivelsen og transportørens hendelseskode når de oppgis. Disse verdiene gir supportmedarbeidere kontekst som kan mangle i en normalisert status, særlig når en transportør bruker en spesifikk operasjonell formulering.

Hold originaltekst adskilt fra oversatte eller omskrevne beskrivelser. Ellers kan en forklaring beregnet på kunden forveksles med transportørens nøyaktige ordlyd. Behandle transportørtekst som upålitelig inndata når den vises: Escap den på riktig måte, og ikke gjengi den som kjørbar HTML.

5. Historikk over sporingshendelser

En nyttig respons bør vise forsendelsens tidslinje, ikke bare den siste hendelsen. Hver hendelse bør ideelt sett inneholde en identifikator, status eller kode, beskrivelse, tidsstempel og tilgjengelig stedsinformasjon.

Kontroller om API-et returnerer hele historikken, et begrenset tidsrom eller paginerte resultater. Avklar også hvordan korrigeringer og doble observasjoner representeres. Applikasjonen bør ikke anta at det første elementet alltid er det nyeste, med mindre responskontrakten uttrykkelig garanterer denne rekkefølgen.

6. Tidspunkter for hendelser og tidssoneinformasjon

Tidspunktet en hendelse fant sted, er forskjellig fra tidspunktet API-et mottok eller returnerte den. Bevar begge når de er tilgjengelige. Dette skillet bidrar til å forklare hvorfor en nylig mottatt oppdatering kan beskrive noe som skjedde tidligere.

Be om tidsstempler med uttrykkelige UTC-forskyvninger eller UTC-notasjon. RFC 3339 definerer et tidsstempelformat som egner seg for internettprotokoller, inkludert numeriske tidsforskyvninger. Hvis en kilde bare oppgir lokal tid uten en kjent forskyvning, bør du bevare denne usikkerheten i stedet for å behandle den som UTC uten å si fra. Gi aldri inntrykk av presisjon på sekundnivå når den underliggende kilden bare oppgir en dato.

7. Hendelsessteder og forsendelsens geografi

Se etter strukturerte stedskomponenter som by, region, land og postnummer når de oppgis. Bevar også en rå stedsstreng dersom en konvertering til strukturerte felt kan føre til tap av betydning.

Et skanningssted er ikke nødvendigvis pakkens faktiske posisjon. På samme måte er det sist rapporterte anlegget ikke et bevis på at pakken fortsatt befinner seg der. Kundevendte sider bør beskrive det som det sist rapporterte stedet. Unngå å utlede koordinater eller en nøyaktig leveringsadresse fra ufullstendig skanningstekst.

8. Beregnet leveringsdato eller -intervall

Et felt for beregnet levering bør angi om det inneholder én dato eller et intervall, hvem som produserte det og når det sist ble oppdatert. Et estimat fra transportøren og en separat beregnet prognose bør kunne skilles fra hverandre.

Ikke konverter et estimat som bare inneholder en dato, til et presist ankomsttidspunkt. Integrasjonen bør også håndtere reviderte eller trukne estimater uten å beholde et utdatert løfte på sporingssiden. Hvis det ikke finnes noe estimat, bør du vise at det er utilgjengelig i stedet for å beregne ett basert på en udokumentert antakelse.

9. Årsak til avvik og nødvendig tiltak

Informasjon om avvik bør forklare problemet og, når kilden støtter det, identifisere et tiltak, en ansvarlig part eller en frist. Et generelt forsinkelsesvarsel er operasjonelt forskjellig fra en forespørsel om mottakerinformasjon.

Hold rapporterte fakta adskilt fra beslutninger i din egen arbeidsflyt. Virksomheten din kan for eksempel opprette en supportsak etter en konfigurert periode uten oppdatering. Det er en intern eskaleringsregel, ikke bevis på at transportøren har erklært pakken tapt. Ikke generer betalingsinstruksjoner eller forespørsler om sensitiv informasjon fra tvetydig sporingstekst.

10. Overleveringer mellom transportører og relaterte sporingsnumre

Når en forsendelse flyttes mellom operatører, omfatter nyttige data neste transportør, et tilknyttet sporingsnummer og forholdet mellom de opprinnelige og etterfølgende postene. Dette kan bidra til å bevare kontinuiteten når leveringsetappen bruker en annen identifikator.

Behandle en rapportert overlevering som et forhold i stedet for å overskrive den opprinnelige transportøren. Ikke slå sammen poster bare fordi destinasjonene eller sporingsnumrene ser like ut. Hvis forholdet ikke er oppgitt eller bekreftet på annen måte, bør det forbli uavklart i stedet for at du finner på en sammenhengende reise.

11. Leveringsresultat og referanser til leveringsbevis

Når levering er rapportert, bør responsen oppgi registrert leveringstidspunkt og tilgjengelige leveringsdetaljer, for eksempel en beskrivelse av et trygt sted eller en mottakerkategori. En referanse til leveringsbevis kan også være nyttig når transportøren og tjenesten gjør den tilgjengelig.

En levert-status bør ikke behandles som bevis på at den tiltenkte mottakeren personlig tok imot pakken. Signaturer, fotografier, navn og nøyaktige steder kan inneholde personopplysninger. Begrens tilgangen, unngå å vise disse detaljene på offentlige sporingssider, og bekreft eventuelle krav til autorisasjon eller utløp for lenker til leveringsbevis.

12. Aktualitet, hentestatus og responsmetadata

Be om nok metadata til å skille den siste forsendelseshendelsen fra den siste vellykkede datahentingen. Nyttige verdier omfatter siste vellykkede kontroll, siste mislykkede forsøk, tidspunktet responsen ble generert og om returnerte data er bufrede eller delvise.

En vellykket API-forespørsel fastslår ikke i seg selv at transportøren har publisert en ny skanning. Semantikken i HTTP-responsen beskriver resultatet av forespørselen; forsendelsens fremdrift hører hjemme i applikasjonsdataene. Bevar hente feil separat fra forsendelsesavvik, slik at et midlertidig tilkoblingsproblem ikke blir til et falskt leveringsvarsel.

Manglende data trenger en definert betydning

At et felt finnes, er bare en del av kontrakten. Teamet ditt må også forstå hva en fraværende verdi betyr. Et leveringsestimat kan være utilgjengelig fra kilden, ennå ikke hentet eller ikke relevant etter levering. Disse situasjonene bør ikke automatisk føre til samme kundemelding.

  • Ukjent: Verdien er ikke fastslått.
  • Ikke oppgitt: Kilden oppga ikke verdien i de hentede dataene.
  • Ikke relevant: Feltet gjelder ikke for denne posten eller tilstanden.
  • Henting mislyktes: Systemet klarte ikke å fullføre det relevante oppslaget.

Dette er anbefalte skiller, ikke obligatoriske bokstavelige verdier. Uansett hvilken representasjon du velger, bør den dokumenteres. Unngå plassholderdatoer, tomme objekter som ligner gyldige poster, og standardkoordinater som kan forveksles med virkelige steder.

Slik tester du responsen før integrering

Vurder faktiske nyttelaster fra transportørene, tjenestene og fraktrutene virksomheten din bruker. Et skjema kan liste et valgfritt felt uten å garantere at alle underliggende kilder fyller det ut. For en 17TRACK-integrasjon kan du bruke den offisielle Tracking API-dokumentasjonen til å kontrollere responskontrakten, i stedet for å behandle de konseptuelle feltnavnene i denne veiledningen som parametere som kan kopieres direkte.

  1. Bygg et representativt utvalg. Ta med nylig registrerte forsendelser, aktive forsendelser, leveringsforsøk, fullførte leveranser og tilgjengelige tilfeller med overlevering.
  2. Spor feltene tilbake til hendelsene. Bekreft at den viste statusen, den siste hendelsen og leveringsdetaljene beskriver en konsistent post. Undersøk avvik i stedet for å skjule dem.
  3. Test forsinkede og gjentatte oppdateringer. Behandle den samme nyttelasten på nytt, og motta en eldre hendelse etter en nyere. Bekreft at ingen av tilfellene oppretter doble varsler eller feilaktig reverserer den viste tilstanden.
  4. Test manglende og feilformaterte verdier. Ta med manglende estimater, ukjente steder, ukjente statuskoder og ufullstendige tidsstempler. Applikasjonen bør forbli brukbar uten å finne på erstatningsverdier.
  5. Skill transportfeil fra sporingsresultater. En autentiseringsfeil, tidsavbrudd eller feilformatert respons bør gå til en integrasjonsfeilflyt, ikke en arbeidsflyt for forsendelsesavvik.
  6. Valider kundevisningen. Kontroller at interne referanser, rå diagnostikkdetaljer og personopplysninger ikke lekker til offentlige sider eller varsler.

For webhook-baserte oppdateringer bør du også kontrollere leveringsidentifikatorer, autentisering, nytt forsøk og håndtering av avspillinger i leverandørens dokumentasjon. Dette er integrasjonskrav, ikke forsendelsesfakta. Mottakeren bør behandle gjentatte leveringer på en sikker måte og bør ikke anta at ankomstrekkefølgen er lik hendelsesrekkefølgen.

Godkjenningskriteriet bør være praktisk: Kan applikasjonen forklare forsendelsen uten å komme med udokumenterte påstander, og kan driftsteamet identifisere det neste berettigede tiltaket? En mindre, veldefinert nyttelast kan være mer nyttig enn en større respons full av uforklarte valgfrie verdier.

Vanlige spørsmål

Må alle 12 datagrupper være utfylt for hver forsendelse?

Nei. Leveringsbevis, etterfølgende sporingsnumre og beregnede leveringsdatoer er kanskje ikke tilgjengelige eller relevante. Krev tydelige feltdefinisjoner og forutsigbar håndtering av manglende verdier i stedet for at alle felt alltid må være utfylt. Kontroller de viktigste feltene mot den faktiske sammensetningen av forsendelsene dine.

Bør vi lagre den rå responsen eller bare normaliserte felt?

Lagre normaliserte felt for applikasjonslogikk. Det kan også være nyttig å beholde relevante kildenyttelaster for feilsøking og endringer i mapping, under forutsetning av kravene dine til personvern, sikkerhet, avtaler og lagring. Begrens tilgangen, og unngå å beholde sensitivt innhold bare fordi det forekommer i en respons.

Hvilket tidsstempel bør avgjøre hva som er den siste hendelsen?

Bruk dokumentert hendelseskronologi og leverandørens regler for rekkefølge, og ta hensyn til tidssoner og korrigeringer. Mottakstidspunktet forteller når systemet ditt fikk vite om en hendelse, ikke nødvendigvis når den fant sted. Hvis tidsstemplene er ufullstendige eller motstridende, bør du bevare tvetydigheten i stedet for å hevde en presis rekkefølge.

Kan et sporings-API bekrefte at en pakke er tapt?

Behandle bare en forsendelse som tapt ifølge transportøren når kilden uttrykkelig støtter denne tolkningen. En lang periode uten skanninger kan gi grunnlag for undersøkelse etter driftsreglene dine, men stillhet alene fastslår ikke at pakken er tapt. Hold «foreldet sporing» og «rapportert tapt» som separate begreper.

Er en levert-status nok til å avslutte en kundeklage?

Ikke automatisk. Den fastslår det rapporterte sporingsresultatet, men løser kanskje ikke mottakerens innsigelse. Gå gjennom tilgjengelige leveringsdetaljer, kundens konto og supportprosessen din. Unngå å behandle en statusetikett som en erstatning for å undersøke motstridende informasjon.

Kilder