Skip to main content
HjemBlogVejledninger6 tjek for at verificere, at de seneste sporingshændelser fra transportøren er synkroniseret via dit API

6 tjek for at verificere, at de seneste sporingshændelser fra transportøren er synkroniseret via dit API

17TRACK

For at bekræfte, at din API har synkroniseret de seneste hændelser i transportørens sporing, skal du kontrollere forsendelsesidentiteten, hændelsestidspunkterne, hændelsesdetaljerne, leveringsruten, hændelsernes rækkefølge og aktualiteten i forhold til en uafhængig sporingsvisning. Et vellykket API-svar eller en webhook-bekræftelse bekræfter kun én del af denne kæde; det beviser ikke i sig selv, at din applikation har transportørens nyeste hændelse.

6 kontroller til bekræftelse af, at de seneste sporingshændelser fra transportøren er synkroniseret

Denne vejledning er til udviklere og driftsteams, der har ansvaret for at få sporingsdata ind i et ordrebehandlingssystem, en kundevendt side, et supportværktøj eller et alarmworkflow. Målet er at finde ud af, hvor en hændelse mangler eller er blevet ændret, og derefter afgøre, om behandlingen skal forsøges igen, en mapping skal korrigeres, eller man skal vente på nye oplysninger fra transportøren.

Før du begynder: Definér, hvad “seneste” betyder

Hold tre tidspunkter adskilt: hvornår transportøren angiver, at en hændelse fandt sted, hvornår din sporingsudbyder modtog eller viste den, og hvornår din applikation gemte den. Disse tidspunkter kan være forskellige. En transportør kan offentliggøre en scanning efter den fysiske hændelse, mens din integration først behandler den senere. Den nyeste hændelse efter hændelsestidspunktet er derfor ikke nødvendigvis den senest modtagne registrering.

Vælg et sammenligningspunkt, før du undersøger problemet. Brug helst transportørens sporingsside eller en anden autoriseret registrering fra transportøren for den samme forsendelse. Hvis det ikke er muligt, skal du sammenligne din applikation med sporingsudbyderens aktuelle API-svar. Denne snævrere sammenligning kan fastslå, om din applikation stemmer overens med udbyderen; den kan ikke fastslå, om udbyderen allerede har alle transportørens scanninger. Notér, hvornår du foretog sammenligningen, så en senere opdatering ikke får et tidligere resultat til at se inkonsekvent ud.

1. Bekræft, at begge systemer henviser til den samme forsendelse

Start med sporingsnummeret, transportøren og eventuelle konto- eller forsendelsesidentifikatorer, som din integration bruger. Sporingsnumre alene er muligvis ikke tilstrækkelige til fejlfinding: et nummer kan være indtastet forkert, knyttet til den forkerte transportør eller genbrugt i en intern registrering, efter at en ordre er blevet redigeret. Et ordrenummer og et sporingsnummer tjener også forskellige formål. Én ordre kan have flere pakker, så kontrol af ordrens seneste status kan skjule en forældet pakke.

  • Find det nøjagtige sporingsnummer og den transportør, der blev sendt til sporings-API'en.
  • Bekræft, hvilken intern forsendelses- eller pakkeregistrering der modtog svaret.
  • Kontrollér, om forsendelsen blev erstattet, opdelt, annulleret eller knyttet til en anden registrering efter registreringen.
  • Sammenlign transportøren og nummeret i kilderegistreringen med dem, der vises i din applikation.

Hvis identifikatorerne ikke stemmer overens, skal du holde op med at betragte forskellen som en synkroniseringsforsinkelse. Korrigér først tilknytningen, og gentag derefter hændelsessammenligningen. Gem tilstrækkeligt mange identifikatorer i diagnostiklogfiler til at spore en forsendelse uden at anbringe følsomme kontooplysninger i logfilerne.

2. Sammenlign hændelsestidspunkter uden at miste deres betydning

For hver mulig seneste hændelse skal du registrere det af transportøren angivne hændelsestidspunkt, den angivne tidszone eller forskydning, hvis den findes, samt din applikations modtagelses- og lagringstidspunkter. Konvertér tidsstempler til et fælles grundlag for sammenligning, men behold den oprindelige værdi. RFC 3339 definerer et internetformat for tidsstempler med eksplicitte oplysninger om forskydning; det er en nyttig reference, når du designer dine egne tidsstempelfelter. Det garanterer ikke, at en transportør eller udbyder leverer en tidszone for hver hændelse.

En visning, der kun viser klokkeslættet, en antaget lokal tidszone eller en parser, der lydløst fjerner en forskydning, kan flytte en hændelse til en anden kalenderdag eller placere den i den forkerte rækkefølge. Når kilden angiver et tvetydigt lokalt klokkeslæt, skal sammenligningen markeres som usikker i stedet for at opfinde et præcist UTC-øjeblik. Skeln også mellem en hændelses forekomsttidspunkt og et API-svartidspunkt: et svar, der hentes nu, kan med rette indeholde en hændelse, der fandt sted tidligere.

Skriv tidspunktet ned, hvor du kontrollerede transportørens eller udbyderens visning. Hvis kilden offentliggjorde en ny scanning efter din API-anmodning, viser en forskel mellem de to visninger ikke, at den tidligere anmodning mislykkedes.

3. Kontrollér hændelsesdataene, ikke kun overskriftsstatussen

Sammenlign den seneste hændelses beskrivelse, placering, transportørstatus eller -kode samt relevante leveringsfelter med registreringen fra den overliggende kilde. En normaliseret status som “under transport” kan opsummere flere forskellige scanninger. Hvis din applikation kun gemmer opsummeringen, kan den se uændret ud, selv om en ny hændelse er ankommet.

Undersøg det rå API-svar eller den gemte webhook-krop, hvor dine regler for datahåndtering tillader det. Følg derefter hændelsen gennem parsing, feltmapping, lagring og præsentation. Se efter null-felter, der overskrives af standardværdier, uventede statuskoder, der falder ind under en generisk kategori, tekst, der afkortes, eller en brugergrænseflade, der kun viser udvalgte hændelsestyper. En uoverensstemmelse i statusetiketten er forskellig fra en manglende hændelse: den peger på transformations- eller visningslogik snarere end levering.

Antag ikke, at der har fundet en levering sted, blot fordi en placering eller status lyder afsluttende. Bekræft den specifikke hændelse og de felter, som dit workflow er afhængigt af. Omvendt er en uændret overordnet status ikke et bevis på, at synkroniseringen er stoppet; en nyligt modtaget scanning kan være knyttet til den samme kategori. Din diagnostikregistrering bør bevare både hændelsen fra den overliggende kilde og den værdi, der vises til brugerne.

4. Spor, hvordan hændelsen nåede din applikation

Hvis du bruger webhooks, skal du kontrollere modtagelsesloggen for den relevante forsendelse og hændelse. Bekræft, at dit slutpunkt accepterede anmodningen, at meddelelsen bestod valideringen, og at den efterfølgende behandling blev fuldført. Et HTTP-succesvar fra dit slutpunkt beviser ikke, at en efterfølgende køarbejder gemte hændelsen. Hvis behandlingen er asynkron, skal du undersøge både den indgående anmodning og jobresultatet.

Hvis du spørger en API, skal du kontrollere den senest fuldførte anmodning, forsendelsesidentifikatoren i den anmodning, dens svar samt den paginerings- eller hentelogik, som din integration bruger. En vellykket anmodning kan stadig blive efterfulgt af en mislykket databaseskrivning eller en læsning fra en forældet cache. Brug udbyderens relevante dokumentation til at bekræfte de faktiske svarfelter, godkendelseskrav og leveringsadfærd for din integration i stedet for at antage, at alle sporings-API'er følger den samme kontrakt. For en 17TRACK-integration er de relevante startpunkter dens side for Tracking API og API-dokumentation; bekræft den dokumenterede adfærd for det slutpunkt og den metode, du bruger.

Gør hændelsesbehandlingen sikker at gentage. Et nyt forsøg bør ikke oprette duplikerede scanninger, sende den samme kundemeddelelse gentagne gange eller erstatte en nyere gemt tilstand med en ældre datamængde. Den passende duplikatnøgle afhænger af de felter, som din udbyder faktisk leverer. Test den valgte nøgle mod forskellige hændelser, der tilfældigvis deler en status eller et tidsstempel; disse hændelser bør ikke slås sammen, blot fordi de ligner hinanden.

5. Bekræft reglerne for rækkefølge og tilstandsovergange

Sortér de registrerede hændelser efter en klart defineret regel, og undersøg derefter resultatet. Mange applikationer skal skelne mellem “seneste hændelse, der fandt sted” og “seneste hændelse, vi modtog”. En forsinket tidligere scanning kan ankomme efter en nyere scanning. Hvis din database blot gør den senest behandlede meddelelse til den aktuelle forsendelsestilstand, kan den forsinkede scanning få den viste status til at gå tilbage.

Sammenlign din gemte historik med historikken fra den overliggende kilde, ikke kun det enkelte statusfelt. Spørg, om en nyligt modtaget registrering blev tilføjet, kasseret som en dublet eller fik lov til at opdatere den aktuelle tilstand. Kontrollér alle regler, der giver visse hændelser prioritet over andre. En sådan regel kan være tilsigtet, men den bør ikke skjule den underliggende hændelse eller antyde, at transportøren har tilbageført en milepæl, når applikationen blot modtog en ældre scanning sent.

Som en praktisk test kan du tage en forsendelse med mere end én hændelse og afspille dens meddelelser i en anden ankomstrækkefølge i et ikke-produktionsmiljø. Bekræft, at hændelseshistorikken forbliver intakt, og at den kundevendte status følger din dokumenterede regel. Dette afslører rækkefølgefejl, som en normal test med korrekt rækkefølge ikke kan afdække.

6. Mål aktualiteten, og afstem undtagelser

Sammenlign til sidst, hvad hvert lag vidste på det samme observationstidspunkt: transportørens visning, sporingsudbyderens svar, den indgående webhook eller poll-resultatet, databaseregistreringen og det kundevendte output. Markér det første lag, hvor den forventede hændelse forsvinder. Denne grænse er mere nyttig end en generel rapport om, at “sporingen er forsinket”.

Mål både alderen på den seneste hændelse, der er rapporteret af transportøren, og tiden siden din integration sidst kontrollerede eller modtog data med succes. De besvarer forskellige spørgsmål. En pakke kan mangle en ny scanning fra transportøren, selv om din integration fungerer korrekt; alternativt kan transportøren vise en ny scanning, mens din seneste vellykkede anmodning er gammel. Brug alarmtærskler, der afspejler dine egne driftskrav og den adfærd, du har observeret. Lov ikke kunderne et fast opdateringsinterval, medmindre dine aftaler med transportør og udbyder understøtter det.

Opret en lille afstemningskø for forsendelser, hvis registreringer adskiller sig fra den valgte sammenligningskilde. Medtag identifikatorer, den manglende eller uoverensstemmende hændelse, relevante tidsstempler, det første fejlende lag og den næste handling. En hændelse, der findes i udbyderens svar, men mangler i din database, kræver for eksempel en undersøgelse af integrationen. En hændelse, der findes i din database, men mangler på sporingssiden, kræver en kontrol af visning eller caching. Hvis transportøren selv ikke viser en ny scanning, kan en ny API-anmodning ikke skabe en.

Den operationelle test er enkel: Kan du identificere den samme forsendelse, finde dens senest kendte hændelse fra den overliggende kilde og følge hændelsen hele vejen til den brugervendte visning uden at ændre dens betydning? Hvis ikke, indsnævrer de seks kontroller problemet til en specifik grænse og giver dit team et velbegrundet næste skridt.

Ofte stillede spørgsmål

Betyder et vellykket webhook-svar, at den seneste hændelse er synkroniseret?

Nej. Det viser, at dit slutpunkt returnerede et vellykket svar på en anmodning. Bekræft også, at validering, købehandling, databaselagring og visning lykkedes. Kontrollér datamængden for at fastslå, hvilken hændelse anmodningen indeholdt.

Hvorfor viser transportørens side en nyere scanning end mit API-svar?

Bekræft først, at du ser den samme pakke, og at begge observationer blev foretaget på sammenlignelige tidspunkter. Transportørens offentliggørelse og sporingsudbyderens modtagelse eller visning af en hændelse kan finde sted på forskellige tidspunkter. Hvis forskellen fortsætter, skal du bruge udbyderens dokumentation og supportproces til at undersøge den specifikke forsendelse i stedet for at antage, at der er en opdateringsgaranti.

Skal jeg bruge hændelsestidsstemplet eller tidspunktet, hvor mit system modtog den, til at vælge den seneste status?

Brug en dokumenteret regel, der passer til dit workflow, og behold begge værdier. Hændelsestidsstemplet beskriver, hvornår den rapporterede aktivitet fandt sted; modtagelsestidspunktet beskriver, hvornår dit system fik kendskab til den. Ingen af felterne løser alene alle tilfælde, især ikke når kildetidspunkterne er tvetydige, eller tidligere scanninger ankommer sent.

Hvad hvis API-statussen er uændret, men hændelseslisten har en ny post?

Det kan være forventet, hvis flere hændelser fra transportøren knyttes til én normaliseret status. Sammenlign hændelsesdetaljerne, og bekræft, at din applikation gemte og viser den nye post, hvor det er relevant. Behandl en manglende hændelse og en uændret opsummeringsetiket som forskellige problemer.

Kilder