Skip to main content
EtusivuBlogiOppaatMitä tietoja seuranta-API:n tulisi palauttaa? 12 kenttää nykyisen tilan lisäksi?

Mitä tietoja seuranta-API:n tulisi palauttaa? 12 kenttää nykyisen tilan lisäksi?

17TRACK

A seurant API:n pitäisi palauttaa enemmän kuin pelkkä tunniste, kuten »Kuljetuksessa«. Nykyisen tilan lisäksi etsi lähetyksen tunnisteet, kuljetusyhtiön tiedot, yksityiskohtaiset tilatiedot, kuljetusyhtiön alkuperäiset viestit, tapahtumahistoria, tapahtumien aikaleimat, sijainnit, toimitusarviot, poikkeukset, kuljetusyhtiöiden väliset siirrot, toimitustiedot sekä tietojen ajantasaisuutta koskevat metatiedot. Yhdessä nämä 12 tietoryhmää auttavat kehittäjiä rakentamaan luotettavia työnkulkuja ja antavat operatiivisille tiimeille riittävästi kontekstia toimia.

Mitä tietoja seurant API:n tulisi palauttaa: 12 kenttää nykyisen tilan lisäksi

Tämä on suositeltu vastaussopimus kehittäjille, teknisille ostajille ja verkkokaupan operatiivisille tiimeille – ei väite siitä, että jokainen kuljetusyhtiö tai API tarjoaisi kaikki kentät. Jotkin arvot eivät perustellusti ole saatavilla. Parempi ratkaisu on tehdä puutteet näkyviksi sen sijaan, että ne täytettäisiin oletuksilla.

Mikä tekee seurantatiedoista hyödyllisiä?

Nykyinen tila vastaa yhteen rajattuun kysymykseen: mikä on lähetyksen yhteenvetotila? Se ei välttämättä selitä, mitä tapahtui, milloin se tapahtui, ovatko tiedot tuoreita tai mitä pitäisi tehdä seuraavaksi.

Esimerkiksi kaksi lähetystä voi molemmat näyttää tilan »Kuljetuksessa«, vaikka ne vaativat erilaisia toimia. Toisesta voi olla äskettäinen skannaus terminaalissa eikä ilmoitettuja ongelmia. Toisella voi olla tapahtumahistoriaan kirjattu ratkaisematon osoiteongelma. Vain päätilaa lukeva sovellus voi jäädä paitsi tästä erosta.

Arvioi vastausta kolmen käytännön tehtävän perusteella: lähetyksen yhdistäminen oikeaan tilaukseen, sen etenemisen tarkka selittäminen ja sen päättäminen, onko toimenpide perusteltu. Seuraavat kentät tukevat näitä tehtäviä. Kenttien nimet ovat esimerkkejä; ne eivät ole yleinen standardi tai tietyn palveluntarjoajan skeema.

12 kenttää arvioitavaksi nykyisen tilan lisäksi

1. Lähetyksen ja seurannan tunnisteet

Vastauksen pitäisi tunnistaa kuvattava lähetys. Hyödyllisiä arvoja ovat lähetetty seurantanumero, API:n seurantatietueen tunniste ja asiakasviite, jonka järjestelmäsi voi yhdistää toimitus- tai pakettitietueeseen.

Älä oleta, että yksi tilaus vastaa yhtä lähetystä. Tilaus voidaan jakaa useisiin paketteihin, ja korvaava toimitus voi luoda uuden lähetyksen. Tallenna seurantatietueet paketti- tai toimitustasolla ja yhdistä ne sen jälkeen tilaukseen. Säilytä seurantanumerot merkkijonoina, jotta muotoilu ja alkunollat eivät katoa.

Saatat myös pitää tästä: How to Choose a Shipment Tracking Api for Ecommerce?

Lisätietoja: Split Shipment Tracking: How to Track One Order Sent in Multiple Packages

2. Kuljetusyhtiön tunnistetiedot

Etsi vakaa kuljetusyhtiön tunniste luettavan nimen rinnalle. Jos mahdollista, vastauksessa pitäisi erottaa kuljetusyhtiö, jonka sovelluksesi ilmoitti nimenomaisesti, automaattisesti valitusta kuljetusyhtiöstä.

Kuljetusyhtiön konteksti on tärkeä seurantanumeron ja tapahtumien tulkinnassa. Jos tunnistus on epäselvä, integraatiossasi pitäisi olla tapa ratkaista se sen sijaan, että epävarma osuma esitetään huomaamatta vahvistettuna. Säilytä palvelutason tiedot erillään: kuljetusyhtiön nimi yksin ei kerro, käytetäänkö pika-, posti- vai muuta palvelua.

3. Normalisoidut tilatiedot

Pyydä päätilan ohella dokumentoitu tietokoodi tai alitila. Laaja luokka voi kuvata lähetyksen poikkeukseksi, kun taas tarkempi tieto kertoo epäonnistuneesta toimitusyrityksestä, osoiteongelmasta tai tulliin liittyvästä pidätyksestä.

Käytä liiketoimintalogiikassa vakaita koodeja ja esityksessä helposti luettavia tunnisteita. Varmista, miten palveluntarjoaja yhdistää kuljetusyhtiön tapahtumat näihin koodeihin ja miten tuntemattomia tai yhdistämättömiä tapahtumia käsitellään. Normalisoitu tunniste helpottaa eri kuljetusyhtiöiden tietosyötteiden käyttöä, mutta sen ei pitäisi häivyttää tukitiimin tarvitsemia eroja.

4. Kuljetusyhtiön alkuperäiset viestit ja koodit

Säilytä alkuperäinen tapahtumakuvaus ja kuljetusyhtiön tapahtumakoodi, jos ne toimitetaan. Nämä arvot antavat tukihenkilöille kontekstia, joka voi puuttua normalisoidusta tilasta, etenkin kun kuljetusyhtiö käyttää tiettyä operatiivista ilmaisua.

Pidä alkuperäinen teksti erillään käännetyistä tai uudelleen kirjoitetuista kuvauksista. Muutoin asiakkaalle tarkoitettu selitys voidaan sekoittaa kuljetusyhtiön täsmälliseen sanamuotoon. Käsittele kuljetusyhtiön tekstiä epäluotettavana syötteenä sitä näytettäessä: suojaa se asianmukaisesti äläkä esitä sitä suoritettavana HTML:nä.

5. Seurantatapahtumien historia

Hyödyllisen vastauksen pitäisi näyttää lähetyksen aikajana, ei vain viimeisintä tapahtumaa. Jokaisen tapahtuman tulisi ihannetapauksessa sisältää tunniste, tila tai koodi, kuvaus, aikaleima ja saatavilla olevat sijaintitiedot.

Tarkista, palauttaako API koko historian, rajatun ajanjakson vai sivutetut tulokset. Selvitä myös, miten korjaukset ja päällekkäiset havainnot esitetään. Sovelluksesi ei saa olettaa ensimmäisen kohteen olevan aina uusin, ellei vastaussopimus nimenomaisesti takaa tätä järjestystä.

6. Tapahtumien aikaleimat ja aikavyöhyketiedot

Tapahtuman tapahtuma-aika eroaa ajasta, jolloin API vastaanotti tai palautti sen. Säilytä molemmat, jos mahdollista. Ero auttaa selittämään, miksi juuri vastaanotettu päivitys voi kuvata aiemmin tapahtunutta asiaa.

Pyydä aikaleimat, joissa on selkeä UTC-poikkeama tai UTC-merkintä. RFC 3339 määrittelee Internet-protokolliin sopivan aikaleimamuodon, joka sisältää numeeriset aikaerot. Jos lähde tarjoaa vain paikallisen ajan ilman tunnettua poikkeamaa, säilytä tämä epävarmuus äläkä käsittele sitä huomaamatta UTC-aikana. Älä koskaan esitä sekuntitason tarkkuutta, jos lähde tarjoaa vain päivämäärän.

7. Tapahtumien sijainnit ja lähetyksen maantiede

Etsi rakenteisia sijaintikomponentteja, kuten kaupunki, alue, maa ja postinumero, jos ne toimitetaan. Säilytä myös raaka sijaintimerkkijono, jos sen muuntaminen rakenteisiksi kentiksi voisi hävittää merkitystä.

Skannauksen sijainti ei välttämättä ole paketin todellinen sijainti. Samoin viimeksi ilmoitettu terminaali ei todista, että paketti on yhä siellä. Asiakkaille tarkoitetuilla sivuilla sitä pitäisi kuvata viimeksi ilmoitetuksi sijainniksi. Älä päättele puuttuvasta skannaustekstistä koordinaatteja tai tarkkaa toimitusosoitetta.

8. Arvioitu toimituspäivä tai -aikaikkuna

Arvioidun toimituksen kentän pitäisi ilmoittaa, sisältääkö se yhden päivämäärän vai aikaikkunan, kuka arvion tuotti ja milloin se päivitettiin viimeksi. Kuljetusyhtiön antama arvio ja erikseen laskettu ennuste on pidettävä erotettavina.

Älä muunna pelkkää päivämäärää täsmälliseksi saapumisajaksi. Integraation on myös käsiteltävä muutetut tai perutut arviot niin, ettei vanhentunut lupaus jää seurantaan. Jos arviota ei ole, ilmoita sen puuttuvan sen sijaan, että laskisit sellaisen perusteettoman oletuksen pohjalta.

9. Poikkeuksen syy ja tarvittava toimenpide

Poikkeustietojen pitäisi selittää ongelma ja, jos lähde tukee sitä, ilmoittaa toimenpide, vastuullinen osapuoli tai määräaika. Yleinen viivästysilmoitus on toiminnallisesti eri asia kuin vastaanottajan tietoja koskeva pyyntö.

Pidä ilmoitetut tosiasiat erillään omista työnkulkupäätöksistäsi. Yrityksesi voi esimerkiksi avata tukitehtävän, jos päivitystä ei ole tullut määritettynä aikana. Tämä on sisäinen eskalointisääntö, ei todiste siitä, että kuljetusyhtiö olisi ilmoittanut paketin kadonneeksi. Älä luo epäselvästä seurantatekstistä maksuohjeita tai arkaluonteisia tietopyyntöjä.

10. Kuljetusyhtiöiden väliset siirrot ja niihin liittyvät seurantanumerot

Kun lähetys siirtyy operaattorilta toiselle, hyödyllisiä tietoja ovat seuraava kuljetusyhtiö, siihen liittyvä seurantanumero sekä alkuperäisen ja seuraavan tietueen välinen suhde. Tämä auttaa säilyttämään jatkuvuuden, kun toimitusosuudella käytetään eri tunnistetta.

Käsittele ilmoitettu siirto suhteena sen sijaan, että korvaisit alkuperäisen kuljetusyhtiön. Älä yhdistä tietueita vain siksi, että niiden määränpäät tai seurantanumerot näyttävät samanlaisilta. Jos suhdetta ei ilmoiteta tai muuten vahvisteta, jätä se ratkaisemattomaksi äläkä keksi yhtenäistä toimitusketjua.

11. Toimituksen lopputulos ja todisteviitteet

Kun toimitus ilmoitetaan suoritetuksi, vastauksessa pitäisi olla kirjattu toimitusaika ja saatavilla olevat toimitustiedot, kuten kuvaus turvallisesta jättöpaikasta tai vastaanottajan luokka. Toimitustodisteen viite voi myös olla hyödyllinen, jos kuljetusyhtiö ja palvelu tarjoavat sen.

Toimitettu-tilaa ei pidä tulkita todisteeksi siitä, että aiottu vastaanottaja vastaanotti paketin henkilökohtaisesti. Allekirjoitukset, valokuvat, nimet ja tarkat sijainnit voivat sisältää henkilötietoja. Rajoita käyttöoikeuksia, vältä näiden tietojen näyttämistä julkisilla seurant、sivuilla ja varmista toimitustodistelinkkien valtuutus- ja vanhenemisvaatimukset.

12. Ajantasaisuus, haun tila ja vastauksen metatiedot

Pyydä riittävästi metatietoja erottaaksesi viimeisimmän lähetyksen tapahtuman viimeisimmästä onnistuneesta tietojen hausta. Hyödyllisiä arvoja ovat viimeisin onnistunut tarkistus, viimeisin epäonnistunut yritys, vastauksen luontiaika sekä tieto siitä, ovatko palautetut tiedot välimuistissa tai osittaisia.

Onnistunut API-pyyntö ei yksin osoita, että kuljetusyhtiö on julkaissut uuden skannauksen. HTTP-vastauksen semantiikka kuvaa pyynnön tulosta; lähetyksen eteneminen kuuluu sovelluksen tietoihin. Säilytä hakujen virheet erillään lähetyksen poikkeuksista, jotta tilapäinen yhteysongelma ei muutu virheelliseksi toimitushälytykseksi.

Puuttuvilla tiedoilla on oltava määritelty merkitys

Kentän olemassaolo on vain osa sopimusta. Tiimisi on myös ymmärrettävä, mitä puuttuva arvo tarkoittaa. Toimitusarvio voi puuttua lähteestä, sitä ei ehkä ole vielä haettu tai se ei enää koske lähetystä toimituksen jälkeen. Näistä tilanteista ei pitäisi automaattisesti muodostaa samaa asiakasviestiä.

  • Tuntematon: Arvoa ei ole vahvistettu.
  • Ei toimitettu: Lähde ei tarjonnut arvoa haetuissa tiedoissa.
  • Ei sovellettavissa: Kenttä ei koske tätä tietuetta tai tilaa.
  • Haku epäonnistui: Järjestelmä ei pystynyt suorittamaan asiaankuuluvaa hakua.

Nämä ovat suositeltuja erotteluja, eivät pakollisia kirjaimellisia arvoja. Dokumentoi valitsemasi esitystapa. Vältä paikkamerkkipäiviä, kelvollisilta näyttäviä tyhjiä objekteja ja oletuskoordinaatteja, jotka voidaan sekoittaa oikeisiin sijainteihin.

Vastauksen testaaminen ennen integraatiota

Arvioi todellisia tietosisältöjä niiltä kuljetusyhtiöiltä, palveluilta ja toimitusreiteiltä, joita yrityksesi käyttää. Skeema voi luetella valinnaisen kentän takaamatta, että jokainen taustalla oleva lähde täyttää sen. 17TRACK:n virallisesta Tracking API -dokumentaatiosta voit tarkistaa vastaussopimuksen sen sijaan, että pitäisit tämän oppaan käsitteellisiä kenttien nimiä suoraan käyttövalmiina parametreina.

  1. Rakenna edustava otos. Sisällytä uudet lähetykset, aktiiviset lähetykset, toimitusyritykset, valmiit toimitukset ja saatavilla olevat siirtotapaukset.
  2. Jäljitä kentät tapahtumiin. Varmista, että näytetty tila, viimeisin tapahtuma ja toimitustiedot kuvaavat johdonmukaista tietuetta. Selvitä ristiriidat niiden piilottamisen sijaan.
  3. Testaa viivästyneet ja toistuvat päivitykset. Käsittele sama tietosisältö uudelleen ja vastaanota vanhempi tapahtuma uudemman jälkeen. Varmista, ettei kumpikaan tapa aiheuta päällekkäisiä ilmoituksia tai muuta näytettyä tilaa virheellisesti taaksepäin.
  4. Testaa puuttuvat ja virheelliset arvot. Sisällytä puuttuvat arviot, tuntemattomat sijainnit, vieraat tilakoodit ja puutteelliset aikaleimat. Sovelluksen pitäisi pysyä käyttökelpoisena keksimättä korvaavia arvoja.
  5. Erota siirtovirheet seurantatuloksista. Todennusvirheen, aikakatkaisun tai virheellisen vastauksen tulee siirtyä integraatiovirheiden käsittelyyn, ei lähetyksen poikkeustyönkulkuun.
  6. Vahvista asiakasnäkymä. Tarkista, etteivät sisäiset viitteet, raakatason vianmääritystiedot tai henkilötiedot vuoda julkisille sivuille tai ilmoituksiin.

Webhook-pohjaisissa päivityksissä tarkista myös toimitustunnisteet, todennus, uudelleenyritysmenettely ja toistojen käsittely palveluntarjoajan dokumentaatiosta. Nämä ovat integraatiovaatimuksia, eivät lähetyksen tosiasioita. Vastaanottimen tulee käsitellä toistuvat toimitukset turvallisesti eikä olettaa saapumisjärjestyksen vastaavan tapahtumajärjestystä.

Hyväksymiskriteerin pitäisi olla käytännöllinen: pystyykö sovelluksesi selittämään lähetyksen esittämättä perusteettomia väitteitä, ja pystyykö operatiivinen tiimisi tunnistamaan seuraavan perustellun toimenpiteen? Pienempi, hyvin määritelty tietosisältö voi olla hyödyllisempi kuin suurempi vastaus, joka sisältää paljon selittämättömiä valinnaisia arvoja.

FAQ

Onko jokaisessa lähetyksessä oltava kaikki 12 tietoryhmää täytettyinä?

Ei. Toimitustodisteet, seuraavien kuljetusyhtiöiden seurantanumerot ja arvioidut toimituspäivät eivät välttämättä ole saatavilla tai sovellettavissa. Vaadi selkeät kenttämääritelmät ja ennakoitava puuttuvien arvojen käsittely yleisen täyttöasteen sijaan. Tarkista tärkeimmät kentät todellista toimitusvalikoimaasi vasten.

Pitäisikö meidän tallentaa raaka vastaus vai vain normalisoidut kentät?

Tallenna normalisoidut kentät sovelluslogiikkaa varten. Asiaankuuluvien lähdetietosisältöjen säilyttäminen voi myös auttaa vianmäärityksessä ja muutosten yhdistämisessä, huomioiden yksityisyys-, turvallisuus-, sopimus- ja säilytysvaatimukset. Rajoita käyttöoikeuksia äläkä säilytä arkaluonteista sisältöä vain siksi, että se esiintyy vastauksessa.

Minkä aikaleiman pitäisi määrittää viimeisin tapahtuma?

Käytä dokumentoitua tapahtumakronologiaa ja palveluntarjoajan järjestyssääntöjä sekä huomioi aikavyöhykkeet ja korjaukset. Vastaanottoaika kertoo, milloin järjestelmäsi sai tiedon tapahtumasta, ei välttämättä sitä, milloin tapahtuma sattui. Jos aikaleimat ovat puutteellisia tai ristiriitaisia, säilytä epäselvyys sen sijaan, että väittäisit järjestyksen olevan tarkka.

Voiko seurant API vahvistaa, että paketti on kadonnut?

Käsittele lähetys kadonneena kuljetusyhtiön ilmoituksen perusteella vain, jos lähde tukee tätä tulkintaa nimenomaisesti. Pitkä skannausten välinen aika voi oikeuttaa tutkimuksen operatiivisten sääntöjesi mukaisesti, mutta hiljaisuus yksin ei osoita katoamista. Pidä »vanhentunut seuranta« ja »ilmoitettu kadonneeksi« erillisinä käsitteinä.

Riittääkö toimitettu-tila asiakasvalituksen sulkemiseen?

Ei automaattisesti. Se vahvistaa ilmoitetun seurantatuloksen, mutta ei välttämättä ratkaise vastaanottajan kiistaa. Tarkista saatavilla olevat toimitustiedot, asiakkaan tili ja tukiprosessisi. Älä käsittele tilatunnistetta ristiriitaisten tietojen tutkimisen korvikkeena.

Lähteet