Skip to main content
EtusivuBlogiOppaatLähetysseurannan API-työnkulku: lähetyksen rekisteröinnistä seurantatietojen hakemiseen

Lähetysseurannan API-työnkulku: lähetyksen rekisteröinnistä seurantatietojen hakemiseen

17TRACK

Lähetyksen seurantaan tarkoitetun API-työnkulun alussa lähetetään seurantanumero ja mahdolliset vaaditut kuljetusliikenteen harjoittajan tiedot, tarkistetaan, onnistuiko rekisteröinti, annetaan seurantatietojen tulla saataville ja haetaan lähetyksen tila sekä tapahtumahistoria. Tuotantointegraatiota varten kehittäjien on lisäksi yhdistettävä jokainen seurantatietue tilaukseen, käsiteltävä osittaiset virheet, käsiteltävä päivitykset turvallisesti ja erotettava hyväksytty rekisteröinti todellisesta kuljetusliikkeen skannauksesta.

Shipment Tracking API Workflow from Registering a Shipment to Retrieving

Tässä oppaassa selitetään tämä työnkulku kehittäjille, jotka yhdistävät verkkokauppa-alustan, tilaustenhallintajärjestelmän, varastosovelluksen tai asiakaspalvelutyökalun. Siinä erotetaan sovellussuunnittelua koskevat suositukset palveluntarjoajakohtaisista API-vaatimuksista. 17TRACK-integraatiota varten tarkista virallisesta API-dokumentaatiosta pyyntöjen rakenne, todennus, tuetut toiminnot ja vastauskentät ennen alla olevien esimerkkien toteuttamista.

Ymmärrä, mitä rekisteröinti tekee ja mitä se ei tee

Lähetyksen rekisteröinti seurantapalveluun tarkoittaa tunnisteen lähettämistä, jotta palvelu voi seurata tai hallita kyseistä lähetystä API-sopimuksensa mukaisesti. Se ei ole sama toiminto kuin postimaksun ostaminen, lähetystarran luominen, noudon varaaminen tai paketin luovuttaminen kuljetusliikkeelle.

Pidä seuraavat kolme lopputulosta erillään sovelluksessasi:

  • Pyyntö vastaanotettu: API palautti vastauksen HTTP-pyyntöösi.
  • Rekisteröinti hyväksytty: Palvelu hyväksyi yksittäisen seurantatietueen käsiteltäväksi.
  • Seurantatiedot saatavilla: Palvelulla on lähetystietoja, joita sovelluksesi voi hakea tai vastaanottaa.

Näitä tuloksia ei pidä yhdistää yhdeksi ”onnistui”-lipuksi. Hyväksytyllä seurantanumerolla ei ehkä vielä ole kuljetusliikkeen tapahtumia. Vastaavasti eräpyynnön onnistunut HTTP-vastaus ei osoita, että jokainen erän kohde hyväksyttiin; tarkista palveluntarjoajan määrittämä sovellustason tulosrakenne.

1. Valmistele lähetyksen tunnistetiedot ja API-määritykset

Ennen rekisteröintipyynnön tekemistä päätä, miten lähetys tunnistetaan omassa järjestelmässäsi. Pelkkä tilauksen tunniste ei yleensä riitä, koska yksi tilaus voidaan jakaa useisiin paketteihin. Anna jokaiselle lähetykselle tai paketille oma sisäinen tietueensa ja yhdistä tietue asiaankuuluvaan tilaukseen.

Hyödyllinen sisäinen tietue sisältää seuraavat tiedot. Nämä ovat suositeltuja sovelluskenttiä, eivät 17TRACK-pyynnön rakennetta.

  • Sisäinen lähetys-ID: Pysyvä tunnisteesi paketille.
  • Tilauksen viite: Tilaus tai toimitustietue, johon se kuuluu.
  • Seurantanumero: Kuljetusliikkeen antama tunniste, joka tallennetaan tekstinä alkunollien säilyttämiseksi.
  • Kuljetusliikkeen tiedot: Toimitusjärjestelmäsi ilmoittama kuljetusliikkeen tunniste, jos se tiedetään.
  • Palveluntarjoajan viite: Seurantapalvelun palauttama tunniste, jota tarvitaan myöhemmissä toiminnoissa.
  • Rekisteröinnin tila: Tietueesi siitä, onko lähetys odottamassa, hyväksytty, hylätty vai täsmäytystä odottava.
  • Seurannan tila: Uusin lähetyksen tila, jota ylläpidetään erillään rekisteröinnin tilasta.

Vahvista syötteet ennen lähettämistä. Poista tahattomat ympäröivät välilyönnit, mutta älä muokkaa seurantanumeroa kuljetusliikkeen oletetun muodon perusteella. Säilytä alkuperäinen arvo vianmääritystä varten. Jos kuljetusliike tiedetään, yhdistä se palveluntarjoajan dokumentoituun kuljetusliiketunnisteeseen epävirallisen näyttönimen sijaan.

Määritä todennus palvelinpuolella. Säilytä tunnistetiedot lähdekoodin hallinnan ulkopuolella, pidä kehitys- ja tuotantomääritykset erillään ja peitä salaisuudet lokeista. Vahvista dokumentoitu API-versio, pyyntörajoitukset, erärajoitukset ja tilivaatimukset sen sijaan, että lainaisit arvoja toisesta, asiaankuulumattomasta integraatiosta.

2. Rekisteröi lähetys ja tallenna kohdetason tulos

Lähetä seurantatietue palveluntarjoajan dokumentaatiossa kuvatulla rekisteröintitoiminnolla. Sisällytä vain pakolliset kentät ja valinnaiset tiedot, joilla on määritelty tarkoitus. Älä lähetä asiakkaiden nimiä, osoitteita tai muita henkilötietoja vain siksi, että ne ovat saatavilla tilaustietokannassasi.

Seuraava pseudokoodi havainnollistaa sovelluksen toimintajärjestystä. Funktioiden nimet ovat esimerkinomaisia; ne eivät ole API-päätepisteitä tai SDK-metodeja.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Tallenna riittävästi tietoa tapahtumien selittämiseksi: sisäinen lähetys-ID, lähetysaika, yritysnumero, kohdetason tulos ja mahdollinen palveluntarjoajan pyyntöviite. Älä luota pelkästään väliaikaiseen työntekijälokiin. Asiakaspalvelu- ja operatiiviset tiimisi tarvitsevat pysyvän vastauksen siihen, rekisteröitiinkö lähetys onnistuneesti.

Käsittele erälähetykset yksitellen

Jos API tukee erärekisteröintiä, yhdistä jokainen palautettu kohde alkuperäiseen lähetykseensä. Älä merkitse koko erää hyväksytyksi vain siksi, että HTTP-pyyntö suoritettiin onnistuneesti. Tallenna hyväksytyt kohteet, eristä hylätyt kohteet ja tutki epäselvät tulokset erikseen.

Näin yksi virheellinen seurantanumero ei aiheuta jo onnistuneiden tietueiden tarpeettomia uusintayrityksiä. Lisäksi operatiivinen henkilöstö saa toimivan luettelon korjausta vaativista tietueista.

Käsittele aikakatkaisut epävarmoina tuloksina

Aikakatkaisu ei todista rekisteröinnin epäonnistuneen. Palveluntarjoaja on voinut hyväksyä pyynnön ennen yhteytesi katkeamista. Käytä dokumentoitua idempotenssikäyttäytymistä, kaksoiskappaleiden käsittelyä tai hakutoimintoja tuloksen täsmäyttämiseen ennen sokeaa uudelleenlähetystä.

Jos palveluntarjoajan toiminta kaksoiskappaleiden kohdalla on epäselvää, testaa sitä hallituilla tietueilla ja varmista sopimus ennen automaattisten uusintayritysten käyttöönottoa. Rekisteröintitöiden sisäinen kaksoiskappaleiden suodatus on silti hyödyllistä, mutta se ei korvaa sen ymmärtämistä, miten etäpalvelu käsittelee toistuvia pyyntöjä.

3. Varaudu ensimmäisten seurantatietojen saapumiseen

Kun rekisteröinti on hyväksytty, seurantatiedot eivät ehkä ole heti saatavilla. Lähetystarra voi olla olemassa ennen kuin kuljetusliike on kirjannut fyysisen käsittelytapahtuman. Puuttuvat tiedot voivat myös edellyttää seurantanumeron, kuljetusliikkeen valinnan tai lähetyskohtaisen hakumenettelyn tarkistamista.

Esitä tämä tila nimenomaisesti. ”Rekisteröity; seurantatietoja odotetaan” on tarkempi kuin joko ”Kuljetuksessa” tai ”Rekisteröinti epäonnistui”. Älä keksi toimitusarviota tai liikehdintätapahtumaa tyhjän käyttöliittymän täytteeksi.

Kun tietue pysyy tyhjänä, tutki asia käytännöllisessä järjestyksessä:

  1. Vahvista, että yksittäinen rekisteröinti hyväksyttiin.
  2. Vertaa lähetettyä seurantanumeroa toimitustietueeseen.
  3. Tarkista kuljetusliikeyhdistäminen ja mahdolliset dokumentoidut lisähakuvaatimukset.
  4. Tarkista saman lähetyksen tiedot kuljetusliikkeen omalta seurantisivulta.
  5. Jos kuljetusliikkeellä on tapahtumia mutta integraatiossasi ei, tarkista hakuvastaukset ja ota yhteyttä API-palveluntarjoajaan sensuroitujen vianmääritystietojen kera.

Vältä yleisen odotusajan käyttöönottoa ilman näyttöä. Eskalointisääntöjen tulee kuvastaa toimituspalvelua, odotettua luovutusprosessia ja omia operatiivisia sitoumuksiasi.

4. Hae seurantatiedot ja tulkitse ne oikein

Kun tietue on saatavilla, kutsu dokumentoitua seurantatietojen hakutoimintoa käyttämällä sen vaatimia tunnisteita. Älä oleta, että rekisteröinti ja haku hyväksyvät samat kentät. Joissakin API-sopimuksissa erotetaan seurantanumerot, kuljetusliiketunnisteet ja palveluntarjoajan luomat tietueviitteet.

Sovelluksesi tulisi erottaa kolme tietokerrosta:

  • Lähetyksen yhteenveto: Kokonaistila, jota käytetään koontinäytöissä, tilaussivuilla ja operatiivisissa suodattimissa.
  • Tapahtumahistoria: Yksittäiset havainnot, kuten tapahtumakuvaukset, aikaleimat ja sijainnit, kun ne toimitetaan.
  • Haun metatiedot: Milloin sovelluksesi vastaanotti tai haki tiedot ja onnistuiko pyyntö.

Onnistunut haku tarkoittaa, että hakutoiminto onnistui. Se ei tarkoita, että paketti olisi liikkunut edellisen haun jälkeen. Vertaa palautettuja seurantatietoja tallennettuun tietueeseesi ennen ilmoituksen tai seuraavan työnkulun luomista.

Pidä tapahtuma-aika erillään hakuajasta

Tallenna kuljetusliikkeen tapahtumaan liittyvä aika erillään siitä ajasta, jolloin järjestelmäsi vastaanotti tapahtuman. Tänä iltapäivänä haettu tapahtuma voi kuvata aiempaa skannausta. Sen tapahtuma-ajan korvaaminen hakuajalla saisi vanhan päivityksen näyttämään uudelta fyysiseltä liikkeeltä.

Säilytä alkuperäinen aikaleima ja mahdollinen ilmoitettu aikavyöhykepoikkeama. Normalisoi aikaleimat vertailua varten vain, kun aikavyöhyke tunnetaan. Jos tapahtumalla ei ole aikavyöhyketietoa, säilytä epävarmuus sen sijaan, että määrittäisit sille hiljaisesti palvelimesi aikavyöhykkeen.

Säilytä raakatieto normalisoidun tilan rinnalla

Normalisoitu tila on hyödyllinen lähetysten ryhmittelyssä eri kuljetusliikkeiden välillä, mutta alkuperäinen tapahtumakuvaus voi selittää operatiivisen ongelman tarkemmin. Säilytä molemmat, kun ne ovat saatavilla. Pelkkä laaja poikkeusluokka ei ehkä kerro tukihenkilölle, pitääkö seuraavaksi tarkistaa osoite, ottaa yhteyttä vastaanottajaan vai odottaa uutta päivitystä.

Älä päättele epämääräisestä tilasta toimitustakuuta, vahvistettua katoamista tai tiettyä tullikäsittelyn lopputulosta. Eskaloi asia perustietojen ja toimintaperiaatteidesi mukaisesti.

5. Pidä tietueet ajan tasalla kyselyillä tai webhookeilla

Tietojen hakeminen kerran riittää yhteyden testaamiseen, mutta ei lähetysnäkyvyyden ylläpitämiseen. Tuotantosuunnittelusi tarvitsee päivitysmekanismin. Vahvista valitsemasi palveluntarjoajan tukemat mekanismit ja niihin liittyvät ehdot.

Kyselymallissa sovelluksesi pyytää seurantatietoja aikataulun mukaan. Ajoita pyynnöt dokumentoitujen rajojen sisällä, vältä muuttumattomien tietueiden toistuvaa kyselyä ilman syytä ja käytä perääntymistä uudelleen yritettävissä virheissä. Tilaussivun avaaminen ei saisi automaattisesti käynnistää rajoittamatonta upstream-pyyntöä; tallennettu seurantanäkymä voi palvella sivua, kun hallittu taustaprosessi päivittää sitä.

Jos käytät webhookeja, vahvista saapuvat pyynnöt palveluntarjoajan dokumentoidulla varmennusmekanismilla. Tallenna hyväksytyt viestit pysyvästi tai lisää ne kestävään jonoon ennen niiden kuittaamista webhook-sopimuksen mukaisesti ja käsittele tapahtumat sitten asynkronisesti.

Rakenna vastaanotin sietämään kaksoiskappaleita ja odottamattomassa järjestyksessä saapuvia tapahtumia, ellei dokumentoitu toimitussopimus takaa muuta. Käytä palveluntarjoajan tapahtumatunnistetta kaksoiskappaleiden poistamiseen, jos se on saatavilla. Muussa tapauksessa määritä ja testaa sopiviin tapahtumakenttiin perustuva sormenjälki huomioiden, että se voi vaatia tietojesi mukaisia muutoksia.

Webhook-pohjainen integraatio voi käyttää hallittua hakua myös täsmäytykseen. Esimerkiksi palautustyö voi tarkistaa vastaanottimen käyttökatkoksesta kärsineet tietueet. Tämä on häiriönsietomalli, ei lupa jättää nopeusrajoituksia tai palveluntarjoajakohtaisia ohjeita huomiotta.

6. Muuta seurantatiedot turvallisiksi liiketoimintatoimiksi

Päivitä sisäinen lähetyksen tietue ennen asiakasnäkyvien toimintojen käynnistämistä. Säilytä ilmoituksista ja työnkulkujen siirtymistä pysyvä tietue, jotta toistuva tapahtuma ei tuota toistuvia viestejä.

Yhdistä liiketoimintatoimet merkityksellisiin muutoksiin jokaisen API-vastauksen sijaan. Uusi havaittu toimitustapahtuma voi oikeuttaa toimitusilmoituksen. Toistuvan, saman tapahtuman sisältävän vastauksen ei pitäisi. Poikkeama voi oikeuttaa sisäisen tarkastelun, mutta asiakasviestin tulee kuvastaa sitä, mitä tapahtuma tosiasiassa kertoo.

Määritä, miten käsittelet tapahtumat, jotka vastaanotetaan sen jälkeen, kun lähetys on katsottu valmiiksi. Älä poista tapahtumahistoriaa tai estä pysyvästi kaikkia myöhempiä päivityksiä vain siksi, että yhteenveto saavutti päätetilan. Säilytys-, täsmäytys- ja ilmoitussääntöjesi tulee ottaa huomioon oikeutetut korjaukset ilman, että valmiita työnkulkuja avataan jatkuvasti uudelleen.

Työnkulun soveltaminen 17TRACK-integraatioon

Mukautetun seuranta-integraation olennaiset lähtökohdat ovat 17TRACK Tracking API -sivu ja sen kehittäjädokumentaatio. Arvioi tarjonta tuotesivun avulla ja määritä varsinainen integraatiosopimus dokumentaation perusteella. Kuluttajille tarkoitetut seurantisivut eivät korvaa API-määrityksiä.

Vahvista ennen sovitinsovelluksen kirjoittamista todennusmuoto, rekisteröinti- ja hakutoiminnot, kuljetusliikkeen tunnistamista koskevat säännöt, kohdetason vastausten käsittely ja sovellettavat pyyntörajoitukset. Webhook-pohjaisessa käsittelyssä vahvista myös hyötykuorman rakenne, varmennusprosessi, kuittausvaatimukset ja uudelleenyrityskäyttäytyminen.

Pidä nämä palveluntarjoajakohtaiset tiedot sovittimessa sen sijaan, että levittäisit vastauskenttiä koskevat oletukset koko tilausjärjestelmään. Tällöin muu sovellus voi käyttää sisäisiä käsitteitä, kuten rekisteröinnin tulosta, lähetyksen tilaa, tapahtumahistoriaa ja viimeisintä onnistunutta synkronointia.

Julkaisua edeltävät tarkistukset, joilla vältetään kalliit virheet

  • Hyväksytty mutta tyhjä tietue: Käyttöliittymä näyttää, että seurantatietoja odotetaan, ei sitä, että paketti liikkuu.
  • Sekoitettu erätulos: Jokainen lähetys saa oman tallennetun tuloksensa.
  • Aikakatkaisu lähetyksen jälkeen: Työntekijä täsmäyttää epävarman tuloksen sen sijaan, että olettaisi epäonnistumisen.
  • Toistuva tapahtuma: Lähetyksen aikajana ja asiakasilmoitus pysyvät ilman kaksoiskappaleita.
  • Vanhempi tapahtuma vastaanotetaan myöhemmin: Tapahtuma säilytetään korvaamatta uudempaa yhteenvetoa sokeasti.
  • Upstream-palvelu ei ole saatavilla: Asiakassivu voi näyttää viimeksi tallennetun tuloksen ja asianmukaisen tuoreustiedon.
  • Virheellinen kuljetusliikeyhdistäminen: Tietue voidaan korjata dokumentoidun palautuspolun kautta.
  • Jaettu tilaus: Jokainen paketti säilyttää oman seurantatilansa ja tapahtumahistoriansa.
  • Tunnistetietojen tai hyötykuorman paljastuminen: Lokit sisältävät vianmääritysviitteet paljastamatta salaisuuksia tai tarpeettomia henkilötietoja.

Käytännön valmistumiskriteeri ei ole vain onnistuneen rekisteröintivastauksen vastaanottaminen. Olennaista on pystyä seuraamaan pakettia lähettämisestä päivityksiin, selittämään tyhjä tai epäonnistunut tulos ja palautumaan keskeytyneestä käsittelystä menettämättä tapahtumia tai luomatta asiakastoimintoja toistuvasti.

Usein kysytyt kysymykset

Luoko seurantanumeron rekisteröinti lähetyksen?

Ei tässä kuvatussa työnkulussa. Seurannan rekisteröinti lähettää olemassa olevan tunnisteen seurantapalveluun. Tarran luominen, postimaksun ostaminen ja kuljetusliikkeen varaus ovat erillisiä toimintoja, ellei jokin tietty API nimenomaisesti yhdistä niitä.

Miksi seurantatiedot ovat tyhjiä rekisteröinnin onnistumisen jälkeen?

Rekisteröinnin hyväksyminen ja seurantatietojen saatavuus ovat eri ehtoja. Kuljetusliike ei ehkä ole vielä kirjannut tapahtumaa, tai seurantanumero, kuljetusliikeyhdistäminen tai lisähakutiedot on ehkä tarkistettava. Tarkista kohdetason tulos ennen kuin pidät tietuetta onnistuneesti rekisteröitynä.

Pitäisikö lähetys rekisteröidä joka kerta, kun haen sen tilan?

Älä käytä toistuvaa rekisteröintiä oletusarvoisena päivitysmekanismina. Tallenna hyväksytty rekisteröintitila ja käytä dokumentoitua haku- tai päivitysmekanismia. Noudata palveluntarjoajan nimenomaisia sääntöjä korjauksille, uudelleenaktivoinnille tai kaksoiskappaleiden lähetyksille.

Pitäisikö käyttää kyselyitä vai webhookeja?

Käytä mekanismia, joka sopii dokumentoituun API-sopimukseen ja operatiivisiin vaatimuksiisi. Kyselyt edellyttävät hallittua pyyntöaikataulua. Webhookit edellyttävät turvallista, kestävää vastaanotinta ja kaksoiskappaleita turvallisesti käsittelevää prosessointia. Jos webhook-päivityksiä tuetaan, ne voivat yhdessä kohdennetun täsmäytyksen kanssa tarjota käytännöllisen palautuspolun.

Voinko käyttää seurantanumeroa tietokantani ainoana lähetyksen tunnisteena?

Käytä sen sijaan sisäistä lähetyksen tunnistetta. Tallenna seurantanumero ja asiaankuuluvat kuljetusliikkeen tiedot kyseisen tietueen ominaisuuksina. Näin jaettujen tilausten, korjattujen seurantanumeroiden ja palveluntarjoajakohtaisten viitteiden hallinta helpottuu ilman sisäisen lähetyksen tunnisteen muuttamista.

Lähteet

  • 17TRACK Tracking API — virallinen tuotesivu 17TRACK API -integraation arviointiin.
  • 17TRACK API documentation — virallinen viite toteutuskohtaisille pyyntömuodoille, toiminnoille, vastauksille ja integraatiovaatimuksille. Tämän oppaan pseudokoodi ja sisäisten kenttien ehdotukset ovat sovellussuunnitteluesimerkkejä eivätkä tämän API-sopimuksen lainauksia.