Kaip gauti naujausią siuntos būseną per API nelaukiant Webhook
Norėdami gauti naujausią prieinamą siuntos būseną nelaukdami webhook, siųskite autentifikuotą užklausą savo siuntų sekimo teikėjo siuntų užklausų API. Naudokite atsakymą, kad nedelsdami atnaujintumėte savo programą, o vėlesniems pakeitimams ir toliau įjunkite webhook. Svarbus skirtumas yra tas, kad užklausa paprastai gauna naujausią teikėjo išsaugotą sekimo informaciją; ji nebūtinai inicijuoja naują vežėjo patikrą.

Šis būdas naudingas, kai klientas atidaro užsakymo puslapį, pagalbos darbuotojui reikia atnaujinimo arba jūsų sistemai reikia atkurti praleistą pranešimą. Patikimas įgyvendinimas apima užklausas pagal poreikį, aiškius aktualumo indikatorius ir apsaugas nuo pasikartojančių arba ne eilės tvarka gaunamų atnaujinimų.
Nuspręskite, ką reiškia „naujausia siuntos būsena“
Prieš pasirinkdami galinį tašką, atskirkite tris operacijas, kurios gali skambėti panašiai, tačiau pateikia skirtingus rezultatus.
| Operacija | Ką ji atlieka | Ko ji nenustato |
|---|---|---|
| Perskaityti savo duomenų bazę | Grąžina sekimo informaciją, kurią jūsų programa jau turi. | Ar teikėjas gavo naujesnį atnaujinimą. |
| Pateikti užklausą sekimo API | Gauna informaciją, prieinamą per teikėjo užklausos operaciją. | Ar per šią užklausą buvo atlikta nauja vežėjo paieška. |
| Prašyti atnaujinti sekimą | Prašo atlikti kitą aukštesnio lygio patikrą, jei teikėjas siūlo tokią operaciją. | Kad vežėjas turi naują nuskaitymą arba kad atnaujinimas bus baigtas sinchroniškai. |
Naudokite užklausą, kai atsakymo reikia dabar. Atnaujinimo operaciją nagrinėkite tik tada, kai reikia, kad teikėjas bandytų atlikti kitą aukštesnio lygio patikrą. Nemanykite, kad talpyklos vengimo parametro pridėjimas, užklausos kartojimas ar HTTP talpyklos valdymo antraštės siuntimas privers vežėją pateikti naują informaciją.
Siuntos matomumas turi kelis etapus: vežėjas užregistruoja įvykį, sekimo teikėjas jį gauna, o jūsų programa jį gauna arba nuskaito. Tiesioginė API užklausa gali padėti nelaukti pranešimo pristatymo, tačiau ji negali pašalinti ankstesnių šios grandinės etapų vėlavimų.
Prieš rašydami kodą patikrinkite užklausos sutartį
Šią eigą valdo kūrėjas, integruojantis sekimo paslaugą. Pradėkite nuo dabartinės teikėjo dokumentacijos, o ne nuo galinio taško, nukopijuoto iš seno integracijos pavyzdžio. Patvirtinkite šią informaciją:
- Siuntos tapatybė: ar užklausa priima sekimo numerį, vidinį siuntos ID arba sekimo numerį kartu su vežėjo identifikatoriumi?
- Registracijos reikalavimai: ar siunta turi būti užregistruota prieš ją užklausiant?
- Autentifikavimas: kokia antraštė arba autentifikavimo priemonė reikalinga?
- Atsakymo reikšmė: ar operacija grąžina išsaugotą informaciją, inicijuoja duomenų gavimą, ar grąžina užduotį, kurią reikia patikrinti vėliau?
- Rezultato tvarkymas: ar sėkmingame HTTP atsakyme gali būti siuntos lygmens klaida arba laukiantis rezultatas?
- Naudojimo apribojimai: kokie taikomi užklausų dažnio, paketų ir konkrečios paskyros apribojimai?
- Aktualumo laukai: kurios laiko žymos nurodo vežėjo įvykius, teikėjo atnaujinimus ir atsakymo generavimą?
17TRACK integracijai svarbus produktas yra Tracking API, o ne vartotojams skirtas sekimo puslapis ar parduotuvės sekimo sąsaja. Naudokite oficialią API dokumentaciją, kad patvirtintumėte sekimo informacijos užklausos operaciją, autentifikavimą, užklausos laukus ir atsakymo struktūrą savo integracijai. Užklausas ir webhook tvarkymą laikykite atskirais programos keliais, kurie atnaujina tą patį siuntos įrašą.
Venkite į kodą įrašyti prielaidų apie atnaujinimo elgseną ar užklausų dažnumą. Ši informacija turi atitikti faktiškai naudojamą operaciją ir paslaugos sąlygas.
Sukurkite užklausą pagal poreikį per savo backend
Praktiškas sprendimas – savo programoje pateikti autentifikuotą galinį tašką. Naršyklė prašo siuntos atnaujinimo iš šio galinio taško; jūsų serveris patikrina autorizaciją, nusprendžia, ar teikėjo užklausa būtina, ir grąžina normalizuotą rezultatą.
Toliau pateiktas maršrutas yra galinio taško, kurį sukurtumėte savo programoje, pavyzdys. Tai nėra 17TRACK galinis taškas ar teikėjo užklausos specifikacija.
GET /api/orders/{order_id}/shipment-statusNaudokite užsakymo identifikatorių, kad serveryje rastumėte siuntą. Neleiskite skambinančiajam gauti kito kliento sekimo istorijos vien pakeičiant sekimo numerį užklausoje. Teikėjo API prisijungimo duomenis laikykite savo backend, o ne naršyklės JavaScript kode ar mobiliosios programos pakete.
Užklausos eiga, kurią galite įgyvendinti
- Autorizuokite prieigą. Patvirtinkite, kad klientas arba darbuotojas gali peržiūrėti užsakymą.
- Nustatykite siuntą. Nuskaitykite išsaugotą sekimo identifikatorių ir, jei taikoma, vežėjo informaciją.
- Patikrinkite vietinį aktualumą. Jei neseniai jau buvo atlikta sėkminga užklausa, pakartotinai naudokite jos rezultatą pagal savo programos aktualumo politiką.
- Kai reikia, pateikite užklausą teikėjui. Naudokite dokumentuotą operaciją ir ribotą užklausos skirtąjį laiką.
- Patvirtinkite rezultatą. Patikrinkite ir HTTP rezultatą, ir siuntos lygmens rezultatą.
- Sujunkite informaciją. Taikykite tas pačias normalizavimo ir suderinimo taisykles, kurios naudojamos webhook įvykiams.
- Grąžinkite būseną ir aktualumą. Jei įmanoma, įtraukite naujausio įvykio laiką ir paskutinės sėkmingos teikėjo patikros laiką.
Vietinio aktualumo politika yra inžinerinis sprendimas, o ne teiginys apie vežėjo atnaujinimų dažnumą. Pasirinkite ją atsižvelgdami į sąsajos reikalavimus, teikėjo apribojimus, siuntų kiekį ir stebimą užklausų naudą. Klientas, pakartotinai spaudžiantis atnaujinimo mygtuką, neturėtų sukurti neriboto aukštesnio lygio užklausų srauto.
Normalizuokite atsakymą neišgalvodami aktualumo
Jūsų programa gali grąžinti stabilų vidinį formatą, net jei teikėjų atsakymų struktūros skiriasi. Šis iliustracinis objektas yra jūsų programos sutartis, o ne tikras teikėjo naudingasis turinys:
{
"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"
}Kiekvieną laiko žymą užpildykite tik tada, kai jos reikšmė žinoma. Laikas, kai jūsų serveris gavo atsakymą, priklauso jūsų užklausos metaduomenims; jis neturi būti pateikiamas kaip laikas, kada siunta pajudėjo. Jei teikėjas nepateikia teikėjo atnaujinimo laiko žymos, palikite šį lauką tuščią arba null, o ne pakeiskite jį kita laiko žyma.
Kliento sąsajoje atskirkite pranešimus: „Naujausias vežėjo įvykis“ apibūdina siuntos veiklą, o „Sekimas patikrintas“ apibūdina jūsų programos gavimo veiklą. Šis skirtumas neleidžia nepakitusiam nuskaitymui atrodyti kaip naujai užregistruotam.
Neleiskite API užklausoms ir webhook perrašyti vienas kito
Kai abu mechanizmai aktyvūs, tas pats įvykis gali būti gautas per užklausą ir webhook. Jie taip pat gali būti baigti kita tvarka nei pradėti. Pirmiau paleista užklausa gali būti baigta po to, kai webhook jau pateikė naujesnę informaciją.
Nenaudokite logikos „laimi paskutinis atsakymas“. Neseniausiai gautas naudingasis turinys nebūtinai atspindi naujausią siuntos būseną.
- Naudokite vieną atnaujinimo konvejerį. Užklausų rezultatus ir webhook naudingąjį turinį siųskite per tas pačias tikrinimo, normalizavimo ir išsaugojimo funkcijas.
- Pašalinkite pasikartojančius įvykius. Pirmenybę teikite dokumentuotam įvykio identifikatoriui. Jei jo nėra, sukurkite kruopščiai apibrėžtą piršto atspaudą iš prieinamų laukų, pavyzdžiui, įvykio laiko, būsenos, vietos ir aprašo.
- Naudokite žinomą reikšmę turinčius eiliškumo laukus. Dokumentuota versija ar seka yra naudingesnė nei prielaida, kad gavimo laikas nurodo įvykių tvarką.
- Išsaugokite istoriją. Naujai gautas įvykis gali užpildyti istorinę spragą nepakeisdamas dabartinės siuntos suvestinės.
- Leiskite taisymus. Būsenos nėra universali tiesinė seka. Vadovaukitės dokumentuota taisymų elgsena, o ne visam laikui atmeskite kiekvieną tariamą grįžimą į ankstesnę būseną.
Kai įvykių tvarka neaiški, išsaugokite pradinį naudingąjį turinį ir jo kilmę tyrimui. Neišspręskite dviprasmybės išgalvodami įvykio laiko žymą arba manydami, kad visos vežėjo laiko žymos naudoja tą pačią laiko juostą.
Trūkstamus duomenis ir nepavykusias užklausas tvarkykite skirtingai
Tuščias rezultatas, nepakitęs rezultatas ir nepavykusi užklausa neturėtų sukurti to paties pranešimo klientui.
Užklausa pavyksta, tačiau būsena nepasikeitė
Išsaugokite esamą siuntos būseną ir atnaujinkite paskutinės sėkmingos užklausos laiką. Nekurkite naujo siuntos įvykio vien todėl, kad buvo baigta kita paieška. Jei klientui reikia daugiau informacijos, parodykite esamą įvykių istoriją ir paaiškinkite, kad naujesnis sekimo įvykis nebuvo grąžintas.
Siunta dar neturi sekimo informacijos
Patikrinkite, ar būtina registracija, ar identifikatorius ir vežėjas yra teisingi ir kaip teikėjas nurodo laukiančių duomenų gavimą. Įvykių nebuvimas savaime neįrodo, kad sekimo numeris neteisingas arba siunta prarasta. Išsaugokite teikėjo skirtumą tarp nežinomo identifikatoriaus, užregistruotos siuntos, laukiančios informacijos, ir užklausos, kurios nepavyko apdoroti.
Teikėjo užklausa baigėsi skirtuoju laiku arba nepavyko
Jei turite ankstesnę galiojančią būseną, grąžinkite ją aiškiai nurodydami, kad naujausia patikra nepavyko. Ankstesnės sėkmingos užklausos laiko žymą palikite nepakeistą. Tinklo klaida nėra pristatymo išimtis ir neturėtų pakeisti siuntos verslo būsenos.
Atitinkamoms laikinosioms klaidoms naudokite ribotą pakartojimų skaičių su didėjančia pauze ir atsitiktiniu laiko poslinkiu. Negaliojančių prisijungimo duomenų ar netinkamai suformuotų užklausų nekartokite nuolat. Jei atsakyme pateikiama Retry-After, interpretuokite ją pagal teikėjo sutartį ir HTTP semantiką. HTTP specifikacija leidžia šią reikšmę išreikšti sekundžių delsa arba HTTP data.
Gaunamos kelios tos pačios siuntos užklausos
Sujunkite lygiagrečias paieškas, kad jos galėtų bendrinti vieną aukštesnio lygio užklausą. Taikykite apribojimus paskyrai ir siuntai bei neleiskite automatiniam pakartojimui daugintis keliuose programos sluoksniuose. Jei palaikomas paketinis apdorojimas, patikrinkite kiekvienos siuntos rezultatą, o ne laikykite visą paketą sėkmingu vien todėl, kad HTTP užklausa baigta.
Naudokite apklausą kaip kontroliuojamą atsarginį būdą
Be webhook suplanuota apklausa gali palaikyti atnaujintą jūsų duomenų bazę, tačiau jai reikia aiškios veikimo politikos. Nuspręskite, kurios siuntos lieka tinkamos tikrinti, kaip klaidos veikia grafiką ir kada įprasta apklausa sustabdoma.
Daugeliui integracijų hibridinis sprendimas yra tinkama pradžia: webhook tvarko foninius pakeitimus, užklausos pagal poreikį aptarnauja interaktyvias užklausas, o suderinimo užduotys tikrina įrašus, kuriems reikia dėmesio. Tai architektūrinė rekomendacija, o ne garantija, kad ji sumažins kiekvienos paskyros išlaidas.
- Suteikite pirmenybę aktyvioms siuntoms ir įrašams, kuriuose yra neišspręstų gavimo klaidų.
- Venkite kiekvieno suplanuoto paleidimo metu užklausti visų istorinių siuntų.
- Apibrėžkite, kaip tvarkomos užbaigtos siuntos, įskaitant bet kokį jūsų verslui reikalingą taisymo laikotarpį.
- Sekite, kaip dažnai užklausos randa iš tikrųjų naują informaciją.
- Tirkite webhook pristatymo problemas, užuot slėpę jas vis dažnesne apklausa.
Stebėkite teikėjo užklausų delsą, nesėkmingas užklausas, dažnio ribojimo atsakymus ir skirtumus tarp užklaustų duomenų bei per webhook gautų įrašų. Atskirai stebėkite naujausio vežėjo įvykio amžių. Sėkmingi API atsakymai gali egzistuoti kartu su nepakitusia sekimo informacija.
Prieš išleisdami išbandykite eigą
Sėkminga užklausa yra tik pirmasis testas. Patikrinkite situacijas, kurios kitu atveju gali sukurti klaidinančius būsenos atnaujinimus:
- Webhook gaunamas, kol užklausa pagal poreikį dar vykdoma.
- Du klientai arba darbuotojų sesijos tuo pačiu metu prašo tos pačios siuntos.
- Teikėjas grąžina HTTP sėkmę, tačiau praneša apie siuntos lygmens klaidą.
- Užklausa nepavyksta po to, kai jūsų programa jau turi galiojančią sekimo informaciją.
- Įvykiui trūksta laiko juostos arba jame yra nepažįstamas būsenos kodas.
- Vežėjo taisymas pakeičia anksčiau rodytą rezultatą.
- Naudotojas bando pasiekti siuntą, priklausančią kitai paskyrai.
Jūsų išleidimo kriterijus turėtų būti toks: programa grąžina geriausiai žinomą siuntos informaciją, tiksliai paaiškina jos aktualumą ir nesugadina šios informacijos, kai užklausos nepavyksta arba gaunamos ne eilės tvarka.
DUK
Ar API užklausa priverčia vežėją nuskaityti arba atnaujinti siuntą?
Ne. Sekimo informacijos gavimas negali sukelti fizinio nuskaitymo. Ar užklausa inicijuoja aukštesnio lygio paiešką, priklauso nuo dokumentuotos operacijos. Net palaikomas atnaujinimas gali grąžinti nepakitusią informaciją, jei vežėjas neturi naujesnio įvykio.
Ar galiu naudoti API užklausas nesukonfigūravęs webhook?
Jei teikėjas palaiko reikiamą užklausų eigą, galite kurti integraciją pagal užklausas pagal poreikį arba apklausą. Pirmiausia patvirtinkite registracijos ir užklausų reikalavimus. Tuomet jūsų programa bus atsakinga už sprendimą, kada tikrinti, užklausų kiekio valdymą ir pakeitimų aptikimą.
Kaip dažnai turėčiau tikrinti siuntos būseną?
Universalaus intervalo nėra. Pasirinkite grafiką, atitinkantį teikėjo apribojimus, siuntų kiekį ir verslo naudą, kurią suteikia ankstesnis atnaujinimų radimas. Išmatuokite, kaip dažnai apklausa grąžina naujus įvykius, ir koreguokite grafiką, užuot manę, kad dažnos užklausos pateiks naujesnius vežėjo duomenis.
Kodėl API grąžina informaciją, kurią jau gavau per webhook?
Abu keliai gali atskleisti tą patį pagrindinį siuntos įrašą. Webhook pateikia pranešimą, o užklausa gauna informaciją pagal poreikį. To paties įvykio gavimas abiem būdais nebūtinai yra klaida; jūsų programa turėtų pašalinti jo dublikatą.
Ar atnaujinimo mygtukas turėtų vadintis „Atnaujinti sekimą“?
Tik jei šis pavadinimas tiksliai apibūdina operaciją. Jei mygtukas gauna išsaugotus teikėjo duomenis, aiškiau būtų „Tikrinti, ar yra atnaujinimų“. Naujausią vežėjo įvykį rodykite atskirai nuo laiko, kada jūsų programa paskutinį kartą sėkmingai atliko patikrą.
Šaltiniai
- 17TRACK Tracking API — oficiali produkto nuoroda į šiame vadove aptariamą sekimo API integraciją.
- 17TRACK API dokumentacija — teikėjui būdingų operacijų, autentifikavimo, užklausos laukų ir atsakymų tvarkymo nuoroda.
- RFC 9110, 10.2.3 skyrius: Retry-After — apibrėžia HTTP antraštės delsos sekundžių ir HTTP datos formas.


