Jak používat API pro sledování zásilek k odesílání proaktivních oznámení o doručení
Chcete-li pomocí API pro sledování zásilek odesílat proaktivní oznámení o doručení, propojte každý balík s jeho objednávkou, načítejte aktualizace sledování, převádějte tyto aktualizace na události relevantní pro zákazníka a spouštějte zprávy prostřednictvím své služby pro e-mailová, SMS nebo aplikační oznámení. Mezi příchozí data sledování a odchozí zprávy vložte odolnou frontu a kontroly duplicit, aby opakované nebo opožděné aktualizace nevytvářely matoucí upozornění.

Tato příručka je určena vývojářům a týmům e-commerce provozu, které vytvářejí takový pracovní postup. Cílem není přeposílat každý sken přepravce. Jde o to informovat zákazníky, když se něco významného změní, co tato změna znamená a zda musí něco udělat.
Navrhněte pracovní postup oznámení ještě před připojením API
API pro sledování zásilek poskytuje informace o sledování; vaše aplikace rozhoduje, jak je použít. Přehled o zásilce a komunikaci se zákazníkem považujte za oddělené odpovědnosti, i když vaše zvolená služba nabízí obojí.
Praktická architektura má šest fází:
- Přiřazení objednávky: v případě potřeby propojte sledovací číslo a identifikátor přepravce s interním záznamem zásilky.
- Registrace sledování: odešlete nebo zaregistrujte zásilku podle požadavků poskytovatele na integraci.
- Načítání aktualizací: přijímejte callbacky webhooku, získávejte aktualizace prostřednictvím požadavků API nebo kombinujte oba přístupy.
- Zpracování událostí: ověřujte, normalizujte, odstraňujte duplicity a vyhodnocujte příchozí události.
- Rozhodnutí o oznámení: zvolte, zda oznámení odeslat, koho kontaktovat a který kanál a šablonu použít.
- Doručení zprávy: odešlete oznámení a zaznamenejte odpověď služby pro zasílání zpráv.
Kontaktní údaje zákazníků uchovávejte ve vlastním systému objednávek nebo zpráv, pokud integrace skutečně nevyžaduje jejich sdílení. Služba pro sledování obecně nepotřebuje e-mailovou adresu zákazníka jen proto, aby vaše aplikace mohla přiřadit událost sledování k objednávce.
1. Ověřte integrační kontrakt
Před napsáním přijímače si v dokumentaci poskytovatele ověřte autentizaci, registraci zásilek, identifikaci přepravce, podporované metody aktualizací, formáty odpovědí, limity požadavků a zpracování chyb. U integrací webhooku také ověřte, jak jsou callbacky autentizovány, jaká odpověď potvrzuje jejich přijetí a jak se řeší neúspěšná doručení.
U implementace 17TRACK začněte na stránce 17TRACK Tracking API a v jeho oficiální dokumentaci API. Pro integraci použijte zdokumentovaný kontrakt a nepovažujte názvy polí uvedené v této příručce za skutečná pole požadavků nebo odpovědí 17TRACK. Před implementací ověřte nastavení callbacků, bezpečnostní požadavky a limity konkrétního účtu.
Metodu aktualizací zvolte podle integračního kontraktu:
- Webhooky: pokud jsou podporované a vhodné pro vaši infrastrukturu, používejte callbacky. Umožní aplikaci zpracovat aktualizace, jakmile je poskytovatel odešle, bez opakovaného dotazování na stejnou zásilku.
- Dotazování: pokud callbacky nejsou dostupné nebo vhodné, získávejte informace o sledování podle plánu. Dodržujte zdokumentované limity požadavků.
- Kombinovaný přístup: callbacky používejte pro běžné zpracování a selektivní získávání dat přes API pro kontrolu zásilek, jejichž aktualizace se zdají být zastaralé, pokud poskytovatel tento postup podporuje.
Neříkejte zákazníkům, že oznámení budou okamžitá, jen proto, že používáte webhooky. Vaše aplikace nemůže nahlásit událost přepravce dříve, než ji zpřístupní zdrojová data sledování.
2. Vytvořte záznam zásilky, který obstojí u skutečných objednávek
Jako hlavní referenci používejte interní ID zásilky, nikoli pouze sledovací číslo. Objednávka může obsahovat několik balíků a nelze předpokládat, že sledovací čísla budou navždy globálně jedinečná.
Užitečný interní záznam obsahuje:
- Interní ID objednávky a ID zásilky.
- Sledovací číslo a identifikátor přepravce, pokud jsou známy.
- Referenci zásilky u poskytovatele, pokud je k dispozici.
- Aktuální normalizovaný stav a poslední významnou událost.
- Čas události u přepravce včetně časového pásma nebo posunu, pokud je k dispozici.
- Čas, kdy váš systém aktualizaci přijal.
- Referenci na komunikační preference zákazníka.
- Historii oznámení a případný aktivní postup řešení výjimky.
Čas události ukládejte odděleně od času přijetí. Sken, ke kterému došlo dříve, může dorazit až po novějším skenu. Pokud aplikace řadí události pouze podle pořadí příchodu, může omylem změnit doručenou zásilku zpět na zásilku v přepravě.
U rozdělených objednávek propojujte oznámení s dotčeným balíkem. Pokud se další balík stále přepravuje, je přesnější říci „Jeden balík z vaší objednávky byl doručen“ než „Vaše objednávka byla doručena“.
3. Mapujte události sledování na rozhodnutí zákazníka
Popisy přepravce jsou provozní data, nikoli hotové zprávy pro zákazníky. Vytvořte normalizační vrstvu, která zachová původní událost a zároveň jí přiřadí interní kategorii, které rozumějí pravidla oznámení.
Následující kategorie jsou navrhované aplikační koncepty, nikoli univerzální slovník stavů API:
| Interní kategorie | Rozhodnutí o oznámení | Hranice komunikace |
|---|---|---|
| Informace o zásilce přijata | Aktualizaci o přípravě odešlete jen tehdy, pokud je užitečná. | Naznačujte převzetí zásilky přepravcem pouze na základě vytvoření štítku. |
| V přepravě | Zvažte oznámení při prvním významném pohybu. | Běžné skeny v provozovnách potlačte, pokud nemění další krok zákazníka. |
| Doručení probíhá | Oznámení odešlete, když podporovaná událost indikuje tento stav. | Nepřevádějte stav na garantovaný čas doručení. |
| Pokus o doručení nebo nutné vyzvednutí | Odešlete oznámení s konkrétními kroky. | Termíny nebo pokyny k vyzvednutí uvádějte pouze po ověření. |
| Výjimka při doručení | Posuďte příčinu a to, zda musí zákazník jednat. | Nepopisujte každou výjimku jako ztracený balík. |
| Doručeno | Odešlete potvrzení na úrovni balíku. | Nevymýšlejte příjemce, místo doručení ani doklad o doručení. |
Zachovávejte nejistotu. Nerozpoznaná událost by měla přejít do kontroly nebo záložního postupu, nikoli být násilně zařazena do nejbližší známé kategorie. Původní popis ponechte dostupný pracovníkům podpory pro řešení problémů.
4. Přijímejte aktualizace bez ztráty nebo duplicitního zpracování
Endpoint webhooku by měl ověřit požadavek, trvale uložit přijatou aktualizaci a vrátit potvrzení vyžadované poskytovatelem. Generování zprávy provádějte asynchronně, místo abyste během požadavku callbacku čekali na e-mailovou nebo SMS službu.
Implementujte zdokumentovanou metodu ověřování callbacků poskytovatele. Nevymýšlejte hlavičku podpisu ani nepředpokládejte, že každý poskytovatel používá stejné schéma autentizace. Vynucujte také HTTPS, limity velikosti požadavků, validaci dat a vhodné řízení přístupu.
Zjednodušený tok zpracování vypadá takto. Jde o operace na úrovni aplikace, nikoli o funkční příklad SDK:
přijmout callback
ověřit požadavek pomocí zdokumentovaného mechanismu poskytovatele
ověřit data
atomicky uložit přijatá data a zařadit zpracování do fronty
vrátit zdokumentované potvrzení
zpracovat aktualizaci z fronty
najít interní zásilku
normalizovat relevantní události
ignorovat již zpracované události
vyhodnotit chronologii a přechod stavu
vytvořit úlohu oznámení, pokud to pravidla dovolují
společně potvrdit stav a úlohu
odeslat úlohu oznámení
zkontrolovat preference příjemce a pravidla potlačení
odeslat zprávu službě pro zasílání zpráv
zaznamenat výsledek a opakovat pouze v příslušných případechAtomické kroky jsou důležité. Pokud aplikace uloží změnu stavu, ale před vytvořením úlohy oznámení selže, zákazník nemusí upozornění nikdy obdržet. Jednou z možností návrhu je transakční outbox: uložte změnu stavu a čekající úlohu ve stejné databázové transakci a poté nechte pracovní proces úlohu odeslat.
Neznámé reference zásilek řešte výslovně. Izolujte je pro šetření nebo sesouhlasení, místo abyste odhadovali, který zákazník má oznámení obdržet.
5. Přidejte ochranu před duplicitami a chronologické kontroly
Navrhněte přijímač tak, aby toleroval opakované callbacky a opakované pokusy pracovníků. Pokud je zdokumentován stabilní identifikátor události poskytovatele, použijte jej. Jinak vytvořte deterministický otisk události z vhodných polí, například z interního ID zásilky, kódu události, času události a místa. Před použitím otisk otestujte na skutečných datech.
Odstraňování duplicit událostí a potlačení oznámení řeší odlišné problémy. Odstranění duplicit zabrání dvojímu zpracování stejné události. Potlačení zabrání tomu, aby několik různých skenů vytvořilo v podstatě stejnou zprávu pro zákazníka.
Identitu oznámení definujte kolem obchodní události. Potvrzení doručení může používat ID zásilky a milník doručení. Pokus o doručení může potřebovat identitu specifickou pro daný pokus, protože pozdější pokus může být skutečně novou událostí.
U aktualizací mimo pořadí porovnávejte časová razítka událostí a vyhodnocujte povolené přechody stavů. Nepředpokládejte, že callback obsahuje pouze nový sken; ověřte, zda jeho zdokumentovaná struktura představuje jednotlivou událost, snímek nebo historii. Rozporuplné aktualizace směrujte k sesouhlasení místo tichého zahazování všech oprav.
6. Pište zprávy, které vysvětlují další krok
Každé oznámení by mělo uvádět relevantní balík, potvrzenou změnu a další krok zákazníka. Přidejte bezpečný odkaz na sledování a rozpoznatelnou referenci objednávky. Ve zprávách SMS a náhledech na uzamčené obrazovce nezobrazujte celé adresy ani nepotřebné osobní údaje.
Například:
- Doručení probíhá: „Váš balík k objednávce {order_reference} je doručován. Průběh můžete sledovat zde: {tracking_link}.“
- Pokus o doručení: „Přepravce nahlásil pokus o doručení vašeho balíku. Dostupné další kroky najdete na stránce sledování: {tracking_link}.“
- Doručeno: „Přepravce označil váš balík k objednávce {order_reference} jako doručený. Zobrazit dostupné údaje o doručení: {tracking_link}.“
Placeholdery vykreslujte pouze z ověřených dat. Pokud je k dispozici odhad doručení a je vhodný k zobrazení, označte jej jako odhad. Pokud chybí, vynechte jej místo vymýšlení data.
U výjimek rozlišujte problém zásilky od úkolu zákazníka. Narušení může vyžadovat pouze vysvětlení; ověřený problém s adresou může vyžadovat akci. Neposílejte zákazníky na stránku s platbou nebo nahráním dokumentů pouze na základě nedůvěryhodného volného textu ze sledování.
Kanály vybírejte podle preferencí zákazníka, oprávnění kanálu, naléhavosti a příslušných pravidel. Ověřte požadavky na souhlas, odhlášení a klidové hodiny pro jurisdikce a komunikační kanály, které používáte. Oznámení o doručení udržujte oddělená od propagačních kampaní a nepředpokládejte, že pro obě kategorie platí stejná oprávnění.
7. Definujte, co se stane, když se sledování odmlčí
Proaktivní komunikace by měla pokrývat chybějící postup i nové události, samotné ticho však nedokazuje, že je zásilka zpožděná nebo ztracená.
Vytvořte pravidlo zastaralého sledování s využitím úrovně služby, trasy, poslední významné události a případného podporovaného odhadu doručení. Prahové hodnoty nastavte podle provozních dat a procesu podpory, nikoli jednou univerzální čekací dobou pro každou zásilku.
Když se pravidlo spustí, zkontrolujte vynechané zpracování, případně proveďte sesouhlasení se zdrojem sledování a rozhodněte, zda otevřít interní úkol podpory. Pokud zákazníka informujete, používejte formulaci odpovídající tomu, co víte: „Neobdrželi jsme novou aktualizaci sledování“ se liší od „Váš balík se ztratil“.
Nezpracované výjimky musí mít přiřazeného vlastníka. Systém oznámení, který opakovaně oznamuje problém, aniž by vytvořil cestu k jeho vyřešení, může zvyšovat frustraci zákazníků.
8. Otestujte celou cestu před aktivací automatického odesílání
Nejprve spusťte pracovní postup v režimu shadow: načítejte skutečné nebo schválené testovací události, vytvářejte navrhovaná oznámení a kontrolujte výsledky bez kontaktování zákazníků.
- Přehrajte totožný callback a ověřte, že nevytvoří další zprávu.
- Zpracujte starší událost přepravy po události doručení a zkontrolujte výsledný stav.
- Otestujte chybějící časová razítka, neznámé stavy a poškozená data.
- Simulujte selhání databáze před potvrzením a selhání pracovníka po uložení.
- Otestujte časové limity zasílání zpráv včetně nejisté odpovědi, kdy služba již mohla zprávu přijmout.
- Ověřte, že rozdělené zásilky vytvářejí formulace specifické pro jednotlivé balíky.
- Zkontrolujte příjemce po odhlášení, neplatné kontaktní údaje a zpracování klidových hodin.
- Ověřte, že odkazy na sledování nezpřístupní údaje o objednávce jiného zákazníka.
Sledujte přijaté callbacky, chyby zpracování, stáří fronty, úlohy oznámení, potlačení duplicit a výsledky zasílání zpráv. Latenci zpracování od času přijetí vaším systémem měřte odděleně od stáří události přepravce. Toto rozlišení pomáhá určit, zda pomalé oznámení způsobila dostupnost zdrojových dat, nebo vlastní zpracovatelský tok.
Začněte s malou sadou dobře pochopených milníků. Pravidla rozšiřujte až poté, co se podpůrné a provozní týmy shodnou, že zprávy jsou přesné, akční a stojí za to je přijímat.
Časté dotazy
Odesílá API pro sledování zásilek automaticky e-maily nebo SMS?
Ne nutně. Přístup k údajům o sledování a komunikace se zákazníkem jsou oddělené funkce. Ověřte zdokumentovaný rozsah služby. Ve vlastní integraci může aplikace zpracovávat aktualizace sledování a odesílat oznámení prostřednictvím samostatné služby pro zasílání zpráv.
Mám zákazníky informovat o každém skenu sledování?
Obvykle ne. Upřednostněte významné milníky a události, které vyžadují akci. Několik skenů v provozovnách může představovat běžnou přepravu, aniž by měnilo to, co zákazník potřebuje vědět. Podrobnou historii ponechte na stránce sledování.
Mohu garantovat oznámení o doručení v reálném čase?
Po přijetí aktualizace vaším systémem můžete nastavit a sledovat cíl zpracování. Nemůžete garantovat, kdy přepravce sken zaznamená nebo zveřejní. Službu popisujte tak, aby odrážela tuto závislost.
Jak zabránit duplicitním zprávám o doručení?
Používejte trvalé odstraňování duplicit událostí, samostatnou identitu oznámení pro každý obchodní milník a transakční vytváření úloh. Pokud vaše služba pro zasílání zpráv podporuje idempotenci, použijte ji jako další ochranu. Kontrola duplicit pouze v paměti nepřežije restarty ani více pracovníků.
Co se má stát, pokud přepravce opraví stav doručeno?
Zachovejte obě události a sjednoťte stav zásilky. Pokud oprava významně ovlivní zákazníka, odešlete jasnou opravnou zprávu nebo ji podle pravidel předejte podpoře. Stav doručeno nečiněte trvale nevratným jen kvůli zjednodušení kódu.
Zdroje
Následující oficiální zdroje jsou referencemi pro implementaci integrace 17TRACK popsané výše. Interní schéma, pravidla oznámení a tok zpracování v této příručce jsou architektonická doporučení, nikoli citované kontrakty API.
- 17TRACK Tracking API — oficiální výchozí bod pro posouzení integrace API.
- 17TRACK API documentation — reference pro formáty požadavků specifické pro poskytovatele, autentizaci, operace sledování a integrační požadavky.


