Ako používať rozhrania API na sledovanie zásielok na odosielanie proaktívnych upozornení o doručení
Ak chcete pomocou API na sledovanie zásielok odosielať proaktívne upozornenia na doručenie, prepojte každý balík s jeho objednávkou, prijímajte aktualizácie sledovania, prekladajte ich na udalosti relevantné pre zákazníka a spúšťajte správy prostredníctvom svojej e-mailovej, SMS alebo aplikačnej notifikačnej služby. Medzi prichádzajúce údaje o sledovaní a odchádzajúce správy vložte trvalý front a kontroly duplicít, aby opakované alebo oneskorené aktualizácie nevytvárali mätúce upozornenia.
Táto príručka je určená vývojárom a tímom prevádzky elektronického obchodu, ktorí vytvárajú takýto pracovný postup. Cieľom nie je preposielať každý sken dopravcu. Ide o to informovať zákazníkov, keď sa zmysluplne niečo zmení, čo táto zmena znamená a či musia podniknúť nejaký krok.
Navrhnite pracovný postup upozornení ešte pred pripojením API
API na sledovanie zásielok poskytuje informácie o sledovaní; vaša aplikácia rozhoduje o tom, ako ich použije. Viditeľnosť zásielky a komunikáciu so zákazníkom považujte za samostatné zodpovednosti, aj keď vaša vybraná služba ponúka oboje.
Praktická architektúra má šesť fáz:
- Priradenie objednávky: v prípade potreby pripojte číslo zásielky a identifikátor dopravcu k internému záznamu zásielky.
- Registrácia sledovania: odošlite alebo zaregistrujte zásielku podľa požiadaviek poskytovateľa na integráciu.
- Prijímanie aktualizácií: prijímajte spätné volania webhookov, získavajte aktualizácie prostredníctvom požiadaviek API alebo kombinujte oba prístupy.
- Spracovanie udalostí: overujte, normalizujte, odstraňujte duplicity a vyhodnocujte prichádzajúce udalosti.
- Rozhodnutie o upozornení: vyberte, či upozorniť, koho kontaktovať a ktorý kanál a šablónu použiť.
- Doručenie správy: odošlite upozornenie a zaznamenajte odpoveď služby na odosielanie správ.
Kontaktné údaje zákazníkov uchovávajte vo vlastnom systéme objednávok alebo správ, pokiaľ ich zdieľanie integrácia skutočne nevyžaduje. Služba sledovania zvyčajne nepotrebuje e-mailovú adresu zákazníka len preto, aby vaša aplikácia mohla priradiť udalosť sledovania k objednávke.
1. Potvrďte integračnú zmluvu
Pred vytvorením prijímača si v dokumentácii poskytovateľa overte autentifikáciu, registráciu zásielky, identifikáciu dopravcu, podporované metódy aktualizácie, formáty odpovedí, limity požiadaviek a spracovanie chýb. Pri integráciách webhookov si tiež overte, ako sa autentifikujú spätné volania, ktorá odpoveď potvrdzuje prijatie a ako sa spracúvajú neúspešné doručenia.
Pri implementácii 17TRACK začnite na stránke 17TRACK Tracking API a v jeho oficiálnej dokumentácii API. Pri integrácii používajte zdokumentovanú zmluvu a nepovažujte ilustračné názvy polí v tejto príručke za polia požiadaviek alebo odpovedí 17TRACK. Pred implementáciou potvrďte nastavenie spätných volaní, bezpečnostné požiadavky a limity špecifické pre účet.
Metódu aktualizácie vyberte podľa integračnej zmluvy:
- Webhooky: používajte spätné volania, ak sú podporované a vhodné pre vašu infraštruktúru. Umožňujú aplikácii spracovať aktualizácie v okamihu, keď ich poskytovateľ odošle, bez opakovaného vyžadovania rovnakej zásielky.
- Polling: získavajte informácie o sledovaní podľa harmonogramu, keď spätné volania nie sú dostupné alebo vhodné. Harmonogram udržiavajte v rámci zdokumentovaných limitov požiadaviek.
- Kombinovaný prístup: používajte spätné volania na bežné spracovanie a selektívne získavanie údajov cez API na zosúladenie zásielok, ktorých aktualizácie sa javia ako zastarané, ak poskytovateľ tento pracovný postup podporuje.
Neinzerujte zákazníkom okamžité upozornenia len preto, že používate webhooky. Vaša aplikácia nemôže oznámiť udalosť dopravcu skôr, než ju sprístupnia nadradené údaje o sledovaní.
2. Vytvorte záznam zásielky, ktorý zvládne skutočné objednávky
Ako hlavný odkaz používajte interné ID zásielky, nie iba číslo zásielky. Objednávka môže obsahovať viac balíkov a nemožno predpokladať, že čísla zásielok budú navždy globálne jedinečné.
Užitočný interný záznam obsahuje:
- Interné ID objednávky a ID zásielky.
- Číslo zásielky a identifikátor dopravcu, ak sú známe.
- Referenciu zásielky poskytovateľa, ak bola poskytnutá.
- Aktuálny normalizovaný stav a poslednú významnú udalosť.
- Čas udalosti u dopravcu vrátane časového pásma alebo posunu, ak je dostupný.
- Čas, keď váš systém prijal aktualizáciu.
- Odkaz na komunikačné preferencie zákazníka.
- Históriu upozornení a prípadný aktívny pracovný postup pre výnimky.
Čas udalosti ukladajte oddelene od času prijatia. Sken, ktorý sa uskutočnil skôr, môže doraziť po novšom skene. Ak aplikácia triedi iba podľa poradia príchodu, môže omylom zmeniť doručenú zásielku späť na zásielku v preprave.
Pri rozdelených objednávkach pripájajte upozornenia k dotknutému balíku. Veta „Jeden balík z vašej objednávky bol doručený“ je presnejšia než „Vaša objednávka bola doručená“, ak sa ďalší balík stále prepravuje.
3. Mapujte udalosti sledovania na rozhodnutia zákazníka
Popisy dopravcu sú prevádzkové údaje, nie hotové správy pre zákazníkov. Vytvorte normalizačnú vrstvu, ktorá zachová pôvodnú udalosť a zároveň jej priradí internú kategóriu, ktorej rozumejú pravidlá upozornení.
Nasledujúce kategórie sú navrhované koncepty aplikácie, nie univerzálny slovník stavov API:
| Interná kategória | Rozhodnutie o upozornení | Hranica komunikácie |
|---|---|---|
| Informácie o zásielke prijaté | Aktualizáciu o príprave odošlite iba vtedy, ak je užitočná. | Samotné vytvorenie štítku neznamená, že dopravca zásielku fyzicky prevzal. |
| V preprave | Zvážte upozornenie pri prvom významnom pohybe. | Bežné skeny v prevádzke potlačte, pokiaľ nemenia ďalší krok zákazníka. |
| Na doručenie | Upozornite, keď podporovaná udalosť signalizuje tento stav. | Stav neprezentujte ako garantovaný čas doručenia. |
| Pokus o doručenie alebo potrebné vyzdvihnutie | Odošlite upozornenie s konkrétnym krokom. | Lehoty alebo pokyny na vyzdvihnutie uvádzajte iba vtedy, keď sú overené. |
| Výnimka pri doručení | Posúďte príčinu a to, či musí zákazník konať. | Každú výnimku neoznačujte ako stratený balík. |
| Doručené | Odošlite potvrdenie na úrovni balíka. | Nevymýšľajte príjemcu, miesto doručenia ani dôkaz o doručení. |
Zachovajte neistotu. Nerozpoznaná udalosť by mala prejsť kontrolou alebo záložným postupom namiesto núteného zaradenia do najbližšej známej kategórie. Pôvodný popis ponechajte dostupný pracovníkom podpory na riešenie problémov.
4. Prijímajte aktualizácie bez straty alebo duplikovania práce
Váš koncový bod webhooku by mal overiť požiadavku, trvalo uložiť prijatú aktualizáciu a vrátiť potvrdenie požadované poskytovateľom. Generovanie správ vykonávajte asynchrónne namiesto čakania na e-mailovú alebo SMS službu počas požiadavky na spätné volanie.
Implementujte zdokumentovanú metódu overovania spätných volaní poskytovateľa. Nevymýšľajte hlavičku podpisu ani nepredpokladajte, že každý poskytovateľ používa rovnakú schému autentifikácie. Vynucujte tiež HTTPS, limity veľkosti požiadaviek, overovanie dát a primerané riadenie prístupu.
prijmi spätné volanie
over požiadavku pomocou zdokumentovaného mechanizmu poskytovateľa
over dátový obsah
atómovo ulož prijatý obsah a vlož spracovanie do frontu
vráť zdokumentované potvrdenie
spracuj aktualizáciu z frontu
nájdi internú zásielku
normalizuj relevantné udalosti
ignoruj už spracované udalosti
vyhodnoť chronológiu a prechod stavu
vytvor úlohu upozornenia, ak to pravidlá povoľujú
spoločne potvrď stav a úlohu
odošli úlohu upozornenia
skontroluj preferencie príjemcu a pravidlá potlačenia
odošli správu službe na odosielanie správ
zaznamenaj výsledok a opakuj iba vtedy, keď je to vhodné
Atómové kroky sú dôležité. Ak aplikácia uloží zmenu stavu, ale pred vytvorením úlohy upozornenia havaruje, zákazník nemusí upozornenie nikdy dostať. Jednou z možností návrhu je transakčný outbox: uložte zmenu stavu a čakajúcu úlohu v rámci rovnakej databázovej transakcie a potom nechajte pracovníka úlohu odoslať.
Neznáme referencie zásielok riešte explicitne. Umiestnite ich do karantény na preskúmanie alebo zosúladenie namiesto hádania, ktorý zákazník má dostať upozornenie.
5. Pridajte ochranu proti duplicite a chronologické kontroly
Navrhnite prijímač tak, aby zvládal opakované spätné volania a opakovanie úloh pracovníkom. Ak je zdokumentovaný stabilný identifikátor udalosti poskytovateľa, uprednostnite ho. Inak vytvorte deterministický odtlačok udalosti z vhodných polí, napríklad z interného ID zásielky, kódu udalosti, času udalosti a miesta. Pred spoliehaním sa naň otestujte odtlačok na skutočných dátových obsahoch.
Odstraňovanie duplicít udalostí a potlačenie upozornení riešia odlišné problémy. Odstraňovanie duplicít zabraňuje dvojitému spracovaniu rovnakej udalosti. Potlačenie zabraňuje tomu, aby niekoľko odlišných skenov vytvorilo v podstate rovnakú správu pre zákazníka.
Definujte identitu upozornenia okolo obchodnej udalosti. Potvrdenie doručenia môže používať ID zásielky a míľnik doručenia. Pokus o doručenie môže potrebovať identitu špecifickú pre daný pokus, pretože neskorší pokus môže byť skutočne novou udalosťou.
Pri aktualizáciách mimo poradia porovnávajte časové pečiatky udalostí a vyhodnocujte povolené prechody stavov. Nepredpokladajte, že spätné volanie obsahuje iba nový sken; skontrolujte, či jeho zdokumentovaná štruktúra predstavuje jednotlivú udalosť, snímku alebo históriu. Protichodné aktualizácie smerujte na zosúladenie namiesto tichého zahodenia všetkých opráv.
6. Píšte správy, ktoré vysvetľujú, čo bude nasledovať
Každé upozornenie by malo uvádzať príslušný balík, potvrdenú zmenu a ďalší krok zákazníka. Zahrňte bezpečný odkaz na sledovanie a rozpoznateľnú referenciu objednávky. V SMS správach a náhľadoch na uzamknutej obrazovke nezverejňujte celé adresy ani nepotrebné osobné údaje.
Napríklad:
- Na doručenie: „Váš balík k objednávke {order_reference} je na doručenie. Jeho priebeh sledujte tu: {tracking_link}.“
- Pokus o doručenie: „Dopravca nahlásil pokus o doručenie vášho balíka. Dostupné ďalšie kroky nájdete na stránke sledovania: {tracking_link}.“
- Doručené: „Dopravca označil váš balík k objednávke {order_reference} ako doručený. Zobraziť dostupné podrobnosti o doručení: {tracking_link}.“
Zástupné symboly vykresľujte iba z overených údajov. Ak je k dispozícii odhad doručenia a je vhodný na zobrazenie, označte ho ako odhad. Ak chýba, vynechajte ho namiesto vymýšľania dátumu.
Pri výnimkách rozlišujte problém so zásielkou od úlohy zákazníka. Prerušenie môže vyžadovať iba vysvetlenie; overený problém s adresou môže vyžadovať zásah. Zákazníkov neposielajte na stránku platieb alebo nahrávania dokumentov iba na základe nedôveryhodného voľného textu zo sledovania.
Kanály vyberajte podľa preferencií zákazníka, povolení kanála, naliehavosti a príslušných pravidiel. Preskúmajte požiadavky na súhlas, odhlásenie a tiché hodiny pre jurisdikcie a kanály správ, ktoré používate. Upozornenia o doručení držte oddelene od propagačných kampaní a nepredpokladajte, že rovnaké povolenia pokrývajú oboje.
7. Definujte, čo sa stane, keď sledovanie utíchne
Proaktívna komunikácia by mala pokrývať chýbajúci priebeh aj nové udalosti, samotné ticho však nedokazuje, že zásielka mešká alebo sa stratila.
Vytvorte pravidlo zastaraného sledovania s použitím úrovne služby, trasy, poslednej významnej udalosti a prípadného podporovaného odhadu doručenia. Prahy nastavte podľa prevádzkových údajov a procesu podpory, nie použitím jednej univerzálnej čakacej lehoty pre každú zásielku.
Keď sa pravidlo spustí, skontrolujte vynechané spracovanie, podľa možností zosúlaďte údaje so zdrojom sledovania a rozhodnite, či vytvoriť internú úlohu podpory. Ak zákazníka upozorníte, použite formuláciu zodpovedajúcu tomu, čo viete: „Neprijali sme novú aktualizáciu sledovania“ sa líši od „Váš balík sa stratil.“
Nevyriešeným výnimkám priraďte zodpovednú osobu. Systém upozornení, ktorý opakovane oznamuje problém bez vytvorenia cesty k jeho vyriešeniu, môže zvyšovať frustráciu zákazníkov.
8. Pred povolením automatického odosielania otestujte celú cestu
Najprv spustite pracovný postup v režime shadow: prijímajte skutočné alebo schválené testovacie udalosti, vytvárajte navrhované upozornenia a kontrolujte výsledky bez kontaktovania zákazníkov.
- Zopakujte identické spätné volanie a potvrďte, že nevytvorí ďalšiu správu.
- Po udalosti doručenia spracujte staršiu udalosť prepravy a skontrolujte výsledný stav.
- Otestujte chýbajúce časové pečiatky, neznáme stavy a nesprávne dátové obsahy.
- Simulujte zlyhanie databázy pred potvrdením a zlyhanie pracovníka po uložení.
- Otestujte časové limity správ vrátane neistej odpovede, keď služba už mohla správu prijať.
- Potvrďte, že rozdelené zásielky vytvárajú formulácie špecifické pre jednotlivé balíky.
- Skontrolujte príjemcov po odhlásení, neplatné kontaktné údaje a spracovanie tichých hodín.
- Overte, že odkazy na sledovanie neodhaľujú informácie o objednávke iného zákazníka.
Monitorujte prijaté spätné volania, zlyhania spracovania, vek frontu, úlohy upozornení, potlačenie duplicít a výsledky odosielania správ. Latenciu spracovania od času prijatia vaším systémom merajte oddelene od veku udalosti dopravcu. Toto rozlíšenie pomáha určiť, či pomalé upozornenie vzniklo dostupnosťou nadradených údajov alebo vaším vlastným potrubím.
Začnite malou skupinou dobre pochopených míľnikov. Pravidlá rozširujte až potom, čo tímy podpory a prevádzky potvrdia, že správy sú presné, užitočné a hodné prijatia.
Často kladené otázky
Odosiela API na sledovanie zásielok automaticky e-maily alebo SMS správy?
Nie nevyhnutne. Prístup k údajom o sledovaní a komunikácia so zákazníkom sú samostatné funkcie. Overte zdokumentovaný rozsah služby. Pri vlastnej integrácii môže vaša aplikácia spracúvať aktualizácie sledovania a odosielať upozornenia prostredníctvom samostatnej služby na odosielanie správ.
Mám zákazníkov upozorňovať na každý sken sledovania?
Zvyčajne nie. Uprednostnite významné míľniky a udalosti, ktoré vyžadujú zásah. Niekoľko skenov v prevádzke môže predstavovať bežnú prepravu bez zmeny toho, čo zákazník potrebuje vedieť. Podrobnú históriu ponechajte na stránke sledovania.
Môžem garantovať upozornenia na doručenie v reálnom čase?
Po prijatí aktualizácie vaším systémom môžete nastaviť a monitorovať cieľ spracovania. Nemôžete garantovať, kedy dopravca zaznamená alebo zverejní sken. Službu opisujte spôsobom, ktorý zohľadňuje túto závislosť.
Ako môžem zabrániť duplicitným správam o doručení?
Používajte trvalé odstraňovanie duplicít udalostí, samostatnú identitu upozornenia pre každý obchodný míľnik a transakčné vytváranie úloh. Ak vaša služba správ podporuje idempotenciu, použite ju ako ďalšiu ochranu. Samotná kontrola duplicít v pamäti neprežije reštart ani viac pracovníkov.
Čo sa má stať, ak dopravca opraví stav doručenia?
Zachovajte obe udalosti a zosúlaďte stav zásielky. Ak oprava významne ovplyvňuje zákazníka, odošlite jasnú opravu alebo ju podľa pravidiel smerujte na podporu. Stav doručenia nerobte natrvalo nezvratným iba preto, aby sa zjednodušil kód.
Zdroje
Nasledujúce oficiálne zdroje sú implementačnými referenciami pre integráciu 17TRACK uvedenú vyššie. Interná schéma, pravidlá upozornení a pracovný postup v tejto príručke sú architektonické odporúčania, nie citované zmluvy API.
- 17TRACK Tracking API — oficiálny východiskový bod na posúdenie integrácie API.
- Dokumentácia API 17TRACK — referencia pre formáty požiadaviek špecifické pre poskytovateľa, autentifikáciu, operácie sledovania a integračné požiadavky.


