6 tarkistusta, joilla varmistat API:si kautta synkronoidut uusimmat kuljetusyhtiön seurantatapahtumat
Varmistaaksesi, että API:si on synkronoinut uusimmat kuljetusyhtiön seurantatapahtumat, tarkista lähetyksen tunnistetiedot, tapahtumien aikaleimat, tapahtumien tiedot, toimitusreitti, tapahtumien järjestys ja tietojen tuoreus riippumattoman seurantatiedon perusteella. Onnistunut API-vastaus tai webhook-kuittaus vahvistaa vain yhden osan tästä ketjusta; se ei yksin todista, että sovelluksesi sisältää kuljetusyhtiön uusimman tapahtuman.

Tämä opas on tarkoitettu kehittäjille ja operatiivisille tiimeille, jotka vastaavat seurantatietojen toimittamisesta tilaustenhallintajärjestelmään, asiakkaille näkyvälle sivulle, tukityökaluun tai hälytystyönkulkuun. Tavoitteena on selvittää, missä tapahtuma katosi tai muuttui, ja päättää sitten, yritetäänkö käsittelyä uudelleen, korjataanko määritys vai odotetaanko kuljetusyhtiöltä uusia tietoja.
Ennen aloittamista: määritä, mitä “uusin” tarkoittaa
Pidä kolme ajankohtaa erillään: milloin kuljetusyhtiö ilmoittaa tapahtuman tapahtuneen, milloin seurantapalveluntarjoajasi vastaanotti tai julkaisi sen ja milloin sovelluksesi tallensi sen. Nämä ajankohdat voivat poiketa toisistaan. Kuljetusyhtiö voi julkaista skannauksen fyysisen tapahtuman jälkeen, ja integraatiosi voi käsitellä sen vielä myöhemmin. Tapahtuma, joka on uusin tapahtuma-ajan perusteella, ei siis välttämättä ole viimeksi vastaanotettu tietue.
Valitse vertailukohta ennen tutkimista. Käytä mieluiten saman lähetyksen kuljetusyhtiön seurantaa tai muuta valtuutettua kuljetusyhtiön tarjoamaa tietuetta. Jos se ei ole saatavilla, vertaa sovellustasi seurantapalveluntarjoajan nykyiseen API-vastaukseen. Tämä suppeampi vertailu voi osoittaa, vastaako sovelluksesi palveluntarjoajaa; se ei kuitenkaan osoita, että palveluntarjoajalla on jo kaikki kuljetusyhtiön skannaukset. Kirjaa vertailun ajankohta, jotta myöhempi päivitys ei saa aiempaa tulosta näyttämään ristiriitaiselta.
1. Varmista, että molemmat järjestelmät viittaavat samaan lähetykseen
Aloita integraatiosi käyttämästä seurantanumerosta, kuljetusyhtiöstä sekä mahdollisista tili- tai lähetyskohtaisista tunnisteista. Pelkkä seurantanumero ei välttämättä riitä vianmääritykseen: numeroon voi liittyä kirjoitusvirhe, se voidaan yhdistää väärään kuljetusyhtiöön tai sitä voidaan käyttää uudelleen sisäisessä tietueessa tilauksen muokkauksen jälkeen. Tilausnumero ja seurantanumero palvelevat myös eri tarkoituksia. Yhdellä tilauksella voi olla useita paketteja, joten tilauksen uusimman tilan tarkistaminen voi peittää vanhentuneen paketin.
- Etsi tarkka seurantanumero ja kuljetusyhtiö, jotka lähetettiin tracking API:lle.
- Varmista, mikä sisäinen lähetys- tai pakettitietue vastaanotti vastauksen.
- Tarkista, korvattiinko, jaettiinko, peruttiinko tai yhdistettiinkö lähetys uudelleen rekisteröinnin jälkeen.
- Vertaa lähdetietueessa näkyvää kuljetusyhtiötä ja numeroa sovelluksessasi näkyviin tietoihin.
Jos tunnisteet eivät täsmää, älä käsittele eroa synkronointiviiveenä. Korjaa yhdistäminen ensin ja toista sitten tapahtumien vertailu. Tallenna diagnostiikkalokeihin riittävästi tunnisteita lähetyksen jäljittämiseksi, mutta älä lisää niihin arkaluonteisia tilitunnuksia.
2. Vertaa tapahtuma-aikoja menettämättä niiden merkitystä
Kerää jokaisesta mahdollisesta uusimmasta tapahtumasta kuljetusyhtiön ilmoittama tapahtuma-aika, ilmoitettu aikavyöhyke tai poikkeama, jos se on annettu, sekä sovelluksesi vastaanotto- ja tallennusajat. Muunna aikaleimat vertailua varten yhteiseen aikaperustaan, mutta säilytä alkuperäinen arvo. RFC 3339 määrittelee internetin aikaleimaformaatin, jossa poikkeamat ilmoitetaan eksplisiittisesti; se on hyödyllinen viite omia aikaleimakenttiä suunniteltaessa. Se ei takaa, että kuljetusyhtiö tai palveluntarjoaja toimittaa aikavyöhykkeen jokaiselle tapahtumalle.
Pelkkä kellonaikanäyttö, oletettu paikallinen aikavyöhyke tai jäsentäjä, joka hävittää poikkeaman huomaamatta, voi siirtää tapahtuman toiselle kalenteripäivälle tai väärään järjestykseen. Jos lähde antaa epäselvän paikallisen ajan, merkitse vertailu epävarmaksi sen sijaan, että keksisit tarkan UTC-hetken. Erota myös tapahtuma-aika API-vastausajasta: nyt haettu vastaus voi perustellusti sisältää aiemmin tapahtuneen tapahtuman.
Kirjaa aika, jolloin tarkistit kuljetusyhtiön tai palveluntarjoajan näkymän. Jos lähde julkaisi uuden skannauksen API-pyyntösi jälkeen, näkymien välinen ero ei osoita, että aiempi pyyntö epäonnistui.
3. Tarkista tapahtuman sisältö, älä vain päätilaa
Vertaa uusimman tapahtuman kuvausta, sijaintia, kuljetusyhtiön tilaa tai koodia sekä asiaankuuluvia toimituskenttiä ylävirran tietueeseen. Normalisoitu tila, kuten “kuljetuksessa”, voi tiivistää useita erilaisia skannauksia. Jos sovelluksesi tallentaa vain yhteenvedon, tila voi näyttää muuttumattomalta, vaikka uusi tapahtuma olisi saapunut.
Tarkista raaka API-vastaus tai säilytetty webhook-runko, jos tiedonkäsittelysäännöt sallivat sen. Seuraa tapahtumaa sen jälkeen jäsentämisen, kenttien yhdistämisen, tallennuksen ja esittämisen läpi. Etsi oletusarvoilla korvattuja tyhjiä kenttiä, yleiseen luokkaan päätyviä odottamattomia tilakoodeja, katkaistua tekstiä tai käyttöliittymää, joka näyttää vain valitut tapahtumatyypit. Tilan nimen ero on eri asia kuin puuttuva tapahtuma: se viittaa muunnos- tai näyttölogiikkaan toimitusongelman sijaan.
Älä päättele toimitusta pelkästään siksi, että sijainti tai tila vaikuttaa lopulliselta. Vahvista kyseinen tapahtuma ja ne kentät, joihin työnkulkusi perustuu. Muuttumaton ylätason tila ei myöskään todista, että synkronointi olisi pysähtynyt; uusi skannaus voi yhdistyä samaan luokkaan. Diagnostiikkatietueessa tulee säilyttää sekä ylävirran tapahtuma että käyttäjille näytetty arvo.
4. Selvitä, miten tapahtuma saapui sovellukseesi
Jos käytät webhookeja, tarkista kyseisen lähetyksen ja tapahtuman vastaanottoloki. Varmista, että päätepisteesi hyväksyi pyynnön, viesti läpäisi validoinnin ja jatkokäsittely valmistui. Päätepisteesi HTTP-onnistumisvastaus ei todista, että myöhempi jonotyöntekijä tallensi tapahtuman. Jos käsittely on asynkronista, tarkista sekä saapuva pyyntö että työn tulos.
Jos kyselet API:ta, tarkista viimeisin valmis pyyntö, pyynnön lähetysidentiteetti, vastaus sekä integraatiosi käyttämä sivutus- tai hakulogiikka. Onnistunutta pyyntöä voi seurata epäonnistunut tietokantakirjoitus tai vanhentuneen välimuistin luku. Varmista integraatiosi todelliset vastauskentät, todennusvaatimukset ja toimituskäyttäytyminen palveluntarjoajan soveltuvista ohjeista sen sijaan, että olettaisit kaikkien tracking API -rajapintojen noudattavan samaa sopimusta. 17TRACK-integraatiossa olennaiset aloituskohdat ovat sen Tracking API -sivu ja API-dokumentaatio; varmista käyttämäsi päätepisteen ja menetelmän dokumentoitu toiminta.
Tee tapahtumien käsittelystä turvallisesti toistettavaa. Uudelleenyritys ei saa luoda kaksoisskannauksia, lähettää samaa asiakasilmoitusta toistuvasti tai korvata uudempaa tallennettua tilaa vanhemmalla sisällöllä. Sopiva duplikaattiavain riippuu kentistä, joita palveluntarjoajasi todella toimittaa. Testaa valittu avain erillisillä tapahtumilla, joilla sattuu olemaan sama tila tai aikaleima; niitä ei saa yhdistää vain siksi, että ne näyttävät samanlaisilta.
5. Varmista järjestys- ja tilasiirtymäsäännöt
Järjestä tallennetut tapahtumat selkeästi määritellyn säännön mukaan ja tarkista tulos. Monissa sovelluksissa on erotettava “viimeisin tapahtunut tapahtuma” ja “viimeisin vastaanotettu tapahtuma”. Viivästynyt aiempi skannaus voi saapua uudemman skannauksen jälkeen. Jos tietokanta tekee viimeksi käsitellystä viestistä yksinkertaisesti nykyisen lähetyksen tilan, viivästynyt skannaus voi siirtää näytetyn tilan taaksepäin.
Vertaa tallennettua historiaa ylävirran historiaan, älä vain yksittäiseen tilakenttään. Selvitä, lisättiinkö uusi tietue, hylättiinkö se duplikaattina vai saiko se päivittää nykyisen tilan. Tarkista kaikki säännöt, jotka antavat tietyille tapahtumille etusijan. Sääntö voi olla tarkoituksellinen, mutta se ei saa piilottaa taustalla olevaa tapahtumaa tai antaa kuvaa, että kuljetusyhtiö perui välivaiheen, kun sovellus tosiasiassa vastaanotti vanhemman skannauksen myöhässä.
Käytännön testissä ota lähetys, jolla on useampi kuin yksi tapahtuma, ja toista sen viestit eri saapumisjärjestyksessä tuotantoon kuulumattomassa ympäristössä. Varmista, että tapahtumahistoria säilyy ja että asiakkaille näkyvä tila noudattaa dokumentoitua sääntöäsi. Näin paljastuvat järjestysvirheet, joita normaali oikeassa järjestyksessä tehty testi ei havaitse.
6. Mittaa tietojen tuoreus ja täsmäytä poikkeamat
Vertaa lopuksi, mitä kukin kerros tiesi samassa havaintohetkessä: kuljetusyhtiön näkymä, seurantapalveluntarjoajan vastaus, saapuva webhook tai kyselyn tulos, tietokantatietue ja asiakkaalle näkyvä tuloste. Merkitse ensimmäinen kerros, jossa odotettu tapahtuma katoaa. Tämä raja on hyödyllisempi kuin yleinen raportti, jonka mukaan “seuranta on viivästynyt”.
Mittaa sekä viimeisimmän kuljetusyhtiön ilmoittaman tapahtuman ikä että aika siitä, kun integraatiosi viimeksi onnistuneesti tarkisti tai vastaanotti tietoja. Ne vastaavat eri kysymyksiin. Paketilla ei ehkä ole uutta kuljetusyhtiön skannausta, vaikka integraatiosi toimii hyvin; vaihtoehtoisesti kuljetusyhtiö voi näyttää uuden skannauksen, vaikka viimeisin onnistunut pyyntösi on vanha. Käytä hälytysrajoja, jotka vastaavat omia toimintavaatimuksiasi ja havaitsemaasi käyttäytymistä. Älä lupaa asiakkaille kiinteää päivitysväliä, elleivät kuljetusyhtiö- ja palveluntarjoajajärjestelysi tue sitä.
Luo pieni täsmäytysjono lähetyksille, joiden tietueet poikkeavat valitusta vertailulähteestä. Sisällytä tunnisteet, puuttuva tai poikkeava tapahtuma, asiaankuuluvat aikaleimat, ensimmäinen epäonnistunut kerros ja seuraava toimenpide. Jos tapahtuma on palveluntarjoajan vastauksessa mutta puuttuu tietokannastasi, tarvitaan integraatiotutkimus. Jos tapahtuma on tietokannassasi mutta puuttuu seurantatieltä, tarkista näyttö tai välimuisti. Jos kuljetusyhtiö ei itse näytä uutta skannausta, uusi API-pyyntö ei voi luoda sitä.
Toiminnallinen testi on suoraviivainen: pystytkö tunnistamaan saman lähetyksen, löytämään sen viimeisimmän tunnetun ylävirran tapahtuman ja seuraamaan tapahtumaa muuttamatta sen merkitystä aina käyttäjälle näkyvään näkymään asti? Jos et, kuusi tarkistusta rajaavat ongelman tiettyyn rajapintaan ja antavat tiimillesi perustellun seuraavan askeleen.
UKK
Tarkoittaako onnistunut webhook-vastaus, että uusin tapahtuma on synkronoitu?
Ei. Se osoittaa, että päätepisteesi palautti onnistuneen vastauksen pyyntöön. Varmista myös validoinnin, jonokäsittelyn, tietokantatallennuksen ja näytön onnistuminen. Tarkista sisältö selvittääksesi, minkä tapahtuman pyyntö sisälsi.
Miksi kuljetusyhtiön sivu näyttää uudemman skannauksen kuin API-vastaukseni?
Varmista ensin, että tarkastelet samaa pakettia ja että molemmat havainnot tehtiin vertailukelpoisina ajankohtina. Kuljetusyhtiön julkaisu ja seurantapalveluntarjoajan tapahtuman vastaanotto tai julkaisu voivat tapahtua eri aikoina. Jos ero säilyy, tutki kyseistä lähetystä palveluntarjoajan dokumentaation ja tukiprosessin avulla sen sijaan, että olettaisit päivitystakuun.
Pitäisikö uusimman tilan valintaan käyttää tapahtuman aikaleimaa vai aikaa, jolloin järjestelmäni vastaanotti sen?
Käytä työnkulkuusi sopivaa dokumentoitua sääntöä ja säilytä molemmat arvot. Tapahtuma-aikaleima kuvaa, milloin ilmoitettu toiminta tapahtui; vastaanottoaika kuvaa, milloin järjestelmäsi sai siitä tiedon. Kumpikaan kenttä ei yksin ratkaise kaikkia tapauksia, etenkin kun lähdeajat ovat epäselviä tai aiemmat skannaukset saapuvat myöhässä.
Mitä jos API-tila ei muutu, mutta tapahtumaluettelossa on uusi merkintä?
Se voi olla odotettua, jos useat kuljetusyhtiön tapahtumat yhdistyvät yhteen normalisoituun tilaan. Vertaa tapahtuman tietoja ja varmista, että sovelluksesi tallensi ja näyttää uuden merkinnän tarvittaessa. Käsittele puuttuvaa tapahtumaa ja muuttumatonta yhteenvetotunnistetta eri ongelmina.
Lähteet
- 17TRACK Tracking API — tuoteviite tracking API -integraatioille.
- 17TRACK API documentation — viite sovellettavan integraatiosopimuksen tarkistamiseen.
- RFC 3339: Date and Time on the Internet: Timestamps — aikaleima- ja UTC-poikkeamamuodon viite.


