Ваш први захтев ка Tracking API-ју: упутство за Rest Client са Postman-ом и Curl-ом
Da biste poslali svoj prvi zahtev ka API-ju za praćenje, konfigurišite krajnju tačku, zaglavlje za autentifikaciju i JSON telo u REST klijentu, pošaljite zahtev i proverite HTTP status i telo odgovora. Ovaj vodič koristi 17TRACK Tracking API kako bi demonstrirao isti tok rada u Postman-u i curl-u: registrujte pošiljku, zatražite informacije o njenom praćenju i proverite da li je rezultat spreman za upotrebu u vašoj aplikaciji.

Cilj je mali, ponovljiv integracioni test, a ne postavljanje u produkciju. Biće vam potrebni API akreditiv i broj za praćenje čiju obradu imate pravo da izvršite. Komande u nastavku koriste obrazac krajnje tačke v2.2; pre njihovog pokretanja potvrdite verziju krajnje tačke i zahteve specifične za nalog u 17TRACK API dokumentaciji.
Razumevanje cilja vašeg prvog zahteva
Integracija praćenja pošiljke obuhvata dve odvojene stvari: obavestiti servis koju pošiljku treba pratiti i preuzeti informacije o praćenju povezane sa tom pošiljkom. U ovde prikazanom toku rada to su odvojeni zahtevi. Registracija ne znači da se paket već kreće, a uspešna registracija ne garantuje da će događaji prevoznika odmah biti dostupni.
Za prvi test koristite jednu pošiljku umesto grupe pošiljaka. Tako je lakše izdvojiti greške autentifikacije, nevažeće brojeve za praćenje i tumačenje odgovora. Prva korisna prekretnica nije samo „dobio sam HTTP 200“. Ona glasi: „API je prihvatio željenu operaciju i mogu da objasnim rezultat na nivou pošiljke.“
Postman pruža vizuelni interfejs za uređivanje zahteva i pregled odgovora. curl čini istu HTTP razmenu ponovljivom iz terminala. Nijedan od njih ne menja pravila autentifikacije API-ja, podatke o pošiljci niti ponašanje obrade. Koristite alat koji vam pomaže da jasnije istražite zahtev, a zatim ponovite funkcionalnu konfiguraciju u drugom alatu.
Pripremite akreditiv, pošiljku i detalje zahteva
Pre nego što otvorite bilo koji klijent, pripremite sledeće:
- Ovlašćeni API akreditiv: pribavite ga kroz podešavanje svog 17TRACK API naloga. Sesija za korisničko praćenje nije zamena za API akreditiv.
- Stvarni broj za praćenje: koristite pošiljku koja je vaša ili kojoj imate dozvolu da pristupite. Nedavno aktivna pošiljka je obično korisnija od izmišljenog broja pri testiranju stvarnih podataka o praćenju.
- Prevoznik, ako je poznat: imajte naziv prevoznika pri ruci radi dijagnostike. Ako je za vaš slučaj potreban identifikator prevoznika, koristite vrednost i polje definisane u API dokumentaciji, umesto da nagađate.
- Važeći ugovor zahteva: potvrdite verziju API-ja, zaglavlje za autentifikaciju, šemu zahteva i sva ograničenja naloga.
- Bezbedno radno okruženje: ne stavljajte akreditive, podatke korisnika ili potpune odgovore za praćenje u javne repozitorijume, snimke ekrana ili deljene poruke podršci.
Minimalni primeri zahteva koriste sledeća podešavanja:
| Podešavanje | Primer konfiguracije |
|---|---|
| Osnovni URL | https://api.17track.net/track/v2.2 |
| Operacija registracije | POST /register |
| Operacija informacija o praćenju | POST /gettrackinfo |
| Zaglavlje za autentifikaciju | 17token: YOUR_API_TOKEN |
| Format tela | Content-Type: application/json, sa JSON nizom objekata pošiljki |
Brojeve za praćenje čuvajte kao stringove. Pretvaranje u numerički tip može ukloniti početne nule ili na drugi način promeniti njihovu vrednost. Rezervisano mesto YOUR_TRACKING_NUMBER u nastavku mora biti zamenjeno stvarnom testnom pošiljkom; ono nije funkcionalan primer broja.
Pošaljite zahtev za registraciju u Postman-u
1. Kreirajte malo testno okruženje
U Postman-u kreirajte okruženje sa tri promenljive: base_url, tracking_token i tracking_number. Podesite base_url na prethodno navedeni osnovni URL, a u druge dve promenljive unesite akreditiv i broj pošiljke. Izaberite to okruženje pre slanja zahteva.
Koristite Postman kontrole za bezbedno rukovanje tajnama i proverite šta vaše radno okruženje deli ili sinhronizuje. Sakrivanje vrednosti u interfejsu nije zamena za kontrolu ko joj može pristupiti. Ne izvozite popunjene akreditive sa kolekcijom namenjenom kolegama ili javnoj dokumentaciji.
2. Konfigurišite metod, URL i zaglavlja
Kreirajte HTTP zahtev, izaberite POST i unesite {{base_url}}/register kao URL. Na kartici Headers dodajte:
17token: {{tracking_token}}
Content-Type: application/jsonU ovom primeru akreditiv pripada prilagođenom zaglavlju 17token. Nemojte ga zameniti konfiguracijom Bearer tokena samo zato što je neki drugi API koristio taj obrazac. Takođe proverite da li podešavanja nasleđene kolekcije uvode neželjeno Authorization zaglavlje.
3. Dodajte JSON telo
Otvorite Body, izaberite raw, a zatim JSON. Unesite:
[
{
"number": "{{tracking_number}}"
}
]Spoljašnje uglaste zagrade su važne: ovaj zahtev koristi niz, iako sadrži samo jednu pošiljku. Koristite dvostruke navodnike, uklonite zareze na kraju i ne stavljajte komentare u JSON. Ako dokumentacija zahteva dodatne informacije za vašeg prevoznika ili pošiljku, dodajte dokumentovana polja pre slanja.
4. Pošaljite zahtev i pregledajte rezultat
Izaberite Send. Najpre proverite da li ste uopšte dobili HTTP odgovor. DNS greška, TLS greška, problem sa proksi serverom ili istek vremena razlikuju se od odgovora koji objašnjava da je zahtev nevažeći. Zatim pregledajte telo odgovora radi rezultata operacije i informacija o prihvatanju ili odbijanju na nivou pošiljke.
Sačuvajte zahtev pod nazivom „Register test shipment“. Zabeležite HTTP status, rezultat API-ja i poruku o grešci, bez kopiranja tokena. Ako registracija ne uspe, rešite taj problem pre nego što nastavite. Ponovljeno slanje nepromenjenog zahteva otežava dijagnostiku i može trošiti resurse naloga.
Ponovite zahtev pomoću curl-a
Sledeće komande koriste POSIX školjku, kao što su Bash ili Zsh. PowerShell i Windows Command Prompt imaju drugačija pravila za navodnike i promenljive. U PowerShell-u po potrebi koristite curl.exe da biste pozvali izvršnu datoteku curl umesto pseudonima specifičnog za školjku.
Podesite osnovni URL i učitajte akreditiv u promenljivu okruženja kroz uobičajeni tok rada za rukovanje tajnama:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.Promenljiva okruženja drži akreditiv izvan primera koji se može ponovo koristiti, ali nije potpun sistem za upravljanje tajnama. Pri lokalnom testiranju izbegavajte unošenje stvarnog tokena u komandu koju će istorija školjke sačuvati. Za automatizaciju koristite skladište tajni svoje platforme i ograničite izlaz evidencije.
Kreirajte datoteku pod nazivom shipment.json i zamenite rezervisano mesto svojim testnim brojem za praćenje:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]Pošaljite zahtev za registraciju:
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'Ovo čuva telo odgovora u register-response.json i zasebno ispisuje HTTP status. Vremenska ograničenja veze i ukupnog trajanja predstavljaju lokalni izbor za testiranje, a ne garancije servisa 17TRACK. Otvorite sačuvanu datoteku da biste pregledali rezultat API-ja; sama statusna linija nije dovoljna.
curl može uspešno završiti prenos čak i kada server vrati HTTP odgovor sa greškom. Suprotno tome, neuspeh transporta može sprečiti prijem bilo kakvog upotrebljivog API odgovora. Pri pisanju skripti tretirajte izlazni status curl-a, HTTP status i rezultat na nivou aplikacije kao odvojene signale.
Zatražite informacije o praćenju pošiljke
Nakon potvrde registracije, duplirajte Postman zahtev i promenite URL u {{base_url}}/gettrackinfo. Zadržite POST metod, zaglavlje za autentifikaciju, tip sadržaja i telo pošiljke. Sačuvajte ga zasebno kako ne biste slučajno ponovo registrovali pošiljku kada nameravate da preuzmete podatke.
Ekvivalentan curl zahtev 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'Ne pretpostavljajte da će novoregistrovana pošiljka odmah vratiti potpunu istoriju događaja. Dostupnost podataka zavisi od pošiljke i obrade servisa. Ako informacije još nisu dostupne, pratite dokumentovane smernice za preuzimanje i ažuriranje, umesto da stalno registrujete isti broj ili pokrećete učestalo ispitivanje.
Čitajte odgovor na tri nivoa
- Transport: da li se klijent povezao i primio HTTP odgovor?
- Operacija: da li je API prihvatio zahtev i da li je pojedinačna pošiljka uspešna?
- Informacije o pošiljci: da li vraćeni podaci identifikuju željeni paket i šta njegov status ili istorija događaja zaista potvrđuju?
Koristite zvaničnu šemu odgovora da pronađete polja za status, prevoznika i događaje. Očuvajte razliku između normalizovanog statusa pošiljke i originalnog opisa događaja prevoznika. Uspešno preuzimanje nije dokaz isporuke, a nedostatak događaja nije dokaz da je paket izgubljen.
Pri čuvanju vremenskih oznaka zadržite dostavljene informacije o vremenskoj zoni ili pomaku. Izbegavajte sortiranje sirovih nizova datuma iz različitih formata uz pretpostavku da predstavljaju ispravan hronološki redosled. Takođe razlikujte vreme kada je vaša aplikacija preuzela zapis od vremena kada se događaj pošiljke desio.
Otklanjajte probleme bez menjanja svega odjednom
- Nema odgovora: proverite naziv hosta, pristup mreži, podešavanja proksi servera, TLS konfiguraciju i lokalno vremensko ograničenje. Nemojte rutinski onemogućavati proveru sertifikata.
- Neuspešna autentifikacija: potvrdite da je token aktivan, da je zaglavlje
17tokenprisutno i da izabrano Postman okruženje ispravno razrešava promenljivu. Proverite slučajne razmake. - Nevažeći zahtev: proverite verziju API-ja, putanju operacije, POST metod, tip sadržaja i strukturu JSON niza prema dokumentaciji.
- Pošiljka odbijena: pročitajte grešku specifičnu za pošiljku. Proverite broj i sve potrebne informacije o prevozniku, umesto da svako odbijanje tretirate kao problem autentifikacije.
- Nema događaja praćenja: potvrdite registraciju i identitet željene pošiljke. Proverite da li su potrebne informacije o prevozniku i da li su ažuriranja dostupna pre ponovnog pokušaja.
- Postman radi, ali curl ne radi: uporedite razrešeni URL, stvarna zaglavlja i bajtove tela. Navodnici u školjci i nedeklarisane promenljive okruženja česta su mesta na kojima se zahtevi razlikuju.
Menjajte jednu promenljivu po testu i vodite kratku evidenciju rezultata. Ako pregledate Postman konzolu ili koristite opširan izlaz curl-a, tretirajte izlaz kao osetljiv: zaglavlja zahteva mogu otkriti akreditive. Uklonite tajne i podatke korisnika pre deljenja dijagnostike.
Znajte kada je vodič završen
Smisleni prvi integracioni test završen je kada oba klijenta šalju željeni zahtev, kada je registracija jasna, kada preuzimanje vraća razumljiv rezultat i kada možete razlikovati grešku API-ja od pošiljke bez novih informacija. Podudarni HTTP statusi sami po sebi ne dokazuju da su se dva klijenta ponašala identično.
Pre premeštanja toka rada u aplikaciju čuvajte akreditive na serveru, proveravajte ulaze i koristite strukturirano rukovanje greškama. Pogledajte dokumentovana ograničenja brzine, ograničenja grupa, smernice za ponovne pokušaje i opcije dostavljanja ažuriranja za svoj nalog. Nemojte pretpostaviti da je bezbedno naslepo ponoviti registraciju nakon isteka vremena: server je možda obradio zahtev iako vaš klijent nije primio odgovor.
Dodajte testove za nevažeći akreditiv, neispravan JSON, nevažeći broj pošiljke, već registrovanu pošiljku, nedostupne podatke o praćenju i mrežni istek vremena. Svaki slučaj treba da dovede do namernog ishoda aplikacije, a ne do neobrađenog izuzetka ili obmanjujućeg statusa prikazanog korisniku.
Česta pitanja
Mogu li testirati bez stvarnog broja za praćenje?
Možete testirati određeno ponašanje validacije zahteva pomoću nevažeće vrednosti, ali to ne proverava praćenje pošiljke. Za testiranje stvarnih događaja koristite ovlašćenu pošiljku ili dokumentovani testni primer ako ga servis pruža. Nemojte pretpostaviti da proizvoljni primeri brojeva pripadaju sandbox okruženju.
Zašto HTTP 200 odgovor i dalje sadrži grešku?
HTTP status i rezultati aplikacije opisuju različite nivoe. Server može uspešno primiti i obraditi zahtev, a istovremeno prijaviti da je pojedinačna pošiljka odbijena. Čitajte telo odgovora i dokumentovani rezultat na nivou pošiljke, a ne samo HTTP status.
Zašto se POST koristi za preuzimanje informacija o praćenju?
Koristite metod naveden u ugovoru krajnje tačke. Ovaj primer preuzimanja prihvata identifikatore pošiljki u JSON telu zahteva putem POST-a. Promena u GET zato što operacija čita podatke ne čuva dokumentovani zahtev.
Da li treba da stavim API token u JavaScript pregledača?
Ne ugrađujte privatni API akreditiv u javno dostavljen frontend kod. Usmerite zahteve kroz ovlašćeni backend koji štiti akreditiv, proverava ulaze i kontroliše kojim informacijama o pošiljkama svaki korisnik može da pristupi.
Da li su mi za produkciju potrebni i Postman i curl?
Ne. Oni su korisni alati za testiranje i dijagnostiku. Vaša produkciona aplikacija može koristiti odgovarajući HTTP klijent. Čuvajte sanitizovani Postman zahtev ili curl komandu kao ponovljivu referencu, bez aktivnog tokena ili nepotrebnih podataka korisnika.
Izvori
- 17TRACK API documentation — referenca za autentifikaciju, ugovore krajnjih tačaka, polja zahteva, tumačenje odgovora i zahteve integracije.
- Postman documentation: Send API requests — konfiguracija zahteva i pregled odgovora.
- Postman documentation: Variables — konfiguracija zahteva zasnovana na promenljivama.
- curl manual — opcije komande za zaglavlja, tela zahteva, vremenska ograničenja, sačuvane odgovore i ispis HTTP statusa.


