Skip to main content
EtusivuBlogiOppaatSeurantanumeron rekisteröinti API:n kautta: pyynnön kentät, kuljetusyhtiöiden koodit ja vastaukset

Seurantanumeron rekisteröinti API:n kautta: pyynnön kentät, kuljetusyhtiöiden koodit ja vastaukset

17TRACK

Rekisteröi seurantatunnus API:n kautta lähettämällä todennettu rekisteröintipyyntö, joka sisältää lähetyksen seurantatunnuksen ja tarvittaessa kuljetusliikkeen tunnisteen. Tarkista sitten jokaisen lähetetyn lähetyksen vastaus — älä pelkästään HTTP-tilaa — ja tallenna, onnistuiko rekisteröinti, epäonnistuiko se vai onko tulos edelleen epävarma. Rekisteröinti käynnistää seurannan työnkulun; se ei todista, että kuljetusliike on skannannut paketin tai että seurantatapahtumat ovat jo saatavilla.

Seurantatunnuksen rekisteröiminen API-pyynnön kenttien avulla

Tämä opas on tarkoitettu kehittäjille, jotka yhdistävät tilaustenhallintajärjestelmän, varastosovelluksen tai verkkokauppa-alustan seuranta-API:in. Esimerkkinä käytetään 17TRACK-integraatiota, ja oppaassa selitetään, mitkä tiedot on tarkistettava valitun API-version dokumentaatiosta.

Mitä rekisteröinti tekee — ja mitä se ei tee

Rekisteröintipyyntö ilmoittaa seurantapalvelulle, mitä lähetystä haluat sen seuraavan. Se eroaa toimitustarran ostamisesta, noudon varaamisesta tai kuljetusliikkeen pyytämisestä luomaan lähetyksen. Tyypillisessä integraatiossa toimitustyönkulku tuottaa ensin seurantatunnuksen, minkä jälkeen sovelluksesi rekisteröi kyseisen tunnuksen.

Pidä nämä kolme tapahtumaa erillään sovelluksessasi:

  • Lähetys luotu: toimitusjärjestelmäsi on määrittänyt seurantatunnuksen.
  • Rekisteröinti hyväksytty: seurantapalvelu on hyväksynyt lähetyksen seurantaa varten.
  • Seurantatiedot vastaanotettu: kuljetusliikkeen tapahtumat ovat tulleet saataville seurantapalvelun kautta.

Älä päivitä tilausta tilaan ”kuljetuksessa” vain siksi, että rekisteröinti onnistui. Äskettäin luodusta tarrasta ei välttämättä vielä ole fyysistä vastaanottoskannausta. Asiakkaalle näytettävän lähetysstatuksen tulee perustua seurantatapahtumiin, joita tulkitaan tilakartoitussääntöjesi avulla, ei rekisteröintivastaukseen.

17TRACK-integraatioissa aloita Tracking API overview -sivulta ja käytä virallista API-dokumentaatiota auktoriteettina päätepisteiden, kenttämääritelmien, todennuksen ja vastauskoodien osalta. Alla olevat esimerkit keskittyvät rekisteröintiin eivätkä erillisiin tulosten hakemisen tai päivitysten vastaanottamisen tehtäviin.

Valmistele pyyntökentät ennen API-kutsun kirjoittamista

Hyödyllisin valmistelu on pieni kenttäsopimus toimitusjärjestelmäsi ja seuranta-integraatiosi välillä. Päätä, mistä kukin arvo tulee, voiko se puuttua ja miten se validoidaan.

Kenttä tai arvoTarkoitusToteutussääntö
SeurantatunnusTunnistaa seurattavan lähetyksen.Tallenna ja lähetä se merkkijonona; säilytä alussa olevat nollat.
Kuljetusliikkeen tunnisteTunnistaa kuljetusliikkeen seurantapalvelun järjestelmässä.Käytä palveluntarjoajan dokumentoimaa tunnistetta, älä sisäistä varastokoodia.
Sisäinen viiteYhdistää rekisteröinnin lähetysmerkintääsi.Käytä tuettua viitekenttää, jos sellainen on saatavilla; säilytä oma tietokantakartoituksesi joka tapauksessa.
Ylimääräiset tunnistetiedotVoivat auttaa lähetyksen tunnistamisessa, jos kuljetusliike vaatii muutakin kuin seurantatunnuksen.Lähetä vain kyseiselle integraatiolle ja kuljetusliikkeelle dokumentoidut kentät.
API-tunnistetietoTodentaa kutsuvan tilin.Säilytä se palvelimella ja jätä se pois sovelluslokeista.

Käsittele seurantatunnusta tunnisteena

Älä koskaan muunna seurantatunnusta kokonaisluvuksi. Numeerinen muunnos voi poistaa alussa olevat nollat, ja suuret arvot voivat menettää tarkkuutta joissakin ohjelmointiympäristöissä. Poista vahingossa lisätyt alun ja lopun välilyönnit, mutta älä poista välimerkkejä tai muuta kirjainkokoa, ellei asiaankuuluva dokumentaatio tai kuljetusliikkeen muoto tue tällaista normalisointia.

Validoi ilmeiset syötevirheet ennen API:n kutsumista: tyhjät merkkijonot, odottamattomat rivinvaihdot ja tilausnumero, joka on kopioitu seurantatunnuksen kenttään. Vältä yhden yleisen pituus- tai merkkisäännön asettamista kaikille kuljetusliikkeille. Yhdelle kuljetusliikkeelle sopiva validointisääntö voi hylätä toisen kuljetusliikkeen kelvolliset tunnukset.

Pidä tilausviitteet erillään lähetyksen tunnisteista

Tilauksella voi olla useita paketteja, ja korvaava lähetys voi tuoda uuden seurantatunnuksen. Mallinna rekisteröinti lähetys- tai pakettitasolla sen sijaan, että olettaisit jokaiselle tilaukselle yhden seurantatunnuksen.

Jos käytät palveluntarjoajan tukemaa tunnistetta tai viitekenttää, suosi läpinäkymätöntä lähetysviitettä asiakkaan sähköpostiosoitteen tai katuosoitteen sijaan. Oman tietokantasi tulee säilyä auktoritatiivisena yhteytenä tilausten, lähetysten, seurantatunnusten ja kuljetusliikekartoitusten välillä.

Valitse oikea kuljetusliikkeen koodi

Kuljetusliikkeen koodi ei välttämättä ole yleinen toimialan tunniste. Seurantapalvelualustan tunnistama arvo voi poiketa toimitusohjelmistoon tallennetusta kuljetusliikkeen nimestä. Jopa kaksi numeerisia koodeja käyttävää järjestelmää voi antaa samalle kuljetusliikkeelle eri numeron.

Ylläpidä nimenomaista kartoitusta toimituspalvelustasi seurantapalveluntarjoajan kuljetusliikkeen tunnisteeseen. Erota tarvittaessa kuljetusliikkeen alueellinen toiminta tai palvelu sen laajemmasta brändistä. Pelkkään näyttönimeen perustuva kartoitus voi muuttua epäselväksi, kun toimitusjärjestelmät käyttävät aliaksia.

  • Kun kuljetusliike tunnetaan: käytä dokumentoitua kuljetusliikkeen tunnistetta, kun sitä tuetaan, erityisesti silloin, kun seurantatunnusten muodot menevät päällekkäin.
  • Kun kuljetusliikettä ei tunneta: käytä automaattista tunnistusta vain dokumentoidun mekanismin kautta. Älä oleta, että puuttuva arvo, tyhjä merkkijono, nolla ja null tarkoittavat samaa.
  • Kun tulos näyttää väärältä: tarkista alkuperäinen tarra, toimituspalvelu ja kartoitus ennen kuin rekisteröit saman tunnuksen toistuvasti.

Automaattinen tunnistus on hyödyllinen, mutta se ei ole todiste siitä, että tietty kuljetusliike pitää lähetystä fyysisesti hallussaan. Samoin kelvollinen kuljetusliikkeen koodi ei takaa, että toimitettu seurantatunnus kuuluu kyseiselle kuljetusliikkeelle.

Pidä kuljetusliikekartoitukset määritettävinä sen sijaan, että hajauttaisit ne sovelluskoodiin. Tallenna, milloin kartoitus tarkistettiin viimeksi, ja sisällytä tunnettu lähetys regressiotesteihin aina, kun muutat sitä.

Esimerkki: lähetä 17TRACK-rekisteröintipyyntö

Seuraava esimerkki havainnollistaa 17TRACK v2.2 -rekisteröinnin päätepistettä, 17token-todennusotsaketta ja taulukkoa, joka sisältää yhden seurantatunnusobjektin. Varmista ennen käyttöönottoa, että tämä versio ja sen pyyntövaatimukset vastaavat tiliäsi ja virallista dokumentaatiota. Seurantatunnus on paikkamerkki, joka on korvattava todellisella lähetyksen tunnisteella.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

Tämä suppea esimerkki ei havainnollista kuljetusliikkeen valintaa tai kuljetusliikekohtaisia lisäkenttiä. Tarkista rekisteröintidokumentaatiosta, miten kuljetusliikkeen tunnistus toimii, kun kuljetusliikkeen kenttä jätetään pois, ja tarvitseeko lähetyksesi lisätietoja. Jos toimitat kuljetusliikkeen, käytä dokumentoitua carrier-kenttää ja kyseisen API-version odottamaa tunnistetta.

Suorita tämä pyyntö palvelinpuolen ympäristöstä. Älä upota tunnistetta julkiseen verkkokauppaan, selaimen komentosarjaan tai asiakkaille jaettavaan mobiilisovellukseen. Ympäristömuuttuja on kätevä paikallisessa esimerkissä; tuotantokäyttöönottojen tulee käyttää organisaatiosi salaisuuksienhallinnan valvontakeinoja.

Testaa ennen volyymin kasvattamista yksi tunnettu lähetys ja tarkista koko vastaus. Testaa sitten virheellinen syöte sekä erä, joka sisältää kelvollisia ja virheellisiä kohteita. Näillä tarkistuksilla selviää, käsitteleekö integraatiosi todella kohdetason tuloksia eikä ainoastaan tunnista HTTP-onnistumisvastausta.

Lue vastaus kolmella tasolla

Luotettava vastauskäsittelijä vastaa kolmeen erilliseen kysymykseen: saavuttiko pyyntö palvelun, hyväksyikö palvelu toiminnon ja mitä kullekin lähetykselle tapahtui?

1. HTTP- ja siirtotason tulos

Yhteyden aikakatkaisu, TLS-virhe tai katkennut vastaus ei välttämättä kerro, käsitteliko palvelin pyynnön. Merkitse tulos epävarmaksi, kunnes voit täsmäyttää sen. HTTP:n onnistumisstatus vahvistaa onnistuneen HTTP-vaihdon, mutta sinun on silti tarkistettava sovelluksen vastaus.

2. Pyyntötason tulos

Tarkista API:n dokumentoidut ylätason tulos- ja virhekentät. Todennusvirheet, virheellinen JSON ja tiliin liittyvät rajoitukset edellyttävät erilaisia toimenpiteitä. Tallenna palveluntarjoajan alkuperäinen virhekoodi ja viesti sen sijaan, että pelkistäisit kaikki virheet muotoon ”seuranta ei ole käytettävissä”.

Älä oleta, että numeerisella sovelluskoodilla on sama merkitys kuin HTTP-statuskoodilla. Niiden merkitykset tulevat eri kerroksista, ja ne on tulkittava erikseen.

3. Lähetystason tulos

Kun rekisteröit erän, käsittele jokainen lähetetty kohde. Vastaus voi erottaa hyväksytyt ja hylätyt lähetykset; jäsentimen tulee noudattaa valitulle versiolle dokumentoitua täsmällistä skeemaa. Älä merkitse koko erää rekisteröidyksi vain siksi, että yksi kohde onnistui.

Normalisoi palveluntarjoajan vastaukset omiin vakaisiin sovellustiloihisi. Tietokantasi voisi esimerkiksi käyttää arvoja accepted, rejected ja uncertain. Nämä ovat ehdotettuja sisäisiä tiloja eivätkä kirjaimellisia 17TRACK-vastausarvoja. Säilytä alkuperäinen palveluntarjoajan vastaus asianmukaisen säilytys- ja käyttöoikeuspolitiikan mukaisesti, jotta kehittäjät voivat tutkia poikkeamia.

Hyödyllinen rekisteröintitietue sisältää sisäisen lähetys-ID:n, lähetetyn tunnuksen, kuljetusliikkeen valinnan, yritysajan, API-version, tuloksen ja palveluntarjoajan virhetiedot. Pidä rekisteröintistatus erillään toimitusstatuksesta.

Käsittele uudelleenyritykset ilman loputonta silmukkaa

Uudelleenyrityskäytännön tulee riippua virheestä, ei yksinkertaisesti siitä, tapahtuiko poikkeus.

  • Virheellinen syöte: korjaa kenttä ennen uudelleenyritystä. Muuttamattoman virheellisen pyynnön toistaminen ei todennäköisesti auta.
  • Todennusvirhe: tarkista tunnistetiedot ja tilin määritykset. Vältä saman epäonnistuvan erän toistuvaa lähettämistä.
  • Rajoitettu käyttötiheys: noudata dokumentoituja rajoja ja soveltuvia uudelleenyritysohjeita. Käytä rajattua backoffia välittömien rinnakkaisten uudelleenyritysten sijaan.
  • Tilapäinen palveluvirhe: yritä uudelleen määritellyn yritys- ja aikabudjetin puitteissa.
  • Aikakatkaisu lähetyksen jälkeen: täsmäytä lähetyksen rekisteröintitila dokumentoidun API-käyttäytymisen avulla ennen kuin oletat ensimmäisen yrityksen epäonnistuneen.
  • Duplikaattiin liittyvä vastaus: tarkista, onko lähetys jo rekisteröity ja yhdistetty oikein sovellustietueeseesi.

Älä oleta rekisteröinnin olevan idempotentti, ellei dokumentaatio määritä tätä toimintaa. Sovellustason duplikaattien poisto vähentää tahattomia toistuvia lähetyksiä, mutta se ei määritä palveluntarjoajan duplikaattien käsittelykäytäntöä.

Käytä lähetysmalliisi sopivaa sisäistä yksilöllisyyssääntöä. Pelkkä seurantatunnus ei välttämättä riitä pysyväksi avaimeksi eri kuljetusliikkeiden ja pitkien säilytysaikojen yli. Säilytä kuljetusliikekonteksti ja oma lähetys-ID:si sekä dokumentoi, miten korvaavat ja korjatut tunnukset käsitellään.

Valvo rekisteröintiä erillään seurantapäivityksistä

API-valvonnan tulee erottaa integraatiohäiriö lähetyksestä, jolla ei yksinkertaisesti ole uutta kuljetusliikkeen tapahtumaa. Nämä tilanteet edellyttävät eri vastuuhenkilöitä ja eri korjauksia.

Valvo rekisteröinnissä hyväksymis- ja hylkäysmäärät, virheluokat, epävarmat tulokset, uudelleenyritysten jonon ja vastausviiveen. Valvo myöhemmässä seurannassa päivitysten vastaanotto- tai hakemisvirheitä erikseen. Älä määritä numeerisia hälytysrajoja ennen kuin ymmärrät normaalin liikenteen ja palveluntarjoajan dokumentoidut käyttörajat.

Käytännöllisen tuotantotarkistuksen tulee vastata seuraaviin kysymyksiin:

  1. Onko jokaisella seurantaa odottavalla lähetyksellä rekisteröintitietue?
  2. Voidaanko jokainen hyväksytty rekisteröinti jäljittää oikeaan pakettiin?
  3. Ohjataanko hylätyt kohteet henkilölle, joka voi korjata taustalla olevat tiedot?
  4. Täsmäytetäänkö epävarmat pyynnöt sen sijaan, että ne hylättäisiin tai niitä yritettäisiin uudelleen loputtomasti?
  5. Perustuvatko asiakkaille näytettävät statukset lähetyksen tapahtumiin eivätkä rekisteröinnin hyväksymiseen?
  6. Onko tunnistetiedot ja tarpeettomat henkilötiedot jätetty pois lokeista?

Verkkokauppatoiminnoissa operatiivinen siirtymä on yhtä tärkeä kuin API-kutsu. Kehittäjien tulee vastata siirto- ja jäsentämisvirheistä; toimitus- tai täyttötiimien tulee pystyä tutkimaan virheellisiä tarroja, kuljetusliikekartoituksia ja puuttuvia lähetystietoja.

UKK

Voinko rekisteröidä seurantatunnuksen ennen ensimmäistä kuljetusliikkeen skannausta?

Rekisteröinti ja kuljetusliikkeen skannaukset ovat erillisiä tapahtumia. Palvelu voi hyväksyä tunnuksen ennen seurantatapahtumien saataville tuloa omien validointisääntöjensä mukaisesti. Älä tulkitse hyväksyntää todisteeksi siitä, että kuljetusliike on vastaanottanut paketin.

Tarvitseeko minun aina ilmoittaa kuljetusliikkeen koodi?

Se riippuu API:n dokumentoidusta tunnistuskäyttäytymisestä ja kyseisestä lähetyksestä. Jos kuljetusliike tunnetaan, eksplisiittinen ja oikein kartoitettu tunniste voi vähentää epäselvyyttä. Jos kuljetusliikettä ei tunneta, käytä dokumentoitua automaattisen tunnistuksen menetelmää sen sijaan, että keksisit kuljetusliikkeen arvon.

Miksi API palautti HTTP-onnistumisen, vaikka lähetys epäonnistui?

HTTP-pyyntö voi onnistua, vaikka sovellus hylkäisi yksittäisen kohteen. Lue ylätason sovellustulos ja lähetystason tulokset. Tämä ero on erityisen tärkeä eräpyynnöissä.

Mitä teen, kun rekisteröintipyyntö aikakatkaistaan?

Käsittele tulosta epävarmana. Palvelin on saattanut käsitellä pyynnön ennen yhteyden katkeamista. Tarkista palveluntarjoajan dokumentoitu duplikaattikäyttäytyminen ja saatavilla olevat rekisteröinti- tai seurantahakumenetelmät, ja täsmäytä tai yritä uudelleen rajatun käytännön mukaisesti.

Määrittääkö rekisteröinti automaattisesti seurantailmoitukset?

Älä oleta niin. Rekisteröinti, seurannan hakeminen ja webhook-määritykset ovat erillisiä integraatioasioita. Tarkista asiaankuuluva dokumentaatio ja testaa koko päivityspolku ennen kuin luotat siihen asiakasilmoituksissa.

Lähteet

  • 17TRACK API documentation — rekisteröinnin päätepisteiden, todennuksen, pyyntökenttien, kuljetusliikkeiden tunnisteiden, vastausskeemojen ja virheenkäsittelyn viite. Sovita toteutustiedot käyttöön ottamaasi API-versioon.
  • 17TRACK Tracking API overview — virallinen lähtöpiste seuranta-API-tuotteelle ja kehittäjien integraatioresursseille.