Vaša prva zahteva za Tracking API: vodič po odjemalcu REST s Postman in Curl
Če želite poslati svojo prvo zahtevo za API za sledenje, v odjemalcu REST nastavite končno točko, glavo za preverjanje pristnosti in telo JSON, pošljite zahtevo ter preverite tako stanje HTTP kot telo odgovora. Ta vodič uporablja API za sledenje 17TRACK, da v Postmanu in curlu prikaže enak potek dela: registracijo pošiljke, zahtevo za podatke o sledenju in preverjanje, ali je rezultat pripravljen za uporabo v vaši aplikaciji.
Cilj je majhen, ponovljiv integracijski preizkus, ne uvedba v produkcijo. Potrebujete poverilnico API in številko za sledenje, za obdelavo katere imate dovoljenje. Spodnji ukazi uporabljajo vzorec končne točke v2.2; pred zagonom preverite različico končne točke in zahteve, specifične za račun, v dokumentaciji API 17TRACK.
Razumevanje cilja vaše prve zahteve
Integracija sledenja pošiljk vključuje dve ločeni nalogi: storitvi sporočiti, kateri pošiljki naj sledi, in pridobiti podatke o sledenju, povezane s to pošiljko. V tukaj prikazanem poteku sta to ločeni zahtevi. Registracija ne pomeni, da se je paket že premaknil, uspešna registracija pa ne zagotavlja, da bodo dogodki prevoznika takoj na voljo.
Za prvi preizkus uporabite eno pošiljko namesto serije pošiljk. Tako boste lažje ločili napake pri preverjanju pristnosti, neveljavne številke za sledenje in razlago odgovorov. Prvi uporaben mejnik ni zgolj »prejel sem HTTP 200«. To je: »API je sprejel načrtovano operacijo in lahko razložim rezultat na ravni pošiljke.«
Postman ponuja vizualni vmesnik za urejanje zahtev in pregledovanje odgovorov. curl omogoča ponovljivost iste izmenjave HTTP iz terminala. Nobeno od orodij ne spreminja pravil preverjanja pristnosti API-ja, podatkov o pošiljki ali načina obdelave. Uporabite tisto, ki vam pomaga jasneje raziskati zahtevo, nato pa delujočo konfiguracijo ponovite v drugem orodju.
Pripravite poverilnico, pošiljko in podrobnosti zahteve
Preden odprete katerega od odjemalcev, zberite naslednje:
- Pooblaščena poverilnica API: pridobite jo z nastavitvijo računa API 17TRACK. Potrošniška seja za sledenje ni nadomestilo za poverilnico API.
- Resnična številka za sledenje: uporabite pošiljko, ki je vaša ali do katere imate dovoljen dostop. Nedavno aktivna pošiljka je pri preizkušanju dejanskih podatkov o sledenju običajno uporabnejša od izmišljene številke.
- Prevoznik, če je znan: ime prevoznika imejte pri roki za diagnosticiranje. Če je za vaš primer potreben identifikator prevoznika, uporabite vrednost in polje, določena v dokumentaciji API, namesto ugibanja.
- Trenutna specifikacija zahteve: preverite različico API-ja, glavo za preverjanje pristnosti, shemo zahteve in morebitne omejitve računa.
- Varno delovno okolje: poverilnic, podatkov strank ali popolnih odgovorov sledenja ne objavljajte v javnih repozitorijih, posnetkih zaslona ali skupnih sporočilih podpori.
Minimalni primeri zahtev uporabljajo te nastavitve:
| Nastavitev | Primer konfiguracije |
|---|---|
| Osnovni URL | https://api.17track.net/track/v2.2 |
| Operacija registracije | POST /register |
| Operacija podatkov o sledenju | POST /gettrackinfo |
| Glava za preverjanje pristnosti | 17token: YOUR_API_TOKEN |
| Oblika telesa | Content-Type: application/json z matriko JSON objektov pošiljk |
Številke za sledenje hranite kot nize. Pretvorba v številski tip lahko odstrani začetne ničle ali kako drugače spremeni vrednost. Nadomestni znak YOUR_TRACKING_NUMBER spodaj morate zamenjati z dejansko testno pošiljko; ne gre za delujočo vzorčno številko.
Pošljite zahtevo za registracijo v Postmanu
1. Ustvarite majhno testno okolje
V Postmanu ustvarite okolje s tremi spremenljivkami: base_url, tracking_token in tracking_number. base_url nastavite na zgornji osnovni URL, v drugi spremenljivki pa vnesite poverilnico in številko pošiljke. Pred pošiljanjem zahteve izberite to okolje.
Za žeton uporabite razpoložljive kontrole Postmana za upravljanje skrivnosti ter preverite, kaj vaše delovno okolje deli ali sinhronizira. Skriva vrednosti v vmesniku ni nadomestilo za nadzor nad tem, kdo lahko do njih dostopa. Ne izvažajte izpolnjenih poverilnic z zbirko, namenjeno sodelavcem ali javni dokumentaciji.
2. Nastavite metodo, URL in glave
Ustvarite zahtevo HTTP, izberite POST in kot URL vnesite {{base_url}}/register. Na zavihku Headers dodajte:
17token: {{tracking_token}}
Content-Type: application/json
V tem primeru poverilnica spada v glavo po meri 17token. Ne zamenjajte je s konfiguracijo žetona Bearer samo zato, ker je drug API uporabljal ta vzorec. Preverite tudi, ali podedovane nastavitve zbirke uvajajo nenamerno glavo Authorization.
3. Dodajte telo JSON
Odprite Body, izberite raw in nato JSON. Vnesite:
[
{
"number": "{{tracking_number}}"
}
]
Zunanji oglat oklepaj je pomemben: ta zahteva uporablja matriko, čeprav vsebuje samo eno pošiljko. Uporabite dvojne narekovaje, odstranite končne vejice in iz JSON-a odstranite komentarje. Če dokumentacija za vašega prevoznika ali pošiljko zahteva dodatne informacije, pred pošiljanjem dodajte dokumentirana polja.
4. Pošljite zahtevo in preglejte rezultat
Kliknite Send. Najprej preverite, ali ste sploh prejeli odgovor HTTP. Napaka DNS, napaka TLS, težava s posredniškim strežnikom ali časovna omejitev se razlikujejo od odgovora, ki pojasnjuje, da je bila zahteva neveljavna. Nato v telesu odgovora preverite rezultat operacije ter morebitne informacije o sprejetju ali zavrnitvi na ravni pošiljke.
Zahtevo shranite kot »Register test shipment«. Zabeležite stanje HTTP, rezultat API-ja in morebitno sporočilo o napaki, ne da bi kopirali žeton. Če registracija ne uspe, napako odpravite, preden nadaljujete. Večkratno pošiljanje nespremenjene zahteve oteži diagnosticiranje in lahko porablja vire računa.
Ponovite zahtevo s curlom
Naslednji ukazi uporabljajo lupino v slogu POSIX, kot sta Bash ali Zsh. PowerShell in ukazni poziv Windows imata drugačna pravila za narekovaje in spremenljivke. V PowerShellu po potrebi uporabite curl.exe, da prikličete izvedljivo datoteko curl namesto vzdevka ukaza, značilnega za lupino.
Nastavite osnovni URL in naložite poverilnico v okoljsko spremenljivko po običajnem postopku za upravljanje skrivnosti:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.
Okoljska spremenljivka ohrani poverilnico zunaj primera, ki ga je mogoče ponovno uporabiti, vendar ni popoln sistem za upravljanje skrivnosti. Pri lokalnem testiranju se izogibajte vnosu pravega žetona v ukaz, ki ga bo shranila zgodovina lupine. Za avtomatizacijo uporabite shrambo skrivnosti svoje platforme in omejite izpis dnevnikov.
Ustvarite datoteko z imenom shipment.json in nadomestni znak zamenjajte s testno številko za sledenje:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]
Pošljite zahtevo za registracijo:
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'
S tem se telo odgovora shrani v register-response.json, stanje HTTP pa se izpiše ločeno. Časovni omejitvi povezave in celotnega postopka sta izbiri za lokalno testiranje, ne zagotovili storitve 17TRACK. Odprite shranjeno datoteko in preglejte rezultat API-ja; samo vrstica s stanjem ni dovolj.
curl lahko uspešno zaključi prenos, tudi če strežnik vrne odgovor HTTP z napako. Nasprotno lahko napaka pri prenosu prepreči prejem uporabnega odgovora API-ja. Pri skriptah obravnavajte izhodno stanje curla, stanje HTTP in rezultat na ravni aplikacije kot ločene signale.
Zahtevajte podatke o sledenju pošiljke
Ko potrdite registracijo, podvojite zahtevo v Postmanu in spremenite URL v {{base_url}}/gettrackinfo. Ohranite metodo POST, glavo za preverjanje pristnosti, vrsto vsebine in telo pošiljke. Shranite jo ločeno, da pošiljke po pomoti ne boste znova registrirali, ko nameravate pridobiti podatke.
Enakovredna zahteva 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'
Ne predvidevajte, da bo na novo registrirana pošiljka takoj vrnila popolno zgodovino dogodkov. Razpoložljivost podatkov je odvisna od pošiljke in obdelave storitve. Če podatki še niso na voljo, upoštevajte dokumentirana navodila za pridobivanje in posodabljanje, namesto da bi isto številko večkrat registrirali ali izvajali tesno zanko preverjanja.
Odgovor preberite v treh plasteh
- Prenos: ali se je odjemalec povezal in prejel odgovor HTTP?
- Operacija: ali je API sprejel zahtevo in ali je bila posamezna pošiljka uspešna?
- Podatki o pošiljki: ali vrnjeni podatki identificirajo želeni paket in kaj njegov status ali zgodovina dogodkov dejansko potrjuje?
Za iskanje polj statusa, prevoznika in dogodkov uporabite uradno shemo odgovorov. Razlikujte med normaliziranim statusom pošiljke in izvirnim opisom dogodka prevoznika. Uspešno iskanje ni dokaz dostave, manjkajoči dogodki pa niso dokaz, da je paket izgubljen.
Pri shranjevanju časovnih žigov ohranite podane podatke o časovnem pasu ali odmiku. Izogibajte se razvrščanju surovih datumskih nizov različnih oblik in predpostavki, da predstavljajo pravilno kronološko zaporedje. Razlikujte tudi med časom, ko je vaša aplikacija pridobila zapis, in časom, ko se je zgodil dogodek pošiljke.
Odpravljanje težav brez spreminjanja vsega hkrati
- Brez odgovora: preverite gostiteljsko ime, omrežni dostop, nastavitve posredniškega strežnika, konfiguracijo TLS in lokalno časovno omejitev. Preverjanja potrdil ne izklapljajte kot običajno rešitev.
- Napaka pri preverjanju pristnosti: preverite, ali je žeton aktiven, ali je prisotna glava
17tokenin ali izbrano okolje Postmana pravilno razreši spremenljivko. Preverite nenamerne presledke. - Neveljavna zahteva: glede na dokumentacijo preverite različico API-ja, pot operacije, metodo POST, vrsto vsebine in strukturo matrike JSON.
- Pošiljka zavrnjena: preberite napako, značilno za pošiljko. Preverite številko in zahtevane podatke o prevozniku, namesto da bi vsako zavrnitev obravnavali kot težavo s preverjanjem pristnosti.
- Ni dogodkov sledenja: potrdite registracijo in identiteto želene pošiljke. Preverite, ali so potrebni podatki o prevozniku in ali so posodobitve na voljo, preden poskusite znova.
- Postman deluje, curl pa ne: primerjajte razrešen URL, dejanske glave in bajte telesa. Narekovaji lupine in nenastavljene okoljske spremenljivke so pogosti razlogi za razlikovanje zahtev.
Pri vsakem preizkusu spremenite eno spremenljivko in vodite kratek zapis rezultata. Če pregledate konzolo Postmana ali uporabite podroben izpis curla, ga obravnavajte kot občutljivega: glave zahtev lahko razkrijejo poverilnice. Pred deljenjem diagnostike prekrijte skrivnosti in podatke strank.
Vedite, kdaj je vodič končan
Pomemben prvi integracijski preizkus ste opravili, ko oba odjemalca pošljeta načrtovano zahtevo, razumete registracijo, pridobivanje vrne razložljiv rezultat in lahko razlikujete med napako API-ja ter pošiljko brez novih informacij. Samo ujemajoče se kode stanja HTTP ne dokazujejo, da sta se odjemalca obnašala enako.
Pred prenosom poteka dela v aplikacijo hranite poverilnice v strežniku, preverjajte vnose in uporabite strukturirano obravnavo napak. Za svoj račun preverite dokumentirane omejitve hitrosti, omejitve serij, navodila za ponovne poskuse in možnosti dostave posodobitev. Ne predvidevajte, da je registracijo po časovni omejitvi varno slepo ponoviti: strežnik je zahtevo morda že obdelal, čeprav odjemalec ni prejel odgovora.
Dodajte teste za neveljavno poverilnico, napačno oblikovan JSON, neveljavno številko pošiljke, že registrirano pošiljko, nerazpoložljive podatke o sledenju in časovno omejitev omrežja. Vsak primer mora voditi do premišljenega rezultata aplikacije, ne do neobravnavane izjeme ali zavajajočega statusa, prikazanega stranki.
Pogosta vprašanja
Ali lahko testiram brez resnične številke za sledenje?
Z neveljavno vrednostjo lahko preizkusite nekaj vedenja preverjanja zahtev, vendar s tem ne preverite sledenja pošiljki. Za preizkus resničnih dogodkov uporabite pooblaščeno pošiljko ali dokumentirano testno pripravo, če jo storitev ponuja. Ne predvidevajte, da poljubne vzorčne številke pripadajo peskovniku.
Zakaj odgovor HTTP 200 še vedno vsebuje napako?
Stanje HTTP in rezultati aplikacije opisujejo različni plasti. Strežnik lahko zahtevo uspešno prejme in obdela, hkrati pa sporoči, da je bila posamezna pošiljka zavrnjena. Preberite telo odgovora in dokumentirani rezultat na ravni pošiljke, ne le stanja HTTP.
Zakaj se za pridobivanje podatkov o sledenju uporablja POST?
Uporabite metodo, določeno v pogodbi končne točke. Ta primer pridobivanja sprejema identifikatorje pošiljk v telesu zahteve JSON prek POST. Če jo spremenite v GET samo zato, ker operacija bere podatke, dokumentirana zahteva ne bo ohranjena.
Ali naj žeton API vstavim v JavaScript brskalnika?
Zasebne poverilnice API ne vstavljajte v javno dostavljeno kodo odjemalca. Zahteve usmerite prek pooblaščenega zaledja, ki varuje poverilnico, preverja vnose in nadzoruje, do katerih podatkov o pošiljkah lahko dostopa posamezen uporabnik.
Ali za produkcijo potrebujem tako Postman kot curl?
Ne. Uporabna sta za testiranje in diagnosticiranje. Produkcijska aplikacija lahko uporablja ustrezen odjemalec HTTP. Ohranite razčiščeno zahtevo Postman ali ukaz curl kot ponovljiv vir, brez aktivnega žetona ali nepotrebnih podatkov strank.
Viri
- Dokumentacija API 17TRACK — vir za preverjanje pristnosti, pogodbe končnih točk, polja zahtev, razlago odgovorov in zahteve za integracijo.
- Dokumentacija Postman: Pošiljanje zahtev API — konfiguracija zahtev in pregledovanje odgovorov.
- Dokumentacija Postman: Spremenljivke — konfiguracija zahtev na podlagi spremenljivk.
- Priročnik curl — možnosti ukazov za glave, telesa zahtev, časovne omejitve, shranjene odgovore in izpis stanja HTTP.


