Skip to main content
DomovBlogPríručkyVaša prvá požiadavka na Tracking API: návod na Rest Client s Postman a Curl

Vaša prvá požiadavka na Tracking API: návod na Rest Client s Postman a Curl

17TRACK

Ak chcete odoslať svoju prvú požiadavku na tracking API, nakonfigurujte koncový bod, autentifikačnú hlavičku a telo JSON v REST klientovi, odošlite požiadavku a skontrolujte stav HTTP aj telo odpovede. Tento návod používa Tracking API služby 17TRACK na demonstráciu rovnakého postupu v nástrojoch Postman a curl: zaregistrujte zásielku, vyžiadajte si informácie o jej sledovaní a skontrolujte, či je výsledok pripravený na použitie vo vašej aplikácii.

Prvá požiadavka na Tracking API: postup v REST klientovi

Cieľom je malý, reprodukovateľný integračný test, nie nasadenie do produkcie. Budete potrebovať poverenie API a číslo zásielky, ktoré máte oprávnenie spracovať. Príkazy nižšie používajú vzor koncového bodu v2.2; pred ich spustením si v dokumentácii API 17TRACK overte verziu koncového bodu a požiadavky špecifické pre účet.

Pochopte, čo má vaša prvá požiadavka dosiahnuť

Integrácia sledovania zásielok zahŕňa dve samostatné úlohy: oznámiť službe, ktorú zásielku má sledovať, a načítať informácie o sledovaní spojené s touto zásielkou. V postupe uvedenom tu ide o samostatné požiadavky. Registrácia neznamená, že sa balík už pohol, a úspešná registrácia nezaručuje, že udalosti od prepravcu budú okamžite dostupné.

Pri prvom teste použite jednu zásielku namiesto dávky. Takto sa ľahšie izolujú chyby autentifikácie, neplatné čísla zásielok a interpretácia odpovede. Prvým užitočným míľnikom nie je jednoducho „dostal som HTTP 200“. Je ním „API prijalo zamýšľanú operáciu a dokážem vysvetliť výsledok na úrovni zásielky“.

Postman poskytuje vizuálne rozhranie na úpravu požiadaviek a kontrolu odpovedí. curl umožňuje reprodukovať rovnakú výmenu HTTP z terminálu. Ani jeden z nich nemení pravidlá autentifikácie API, údaje o zásielke ani správanie spracovania. Použite nástroj, ktorý vám pomôže požiadavku jasnejšie preskúmať, a potom funkčnú konfiguráciu zopakujte v druhom nástroji.

Pripravte poverenie, zásielku a podrobnosti požiadavky

Pred otvorením ktoréhokoľvek klienta si pripravte:

  • Autorizované poverenie API: získajte ho prostredníctvom nastavenia svojho účtu 17TRACK API. Spotrebiteľská relácia sledovania nie je náhradou za poverenie API.
  • Skutočné číslo zásielky: použite zásielku, ktorú vlastníte alebo ku ktorej máte povolený prístup. Nedávno aktívna zásielka je pri testovaní skutočných údajov o sledovaní spravidla užitočnejšia než vymyslené číslo.
  • Prepravcu, ak je známy: majte jeho názov k dispozícii na diagnostiku. Ak váš prípad vyžaduje identifikátor prepravcu, použite hodnotu a pole definované v dokumentácii API, nie odhad.
  • Aktuálnu zmluvu požiadavky: overte verziu API, autentifikačnú hlavičku, schému požiadavky a prípadné obmedzenia účtu.
  • Bezpečné pracovné prostredie: nevkladajte poverenia, údaje zákazníkov ani úplné odpovede sledovania do verejných repozitárov, snímok obrazovky alebo zdieľaných správ podpory.

Minimálne príklady požiadaviek používajú tieto nastavenia:

NastaveniePríklad konfigurácie
Základná URLhttps://api.17track.net/track/v2.2
Operácia registráciePOST /register
Operácia informácií o sledovaníPOST /gettrackinfo
Autentifikačná hlavička17token: YOUR_API_TOKEN
Formát telaContent-Type: application/json, s poľom JSON objektov zásielok

Čísla zásielok uchovávajte ako reťazce. Prevod na číselný typ môže odstrániť úvodné nuly alebo inak zmeniť ich hodnotu. Zástupný text YOUR_TRACKING_NUMBER nižšie musíte nahradiť skutočnou testovacou zásielkou; nejde o funkčné vzorové číslo.

Vytvorenie požiadavky na registráciu v Postmane

1. Vytvorte malé testovacie prostredie

V Postmane vytvorte prostredie s tromi premennými: base_url, tracking_token a tracking_number. Nastavte base_url na vyššie uvedenú základnú URL a do ostatných premenných zadajte svoje poverenie a číslo zásielky. Pred odoslaním požiadavky vyberte toto prostredie.

Na token použite dostupné ovládacie prvky Postmana na bezpečné spracovanie tajných údajov a skontrolujte, čo vaše pracovné prostredie zdieľa alebo synchronizuje. Skrytie hodnoty v rozhraní nenahrádza kontrolu nad tým, kto k nej môže pristupovať. Neexportujte vyplnené poverenia s kolekciou určenou kolegom alebo verejnej dokumentácii.

2. Nakonfigurujte metódu, URL a hlavičky

Vytvorte HTTP požiadavku, vyberte POST a ako URL zadajte {{base_url}}/register. Na karte Headers pridajte:

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

V tomto príklade patrí poverenie do vlastnej hlavičky 17token. Nenahrádzajte ju konfiguráciou tokenu Bearer len preto, že iné API používalo tento vzor. Skontrolujte tiež, či zdedené nastavenia kolekcie nepridávajú neúmyselnú hlavičku Authorization.

3. Pridajte telo JSON

Otvorte Body, vyberte raw a potom JSON. Zadajte:

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

Vonkajšie hranaté zátvorky sú dôležité: táto požiadavka používa pole, hoci obsahuje iba jednu zásielku. Použite dvojité úvodzovky, odstráňte koncové čiarky a do JSON nevkladajte komentáre. Ak dokumentácia vyžaduje pre vášho prepravcu alebo zásielku ďalšie informácie, pred odoslaním pridajte zdokumentované polia.

4. Odošlite požiadavku a skontrolujte výsledok

Kliknite na Send. Najprv skontrolujte, či ste vôbec dostali odpoveď HTTP. Zlyhanie DNS, chyba TLS, problém s proxy alebo časový limit sa líšia od odpovede vysvetľujúcej, že požiadavka bola neplatná. Potom skontrolujte telo odpovede, výsledok operácie a prípadné informácie o prijatí alebo odmietnutí na úrovni zásielky.

Uložte požiadavku ako „Register test shipment“. Zaznamenajte stav HTTP, výsledok API a prípadnú chybovú správu bez kopírovania tokenu. Ak registrácia zlyhá, vyriešte toto zlyhanie pred pokračovaním. Opakované odosielanie nezmenenej požiadavky sťažuje diagnostiku a môže spotrebovať zdroje účtu.

Zopakujte požiadavku pomocou curl

Nasledujúce príkazy používajú shell v štýle POSIX, napríklad Bash alebo Zsh. PowerShell a Windows Command Prompt majú odlišné pravidlá úvodzoviek a premenných. V PowerShelli v prípade potreby použite curl.exe, aby ste vyvolali spustiteľný súbor curl namiesto aliasu špecifického pre shell.

Nastavte základnú URL a načítajte poverenie do premennej prostredia podľa svojho bežného pracovného postupu na spracovanie tajných údajov:

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

Premenná prostredia udrží poverenie mimo opakovane použiteľného príkladu, nejde však o úplný systém správy tajných údajov. Pri lokálnom testovaní nevpisujte skutočný token do príkazu, ktorý si shell uchová v histórii. Pri automatizácii použite úložisko tajných údajov svojej platformy a obmedzte výstup do protokolov.

Vytvorte súbor s názvom shipment.json a nahraďte zástupný text testovacím číslom zásielky:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Odošlite požiadavku na registráciu:

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ýmto sa telo odpovede uloží do súboru register-response.json a stav HTTP sa vypíše samostatne. Časové limity pripojenia a celkového času sú voľbou pre lokálne testovanie, nie zárukou služby 17TRACK. Otvorte uložený súbor a skontrolujte výsledok API; samotný riadok so stavom nestačí.

curl môže úspešne dokončiť prenos aj vtedy, keď server vráti odpoveď HTTP s chybou. Naopak, zlyhanie prenosu môže zabrániť prijatiu použiteľnej odpovede API. Pri skriptovaní spracúvajte návratový stav curl, stav HTTP a výsledok na úrovni aplikácie ako samostatné signály.

Vyžiadajte si informácie o sledovaní zásielky

Po potvrdení registrácie duplikujte požiadavku v Postmane a zmeňte URL na {{base_url}}/gettrackinfo. Zachovajte metódu POST, autentifikačnú hlavičku, typ obsahu a telo zásielky. Uložte ju samostatne, aby ste omylom znova nezaregistrovali zásielku v čase, keď chcete načítať údaje.

Ekvivalentná požiadavka 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'

Nepredpokladajte, že novo zaregistrovaná zásielka okamžite vráti úplnú históriu udalostí. Dostupnosť údajov závisí od zásielky a spracovania službou. Ak informácie ešte nie sú dostupné, postupujte podľa zdokumentovaných pokynov na načítanie a aktualizáciu namiesto opakovaného registrovania rovnakého čísla alebo spúšťania príliš častého cyklu dotazovania.

Čítajte odpoveď v troch vrstvách

  1. Transport: pripojil sa klient a prijal odpoveď HTTP?
  2. Operácia: prijalo API požiadavku a bola jednotlivá zásielka úspešná?
  3. Informácie o zásielke: identifikujú vrátené údaje zamýšľaný balík a čo skutočne potvrdzuje jeho stav alebo história udalostí?

Na vyhľadanie polí stavu, prepravcu a udalostí použite oficiálnu schému odpovede. Zachovajte rozdiel medzi normalizovaným stavom zásielky a pôvodným opisom udalosti od prepravcu. Úspešné vyhľadanie nie je dôkazom doručenia a chýbajúce udalosti nie sú dôkazom straty balíka.

Pri ukladaní časových pečiatok zachovajte dodané informácie o časovom pásme alebo posune. Neusporadúvajte nespracované dátumové reťazce z rôznych formátov s predpokladom, že predstavujú správne chronologické poradie. Rozlišujte tiež čas, keď vaša aplikácia načítala záznam, od času, keď nastala udalosť zásielky.

Riešte problémy bez zmeny všetkého naraz

  • Žiadna odpoveď: skontrolujte názov hostiteľa, sieťový prístup, nastavenia proxy, konfiguráciu TLS a lokálny časový limit. Bežne nevypínajte overovanie certifikátov ako riešenie.
  • Zlyhanie autentifikácie: overte, či je token aktívny, či je prítomná hlavička 17token a či vybrané prostredie Postmana správne vyhodnocuje premennú. Skontrolujte neúmyselné medzery.
  • Neplatná požiadavka: overte verziu API, cestu operácie, metódu POST, typ obsahu a štruktúru poľa JSON podľa dokumentácie.
  • Odmietnutá zásielka: prečítajte chybu špecifickú pre zásielku. Skontrolujte číslo a prípadné požadované informácie o prepravcovi namiesto toho, aby ste každé odmietnutie považovali za problém autentifikácie.
  • Žiadne udalosti sledovania: potvrďte registráciu a identitu zamýšľanej zásielky. Overte, či sú potrebné informácie o prepravcovi a či sú aktualizácie dostupné, než požiadavku zopakujete.
  • Postman funguje, ale curl zlyháva: porovnajte výslednú URL, skutočné hlavičky a bajty tela. Úvodzovky shellu a nenastavené premenné prostredia sú časté miesta rozdielov medzi požiadavkami.

Pri každom teste zmeňte jednu premennú a veďte si krátky záznam výsledku. Ak kontrolujete konzolu Postmana alebo používate podrobný výstup curl, považujte ho za citlivý: hlavičky požiadaviek môžu odhaliť poverenia. Pred zdieľaním diagnostiky odstráňte tajné údaje a informácie o zákazníkoch.

Vedzte, kedy je postup dokončený

Zmysluplný prvý integračný test ste dokončili vtedy, keď oba klienty odošlú zamýšľanú požiadavku, registrácii rozumiete, načítanie vráti interpretovateľný výsledok a dokážete rozlíšiť zlyhanie API od zásielky bez nových informácií. Rovnaké kódy stavu HTTP samy osebe nepotvrdzujú, že sa oba klienty správali identicky.

Pred presunutím postupu do aplikácie uchovávajte poverenia na serveri, overujte vstupy a používajte štruktúrované spracovanie chýb. Oboznámte sa so zdokumentovanými limitmi frekvencie, dávok, opakovaní a možnosťami doručovania aktualizácií pre svoj účet. Nepredpokladajte, že po časovom limite je bezpečné registráciu slepo zopakovať: server mohol požiadavku spracovať, aj keď klient nedostal odpoveď.

Pridajte testy pre neplatné poverenie, nesprávne vytvorený JSON, neplatné číslo zásielky, už zaregistrovanú zásielku, nedostupné údaje sledovania a sieťový časový limit. Každý prípad by mal viesť k zámernému výsledku aplikácie, nie k nespracovanej výnimke alebo zavádzajúcemu stavu zobrazovanému zákazníkovi.

Často kladené otázky

Môžem testovať bez skutočného čísla zásielky?

Pomocou neplatnej hodnoty môžete otestovať niektoré správanie overovania požiadavky, neoverí to však sledovanie zásielky. Ak chcete testovať skutočné udalosti, použite autorizovanú zásielku alebo zdokumentované testovacie dáta, ak ich služba poskytuje. Nepredpokladajte, že ľubovoľné vzorové čísla patria do sandboxu.

Prečo odpoveď HTTP 200 stále obsahuje zlyhanie?

Stav HTTP a výsledky aplikácie opisujú rôzne vrstvy. Server môže požiadavku úspešne prijať a spracovať, pričom oznámi, že jednotlivá zásielka bola odmietnutá. Čítajte telo odpovede a zdokumentovaný výsledok na úrovni zásielky, nielen stav HTTP.

Prečo sa na načítanie informácií o sledovaní používa POST?

Použite metódu určenú zmluvou koncového bodu. Tento príklad načítania prijíma identifikátory zásielok v tele požiadavky JSON prostredníctvom POST. Zmena na GET len preto, že operácia číta údaje, nezachováva zdokumentovanú požiadavku.

Mám vložiť token API do JavaScriptu v prehliadači?

Nevkladajte súkromné poverenie API do verejne doručovaného kódu frontendu. Požiadavky smerujte cez autorizovaný backend, ktorý chráni poverenie, overuje vstupy a riadi, ku ktorým informáciám o zásielkach môže každý používateľ pristupovať.

Potrebujem v produkcii Postman aj curl?

Nie. Ide o užitočné testovacie a diagnostické nástroje. Vaša produkčná aplikácia môže používať vhodného HTTP klienta. Uchovajte si očistenú požiadavku Postmana alebo príkaz curl ako reprodukovateľnú referenciu bez aktívneho tokenu a nepotrebných údajov zákazníkov.

Zdroje