Kuinka saat lähetyksen viimeisimmän tilan API:n kautta odottamatta webhookia
Saadaksesi uusimman saatavilla olevan lähetyksen tilan ilman webhookia, lähetä todennettu pyyntö seurantapalveluntarjoajasi lähetyskysely-APIin. Käytä vastausta sovelluksesi päivittämiseen välittömästi ja pidä webhookit käytössä myöhempiä muutoksia varten. Tärkeä ero on, että kysely yleensä hakee palveluntarjoajan viimeisimmät tallennetut seurantatiedot; se ei välttämättä käynnistä uutta kuljetusyhtiön tarkistusta.

Tämä lähestymistapa on hyödyllinen, kun asiakas avaa tilaussivun, tukihenkilö tarvitsee päivityksen tai järjestelmäsi on palautettava puuttuneen ilmoituksen jälkeen. Luotettava toteutus yhdistää tarvittaessa tehtävät kyselyt, selkeät tuoreusosoittimet sekä suojaukset päällekkäisiä tai väärässä järjestyksessä saapuvia päivityksiä vastaan.
Päätä, mitä ”uusin lähetyksen tila” tarkoittaa
Ennen päätepisteen valitsemista erota toisistaan kolme toimintoa, jotka voivat kuulostaa samanlaisilta mutta tuottavat erilaisia tuloksia.
| Toiminto | Mitä se tekee | Mitä se ei vahvista |
|---|---|---|
| Oman tietokannan lukeminen | Palauttaa seurantatiedot, jotka sovelluksesi jo sisältää. | Onko palveluntarjoaja vastaanottanut uudemman päivityksen. |
| Seuranta-API:n kysely | Hakee palveluntarjoajan kyselytoiminnon kautta saatavilla olevat tiedot. | Tapahtuiko pyynnön aikana uusi kuljetusyhtiön tarkistus. |
| Seurannan päivityksen pyytäminen | Pyytää uutta ylemmän tason tarkistusta, jos palveluntarjoaja tarjoaa kyseisen toiminnon. | Onko kuljetusyhtiöllä uusi skannaus tai valmistuuko päivitys synkronisesti. |
Käytä kyselyä, kun tarvitset vastauksen nyt. Tutki päivitystoimintoa vain, kun haluat palveluntarjoajan yrittävän uutta ylemmän tason tarkistusta. Älä oleta, että välimuistin ohituksen parametrin lisääminen, pyynnön toistaminen tai HTTP-välimuistin hallintaotsakkeen lähettäminen pakottaa kuljetusyhtiön toimittamaan uusia tietoja.
Lähetyksen näkyvyydessä on useita vaiheita: kuljetusyhtiö tallentaa tapahtuman, seurantapalveluntarjoaja vastaanottaa sen ja sovelluksesi vastaanottaa tai hakee sen. Suora API-pyyntö voi ohittaa ilmoituksen toimituksen odottamisen, mutta se ei voi poistaa ketjun aiempia viiveitä.
Tarkista kyselysopimus ennen koodin kirjoittamista
Seurantapalvelun integroiva kehittäjä vastaa tästä työnkulusta. Aloita palveluntarjoajan ajantasaisesta dokumentaatiosta, älä vanhasta integraatioesimerkistä kopioidusta päätepisteestä. Vahvista seuraavat tiedot:
- Lähetyksen tunniste: Hyväksyykö kysely seurantanumeron, sisäisen lähetys-ID:n vai seurantanumeron yhdistettynä kuljetusyhtiön tunnisteeseen?
- Rekisteröintivaatimukset: Onko lähetys rekisteröitävä ennen kuin siitä voidaan tehdä kysely?
- Todennus: Mitä otsaketta tai todennusmenetelmää vaaditaan?
- Vastauksen merkitys: Palauttaako toiminto tallennettuja tietoja, käynnistääkö se tietojen keruun vai palauttaako se myöhemmin tarkistettavan työn?
- Tulosten käsittely: Voiko onnistunut HTTP-vastaus sisältää lähetyskohtaisen virheen tai odottavan tuloksen?
- Käytön rajoitukset: Mitä nopeusrajoituksia, erärajoituksia ja tiliin liittyviä rajoituksia sovelletaan?
- Tuoreuskentät: Mitkä aikaleimat edustavat kuljetusyhtiön tapahtumia, palveluntarjoajan päivityksiä ja vastauksen luontia?
17TRACK-integraatiossa olennainen tuote on Tracking API, ei kuluttajille tarkoitettu seurantásivu tai verkkokaupan seurantaliittymä. Vahvista integraatiosi seurantatietojen kyselytoiminto, todennus, pyyntökentät ja vastausrakenne käyttämällä virallista API-dokumentaatiota. Käsittele kyselyt ja webhookit erillisinä sovelluspolkuina, jotka päivittävät samaa lähetysrekisteriä.
Vältä päivitystoimintaa tai kyselytiheyttä koskevien oletusten kovakoodaamista. Näiden tietojen on vastattava käyttämääsi toimintoa ja palveluehtoja.
Rakenna tarvittaessa tehtävä haku taustajärjestelmäsi kautta
Käytännöllinen rakenne on tarjota omassa sovelluksessasi todennettu päätepiste. Selain pyytää lähetyspäivityksen kyseiseltä päätepisteeltä; palvelimesi tarkistaa valtuutuksen, päättää, tarvitaanko palveluntarjoajan kyselyä, ja palauttaa normalisoidun tuloksen.
Seuraava reitti on esimerkki sovelluksessasi luotavasta päätepisteestä. Se ei ole 17TRACK-päätepiste eikä palveluntarjoajan pyyntömääritys.
GET /api/orders/{order_id}/shipment-statusKäytä tilauksen tunnistetta lähetyksen etsimiseen palvelimella. Älä anna kutsujan hakea toisen asiakkaan seurantahistoriaa vain vaihtamalla seurantanumeroa pyynnössä. Säilytä palveluntarjoajan API-tunnistetiedot taustajärjestelmässäsi, ei selaimen JavaScriptissä tai mobiilisovelluksen paketissa.
Toteutettava pyyntövirta
- Valtuuta käyttö. Vahvista, että asiakas tai työntekijä saa tarkastella tilausta.
- Selvitä lähetys. Lue tallennettu seurannan tunniste ja tarvittaessa kuljetusyhtiön tiedot.
- Tarkista paikallinen tuoreus. Jos viimeaikainen onnistunut kysely on jo olemassa, käytä sitä uudelleen sovelluksesi tuoreuskäytännön mukaisesti.
- Kysy palveluntarjoajalta tarvittaessa. Käytä dokumentoitua toimintoa ja rajattua pyynnön aikakatkaisua.
- Vahvista tulos. Tarkista sekä HTTP-tulos että lähetyskohtainen tulos.
- Yhdistä tiedot. Käytä samoja normalisointi- ja täsmäytyssääntöjä kuin webhook-tapahtumissa.
- Palauta tila ja tuoreus. Sisällytä viimeisimmän tapahtuman aika ja viimeisimmän onnistuneen palveluntarjoajan tarkistuksen aika, kun ne ovat saatavilla.
Paikallinen tuoreuskäytäntö on tekninen päätös, ei lausunto kuljetusyhtiön päivitystiheydestä. Valitse se käyttöliittymävaatimusten, palveluntarjoajan rajoitusten, lähetysmäärän ja havaittavan kyselyhyödyn perusteella. Päivityspainiketta toistuvasti napsauttavan asiakkaan ei pitäisi luoda rajoittamatonta ylemmän tason pyyntövirtaa.
Normalisoi vastaus keksimättä tuoreutta
Sovelluksesi voi palauttaa vakaan sisäisen muodon, vaikka palveluntarjoajien vastausrakenteet eroaisivat toisistaan. Tämä havainnollistava objekti on oman sovelluksesi sopimus, ei todellinen palveluntarjoajan hyötykuorma:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}Täytä kukin aikaleima vain, kun sen merkitys tunnetaan. Aika, jolloin palvelimesi vastaanotti vastauksen, kuuluu kyselymetatietoihin; sitä ei saa esittää paketin liikkumisajankohtana. Jos palveluntarjoaja ei toimita palveluntarjoajan päivityksen aikaleimaa, jätä kenttä puuttuvaksi tai null-arvoiseksi sen sijaan, että korvaisit sen toisella aikaleimalla.
Asiakasliittymässä erota viestit toisistaan: ”Viimeisin kuljetusyhtiön tapahtuma” kuvaa lähetyksen toimintaa, kun taas ”Seuranta tarkistettu” kuvaa sovelluksesi hakutoimintaa. Tämä ero estää muuttumattoman skannauksen näyttämisen uutena tapahtumana.
Estä API-kyselyitä ja webhookeja korvaamasta toisiaan
Kun molemmat mekanismit ovat aktiivisia, sama tapahtuma voi saapua kyselyn ja webhookin kautta. Ne voivat myös valmistua eri järjestyksessä kuin ne käynnistettiin. Ensin käynnistetty kysely voi valmistua sen jälkeen, kun webhook on jo toimittanut uudempia tietoja.
Älä käytä viimeisin vastaus voittaa -logiikkaa. Viimeksi vastaanotettu hyötykuorma ei välttämättä edusta viimeisintä lähetyksen tilaa.
- Käytä yhtä päivitysputkea. Ohjaa kyselytulokset ja webhook-hyötykuormat samojen tarkistus-, normalisointi- ja tallennustoimintojen läpi.
- Poista tapahtumien kaksoiskappaleet. Suosi dokumentoitua tapahtumatunnistetta. Jos sitä ei ole, muodosta huolellisesti määritelty sormenjälki käytettävissä olevista kentistä, kuten tapahtuma-ajasta, tilasta, sijainnista ja kuvauksesta.
- Käytä merkitykseltään tunnettuja järjestyskenttiä. Dokumentoitu revisio tai järjestysnumero on hyödyllisempi kuin oletus, että saapumisaika edustaa tapahtumajärjestystä.
- Säilytä historia. Äskettäin vastaanotettu tapahtuma voi täyttää historiallisen aukon muuttamatta nykyistä lähetysyhteenvetoa.
- Salli korjaukset. Tilat eivät muodosta yleispätevää lineaarista asteikkoa. Noudata dokumentoitua korjauskäyttäytymistä sen sijaan, että hylkäisit pysyvästi kaikki näennäiset taaksepäin siirtymät.
Kun tapahtumajärjestys on epävarma, säilytä alkuperäinen hyötykuorma ja sen alkuperätiedot tutkimista varten. Älä ratkaise epäselvyyttä keksimällä tapahtuman aikaleimaa tai olettamalla, että kaikki kuljetusyhtiöiden aikaleimat käyttävät samaa aikavyöhykettä.
Käsittele puuttuvat tiedot ja epäonnistuneet pyynnöt eri tavoin
Tyhjän tuloksen, muuttumattoman tuloksen ja epäonnistuneen pyynnön ei pitäisi tuottaa samaa asiakasviestiä.
Kysely onnistuu, mutta tila ei ole muuttunut
Säilytä nykyinen lähetyksen tila ja päivitä viimeisimmän onnistuneen kyselyn aika. Älä luo uutta lähetyksen tapahtumaa vain siksi, että toinen haku valmistui. Jos asiakas tarvitsee lisätietoja, näytä nykyinen tapahtumahistoria ja kerro, ettei uudempaa seurantatapahtumaa palautettu.
Lähetyksellä ei ole vielä seurantatietoja
Tarkista, vaaditaanko rekisteröintiä, ovatko tunniste ja kuljetusyhtiö oikein ja miten palveluntarjoaja esittää odottavan tiedonkeruun. Tapahtumien puuttuminen ei yksinään todista, että seurantanumero on virheellinen tai paketti kadonnut. Säilytä palveluntarjoajan ero tuntemattoman tunnisteen, tietoja odottavan rekisteröidyn lähetyksen ja käsittelemättä jääneen pyynnön välillä.
Palveluntarjoajan pyyntö aikakatkaistaan tai epäonnistuu
Jos sinulla on aiempi kelvollinen tila, palauta se ja ilmoita selkeästi, ettei viimeisin tarkistus onnistunut. Säilytä aiemman onnistuneen kyselyn aikaleima muuttumattomana. Verkkovirhe ei ole toimituspoikkeama, eikä sen pitäisi muuttaa paketin liiketoiminnallista tilaa.
Käytä soveltuvissa tilapäisissä virheissä rajattuja uudelleenyrityksiä, viivettä ja satunnaisvaihtelua. Älä yritä toistuvasti uudelleen virheellisiä tunnistetietoja tai virheellisesti muodostettuja pyyntöjä. Kun vastaus sisältää Retry-After-kentän, tulkitse se palveluntarjoajan sopimuksen ja HTTP-semantiikan mukaisesti. HTTP-määritys sallii arvon esittämisen sekunteina ilmoitettuna viiveenä tai HTTP-päivämääränä.
Samasta lähetyksestä saapuu useita pyyntöjä
Yhdistä samanaikaiset haut, jotta ne voivat jakaa yhden ylemmän tason pyynnön. Aseta rajoitukset tilin ja lähetyksen mukaan ja estä automaattisen uudelleenyrityksen monistuminen useissa sovelluskerroksissa. Kun eräkäsittelyä tuetaan, tarkista jokaisen lähetyksen tulos sen sijaan, että käsittelisit koko erää onnistuneena vain siksi, että HTTP-pyyntö valmistui.
Käytä kyselyä hallittuna vararatkaisuna
Ilman webhookeja ajastettu kysely voi pitää tietokannan ajan tasalla, mutta se edellyttää selkeää toimintakäytäntöä. Päätä, mitkä lähetykset pysyvät kelvollisina, miten virheet vaikuttavat aikatauluun ja milloin säännöllinen kysely lopetetaan.
Useimmissa integraatioissa hybridimalli on järkevä lähtökohta: webhookit käsittelevät taustalla tapahtuvat muutokset, tarvittaessa tehtävät kyselyt palvelevat vuorovaikutteisia pyyntöjä ja täsmäytystyöt tarkistavat huomiota tarvitsevat tietueet. Tämä on arkkitehtuurisuositus, ei tae siitä, että kustannukset minimoituvat jokaisella tilillä.
- Aseta etusijalle aktiiviset lähetykset ja tietueet, joissa on ratkaisemattomia hakuvireitä.
- Vältä jokaisen historiallisen lähetyksen kyselyä jokaisella ajastetulla suorituskerralla.
- Määritä, miten valmiit lähetykset käsitellään, mukaan lukien liiketoimintasi tarvitsema korjausikkuna.
- Seuraa, kuinka usein kyselyt löytävät aidosti uutta tietoa.
- Tutki webhookien toimitusongelmat sen sijaan, että peittäisit ne yhä tiheämmällä kyselyllä.
Seuraa palveluntarjoajan pyyntöjen viivettä, epäonnistuneita kyselyitä, nopeusrajoitusvastauksia sekä kyselytietojen ja webhookien kautta syötettyjen tietueiden eroja. Seuraa erikseen viimeisimmän kuljetusyhtiön tapahtuman ikää. Onnistuneet API-vastaukset voivat esiintyä yhdessä muuttumattomien seurantatietojen kanssa.
Testaa työnkulku ennen julkaisua
Onnistunut pyyntö on vasta ensimmäinen testi. Varmista tilanteet, jotka voivat muuten aiheuttaa harhaanjohtavia tilapäivityksiä:
- Webhook saapuu, kun tarvittaessa tehtävä kysely on vielä käynnissä.
- Kaksi asiakasta tai työntekijän istuntoa pyytää samaa lähetystä samanaikaisesti.
- Palveluntarjoaja palauttaa HTTP-onnistumisen mutta ilmoittaa lähetyskohtaisesta virheestä.
- Pyyntö epäonnistuu, vaikka sovelluksellasi on jo kelvolliset seurantatiedot.
- Tapahtumasta puuttuu aikavyöhyke tai se sisältää tuntemattoman tilakoodin.
- Kuljetusyhtiön korjaus muuttaa aiemmin näytettyä tulosta.
- Käyttäjä yrittää käyttää toiselle tilille kuuluvaa lähetystä.
Julkaisukriteerin tulisi olla, että sovellus palauttaa parhaat tunnetut lähetyksen tiedot, selittää niiden tuoreuden oikein eikä turmele tietoja, kun pyynnöt epäonnistuvat tai saapuvat väärässä järjestyksessä.
UKK
Pakottaako API:n kysely kuljetusyhtiön skannaamaan tai päivittämään paketin?
Ei. Seurantatietojen hakeminen ei voi aiheuttaa fyysistä skannausta. Se, käynnistääkö pyyntö ylemmän tason haun, riippuu dokumentoidusta toiminnosta. Jopa tuettu päivitys voi palauttaa muuttumattomat tiedot, jos kuljetusyhtiöllä ei ole uudempaa tapahtumaa.
Voinko käyttää API-kyselyitä ilman webhookien määrittämistä?
Jos palveluntarjoaja tukee vaadittua kyselytyönkulkua, voit rakentaa integraation tarvittaessa tehtävien pyyntöjen tai kyselyn ympärille. Vahvista ensin rekisteröinti- ja kyselyvaatimukset. Sovelluksesi vastuulle jää tällöin päättää, milloin tarkistetaan, hallita pyyntömäärää ja havaita muutokset.
Kuinka usein lähetyksen tila pitäisi kysellä?
Yleispätevää aikaväliä ei ole. Valitse aikataulu palveluntarjoajan rajoitusten, lähetysmääräsi ja päivitysten aikaisemman löytämisen liiketoiminta-arvon mukaan. Mittaa, kuinka usein kysely palauttaa uusia tapahtumia, ja säädä sen perusteella sen sijaan, että olettaisit tiheiden pyyntöjen tuottavan tuoreempia kuljetusyhtiön tietoja.
Miksi API palauttaa tietoja, jotka sain jo webhookin kautta?
Molemmat polut voivat tuoda esiin saman taustalla olevan lähetysrekisterin. Webhook toimittaa ilmoituksen, kun taas kysely hakee tietoja pyynnöstä. Saman tapahtuman vastaanottaminen molempia reittejä pitkin ei välttämättä ole virhe; sovelluksesi pitäisi poistaa sen kaksoiskappale.
Pitäisikö päivityspainikkeen tekstin olla ”Päivitä seuranta”?
Vain jos teksti kuvaa toimintoa täsmällisesti. Jos painike hakee palveluntarjoajan tallentamia tietoja, ”Tarkista päivitykset” on selkeämpi. Näytä viimeisin kuljetusyhtiön tapahtuma erillään ajasta, jolloin sovelluksesi suoritti viimeksi onnistuneen tarkistuksen.
Lähteet
- 17TRACK Tracking API — tässä oppaassa käsitellyn seuranta-API-integraation virallinen tuoteviite.
- 17TRACK API documentation — viite palveluntarjoajakohtaisiin toimintoihin, todennukseen, pyyntökenttiin ja vastausten käsittelyyn.
- RFC 9110, Section 10.2.3: Retry-After — määrittelee HTTP-otsakkeen delay-seconds- ja HTTP-date-muodot.


