Prima dvs. solicitare către Tracking API: ghid pentru Rest Client cu Postman și Curl
Pentru a efectua prima solicitare către API-ul de tracking, configurați endpointul, antetul de autentificare și corpul JSON într-un client REST, trimiteți solicitarea și verificați atât starea HTTP, cât și corpul răspunsului. Acest ghid utilizează Tracking API de la 17TRACK pentru a demonstra același flux de lucru în Postman și curl: înregistrați o expediere, solicitați informațiile de tracking și verificați dacă rezultatul este pregătit pentru a fi utilizat de aplicația dvs.

Scopul este un test de integrare mic și reproductibil, nu o implementare în producție. Veți avea nevoie de o acreditare API și de un număr de tracking pe care sunteți autorizat să îl procesați. Comenzile de mai jos utilizează modelul de endpoint v2.2; confirmați versiunea endpointului și cerințele specifice contului în documentația API 17TRACK înainte de a le rula.
Înțelegeți ce ar trebui să realizeze prima dvs. solicitare
O integrare pentru trackingul expedierilor are două aspecte distincte: indicarea expedierii care trebuie urmărită și preluarea informațiilor de tracking asociate acesteia. În fluxul de lucru demonstrat aici, acestea sunt solicitări separate. Înregistrarea nu înseamnă că pachetul s-a deplasat deja, iar o înregistrare reușită nu garantează că evenimentele transportatorului vor fi disponibile imediat.
Pentru primul test, utilizați o singură expediere, nu un lot. Astfel, erorile de autentificare, numerele de tracking invalide și interpretarea răspunsului pot fi izolate mai ușor. Primul reper util nu este pur și simplu „am primit HTTP 200”. Este „API-ul a acceptat operațiunea intenționată, iar eu pot explica rezultatul la nivelul expedierii”.
Postman vă oferă o interfață vizuală pentru editarea solicitărilor și inspectarea răspunsurilor. curl face același schimb HTTP reproductibil dintr-un terminal. Niciunul nu modifică regulile de autentificare ale API-ului, datele expedierii sau comportamentul de procesare. Utilizați instrumentul care vă ajută să investigați mai clar solicitarea, apoi reproduceți configurația funcțională în celălalt instrument.
Pregătiți acreditarea, expedierea și detaliile solicitării
Înainte de a deschide oricare dintre clienți, pregătiți următoarele:
- O acreditare API autorizată: obțineți-o prin configurarea contului dvs. API 17TRACK. O sesiune de tracking pentru consumatori nu înlocuiește o acreditare API.
- Un număr real de tracking: utilizați o expediere pe care o dețineți sau pe care aveți permisiunea să o accesați. O expediere activă recent este, în general, mai utilă decât un număr inventat atunci când testați date reale de tracking.
- Transportatorul, dacă este cunoscut: păstrați numele transportatorului disponibil pentru diagnosticare. Dacă pentru cazul dvs. este necesar un identificator al transportatorului, utilizați valoarea și câmpul definite în documentația API, nu ghiciți.
- Contractul actual al solicitării: confirmați versiunea API, antetul de autentificare, schema solicitării și eventualele restricții ale contului.
- Un spațiu de lucru sigur: evitați să introduceți acreditări, detalii despre clienți sau răspunsuri complete de tracking în depozite publice, capturi de ecran sau mesaje de asistență partajate.
Exemplele minimale de solicitări utilizează aceste setări:
| Setare | Configurație exemplu |
|---|---|
| URL de bază | https://api.17track.net/track/v2.2 |
| Operațiune de înregistrare | POST /register |
| Operațiune pentru informațiile de tracking | POST /gettrackinfo |
| Antet de autentificare | 17token: YOUR_API_TOKEN |
| Formatul corpului | Content-Type: application/json, cu un array JSON de obiecte de expediere |
Păstrați numerele de tracking sub formă de șiruri de caractere. Convertirea unuia într-un tip numeric poate elimina zerourile de la început sau îi poate modifica valoarea. Înlocuiți substituentul YOUR_TRACKING_NUMBER de mai jos cu expedierea dvs. reală de test; acesta nu este un număr de exemplu funcțional.
Efectuați solicitarea de înregistrare în Postman
1. Creați un mediu de testare mic
În Postman, creați un mediu cu trei variabile: base_url, tracking_token și tracking_number. Setați base_url la URL-ul de bază de mai sus și introduceți acreditarea și numărul expedierii în celelalte variabile. Selectați mediul respectiv înainte de a trimite solicitarea.
Utilizați controalele disponibile în Postman pentru gestionarea secretelor tokenului și verificați ce partajează sau sincronizează spațiul dvs. de lucru. Ascunderea unei valori în interfață nu înlocuiește controlul asupra persoanelor care o pot accesa. Nu exportați acreditări completate împreună cu o colecție destinată colegilor sau documentației publice.
2. Configurați metoda, URL-ul și antetele
Creați o solicitare HTTP, selectați POST și introduceți {{base_url}}/register ca URL. În fila Headers, adăugați:
17token: {{tracking_token}}
Content-Type: application/jsonPentru acest exemplu, acreditarea trebuie introdusă în antetul personalizat 17token. Nu o înlocuiți cu o configurație de tip Bearer token doar pentru că un alt API a utilizat acel model. Verificați, de asemenea, dacă setările moștenite ale colecției introduc un antet Authorization nedorit.
3. Adăugați corpul JSON
Deschideți Body, alegeți raw și selectați JSON. Introduceți:
[
{
"number": "{{tracking_number}}"
}
]Parantezele pătrate exterioare sunt importante: această solicitare utilizează un array, chiar dacă acesta conține o singură expediere. Utilizați ghilimele duble, eliminați virgulele finale și nu includeți comentarii în JSON. Dacă documentația impune informații suplimentare pentru transportatorul sau expedierea dvs., adăugați câmpurile documentate înainte de trimitere.
4. Trimiteți și inspectați rezultatul
Faceți clic pe Send. Mai întâi, verificați dacă ați primit vreun răspuns HTTP. O eroare DNS, o eroare TLS, o problemă de proxy sau expirarea timpului de așteptare diferă de un răspuns care explică faptul că solicitarea a fost invalidă. Apoi, inspectați corpul răspunsului pentru rezultatul operațiunii și orice informație privind acceptarea sau respingerea la nivelul expedierii.
Salvați solicitarea ca „Register test shipment”. Înregistrați starea HTTP, rezultatul API-ului și orice mesaj de eroare, fără a copia tokenul. Dacă înregistrarea eșuează, rezolvați problema înainte de a continua. Trimiterea repetată a unei solicitări neschimbate îngreunează diagnosticarea și poate consuma resursele contului.
Reproduceți solicitarea cu curl
Comenzile următoare utilizează un shell în stil POSIX, precum Bash sau Zsh. PowerShell și Windows Command Prompt au reguli diferite pentru ghilimele și variabile. În PowerShell, utilizați curl.exe atunci când este necesar să apelați executabilul curl, nu un alias de comandă specific shellului.
Setați URL-ul de bază și încărcați acreditarea într-o variabilă de mediu prin fluxul dvs. obișnuit de gestionare a secretelor:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.O variabilă de mediu menține acreditarea în afara exemplului reutilizabil, dar nu reprezintă un sistem complet de gestionare a secretelor. Pentru testarea locală, evitați să introduceți un token real într-o comandă pe care istoricul shellului îl va păstra. Pentru automatizare, utilizați magazinul de secrete al platformei dvs. și limitați rezultatele jurnalelor.
Creați un fișier numit shipment.json și înlocuiți substituentul cu numărul dvs. de tracking pentru test:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]Trimiteți solicitarea de înregistrare:
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'Aceasta salvează corpul răspunsului în register-response.json și afișează separat starea HTTP. Timpurile de expirare pentru conexiune și durata totală sunt alegeri pentru testarea locală, nu garanții ale serviciului 17TRACK. Deschideți fișierul salvat pentru a inspecta rezultatul API-ului; numai linia de stare nu este suficientă.
curl poate finaliza cu succes un transfer chiar și atunci când serverul returnează un răspuns HTTP de eroare. În schimb, o eroare de transport poate împiedica primirea oricărui răspuns API utilizabil. Atunci când creați scripturi, tratați separat codul de ieșire curl, starea HTTP și rezultatul la nivelul aplicației.
Solicitați informațiile de tracking ale expedierii
După confirmarea înregistrării, duplicați solicitarea Postman și modificați URL-ul în {{base_url}}/gettrackinfo. Păstrați metoda POST, antetul de autentificare, tipul de conținut și corpul expedierii. Salvați-o separat pentru a nu reînregistra accidental expedierea atunci când intenționați să preluați date.
Solicitarea curl echivalentă este:
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'Nu presupuneți că o expediere înregistrată recent va returna imediat un istoric complet al evenimentelor. Disponibilitatea datelor depinde de expediere și de procesarea serviciului. Dacă informațiile nu sunt încă disponibile, urmați instrucțiunile documentate privind preluarea și actualizarea, în loc să înregistrați repetat același număr sau să rulați o buclă de interogare prea frecventă.
Citiți răspunsul pe trei niveluri
- Transport: clientul s-a conectat și a primit un răspuns HTTP?
- Operațiune: API-ul a acceptat solicitarea și expedierea individuală a fost procesată cu succes?
- Informațiile expedierii: datele returnate identifică pachetul dorit și ce demonstrează efectiv starea sau istoricul evenimentelor?
Utilizați schema oficială a răspunsului pentru a localiza câmpurile privind starea, transportatorul și evenimentele. Păstrați distincția dintre o stare normalizată a expedierii și descrierea originală a evenimentului furnizată de transportator. O căutare reușită nu reprezintă o dovadă a livrării, iar lipsa evenimentelor nu dovedește că un colet este pierdut.
La stocarea marcajelor temporale, păstrați informațiile despre fusul orar sau decalajul furnizate. Evitați sortarea șirurilor brute de date din formate diferite și presupunerea că acestea reprezintă o ordine cronologică corectă. De asemenea, faceți diferența între momentul în care aplicația dvs. a preluat o înregistrare și momentul în care a avut loc evenimentul expedierii.
Depanați fără a modifica totul simultan
- Niciun răspuns: verificați numele gazdei, accesul la rețea, setările proxy, configurația TLS și timpul de expirare local. Nu dezactivați verificarea certificatelor ca soluție obișnuită.
- Eșec de autentificare: confirmați că tokenul este activ, că antetul
17tokeneste prezent și că mediul Postman selectat rezolvă corect variabila. Verificați existența spațiilor albe accidentale. - Solicitare invalidă: verificați versiunea API, calea operațiunii, metoda POST, tipul de conținut și structura array-ului JSON în raport cu documentația.
- Expediere respinsă: citiți eroarea specifică expedierii. Verificați numărul și orice informații necesare despre transportator, în loc să tratați fiecare respingere ca pe o problemă de autentificare.
- Nu există evenimente de tracking: confirmați înregistrarea și identitatea expedierii dorite. Verificați dacă sunt necesare informații despre transportator și dacă actualizările sunt disponibile înainte de a reîncerca.
- Postman funcționează, dar curl eșuează: comparați URL-ul rezolvat, antetele reale și octeții corpului. Ghilimelele shellului și variabilele de mediu nedefinite sunt locuri frecvente în care solicitările pot diferi.
Modificați o singură variabilă pentru fiecare test și păstrați o evidență scurtă a rezultatului. Dacă inspectați consola Postman sau utilizați rezultatul verbose al curl, tratați rezultatul ca fiind sensibil: antetele solicitării pot expune acreditări. Ascundeți secretele și informațiile despre clienți înainte de a partaja datele de diagnosticare.
Aflați când ghidul este finalizat
Ați finalizat un prim test de integrare relevant atunci când ambii clienți trimit solicitarea intenționată, înregistrarea este înțeleasă, preluarea returnează un rezultat interpretab il, iar dvs. puteți diferenția un eșec al API-ului de o expediere fără informații noi. Faptul că stările HTTP corespund nu demonstrează singur că cei doi clienți s-au comportat identic.
Înainte de a muta fluxul de lucru într-o aplicație, păstrați acreditările pe server, validați intrările și utilizați gestionarea structurată a erorilor. Consultați limitele de rată, limitele pentru loturi, instrucțiunile privind reîncercarea și opțiunile de livrare a actualizărilor documentate pentru contul dvs. Nu presupuneți că înregistrarea poate fi reîncercată orbește după expirarea timpului de așteptare: serverul poate fi procesat solicitarea chiar dacă clientul dvs. nu a primit răspunsul.
Adăugați teste pentru o acreditare invalidă, JSON malformat, un număr de expediere invalid, o expediere deja înregistrată, date de tracking indisponibile și expirarea timpului de așteptare al rețelei. Fiecare caz trebuie să conducă la un rezultat deliberat al aplicației, nu la o excepție netratată sau la o stare înșelătoare afișată clientului.
Întrebări frecvente
Pot testa fără un număr real de tracking?
Puteți testa unele comportamente de validare a solicitării cu o valoare invalidă, dar acest lucru nu verifică trackingul expedierii. Pentru a testa evenimente reale, utilizați o expediere autorizată sau un fixture de test documentat, dacă serviciul oferă unul. Nu presupuneți că numerele de exemplu arbitrare aparțin unui sandbox.
De ce un răspuns HTTP 200 conține totuși un eșec?
Starea HTTP și rezultatele aplicației descriu niveluri diferite. Un server poate primi și procesa cu succes o solicitare, raportând în același timp că o expediere individuală a fost respinsă. Citiți corpul răspunsului și rezultatul documentat la nivelul expedierii, nu doar starea HTTP.
De ce se utilizează POST pentru preluarea informațiilor de tracking?
Utilizați metoda specificată în contractul endpointului. Acest exemplu de preluare acceptă identificatori de expediere într-un corp de solicitare JSON prin POST. Schimbarea în GET deoarece operațiunea citește date nu păstrează solicitarea documentată.
Ar trebui să introduc tokenul API în JavaScript-ul browserului?
Nu încorporați o acreditare API privată în codul frontend livrat public. Direcționați solicitările printr-un backend autorizat care protejează acreditarea, validează intrările și controlează informațiile despre expedieri la care poate avea acces fiecare utilizator.
Am nevoie atât de Postman, cât și de curl pentru producție?
Nu. Acestea sunt instrumente utile pentru testare și diagnosticare. Aplicația dvs. de producție poate utiliza un client HTTP adecvat. Păstrați o solicitare Postman sau o comandă curl igienizată ca referință reproductibilă, fără un token activ sau date inutile despre clienți.
Surse
- Documentația API 17TRACK — referință pentru autentificare, contractele endpointurilor, câmpurile solicitărilor, interpretarea răspunsurilor și cerințele de integrare.
- Documentația Postman: Trimiterea solicitărilor API — configurarea solicitărilor și inspectarea răspunsurilor.
- Documentația Postman: Variabile — configurarea solicitărilor pe bază de variabile.
- Manualul curl — opțiuni de comandă pentru antete, corpuri de solicitări, expirări, răspunsuri salvate și afișarea stării HTTP.


