Skip to main content
DomůBlogPrůvodciTestování integrace Tracking API ve vývojovém prostředí: sandbox, testovací čísla, mock webhooky

Testování integrace Tracking API ve vývojovém prostředí: sandbox, testovací čísla, mock webhooky

17TRACK

Chcete-li v rámci vývoje otestovat integraci API pro sledování zásilek, použijte tři vzájemně se doplňující metody: sandbox poskytovatele nebo zdokumentovaná testovací čísla pro ověření chování API, lokální fixture pro opakovatelné scénáře zásilek a mock webhooky pro váš přijímací endpoint. Poté proveďte řízenou kontrolu v ostrém prostředí a ověřte části, které simulace nemohou prokázat, včetně přihlašovacích údajů, konfigurace odběru a skutečného doručování událostí.

Testování integrace API pro sledování zásilek ve vývojovém sandboxu a testovacích číslech

Tato příručka je určena vývojářům, kteří připojují sledování zásilek k platformě elektronického obchodu, systému pro správu objednávek, ERP nebo službě pro upozornění zákazníků. Cílem není pouze obdržet úspěšnou odpověď API. Je třeba prokázat, že aktualizace sledování vytvářejí správný stav objednávky bez duplicitních zpráv, ztracených událostí nebo náhodného kontaktování skutečných zákazníků.

Oddělte chování poskytovatele od chování aplikace

Integrace sledování má nejméně dvě hranice: požadavky, které vaše aplikace odesílá poskytovateli, a aktualizace, které vaše aplikace následně přijímá nebo načítá. Úspěšný požadavek na první hranici neprokazuje, že funguje i druhá hranice.

Testovací plán sestavte podle těchto hranic, místo abyste očekávali, že celé řešení prověří jediné testovací číslo zásilky.

Metoda testováníCo může ověřitCo sama nemůže prokázat
Sandbox poskytovatelePodporované formáty požadavků, ověřování a simulované chování popsané poskytovatelemDostupnost produkčních dat přepravců ani chování doručování v produkci
Zdokumentovaná testovací číslaKonkrétní scénáře přiřazené k těmto číslůmJiné stavy, přepravce nebo sekvence webhooků
Lokální fixture a mocky APIVáš parser, mapovací pravidla, perzistenci a zpracování chybZda skutečný poskytovatel přijme požadavky nebo odešle stejný payload
Mockované požadavky webhookůZpracování endpointu, validaci, deduplikaci a následné účinkyKonfiguraci callbacků na straně poskytovatele ani skutečné opakované doručování
Řízený test v ostrém prostředíSkutečné připojení a pozorovaný průběh zásilkyKaždou vzácnou chybu, výjimku nebo sekvenci doručení

Doporučený postup: zajistěte deterministické lokální testy, využívejte testování podporované poskytovatelem, pokud je k dispozici, a ostré zásilky používejte pouze k potvrzení propojení mezi systémy.

Před vytvořením fixture si potvrďte smlouvu s poskytovatelem

Začněte oficiální dokumentací k verzi API, kterou hodláte používat. Ověřte základní URL, metodu ověřování, požadavky na registraci, schéma odpovědi, nastavení webhooků a všechny zdokumentované možnosti testování. Nepředpokládejte existenci samostatného sandboxu jen proto, že poskytovatel nabízí API.

Pro integraci 17TRACK použijte jako výchozí body stránku 17TRACK Tracking API a oficiální dokumentaci API. Před vytvořením příkladů specifických pro poskytovatele si zde ověřte příslušné specifikace požadavků a callbacků. Níže uvedené příklady jsou záměrně fixture vlastněné aplikací, nikoli reprezentací schématu API 17TRACK.

Před připojením vývojového kódu k externímu účtu si zodpovězte tyto otázky:

  • Jsou vývojové a produkční přihlašovací údaje oddělené a do jakého prostředí má každý údaj přístup?
  • Podporuje sandbox callbacky, nebo pouze testování požadavek–odpověď?
  • Jsou testovací čísla zdokumentována a jaké přesné výsledky vytvářejí?
  • Mohou registrace nebo jiné testovací požadavky spotřebovávat kvótu účtu nebo vytvářet trvalé záznamy?
  • Jaká pravidla ověřování callbacků, potvrzení, timeoutů a opakování jsou zdokumentována?
  • Které identifikátory propojují registraci sledování, zásilku, přepravce a událost callbacku?

Pokud chování při testování není jasně zdokumentováno, požádejte poskytovatele o potvrzení. Mezitím pokračujte v testování vlastní logiky zpracování pomocí mocků. Nepotvrzená schopnost sandboxu je nejistota při plánování, nikoli důkaz, že poskytovateli tato schopnost chybí.

Vytvořte izolované vývojové prostředí

Používejte samostatnou databázi nebo izolovaného tenanta, oddělená tajemství a syntetické objednávky. E-maily, SMS a další upozornění směrujte na testovací cíle nebo do úložiště oznámení. Zásilka označená ve fixture jako doručená nesmí vyvolat zprávu skutečnému kupujícímu.

Do interních záznamů a logů přidejte explicitní označení prostředí. Přihlašovací údaje poskytovatele uchovávejte na serveru mimo správu zdrojového kódu a při zachycování požadavků tajné údaje redigujte. Pokud je pro callbacky nutný dočasný veřejný přístup, zpřístupněte pouze zamýšlenou vývojovou trasu a zachovejte její ověřovací mechanismy.

Před odesíláním událostí vytvořte malou sadu známých objednávek. Zahrňte dvě zásilky připojené k jedné objednávce a, pokud to vaše aplikace podporuje, stejný řetězec sledovacího čísla v kontextu různých přepravců. Tyto případy odhalí předpoklady, že samotné sledovací číslo vždy identifikuje jedinečný obchodní záznam.

Očekávaný účinek každého testu definujte předem: stav zásilky, přiřazení objednávky, položky časové osy, počet upozornění a auditní záznam. Z demonstrace se tak stane tvrzení, které může projít nebo selhat.

Testovací čísla používejte pouze k jejich zdokumentovanému účelu

Sledovací číslo má při testování dvě odlišné role. Může sloužit jako vstup pro ověření registrace a může identifikovat zásilku, která vytváří události sledování. Číslo, které projde validací formátu, nemusí nutně poskytovat užitečnou historii událostí.

Když jsou k dispozici oficiální testovací čísla

Ke každému číslu zaznamenejte scénář uvedený poskytovatelem. U čísla zdokumentovaného pro doručenou zásilku nepředpokládejte, že simuluje výjimku, vrácení nebo neúspěšný pokus o doručení. Ověřte také, zda je výsledek pevně daný, v čase se mění nebo vyžaduje výběr konkrétního přepravce.

Tato čísla uchovávejte ve vyhrazené konfiguraci integračních testů. Nerozptylujte je po unit testech, kde by změna externího chování mohla učinit jinak deterministické testy nespolehlivými.

Když oficiální testovací čísla nejsou potvrzena

Použijte syntetické identifikátory uvnitř vlastní aplikace a mockujte hranici poskytovatele. Nikdy nevymýšlejte číslo, které vypadá věrohodně, a nepředpokládejte, že je vyhrazeno pro testování: může odpovídat skutečné zásilce.

Pro ověření v ostrém prostředí používejte zásilky, které máte pod kontrolou a k nimž máte oprávnění přístupu. Nekopírujte sledovací čísla z veřejných snímků obrazovky ani z komunikace se zákazníky. Historii zásilek považujte za potenciálně citlivou, protože může obsahovat místa, časová razítka a informace o doručení.

Starší doručená zásilka může pomoci ověřit parsování, ale je špatnou závislostí pro kontinuální integraci. Dostupnost historických dat i externí odpověď se mohou změnit. Zachovejte sanitizovanou fixture pro opakovatelné testy a živou kontrolu udržujte odděleně.

Vytvářejte fixture kolem smysluplných přechodů zásilky

Fixture vytvářejte podle zdokumentovaného schématu a, pokud jsou k dispozici, sanitizovaných skutečných odpovědí. Payloady poskytovatele uchovávejte odděleně od interního normalizovaného modelu událostí. Testujte adaptér mezi nimi, aby interní mock nezakryl nefunkční parser poskytovatele.

Užitečná výchozí sada pokrývá tyto scénáře:

  • Zatím žádné události sledování: zásilku uchovejte, aniž byste tvrdili, že se pohybuje nebo byla doručena.
  • V přepravě: aktualizujte časovou osu a zachovejte správné přiřazení objednávky.
  • Na doručení: použijte svou politiku upozornění, ale nepovažujte doručení za dokončené.
  • Doručeno: zaznamenejte dokončení a zamýšlenou obchodní akci vyšlete právě jednou.
  • Výjimka nebo pokus o doručení: zachovejte rozdíl oproti dokončenému doručení.
  • Pohyb při vrácení: nevykládejte každý pozdější sken jako postup směrem k původnímu příjemci.
  • Neznámý stav: uchovejte dostatek informací pro diagnostiku, aniž byste vymýšleli mapování stavu.

Pro tyto scénáře používejte vlastní normalizované názvy a poté do nich explicitně mapujte zdokumentované hodnoty poskytovatele. Nepředpokládejte, že různá API používají stejné popisky stavů nebo že popisek má všude stejný obchodní význam.

Měňte také tvar dat: prázdný seznam událostí, chybějící volitelná pole, další neznámá pole, názvy míst v Unicode, časová razítka s posuny časových pásem a neplatné povinné hodnoty. Parser by měl tolerovat kompatibilní rozšíření, ale odmítnout data, která nelze bezpečně zpracovat.

Odesílejte mockované webhooky skutečnou přijímací cestou

Mockovaný webhook by měl procházet přijímací trasou, middlewarem pro ověřování, validací, ukládáním a zpracováním workerem — nikoli pouze volat konečnou funkci pro aktualizaci stavu.

Následující payload představuje syntetickou interní událost. Názvy polí, ID události a stav jsou ilustrativní; nejde o smlouvu callbacku poskytovatele.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Uložte jej jako tracking-event.json a odešlete na lokální testovací přijímač:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Tento příkaz ověřuje pouze lokální směrování a zpracování. Neprokazuje ověřování poskytovatele. Vývojovou trasu dostupnou pouze pro vývoj udržujte v produkci nepřístupnou, nebo produkční přijímač testujte pomocí zdokumentované metody ověřování poskytovatele a samostatného testovacího tajemství.

Testujte ověřování bez oslabování produkčních kontrol

Pokud poskytovatel určuje podepisované callbacky, implementujte přesně toto schéma, místo abyste volili libovolnou hlavičku podpisu nebo algoritmus. U schémat, která podepisují bajty požadavku, zachovejte původní tělo pro ověření; parsování a opětovná serializace JSON mohou tyto bajty změnit.

Testujte platné ověření, chybějící přihlašovací údaje, pozměněná těla a nesprávné podpisy, pokud je to relevantní. Pokud zdokumentované schéma zahrnuje časová razítka nebo ochranu proti opakovanému přehrání, testujte i tato pravidla. HMAC je standardizovaná konstrukce pro ověřování zpráv, ale jeho existence neprokazuje, že jej konkrétní poskytovatel sledování používá.

Testujte duplicity, pořadí a obnovu

Zpracování zásilek musí zůstat správné, když stejná aktualizace dorazí opakovaně nebo události přijdou v neočekávaném pořadí. Jde o obranné testovací scénáře, nikoli o tvrzení týkající se garance doručování konkrétního poskytovatele.

TestOčekávané chování aplikace
Odešlete stejnou událost dvakrátZachovejte jednu logickou událost a zabraňte duplicitním upozorněním zákazníků.
Po doručení odešlete starší tranzitní skenZachovejte užitečnou historii, aniž byste automaticky vraceli stav z doručeno.
Odešlete souběžné aktualizacePoužívejte konzistentní přechody stavů i při souběžném zpracování workery.
Po trvalém přijetí zastavte zpracováníObnovte a zpracujte uloženou událost bez nutnosti nového callbacku.
Úložiště selže před trvalým přijetímNeodpovídejte falešným potvrzením úspěšného přijetí.
Odešlete neznámou zásilkuPostupujte podle definované karanténní nebo zamítací politiky; nikdy nehádejte přiřazení objednávky.

Pokud je k dispozici, upřednostněte pro deduplikaci zdokumentovaný stabilní identifikátor události. Jinak definujte pečlivě omezenou identitu z relevantních polí a testujte kolize. Samotné sledovací číslo není identitou události, protože jedna zásilka může vytvářet mnoho legitimních aktualizací.

Oddělte historii událostí od aktuální projekce zásilky. Uchovávání historických skenů neznamená, že každý pozdě doručený sken musí přepsat zobrazený stav. Ani pravidlo „použij nejnovější časové razítko“ není úplné: opravy, procesy vrácení a různé významy časových razítek vyžadují explicitní zpracování.

U asynchronního zpracování potvrďte přijetí až poté, co událost dosáhne trvalého předávacího bodu, například potvrzeného záznamu inboxu nebo trvalé fronty, podle vaší architektury. Dodržujte zdokumentované požadavky poskytovatele na potvrzení. HTTP definuje význam stavových kódů, ale plán opakování konkrétního odesílatele musí vycházet z jeho vlastní smlouvy.

Proveďte řízenou kontrolu v ostrém prostředí a stanovte kritéria vydání

Jakmile deterministické testy projdou, zaregistrujte prostřednictvím skutečné integrace autorizovanou zásilku a ověřte celou cestu. Zkontrolujte, že poskytovatel přijal zamýšlený záznam, konfigurace callbacku směřuje do správného prostředí a příchozí data se mapují na očekávanou zásilku.

Nevyžadujte, aby se během této živé kontroly objevil každý stav zásilky. Skutečné zásilky nejsou kontrolovatelné fixture. Živé spuštění použijte k ověření připojení a pozorované kompatibility smlouvy; k pokrytí vzácných nebo destruktivních scénářů používejte znovu přehratelné fixture.

Před vydáním vyžadujte následující výsledky:

  • Jsou zpracovány zdokumentované úspěšné i chybové odpovědi včetně selhání na úrovni položek, pokud API podporuje dávkové operace.
  • Timeouty nespouštějí slepé opakování vytváření, pokud první požadavek již mohl uspět.
  • Duplicitní události nemohou vytvořit duplicitní obchodní akce.
  • Neplatné callbacky nemohou změnit stav zásilky.
  • Selhání workeru ponechávají obnovitelné události namísto jejich tiché ztráty.
  • Vývojový provoz nemůže upozorňovat skutečné zákazníky ani měnit produkční objednávky.
  • Logy propojují požadavky, přijaté události, výsledky zpracování a pokusy o upozornění, aniž by odhalovaly tajné údaje.

Vydání je připraveno, když dokážete vysvětlit běžný průběh i způsob obnovy systému po nejistém požadavku, opakovaném callbacku nebo přerušeném workeru. Jedno úspěšné vyhledání zásilky nestačí.

Časté dotazy

Mohu testovat integraci sledování bez sandboxu?

Ano. Mockujte hranici odchozího API, přehrávejte zdokumentované fixture callbacků a lokálně testujte normalizaci a obchodní pravidla. Poté použijte autorizovanou živou zásilku k potvrzení skutečného připojení. Získáte tak rozsáhlé pokrytí, ale nebude reprodukováno nedokumentované chování poskytovatele.

Proč můj požadavek na sledování uspěje, ale nevrátí žádné události?

Přijetí požadavku a dostupnost dat o sledování jsou odlišné výsledky. Zkontrolujte podrobnosti odpovědi poskytovatele, požadavky na registraci, pravidla identifikace přepravce a zdokumentované chování u zásilek bez událostí. Nevytvářejte pohyb ani informace o doručení, abyste zaplnili prázdnou časovou osu.

Prokazuje úspěšný mock webhook, že dorazí skutečné webhooky?

Ne. Prokazuje pouze cestu procvičenou mockem. Skutečné doručování závisí také na konfiguraci poskytovatele, veřejné dostupnosti, TLS, ověřování a skutečné smlouvě callbacku. Ověřte je testovacím doručením podporovaným poskytovatelem nebo autorizovaným živým procesem.

Měl bych vrátit HTTP 200 před dokončením zpracování?

Dodržujte zdokumentovanou smlouvu poskytovatele pro potvrzení. V asynchronním návrhu potvrďte přijetí po trvalém přijetí a poté zpracovávejte ve workeru. Vrácení úspěchu před trvalým přijetím může vést ke ztrátě události, pokud proces bezprostředně poté selže.

Jak mám testovat upozornění zákazníků?

Všechna vývojová upozornění odesílejte do kontrolovaného úložiště. Ověřujte cíl, šablonu, spouštěcí přechod a počet odeslání. Přehrajte stejnou událost a simulujte opakování workeru, abyste ověřili, že jedna aktualizace zásilky nevytvoří opakované zprávy zákazníkům.

Zdroje

  • 17TRACK Tracking API — oficiální výchozí bod pro produkt tracking API.
  • Dokumentace 17TRACK API — reference ke smlouvě integrace specifické pro poskytovatele; zde si potvrďte příslušné požadavky na testování a callbacky.
  • RFC 9110: HTTP Semantics — význam HTTP odpovědí a aspekty opakování požadavků.
  • RFC 2104: HMAC — standardizovaná konstrukce ověřování zpráv popsaná v pokynech k zabezpečení callbacků.