Skip to main content
DomůBlogPrůvodciVáš první požadavek na Tracking API: průvodce REST klientem s Postmanem a Curlem

Váš první požadavek na Tracking API: průvodce REST klientem s Postmanem a Curlem

17TRACK

Chcete-li odeslat svůj první požadavek na tracking API, nakonfigurujte v REST klientovi endpoint, autentizační hlavičku a JSON tělo, odešlete požadavek a zkontrolujte stav HTTP i tělo odpovědi. Tento návod používá Tracking API 17TRACK k demonstraci stejného pracovního postupu v nástrojích Postman a curl: zaregistrovat zásilku, vyžádat si její informace o sledování a ověřit, zda je výsledek připraven k použití ve vaší aplikaci.

První požadavek na Tracking API: průvodce REST klientem

Cílem je malý, reprodukovatelný integrační test, nikoli nasazení do produkce. Budete potřebovat přihlašovací údaje API a číslo zásilky, které máte oprávnění zpracovávat. Níže uvedené příkazy používají vzor endpointu v2.2; před jejich spuštěním ověřte verzi endpointu a požadavky specifické pro váš účet v dokumentaci API 17TRACK.

Uvědomte si, čeho by měl váš první požadavek dosáhnout

Integrace sledování zásilky má dvě samostatné části: sdělit službě, kterou zásilku má sledovat, a načíst informace o sledování spojené s touto zásilkou. V zde uvedeném pracovním postupu jde o samostatné požadavky. Registrace neznamená, že se zásilka již pohybuje, a úspěšná registrace nezaručuje, že události dopravce budou okamžitě dostupné.

Pro první test použijte jednu zásilku, nikoli dávku. Díky tomu lze snáze oddělit chyby autentizace, neplatná sledovací čísla a interpretaci odpovědi. Prvním užitečným milníkem není pouze „obdržel jsem HTTP 200“. Je to „API přijalo zamýšlenou operaci a dokážu vysvětlit výsledek na úrovni zásilky“.

Postman poskytuje vizuální rozhraní pro úpravu požadavků a kontrolu odpovědí. curl umožňuje reprodukovat stejnou výměnu HTTP z terminálu. Ani jeden z nich nemění pravidla autentizace API, data zásilky ani chování zpracování. Použijte nástroj, který vám pomůže požadavek lépe prozkoumat, a poté funkční konfiguraci reprodukujte v druhém nástroji.

Připravte si přihlašovací údaje, zásilku a podrobnosti požadavku

Než otevřete některého z klientů, připravte si následující:

  • Autorizované přihlašovací údaje API: získejte je prostřednictvím nastavení svého účtu 17TRACK API. Spotřebitelská relace sledování nenahrazuje přihlašovací údaje API.
  • Skutečné sledovací číslo: použijte zásilku, kterou vlastníte nebo k níž máte oprávnění. Nedávno aktivní zásilka je při testování skutečných dat sledování obecně užitečnější než vymyšlené číslo.
  • Dopravce, pokud je znám: mějte název dopravce k dispozici pro diagnostiku. Pokud je pro váš případ vyžadován identifikátor dopravce, použijte hodnotu a pole definované v dokumentaci API, nikoli odhad.
  • Aktuální smlouvu požadavku: ověřte verzi API, autentizační hlavičku, schéma požadavku a případná omezení účtu.
  • Bezpečné pracovní prostředí: nevkládejte přihlašovací údaje, údaje zákazníků ani úplné odpovědi sledování do veřejných repozitářů, snímků obrazovky nebo sdílených zpráv podpory.

Minimální příklady požadavků používají tato nastavení:

NastaveníPříklad konfigurace
Základní URLhttps://api.17track.net/track/v2.2
Registrační operacePOST /register
Operace informací o sledováníPOST /gettrackinfo
Autentizační hlavička17token: YOUR_API_TOKEN
Formát tělaContent-Type: application/json, s JSON polem objektů zásilek

Sledovací čísla uchovávejte jako řetězce. Převod na číselný typ může odstranit počáteční nuly nebo jinak změnit jejich hodnotu. Zástupný symbol YOUR_TRACKING_NUMBER níže musí být nahrazen skutečnou testovací zásilkou; nejde o funkční ukázkové číslo.

Vytvořte registrační požadavek v Postmanu

1. Vytvořte malé testovací prostředí

V Postmanu vytvořte prostředí se třemi proměnnými: base_url, tracking_token a tracking_number. Nastavte base_url na výše uvedenou základní URL a do ostatních proměnných zadejte své přihlašovací údaje a číslo zásilky. Před odesláním požadavku toto prostředí vyberte.

Pro token použijte dostupné ovládací prvky Postmanu pro práci s tajnými údaji a zkontrolujte, co vaše pracovní prostředí sdílí nebo synchronizuje. Skrytí hodnoty v rozhraní nenahrazuje kontrolu nad tím, kdo k ní má přístup. Neexportujte vyplněné přihlašovací údaje s kolekcí určenou kolegům nebo veřejné dokumentaci.

2. Nakonfigurujte metodu, URL a hlavičky

Vytvořte požadavek HTTP, vyberte POST a jako URL zadejte {{base_url}}/register. Na kartě Headers přidejte:

17token: {{tracking_token}}
Content-Type: application/json

V tomto příkladu patří přihlašovací údaje do vlastní hlavičky 17token. Nenahrazujte ji konfigurací tokenu Bearer jen proto, že jiná API tento vzor používají. Zkontrolujte také, zda zděděná nastavení kolekce nepřidávají nechtěnou hlavičku Authorization.

3. Přidejte JSON tělo

Otevřete Body, vyberte raw a poté JSON. Zadejte:

[
  {
    "number": "{{tracking_number}}"
  }
]

Vnější hranaté závorky jsou důležité: tento požadavek používá pole, i když obsahuje pouze jednu zásilku. Použijte dvojité uvozovky, odstraňte koncové čárky a do JSON nevkládejte komentáře. Pokud dokumentace pro vašeho dopravce nebo zásilku vyžaduje další informace, před odesláním přidejte zdokumentovaná pole.

4. Odešlete požadavek a zkontrolujte výsledek

Klikněte na Send. Nejprve ověřte, zda jste vůbec obdrželi odpověď HTTP. Selhání DNS, chyba TLS, problém s proxy nebo vypršení časového limitu se liší od odpovědi vysvětlující, že požadavek byl neplatný. Poté zkontrolujte tělo odpovědi kvůli výsledku operace a informacím o přijetí nebo zamítnutí na úrovni zásilky.

Uložte požadavek jako „Register test shipment“. Zaznamenejte stav HTTP, výsledek API a případnou chybovou zprávu, ale nekopírujte token. Pokud registrace selže, vyřešte toto selhání, než budete pokračovat. Opakované odesílání nezměněného požadavku ztěžuje diagnostiku a může spotřebovávat prostředky účtu.

Reprodukujte požadavek pomocí curl

Následující příkazy používají shell ve stylu POSIX, například Bash nebo Zsh. PowerShell a Windows Command Prompt mají odlišná pravidla pro uvozovky a proměnné. V PowerShellu podle potřeby použijte curl.exe, abyste vyvolali spustitelný soubor curl namísto aliasu specifického pro shell.

Nastavte základní URL a načtěte své přihlašovací údaje do proměnné prostředí obvyklým způsobem pro práci s tajnými údaji:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Proměnná prostředí udržuje přihlašovací údaje mimo znovupoužitelný příklad, nejde však o úplný systém správy tajných údajů. Při lokálním testování se vyhněte zadávání skutečného tokenu do příkazu, který si shell ponechá v historii. Pro automatizaci použijte úložiště tajných údajů své platformy a omezte výstup do protokolů.

Vytvořte soubor s názvem shipment.json a nahraďte zástupný symbol testovacím sledovacím číslem:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Odešlete registrační požadavek:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Tím se tělo odpovědi uloží do register-response.json a stav HTTP se vypíše samostatně. Časové limity připojení a celkového času jsou volbou pro lokální testování, nikoli zárukou služby 17TRACK. Otevřete uložený soubor a zkontrolujte výsledek API; samotný řádek se stavem nestačí.

curl může úspěšně dokončit přenos, i když server vrátí chybovou odpověď HTTP. Naopak selhání přenosu může zabránit doručení použitelné odpovědi API. Při skriptování zpracovávejte návratový stav curl, stav HTTP a výsledek na úrovni aplikace jako oddělené signály.

Vyžádejte si informace o sledování zásilky

Po potvrzení registrace duplikujte požadavek v Postmanu a změňte URL na {{base_url}}/gettrackinfo. Zachovejte metodu POST, autentizační hlavičku, typ obsahu i tělo zásilky. Uložte jej samostatně, abyste při načítání dat omylem zásilku znovu nezaregistrovali.

Ekvivalentní požadavek curl je:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Nepředpokládejte, že nově zaregistrovaná zásilka okamžitě vrátí úplnou historii událostí. Dostupnost dat závisí na zásilce a zpracování službou. Pokud informace ještě nejsou dostupné, řiďte se zdokumentovanými pokyny pro načítání a aktualizaci, místo opakované registrace stejného čísla nebo příliš častého dotazování.

Čtěte odpověď ve třech vrstvách

  1. Přenos: připojil se klient a obdržel odpověď HTTP?
  2. Operace: přijalo API požadavek a uspěla jednotlivá zásilka?
  3. Informace o zásilce: identifikují vrácená data zamýšlený balík a co skutečně prokazuje jeho stav nebo historie událostí?

Pro nalezení polí stavu, dopravce a událostí použijte oficiální schéma odpovědi. Zachovejte rozdíl mezi normalizovaným stavem zásilky a původním popisem události dopravce. Úspěšné vyhledání není důkazem doručení a chybějící události nejsou důkazem ztráty zásilky.

Při ukládání časových razítek zachovejte dodané informace o časovém pásmu nebo posunu. Neřaďte nezpracované řetězce dat z různých formátů a nepředpokládejte, že představují správné chronologické pořadí. Rozlišujte také čas, kdy vaše aplikace záznam načetla, od času, kdy k události zásilky došlo.

Řešte problémy, aniž byste měnili vše najednou

  • Žádná odpověď: zkontrolujte název hostitele, přístup k síti, nastavení proxy, konfiguraci TLS a místní časový limit. Nevypínejte ověřování certifikátů jako běžnou opravu.
  • Selhání autentizace: ověřte, že token je aktivní, hlavička 17token je přítomná a vybrané prostředí Postmanu správně vyhodnocuje proměnnou. Zkontrolujte náhodné mezery.
  • Neplatný požadavek: ověřte verzi API, cestu operace, metodu POST, typ obsahu a strukturu JSON pole podle dokumentace.
  • Zásilka zamítnuta: přečtěte si chybu specifickou pro zásilku. Zkontrolujte číslo a případné požadované informace o dopravci, místo abyste každé zamítnutí považovali za problém s autentizací.
  • Žádné události sledování: potvrďte registraci a identitu zamýšlené zásilky. Ověřte, zda jsou potřeba informace o dopravci a zda jsou před opakováním dostupné aktualizace.
  • Postman funguje, ale curl selhává: porovnejte vyřešenou URL, skutečné hlavičky a bajty těla. Uvozování v shellu a nenastavené proměnné prostředí jsou častými místy, kde se požadavky rozcházejí.

Při každém testu změňte jednu proměnnou a veďte stručný záznam výsledku. Pokud kontrolujete konzoli Postmanu nebo používáte podrobný výstup curl, považujte jej za citlivý: hlavičky požadavku mohou odhalit přihlašovací údaje. Před sdílením diagnostiky začerňte tajné údaje a informace o zákaznících.

Vězte, kdy je návod dokončen

Smysluplný první integrační test jste dokončili, když oba klienti odesílají zamýšlený požadavek, registraci chápete, načtení vrací interpretovatelný výsledek a dokážete odlišit selhání API od zásilky bez nových informací. Shodné stavové kódy HTTP samy o sobě neprokazují, že se oba klienti chovali identicky.

Před přesunem pracovního postupu do aplikace uchovávejte přihlašovací údaje na serveru, ověřujte vstupy a používejte strukturované zpracování chyb. Pro svůj účet si prostudujte zdokumentované limity rychlosti, dávkové limity, pokyny k opakování a možnosti doručování aktualizací. Nepředpokládejte, že registraci lze po vypršení časového limitu bezpečně slepě opakovat: server mohl požadavek zpracovat, i když váš klient odpověď neobdržel.

Přidejte testy pro neplatné přihlašovací údaje, chybně formátovaný JSON, neplatné číslo zásilky, již zaregistrovanou zásilku, nedostupná data sledování a vypršení časového limitu sítě. Každý případ by měl vést k promyšlenému výsledku aplikace, nikoli k neošetřené výjimce nebo zavádějícímu stavu zobrazenému zákazníkovi.

Často kladené otázky

Mohu testovat bez skutečného sledovacího čísla?

S neplatnou hodnotou můžete otestovat některé chování validace požadavku, ale tím neověříte sledování zásilky. Chcete-li testovat skutečné události, použijte autorizovanou zásilku nebo zdokumentované testovací data, pokud je služba poskytuje. Nepředpokládejte, že libovolná ukázková čísla patří do sandboxu.

Proč odpověď HTTP 200 stále obsahuje selhání?

Stav HTTP a výsledky aplikace popisují různé vrstvy. Server může požadavek úspěšně přijmout a zpracovat, přesto oznámit, že jednotlivá zásilka byla zamítnuta. Čtěte tělo odpovědi a zdokumentovaný výsledek na úrovni zásilky, nikoli pouze stav HTTP.

Proč se k načtení informací o sledování používá POST?

Použijte metodu určenou smlouvou endpointu. Tento příklad načítání přijímá identifikátory zásilek v JSON těle požadavku prostřednictvím POST. Změna na GET jen proto, že operace čte data, nezachovává zdokumentovaný požadavek.

Mám vložit token API do JavaScriptu v prohlížeči?

Soukromé přihlašovací údaje API nevkládejte do veřejně doručovaného kódu frontendu. Směrujte požadavky přes autorizovaný backend, který chrání přihlašovací údaje, ověřuje vstupy a řídí, ke kterým informacím o zásilkách má každý uživatel přístup.

Potřebuji pro produkci Postman i curl?

Ne. Jsou to užitečné testovací a diagnostické nástroje. Vaše produkční aplikace může používat vhodného HTTP klienta. Uchovávejte anonymizovaný požadavek Postmanu nebo příkaz curl jako reprodukovatelnou referenci, bez aktivního tokenu a zbytečných údajů o zákaznících.

Zdroje