Skip to main content
Faqja kryesoreBlogUdhëzuesKërkesa juaj e parë për Tracking API: Udhëzues për klientin REST me Postman dhe Curl

Kërkesa juaj e parë për Tracking API: Udhëzues për klientin REST me Postman dhe Curl

17TRACK

Për të bërë kërkesën tuaj të parë ndaj API-së së gjurmimit, konfiguroni endpoint-in, kokën e autentikimit dhe trupin JSON në një klient REST, dërgoni kërkesën dhe kontrolloni si statusin HTTP, ashtu edhe trupin e përgjigjes. Ky udhëzues përdor Tracking API të 17TRACK për të demonstruar të njëjtin rrjedhë pune në Postman dhe curl: regjistroni një dërgesë, kërkoni informacionin e gjurmimit dhe kontrolloni nëse rezultati është gati për t'u përdorur nga aplikacioni juaj.

Kërkesa juaj e parë ndaj Tracking API: udhëzues për klientin REST

Qëllimi është një test i vogël dhe i riprodhueshëm integrimi—not një vendosje në prodhim. Do t'ju nevojitet një kredencial API dhe një numër gjurmimi që jeni të autorizuar ta përpunoni. Komandat më poshtë përdorin modelin e endpoint-it v2.2; konfirmoni versionin e endpoint-it dhe kërkesat specifike të llogarisë në dokumentacionin e API-së së 17TRACK përpara se t'i ekzekutoni.

Kuptoni çfarë duhet të arrijë kërkesa juaj e parë

Një integrim për gjurmimin e dërgesave ka dy aspekte të ndara: t'i tregojë shërbimit se cilën dërgesë duhet të gjurmojë dhe të marrë informacionin e gjurmimit që lidhet me atë dërgesë. Në rrjedhën e punës së demonstruar këtu, këto janë kërkesa të ndara. Regjistrimi nuk do të thotë se pakoja ka lëvizur tashmë dhe një regjistrim i suksesshëm nuk garanton që ngjarjet e transportuesit do të jenë menjëherë të disponueshme.

Për testin tuaj të parë, përdorni një dërgesë në vend të një grupi. Kjo e bën më të lehtë izolimin e gabimeve të autentikimit, numrave të pavlefshëm të gjurmimit dhe interpretimit të përgjigjes. Arritja juaj e parë e dobishme nuk është thjesht “mora HTTP 200”. Është “API-ja pranoi veprimin që synova dhe mund ta shpjegoj rezultatin në nivel dërgese”.

Postman ju ofron një ndërfaqe vizuale për të redaktuar kërkesat dhe për të kontrolluar përgjigjet. curl e bën të njëjtin shkëmbim HTTP të riprodhueshëm nga terminali. Asnjëri nuk ndryshon rregullat e autentikimit të API-së, të dhënat e dërgesës ose sjelljen e përpunimit. Përdorni atë që ju ndihmon ta hetoni më qartë kërkesën, pastaj riprodhoni konfigurimin funksional në mjetin tjetër.

Përgatitni kredencialin, dërgesën dhe detajet e kërkesës

Përpara se të hapni cilindo klient, mblidhni sa vijon:

  • Një kredencial API të autorizuar: merreni përmes konfigurimit të llogarisë suaj API të 17TRACK. Një sesion konsumatori për gjurmim nuk zëvendëson kredencialin API.
  • Një numër real gjurmimi: përdorni një dërgesë që zotëroni ose për të cilën keni leje aksesi. Një dërgesë së fundmi aktive është përgjithësisht më e dobishme se një numër i sajuar kur testoni të dhëna reale gjurmimi.
  • Transportuesin, nëse dihet: mbajeni emrin e transportuesit të disponueshëm për diagnostikim. Nëse për rastin tuaj kërkohet një identifikues transportuesi, përdorni vlerën dhe fushën e përcaktuar në dokumentacionin e API-së, në vend që të hamendësoni.
  • Kontratën aktuale të kërkesës: konfirmoni versionin e API-së, kokën e autentikimit, skemën e kërkesës dhe çdo kufizim të llogarisë.
  • Një hapësirë pune të sigurt: shmangni vendosjen e kredencialeve, të dhënave të klientëve ose përgjigjeve të plota të gjurmimit në depo publike, pamje ekrani ose mesazhe të përbashkëta mbështetjeje.

Shembujt minimalë të kërkesave përdorin këto cilësime:

CilësimiKonfigurimi shembull
URL-ja bazëhttps://api.17track.net/track/v2.2
Veprimi i regjistrimitPOST /register
Veprimi i informacionit të gjurmimitPOST /gettrackinfo
Koka e autentikimit17token: YOUR_API_TOKEN
Formati i trupitContent-Type: application/json, me një varg JSON objektesh dërgesash

Mbajini numrat e gjurmimit si vargje. Shndërrimi i njërit në tip numerik mund të heqë zerot në fillim ose të ndryshojë ndryshe vlerën e tij. Mbajtësi i vendit YOUR_TRACKING_NUMBER më poshtë duhet të zëvendësohet me dërgesën tuaj reale të testimit; ai nuk është një numër shembull funksional.

Bëni kërkesën e regjistrimit në Postman

1. Krijoni një mjedis të vogël testimi

Në Postman, krijoni një mjedis me tri variabla: base_url, tracking_token dhe tracking_number. Vendoseni base_url në URL-në bazë më sipër dhe vendosni kredencialin dhe numrin e dërgesës në dy variablat e tjera. Zgjidhni atë mjedis përpara se të dërgoni kërkesën.

Përdorni kontrollet e disponueshme të Postman për trajtimin e sigurt të token-it dhe kontrolloni se çfarë ndahet ose sinkronizohet nga hapësira juaj e punës. Fshehja e një vlere në ndërfaqe nuk zëvendëson kontrollin se kush mund ta aksesojë atë. Mos eksportoni kredenciale të plotësuara me një koleksion të destinuar për kolegë ose dokumentacion publik.

2. Konfiguroni metodën, URL-në dhe kokat

Krijoni një kërkesë HTTP, zgjidhni POST dhe vendosni {{base_url}}/register si URL. Në skedën Headers, shtoni:

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

Për këtë shembull, kredenciali duhet të vendoset në kokën e personalizuar 17token. Mos e zëvendësoni me konfigurim Bearer token vetëm sepse një API tjetër përdori atë model. Kontrolloni gjithashtu nëse cilësimet e trashëguara të koleksionit shtojnë një kokë të padëshiruar Authorization.

3. Shtoni trupin JSON

Hapni Body, zgjidhni raw dhe më pas JSON. Vendosni:

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

Kllapat katrore të jashtme kanë rëndësi: kjo kërkesë përdor një varg, edhe pse përmban vetëm një dërgesë. Përdorni thonjëza të dyfishta, hiqni presjet në fund dhe mos vendosni komente në JSON. Nëse dokumentacioni kërkon informacion shtesë për transportuesin ose dërgesën tuaj, shtoni fushat e dokumentuara përpara dërgimit.

4. Dërgoni dhe kontrolloni rezultatin

Klikoni Send. Së pari, kontrolloni nëse morët fare një përgjigje HTTP. Një dështim DNS, gabim TLS, problem me proxy-n ose skadim kohe ndryshon nga një përgjigje që shpjegon se kërkesa ishte e pavlefshme. Më pas, kontrolloni trupin e përgjigjes për rezultatin e veprimit dhe çdo informacion pranimi ose refuzimi në nivel dërgese.

Ruajeni kërkesën si “Regjistrimi i dërgesës së testimit”. Regjistroni statusin HTTP, rezultatin e API-së dhe çdo mesazh gabimi pa kopjuar token-in. Nëse regjistrimi dështon, zgjidheni atë dështim përpara se të vazhdoni. Dërgimi i përsëritur i një kërkese të pandryshuar e vështirëson diagnostikimin dhe mund të konsumojë burimet e llogarisë.

Riprodhoni kërkesën me curl

Komandat e mëposhtme përdorin një shell të stilit POSIX, si Bash ose Zsh. PowerShell dhe Windows Command Prompt kanë rregulla të ndryshme për thonjëzat dhe variablat. Në PowerShell, përdorni curl.exe kur është e nevojshme për të thirrur ekzekutuesin curl në vend të një alias-i komandash specifik për shell-in.

Vendosni URL-në bazë dhe ngarkoni kredencialin në një variabël mjedisi përmes rrjedhës suaj normale të punës për trajtimin e sekreteve:

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

Një variabël mjedisi e mban kredencialin jashtë shembullit të ripërdorshëm, por nuk është një sistem i plotë menaxhimi sekretesh. Për testim lokal, shmangni shtypjen e një token-i real në një komandë që historiku i shell-it tuaj do ta ruajë. Për automatizim, përdorni magazinën e sekreteve të platformës suaj dhe kufizoni daljen e regjistrave.

Krijoni një skedar me emrin shipment.json dhe zëvendësoni mbajtësin e vendit me numrin tuaj të testimit:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Dërgoni kërkesën e regjistrimit:

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'

Kjo e ruan trupin e përgjigjes në register-response.json dhe e shfaq veçmas statusin HTTP. Kufijtë e kohës së lidhjes dhe kohës totale janë zgjedhje për testim lokal, jo garanci të shërbimit 17TRACK. Hapni skedarin e ruajtur për të kontrolluar rezultatin e API-së; vetëm rreshti i statusit nuk mjafton.

curl mund ta përfundojë me sukses transferimin edhe kur serveri kthen një përgjigje gabimi HTTP. Në të kundërt, një dështim transporti mund të pengojë mbërritjen e çdo përgjigjeje të përdorshme nga API-ja. Kur krijoni skripte, trajtoni si sinjale të dallueshme statusin e daljes së curl, statusin HTTP dhe rezultatin në nivel aplikacioni.

Kërkoni informacionin e gjurmimit të dërgesës

Pasi të konfirmoni regjistrimin, dublikoni kërkesën në Postman dhe ndryshoni URL-në në {{base_url}}/gettrackinfo. Mbani metodën POST, kokën e autentikimit, llojin e përmbajtjes dhe trupin e dërgesës. Ruajeni veçmas që të mos e riregjistroni aksidentalisht dërgesën kur synoni të merrni të dhëna.

Kërkesa ekuivalente curl është:

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'

Mos supozoni se një dërgesë e saporegjistruar do të kthejë menjëherë një histori të plotë ngjarjesh. Disponueshmëria e të dhënave varet nga dërgesa dhe përpunimi i shërbimit. Nëse informacioni nuk është ende i disponueshëm, ndiqni udhëzimet e dokumentuara për marrjen dhe përditësimin në vend që të regjistroni përsëri të njëjtin numër ose të ekzekutoni një cikël të shpeshtë polling-u.

Lexoni përgjigjen në tri nivele

  1. Transporti: a u lidh klienti dhe a mori një përgjigje HTTP?
  2. Veprimi: a e pranoi API-ja kërkesën dhe a pati sukses dërgesa individuale?
  3. Informacioni i dërgesës: a i identifikojnë të dhënat e kthyera pakos së synuar dhe çfarë përcaktojnë realisht statusi ose historia e ngjarjeve?

Përdorni skemën zyrtare të përgjigjes për të gjetur fushat e statusit, transportuesit dhe ngjarjeve. Ruani dallimin midis statusit të normalizuar të dërgesës dhe përshkrimit origjinal të ngjarjes nga transportuesi. Një kërkim i suksesshëm nuk është provë dorëzimi dhe mungesa e ngjarjeve nuk është provë se një pako ka humbur.

Kur ruani vulat kohore, mbani informacionin e zonës kohore ose të zhvendosjes së dhënë. Shmangni renditjen e vargjeve të papërpunuara të datave nga formate të ndryshme duke supozuar se përfaqësojnë një renditje të saktë kronologjike. Dalloni gjithashtu kohën kur aplikacioni juaj mori një regjistrim nga koha kur ndodhi ngjarja e dërgesës.

Zgjidhini problemet pa ndryshuar gjithçka njëherësh

  • Nuk ka përgjigje: kontrolloni hostname-in, aksesin në rrjet, cilësimet e proxy-t, konfigurimin TLS dhe kohën lokale të skadimit. Mos çaktivizoni verifikimin e certifikatës si zgjidhje rutinë.
  • Dështim autentikimi: konfirmoni që token-i është aktiv, koka 17token është e pranishme dhe mjedisi i zgjedhur në Postman e zgjidh saktë variablën. Kontrolloni për hapësira të padëshiruara.
  • Kërkesë e pavlefshme: verifikoni versionin e API-së, shtegun e veprimit, metodën POST, llojin e përmbajtjes dhe strukturën e vargut JSON kundrejt dokumentacionit.
  • Dërgesa u refuzua: lexoni gabimin specifik të dërgesës. Kontrolloni numrin dhe çdo informacion të kërkuar për transportuesin, në vend që çdo refuzim ta trajtoni si problem autentikimi.
  • Nuk ka ngjarje gjurmimi: konfirmoni regjistrimin dhe identitetin e synuar të dërgesës. Kontrolloni nëse kërkohet informacion për transportuesin dhe nëse përditësimet janë të disponueshme përpara se të provoni sërish.
  • Postman funksionon, por curl dështon: krahasoni URL-në e zgjidhur, kokat aktuale dhe bajtet e trupit. Thonjëzat e shell-it dhe variablat e papërcaktuara të mjedisit janë vende të zakonshme ku kërkesat mund të ndryshojnë.

Ndryshoni një variabël për çdo test dhe mbani një shënim të shkurtër të rezultatit. Nëse kontrolloni konsolën e Postman ose përdorni daljen verbose të curl, trajtojeni daljen si të ndjeshme: kokat e kërkesës mund të ekspozojnë kredenciale. Fshihni sekretet dhe informacionin e klientëve përpara se të ndani diagnostikimin.

Dini kur udhëzuesi ka përfunduar

Keni përfunduar një test të rëndësishëm fillestar integrimi kur të dy klientët dërgojnë kërkesën e synuar, regjistrimi kuptohet, marrja kthen një rezultat të interpretueshëm dhe mund të dalloni një dështim të API-së nga një dërgesë pa informacion të ri. Vetëm kodet e njëjta të statusit HTTP nuk vërtetojnë se të dy klientët u sollën në mënyrë identike.

Përpara se ta kaloni rrjedhën e punës në një aplikacion, mbajini kredencialet në server, vërtetoni hyrjet dhe përdorni trajtim të strukturuar të gabimeve. Konsultoni kufijtë e dokumentuar të shpejtësisë, kufijtë e grupeve, udhëzimet për riprovim dhe opsionet e dorëzimit të përditësimeve për llogarinë tuaj. Mos supozoni se regjistrimi është i sigurt për t'u riprovuar verbërisht pas një skadimi kohe: serveri mund ta ketë përpunuar kërkesën edhe pse klienti juaj nuk e mori përgjigjen.

Shtoni teste për një kredencial të pavlefshëm, JSON të formatuar gabim, një numër të pavlefshëm dërgese, një dërgesë të regjistruar tashmë, të dhëna gjurmimi të padisponueshme dhe një skadim kohe të rrjetit. Çdo rast duhet të çojë në një rezultat të qëllimshëm të aplikacionit, jo në një përjashtim të patrajtuar ose status mashtrues për klientin.

Pyetjet e shpeshta

A mund të testoj pa një numër real gjurmimi?

Mund të testoni disa sjellje të vërtetimit të kërkesës me një vlerë të pavlefshme, por kjo nuk verifikon gjurmimin e dërgesës. Për të testuar ngjarje reale, përdorni një dërgesë të autorizuar ose një të dhënë testimi të dokumentuar nëse shërbimi ofron një të tillë. Mos supozoni se numrat shembull të rastësishëm i përkasin një sandbox-i.

Pse një përgjigje HTTP 200 përmban ende një dështim?

Statusi HTTP dhe rezultatet e aplikacionit përshkruajnë nivele të ndryshme. Një server mund ta marrë dhe përpunojë me sukses një kërkesë, ndërsa raporton se një dërgesë individuale u refuzua. Lexoni trupin e përgjigjes dhe rezultatin e dokumentuar në nivel dërgese, jo vetëm statusin HTTP.

Pse përdoret POST për të marrë informacionin e gjurmimit?

Përdorni metodën e specifikuar nga kontrata e endpoint-it. Ky shembull marrjeje pranon identifikuesit e dërgesës në një trup kërkese JSON përmes POST. Ndryshimi në GET vetëm sepse veprimi lexon të dhëna nuk e ruan kërkesën e dokumentuar.

A duhet ta vendos token-in API në JavaScript-in e shfletuesit?

Mos e përfshini një kredencial privat API në kodin frontend të dorëzuar publikisht. Drejtojini kërkesat përmes një backend-i të autorizuar që mbron kredencialin, vërteton hyrjet dhe kontrollon se cilin informacion dërgese mund të aksesojë çdo përdorues.

A më duhen si Postman, ashtu edhe curl për prodhim?

Jo. Ato janë mjete të dobishme testimi dhe diagnostikimi. Aplikacioni juaj në prodhim mund të përdorë një klient HTTP të përshtatshëm. Mbani një kërkesë Postman ose komandë curl të pastruar si referencë të riprodhueshme, pa token aktiv ose të dhëna të panevojshme klientësh.

Burimet