Ako získať najnovší stav zásielky cez API bez čakania na webhook
Ak chcete získať najnovší dostupný stav zásielky bez čakania na webhook, odošlite autentifikovanú požiadavku na API vášho poskytovateľa sledovania zásielok na vyhľadanie zásielky. Pomocou odpovede okamžite aktualizujte svoju aplikáciu a potom ponechajte webhooky povolené pre následné zmeny. Dôležitý rozdiel spočíva v tom, že dotaz zvyčajne načíta najnovšie uložené informácie o sledovaní od poskytovateľa; nemusí však nevyhnutne spustiť novú kontrolu u prepravcu.

Tento prístup je užitočný, keď zákazník otvorí stránku objednávky, pracovník podpory potrebuje aktualizáciu alebo váš systém potrebuje obnoviť stav po zmeškanom upozornení. Spoľahlivá implementácia kombinuje dotazy na požiadanie, jasné indikátory aktuálnosti a ochranu pred duplicitnými alebo časovo neusporiadanými aktualizáciami.
Určte, čo znamená „najnovší stav zásielky“
Pred výberom koncového bodu rozlíšte tri operácie, ktoré môžu znieť podobne, ale poskytujú odlišné výsledky.
| Operácia | Čo robí | Čo nepotvrdzuje |
|---|---|---|
| Čítanie vlastnej databázy | Vráti informácie o sledovaní, ktoré už vaša aplikácia uchováva. | Či poskytovateľ prijal novšiu aktualizáciu. |
| Dotaz na API sledovania | Načíta informácie dostupné prostredníctvom dotazovacej operácie poskytovateľa. | Či počas tejto požiadavky prebehlo nové vyhľadanie u prepravcu. |
| Požiadavka na obnovenie sledovania | Vyžiada ďalšiu kontrolu na vyššej úrovni, ak poskytovateľ túto operáciu ponúka. | Že prepravca má nové skenovanie alebo že obnovenie prebehne synchrónne. |
Dotaz použite, keď potrebujete odpoveď teraz. Operáciu obnovenia skúmajte iba vtedy, keď potrebujete, aby sa poskytovateľ pokúsil o ďalšiu kontrolu na vyššej úrovni. Nepredpokladajte, že pridaním parametra na obídenie vyrovnávacej pamäte, opakovaním požiadavky alebo odoslaním hlavičky HTTP cache-control prinútite prepravcu poskytnúť nové informácie.
Viditeľnosť zásielky má niekoľko fáz: prepravca zaznamená udalosť, poskytovateľ sledovania ju získa a vaša aplikácia ju prijme alebo načíta. Priama požiadavka API môže obísť čakanie na doručenie upozornenia, ale nemôže odstrániť oneskorenia, ktoré vznikli skôr v tomto reťazci.
Pred písaním kódu skontrolujte zmluvu dotazu
Za tento pracovný postup zodpovedá vývojár integrujúci službu sledovania. Začnite aktuálnou dokumentáciou poskytovateľa, nie koncovým bodom skopírovaným zo starého príkladu integrácie. Overte tieto podrobnosti:
- Identita zásielky: Prijíma dotaz sledovacie číslo, interné ID zásielky alebo sledovacie číslo v kombinácii s identifikátorom prepravcu?
- Požiadavky na registráciu: Musí byť zásielka zaregistrovaná predtým, ako ju možno vyhľadať?
- Autentifikácia: Ktorá hlavička alebo mechanizmus autentifikácie sa vyžaduje?
- Význam odpovede: Vráti operácia uložené informácie, spustí získavanie údajov alebo vráti úlohu, ktorú treba skontrolovať neskôr?
- Spracovanie výsledku: Môže úspešná odpoveď HTTP obsahovať zlyhanie na úrovni zásielky alebo čakajúci výsledok?
- Obmedzenia používania: Aké limity frekvencie, dávok a obmedzenia špecifické pre účet platia?
- Polia aktuálnosti: Ktoré časové pečiatky predstavujú udalosti prepravcu, aktualizácie poskytovateľa a vytvorenie odpovede?
Pri integrácii 17TRACK je relevantným produktom Tracking API, nie spotrebiteľská stránka sledovania ani rozhranie sledovania v obchode. Pomocou oficiálnej dokumentácie API overte operáciu dotazu na informácie o sledovaní, autentifikáciu, polia požiadavky a štruktúru odpovede pre svoju integráciu. Dotazovanie a spracovanie webhookov považujte za samostatné aplikačné cesty, ktoré aktualizujú ten istý záznam zásielky.
Vyhnite sa pevnému zakódovaniu predpokladov o správaní pri obnovení alebo frekvencii dotazov. Tieto podrobnosti sa musia zhodovať s operáciou a podmienkami služby, ktorú skutočne používate.
Vytvorte vyhľadávanie na požiadanie prostredníctvom backendu
Praktickým návrhom je sprístupniť vo vlastnej aplikácii autentifikovaný koncový bod. Prehliadač si z tohto koncového bodu vyžiada aktualizáciu zásielky; váš server overí oprávnenie, rozhodne, či je dotaz poskytovateľa potrebný, a vráti normalizovaný výsledok.
Nasledujúca trasa je príkladom koncového bodu, ktorý by ste vytvorili vo svojej aplikácii. Nie je to koncový bod 17TRACK ani špecifikácia požiadavky poskytovateľa.
GET /api/orders/{order_id}/shipment-statusIdentifikátor objednávky použite na vyhľadanie zásielky na serveri. Nedovoľte volajúcemu načítať históriu sledovania iného zákazníka jednoducho nahradením sledovacieho čísla v požiadavke. Prihlasovacie údaje k API poskytovateľa uchovávajte na backende, nie v JavaScripte prehliadača ani v balíku mobilnej aplikácie.
Pracovný tok požiadavky, ktorý môžete implementovať
- Autorizujte prístup. Overte, či zákazník alebo pracovník smie zobraziť objednávku.
- Identifikujte zásielku. Načítajte uložený identifikátor sledovania a informácie o prepravcovi, ak sú relevantné.
- Skontrolujte lokálnu aktuálnosť. Ak už existuje nedávny úspešný dotaz, použite ho podľa pravidiel aktuálnosti vašej aplikácie.
- V prípade potreby sa dotážte poskytovateľa. Použite zdokumentovanú operáciu a časový limit požiadavky.
- Overte výsledok. Skontrolujte výsledok HTTP aj výsledok na úrovni zásielky.
- Zlúčte informácie. Použite rovnaké pravidlá normalizácie a zosúladenia ako pri udalostiach z webhookov.
- Vráťte stav a aktuálnosť. Ak sú k dispozícii, uveďte čas najnovšej udalosti a čas poslednej úspešnej kontroly poskytovateľa.
Pravidlá lokálnej aktuálnosti sú inžinierskym rozhodnutím, nie vyjadrením frekvencie aktualizácií prepravcu. Zvoľte ich podľa požiadaviek rozhrania, limitov poskytovateľa, objemu zásielok a pozorovanej užitočnosti dotazov. Opakované klikanie zákazníka na tlačidlo aktualizácie by nemalo vytvoriť neobmedzený prúd požiadaviek na vyššiu úroveň.
Normalizujte odpoveď bez vymýšľania aktuálnosti
Vaša aplikácia môže vrátiť stabilný interný formát aj vtedy, keď sa štruktúry odpovedí poskytovateľov líšia. Tento ilustračný objekt je zmluvou vašej vlastnej aplikácie, nie skutočným obsahom odoslaným poskytovateľom:
{
"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"
}Každú časovú pečiatku vyplňte iba vtedy, keď poznáte jej význam. Čas, keď váš server prijal odpoveď, patrí do metadát dotazu; nesmie byť prezentovaný ako čas pohybu zásielky. Ak poskytovateľ neposkytuje časovú pečiatku aktualizácie poskytovateľa, ponechajte toto pole bez hodnoty alebo null namiesto dosadenia inej časovej pečiatky.
V zákazníckom rozhraní oddeľte tieto správy: „Najnovšia udalosť prepravcu“ opisuje aktivitu zásielky, zatiaľ čo „Sledovanie skontrolované“ opisuje aktivitu načítania vašej aplikácie. Toto rozlíšenie zabraňuje tomu, aby sa nezmenené skenovanie zobrazovalo ako novo zaznamenané.
Zabráňte vzájomnému prepisovaniu dotazov API a webhookov
Keď sú aktívne oba mechanizmy, tá istá udalosť môže prísť prostredníctvom dotazu aj webhooku. Môžu sa tiež dokončiť v inom poradí, než v akom sa začali. Dotaz spustený ako prvý môže byť dokončený až po tom, čo webhook už poskytol novšie informácie.
Nepoužívajte logiku „vyhráva posledná odpoveď“. Najnovšie prijaté údaje nemusia nevyhnutne predstavovať najnovší stav zásielky.
- Zdieľajte jeden aktualizačný proces. Výsledky dotazov a údaje webhookov posielajte cez rovnaké funkcie overovania, normalizácie a ukladania.
- Odstraňujte duplicitné udalosti. Uprednostnite zdokumentovaný identifikátor udalosti. Ak neexistuje, vytvorte starostlivo definovaný odtlačok z dostupných polí, ako sú čas udalosti, stav, miesto a opis.
- Používajte polia poradia so známou sémantikou. Zdokumentovaná revízia alebo sekvencia je užitočnejšia než predpoklad, že čas prijatia predstavuje poradie udalostí.
- Zachovajte históriu. Novo prijatá udalosť môže vyplniť historickú medzeru bez zmeny aktuálneho súhrnu zásielky.
- Umožnite opravy. Stavy netvoria univerzálny lineárny rebrík. Postupujte podľa zdokumentovaného správania pri opravách namiesto trvalého odmietania každého zdanlivého spätného prechodu.
Keď je poradie udalostí neisté, uchovajte pôvodné údaje a ich pôvod na účely vyšetrovania. Neodstraňujte nejednoznačnosť vymýšľaním časovej pečiatky udalosti ani predpokladom, že všetky časové pečiatky prepravcu používajú rovnaké časové pásmo.
Chýbajúce údaje a neúspešné požiadavky spracujte odlišne
Prázdny výsledok, nezmenený výsledok a neúspešná požiadavka by nemali viesť k rovnakej správe pre zákazníka.
Dotaz je úspešný, ale stav sa nezmenil
Ponechajte existujúci stav zásielky a aktualizujte čas posledného úspešného dotazu. Nevytvárajte novú udalosť zásielky iba preto, že sa dokončilo ďalšie vyhľadávanie. Ak zákazník potrebuje viac podrobností, zobrazte existujúcu históriu udalostí a vysvetlite, že nebola vrátená žiadna novšia udalosť sledovania.
Zásielka zatiaľ nemá informácie o sledovaní
Skontrolujte, či je potrebná registrácia, či sú identifikátor a prepravca správne a ako poskytovateľ označuje čakajúce získavanie údajov. Absencia udalostí sama osebe nedokazuje, že sledovacie číslo je neplatné alebo že sa zásielka stratila. Zachovajte rozlíšenie poskytovateľa medzi neznámym identifikátorom, zaregistrovanou zásielkou čakajúcou na informácie a požiadavkou, ktorú nebolo možné spracovať.
Požiadavka poskytovateľa vyprší alebo zlyhá
Ak máte predchádzajúci platný stav, vráťte ho s jasným uvedením, že najnovšia kontrola nebola úspešná. Časovú pečiatku predchádzajúceho úspešného dotazu ponechajte nezmenenú. Chyba siete nie je výnimkou pri doručení a nemala by meniť obchodný stav zásielky.
Pri vhodných dočasných zlyhaniach používajte obmedzené opakovania s odstupom a náhodným rozptylom. Neopakujte opakovane požiadavky s neplatnými prihlasovacími údajmi alebo nesprávnym formátom. Ak odpoveď obsahuje Retry-After, interpretujte ju podľa zmluvy poskytovateľa a sémantiky HTTP. Špecifikácia HTTP povoľuje, aby bola táto hodnota vyjadrená oneskorením v sekundách alebo dátumom HTTP.
Pre tú istú zásielku príde viac požiadaviek
Spájajte súbežné vyhľadávania, aby mohli zdieľať jednu požiadavku na vyššiu úroveň. Uplatňujte limity podľa účtu a zásielky a zabráňte tomu, aby sa automatické opakovanie znásobilo v niekoľkých aplikačných vrstvách. Ak je podporované dávkové spracovanie, skontrolujte výsledok každej zásielky namiesto toho, aby ste celú dávku považovali za úspešnú len preto, že požiadavka HTTP bola dokončená.
Používajte polling ako riadenú záložnú možnosť
Bez webhookov môže plánovaný polling udržiavať databázu aktualizovanú, vyžaduje si však výslovné prevádzkové pravidlá. Určte, ktoré zásielky zostávajú oprávnené na kontrolu, ako zlyhania ovplyvňujú plán a kedy sa bežný polling zastaví.
Pre väčšinu integrácií je hybridný návrh rozumným východiskom: webhooky spracúvajú zmeny na pozadí, dotazy na požiadanie obsluhujú interaktívne požiadavky a úlohy zosúladenia kontrolujú záznamy, ktoré si vyžadujú pozornosť. Ide o architektonické odporúčanie, nie o záruku minimalizácie nákladov pre každý účet.
- Uprednostnite aktívne zásielky a záznamy s nevyriešenými chybami načítania.
- Vyhnite sa dotazovaniu každej historickej zásielky pri každom plánovanom spustení.
- Definujte spracovanie dokončených zásielok vrátane prípadného obdobia na opravy, ktoré vaša firma vyžaduje.
- Sledujte, ako často dotazy nachádzajú skutočne nové informácie.
- Skúmajte problémy s doručovaním webhookov namiesto ich maskovania čoraz častejším pollingom.
Monitorujte latenciu požiadaviek poskytovateľa, neúspešné dotazy, odpovede o prekročení limitu a rozdiely medzi údajmi získanými dotazom a záznamami naplnenými webhookmi. Samostatne monitorujte vek najnovšej udalosti prepravcu. Úspešné odpovede API môžu existovať súčasne s informáciami o sledovaní, ktoré sa nezmenili.
Pred vydaním pracovný tok otestujte
Úspešná požiadavka je iba prvou skúškou. Overte situácie, ktoré by inak mohli vytvoriť zavádzajúce aktualizácie stavu:
- Webhook príde, kým stále prebieha dotaz na požiadanie.
- Dvaja zákazníci alebo pracovníci požiadajú súčasne o tú istú zásielku.
- Poskytovateľ vráti úspech HTTP, ale nahlási chybu na úrovni zásielky.
- Požiadavka zlyhá po tom, čo vaša aplikácia už obsahuje platné informácie o sledovaní.
- Udalosti chýba časové pásmo alebo obsahuje neznámy kód stavu.
- Oprava prepravcu zmení predtým zobrazený výsledok.
- Používateľ sa pokúsi získať prístup k zásielke patriacej inému účtu.
Kritériom vydania by malo byť, že aplikácia vráti najlepšie známe informácie o zásielke, presne vysvetlí ich aktuálnosť a nepoškodí ich pri zlyhaní požiadaviek alebo pri ich doručení v nesprávnom poradí.
Často kladené otázky
Prinúti dotazovanie API prepravcu naskenovať alebo aktualizovať zásielku?
Nie. Načítanie informácií o sledovaní nemôže spôsobiť fyzické skenovanie. To, či požiadavka spustí vyhľadávanie na vyššej úrovni, závisí od zdokumentovanej operácie. Aj podporované obnovenie môže vrátiť nezmenené informácie, ak prepravca nemá novšiu udalosť.
Môžem používať dotazy API bez konfigurácie webhookov?
Ak poskytovateľ podporuje požadovaný pracovný tok dotazov, môžete vytvoriť integráciu založenú na požiadavkách na požiadanie alebo na pollingu. Najprv overte požiadavky na registráciu a dotazy. Vaša aplikácia potom bude zodpovedná za rozhodovanie, kedy kontrolovať, riadenie objemu požiadaviek a zisťovanie zmien.
Ako často mám kontrolovať stav zásielky pomocou pollingu?
Neexistuje univerzálny interval. Zvoľte plán, ktorý zodpovedá limitom poskytovateľa, objemu vašich zásielok a obchodnej hodnote skoršieho nájdenia aktualizácií. Zmerajte, ako často polling vracia nové udalosti, a potom ho upravte namiesto predpokladu, že časté požiadavky prinášajú aktuálnejšie údaje prepravcu.
Prečo API vracia informácie, ktoré som už dostal prostredníctvom webhooku?
Obe cesty môžu sprístupňovať ten istý základný záznam zásielky. Webhook doručuje upozornenie, zatiaľ čo dotaz načítava informácie na požiadanie. Prijatie tej istej udalosti oboma cestami nemusí byť chybou; vaša aplikácia by ju mala deduplikovať.
Malo by tlačidlo aktualizácie obsahovať text „Obnoviť sledovanie“?
Iba vtedy, ak tento text presne opisuje operáciu. Ak tlačidlo načítava uložené údaje poskytovateľa, jasnejšie je „Skontrolovať aktualizácie“. Najnovšiu udalosť prepravcu zobrazujte oddelene od času, keď vaša aplikácia naposledy úspešne dokončila kontrolu.
Zdroje
- 17TRACK Tracking API — oficiálna referencia produktu pre integráciu API sledovania, o ktorej sa hovorí v tejto príručke.
- Dokumentácia API 17TRACK — referencia pre operácie špecifické pre poskytovateľa, autentifikáciu, polia požiadaviek a spracovanie odpovedí.
- RFC 9110, časť 10.2.3: Retry-After — definuje formy oneskorenia v sekundách a dátumu HTTP pre hlavičku.


