6 kontroller for å bekrefte at de nyeste sporingshendelsene fra transportøren er synkronisert via API-et ditt
For å bekrefte at API-et ditt har synkronisert de nyeste sporingshendelsene fra transportøren, må du kontrollere forsendelsesidentiteten, hendelsestidspunktene, hendelsesdetaljene, leveringsruten, hendelsesrekkefølgen og aktualiteten mot en uavhengig sporingsvisning. Et vellykket API-svar eller en webhook-bekreftelse bekrefter bare én del av denne kjeden; det beviser ikke i seg selv at applikasjonen din har transportørens nyeste hendelse.

Denne veiledningen er for utviklere og driftsteam som har ansvar for å få sporingsdata inn i et ordrebehandlingssystem, en kundevendt side, et supportverktøy eller en arbeidsflyt for varsler. Målet er å finne ut hvor en hendelse manglet eller ble endret, og deretter avgjøre om behandlingen skal prøves på nytt, en tilordning skal korrigeres eller man skal vente på ny informasjon fra transportøren.
Før du begynner: definer hva «nyeste» betyr
Hold tre tidspunkter atskilt: når transportøren sier at en hendelse fant sted, når sporingsleverandøren mottok eller viste den, og når applikasjonen din lagret den. Disse tidspunktene kan være forskjellige. En transportør kan publisere en skanning etter den fysiske hendelsen, mens integrasjonen din kan behandle den enda senere. Den nyeste hendelsen etter tidspunktet den fant sted, er derfor ikke nødvendigvis den sist mottatte registreringen.
Velg et sammenligningspunkt før du undersøker saken. Bruk helst transportørens sporingsside eller en annen autorisert registrering levert av transportøren for den samme forsendelsen. Hvis dette ikke er tilgjengelig, sammenligner du applikasjonen med sporingsleverandørens gjeldende API-svar. Denne snevrere sammenligningen kan fastslå om applikasjonen samsvarer med leverandøren; den kan ikke fastslå at leverandøren allerede har alle skanninger fra transportøren. Registrer når du foretok sammenligningen, slik at en senere oppdatering ikke får et tidligere resultat til å virke inkonsekvent.
1. Bekreft at begge systemene gjelder samme forsendelse
Begynn med sporingsnummeret, transportøren og eventuelle konto- eller forsendelsesidentifikatorer som integrasjonen bruker. Sporingsnumre alene er kanskje ikke tilstrekkelige ved feilsøking: Et nummer kan være skrevet feil, knyttet til feil transportør eller gjenbrukt i en intern registrering etter at en ordre er redigert. Et ordrenummer og et sporingsnummer har også ulike formål. Én ordre kan ha flere pakker, så en kontroll av ordrens nyeste status kan skjule en utdatert pakke.
- Finn det nøyaktige sporingsnummeret og transportøren som ble sendt til sporings-API-et.
- Bekreft hvilken intern forsendelses- eller pakkeregistrering som mottok svaret.
- Kontroller om forsendelsen ble erstattet, delt opp, kansellert eller knyttet til en annen registrering etter registreringen.
- Sammenlign transportøren og nummeret som vises i kilderegistreringen, med dem som vises i applikasjonen.
Hvis identifikatorene ikke samsvarer, må du slutte å behandle forskjellen som en synkroniseringsforsinkelse. Korriger tilknytningen først, og gjenta deretter hendelsessammenligningen. Lagre nok identifikatorer i diagnostikkloggene til å spore en forsendelse uten å legge sensitive kontolegitimasjoner i loggene.
2. Sammenlign hendelsestidspunkter uten å miste betydningen
For hver kandidat til nyeste hendelse registrerer du tidspunktet transportøren oppga for når hendelsen fant sted, den angitte tidssonen eller forskyvningen hvis den finnes, samt applikasjonens mottaks- og lagringstidspunkter. Konverter tidsstemplene til et felles tidsgrunnlag for sammenligning, men behold den opprinnelige verdien. RFC 3339 definerer et internettformat for tidsstempler med eksplisitt informasjon om forskyvning; det er en nyttig referanse når du utformer egne tidsstempelfelter. Det garanterer ikke at en transportør eller leverandør oppgir en tidssone for hver hendelse.
En visning som bare inneholder klokkeslett, en antatt lokal tidssone eller en parser som i stillhet forkaster en forskyvning, kan flytte en hendelse til en annen kalenderdag eller plassere den i feil rekkefølge. Når kilden oppgir et tvetydig lokalt klokkeslett, markerer du sammenligningen som usikker i stedet for å finne på et presist UTC-øyeblikk. Skill også mellom tidspunktet en hendelse fant sted og tidspunktet for et API-svar: Et svar som hentes nå, kan legitimt inneholde en hendelse som fant sted tidligere.
Skriv ned tidspunktet da du kontrollerte transportørens eller leverandørens visning. Hvis kilden publiserte en ny skanning etter API-forespørselen din, viser ikke en forskjell mellom de to visningene at den tidligere forespørselen mislyktes.
3. Kontroller hendelsesinnholdet, ikke bare overskriftsstatusen
Sammenlign den nyeste hendelsens beskrivelse, sted, transportørstatus eller kode og alle relevante leveringsfelt med oppstrømsregistreringen. En normalisert status som «under transport» kan oppsummere flere ulike skanninger. Hvis applikasjonen bare lagrer sammendraget, kan den se uendret ut selv om en ny hendelse er kommet inn.
Inspiser det rå API-svaret eller den lagrede webhook-kroppen der reglene for datahåndtering tillater det. Følg deretter hendelsen gjennom parsing, felttilordning, lagring og presentasjon. Se etter null-felt som overskrives av standardverdier, uventede statuskoder som havner i en generell kategori, tekst som avkortes, eller et brukergrensesnitt som bare viser utvalgte hendelsestyper. Et avvik i statusetiketten er forskjellig fra en manglende hendelse: Det peker mot transformasjons- eller visningslogikk snarere enn levering.
Ikke konkluder med at leveringen har funnet sted bare fordi et sted eller en status høres endelig ut. Bekreft den konkrete hendelsen og feltene arbeidsflyten din er avhengig av. På samme måte er en uendret overordnet status ikke et bevis på at synkroniseringen har stoppet; en nylig mottatt skanning kan bli tilordnet samme kategori. Diagnostikkregistreringen bør bevare både oppstrømshendelsen og verdien som vises til brukerne.
4. Spor hvordan hendelsen nådde applikasjonen
Hvis du bruker webhooks, kontroller mottaksloggen for den aktuelle forsendelsen og hendelsen. Bekreft at endepunktet godtok forespørselen, at meldingen besto valideringen og at den videre behandlingen ble fullført. Et vellykket HTTP-svar fra endepunktet beviser ikke at en senere køarbeider lagret hendelsen. Hvis behandlingen er asynkron, undersøker du både den innkommende forespørselen og resultatet av jobben.
Hvis du spør et API regelmessig, kontroller den siste fullførte forespørselen, forsendelsesidentifikatoren i forespørselen, svaret og eventuell paginering eller hentelogikk som integrasjonen bruker. En vellykket forespørsel kan fortsatt etterfølges av en mislykket databaseskriving eller lesing fra en utdatert hurtigbuffer. Bruk leverandørens relevante dokumentasjon for å bekrefte de faktiske svarfeltene, autentiseringskravene og leveringsatferden for integrasjonen din, i stedet for å anta at alle sporings-API-er følger samme kontrakt. For en 17TRACK-integrasjon er de relevante startpunktene Tracking API-siden og API-dokumentasjonen; bekreft den dokumenterte atferden for endepunktet og metoden du bruker.
Gjør hendelsesbehandlingen trygg å gjenta. Et nytt forsøk skal ikke opprette duplikatskanninger, sende det samme kundselet gjentatte ganger eller erstatte en nyere lagret tilstand med en eldre nyttelast. Den riktige duplikatnøkkelen avhenger av feltene leverandøren faktisk leverer. Test den valgte nøkkelen mot ulike hendelser som tilfeldigvis har samme status eller tidsstempel; disse hendelsene skal ikke slås sammen bare fordi de ser like ut.
5. Bekreft regler for rekkefølge og tilstandsoverganger
Sorter de registrerte hendelsene etter en klart definert regel, og inspiser deretter resultatet. Mange applikasjoner må skille mellom «den nyeste hendelsen som fant sted» og «den nyeste hendelsen vi mottok». En tidligere skanning kan komme inn etter en nyere skanning. Hvis databasen ganske enkelt gjør den sist behandlede meldingen til gjeldende forsendelsestilstand, kan den forsinkede skanningen flytte den viste statusen bakover.
Sammenlign den lagrede historikken med oppstrømshistorikken, ikke bare det enkelte statusfeltet. Spør om en nylig mottatt registrering ble lagt til, forkastet som duplikat eller tillatt å oppdatere gjeldende tilstand. Kontroller alle regler som gir enkelte hendelser prioritet over andre. En slik regel kan være tilsiktet, men den bør ikke skjule den underliggende hendelsen eller antyde at transportøren har reversert en milepæl når applikasjonen bare mottok en eldre skanning sent.
Som en praktisk test kan du ta en forsendelse med mer enn én hendelse og spille av meldingene i en annen ankomstrekkefølge i et ikke-produksjonsmiljø. Bekreft at hendelseshistorikken forblir intakt, og at den kundevendte statusen følger den dokumenterte regelen. Dette avdekker rekkefølgefeil som en normal test i riktig rekkefølge ikke kan avdekke.
6. Mål aktualitet og avstem avvik
Til slutt sammenligner du hva hvert lag visste på samme observasjonstidspunkt: transportørvisningen, sporingsleverandørens svar, innkommende webhook- eller pollingresultat, databaseoppføringen og det kundevendte resultatet. Marker det første laget der den forventede hendelsen forsvinner. Denne grensen er mer nyttig enn en generell rapport om at «sporingen er forsinket».
Mål både alderen på den siste hendelsen som transportøren har rapportert, og tiden siden integrasjonen sist kontrollerte eller mottok data på en vellykket måte. De besvarer ulike spørsmål. En pakke kan mangle en ny skanning fra transportøren selv om integrasjonen fungerer; alternativt kan transportøren vise en ny skanning mens det er lenge siden den siste vellykkede forespørselen. Bruk varselgrenser som gjenspeiler dine egne driftskrav og den atferden du har observert. Ikke lov kundene et fast oppdateringsintervall med mindre avtalene med transportøren og leverandøren støtter det.
Opprett en liten avstemmingskø for forsendelser der registreringene avviker fra den valgte sammenligningskilden. Ta med identifikatorer, den manglende eller avvikende hendelsen, relevante tidsstempler, det første laget som feilet og neste handling. En hendelse som finnes i leverandørens svar, men mangler i databasen, krever for eksempel en undersøkelse av integrasjonen. En hendelse som finnes i databasen, men mangler på sporingssiden, krever en kontroll av visning eller hurtigbuffer. Hvis transportøren selv ikke viser noen ny skanning, kan ikke en ny API-forespørsel fremstille en.
Den operative testen er enkel: Kan du identifisere den samme forsendelsen, finne den sist kjente oppstrømshendelsen og følge denne hendelsen helt frem til den brukervendte visningen uten å endre betydningen? Hvis ikke, snevrer de seks kontrollene problemet inn til en bestemt grense og gir teamet ditt et velbegrunnet neste steg.
Vanlige spørsmål
Betyr et vellykket webhook-svar at den nyeste hendelsen er synkronisert?
Nei. Det viser at endepunktet ditt returnerte et vellykket svar på en forespørsel. Bekreft også at validering, købehandling, databaselagring og visning ble vellykket. Kontroller nyttelasten for å fastslå hvilken hendelse forespørselen inneholdt.
Hvorfor viser transportørens side en nyere skanning enn API-svaret mitt?
Bekreft først at du ser på samme pakke, og at begge observasjonene ble gjort på omtrent samme tidspunkt. Transportørens publisering og sporingsleverandørens mottak eller visning av en hendelse kan finne sted på ulike tidspunkter. Hvis forskjellen vedvarer, bruker du leverandørens dokumentasjon og supportprosess til å undersøke den konkrete forsendelsen, i stedet for å anta at oppdateringer er garantert.
Bør jeg bruke hendelsestidsstempelet eller tidspunktet systemet mitt mottok den, for å velge nyeste status?
Bruk en dokumentert regel som passer arbeidsflyten din, og behold begge verdiene. Hendelsestidsstempelet beskriver når den rapporterte aktiviteten fant sted; mottakstidspunktet beskriver når systemet ditt fikk kjennskap til den. Ingen av feltene løser alle tilfeller alene, særlig når kildetidspunktene er tvetydige eller tidligere skanninger kommer sent.
Hva om API-statusen er uendret, men hendelseslisten har en ny oppføring?
Det kan være forventet hvis flere hendelser fra transportøren tilordnes én normalisert status. Sammenlign hendelsesdetaljene, og bekreft at applikasjonen lagret og viser den nye oppføringen der det er relevant. Behandle en manglende hendelse og en uendret sammendragsetikett som to forskjellige problemer.
Kilder
- 17TRACK Tracking API — produktreferanse for integrasjoner med sporings-API.
- 17TRACK API-dokumentasjon — referansepunkt for å kontrollere den relevante integrasjonskontrakten.
- RFC 3339: Date and Time on the Internet: Timestamps — referanse for tidsstempel- og UTC-forskyvningsformat.


