Skip to main content
HjemBlogVejledningerDin første anmodning til Tracking API: en gennemgang af en REST-klient med Postman og Curl

Din første anmodning til Tracking API: en gennemgang af en REST-klient med Postman og Curl

17TRACK

For at foretage din første tracking-API-anmodning skal du konfigurere endpointet, godkendelsesheaderen og JSON-bodyen i en REST-klient, sende anmodningen og kontrollere både HTTP-statussen og response-bodyen. Denne gennemgang bruger 17TRACK’s Tracking API til at demonstrere den samme arbejdsgang i Postman og curl: registrer en forsendelse, anmod om dens trackingoplysninger, og kontrollér, om resultatet er klar til brug i din applikation.

Din første tracking-API-anmodning – gennemgang af en REST-klient

Målet er en lille, reproducerbar integrationstest – ikke en produktionsudrulning. Du skal bruge en API-legitimationsoplysning og et trackingnummer, som du er autoriseret til at behandle. Kommandoerne nedenfor bruger endpointmønstret v2.2; bekræft endpointversionen og de kontospecifikke krav i 17TRACK API-dokumentationen, før du kører dem.

Forstå, hvad din første anmodning skal opnå

En integration til forsendelsessporing har to separate formål: at fortælle tjenesten, hvilken forsendelse der skal spores, og at hente de trackingoplysninger, der er knyttet til denne forsendelse. I den arbejdsgang, der demonstreres her, er der tale om separate anmodninger. Registrering betyder ikke, at pakken allerede er afsendt, og en vellykket registrering garanterer ikke, at transportørens hændelser bliver tilgængelige med det samme.

Brug én forsendelse i stedet for et batch til din første test. Det gør det lettere at isolere godkendelsesfejl, ugyldige trackingnumre og fortolkning af svar. Din første nyttige milepæl er ikke blot “Jeg modtog HTTP 200”. Den er “API’en accepterede min tilsigtede handling, og jeg kan forklare resultatet på forsendelsesniveau”.

Postman giver dig en visuel grænseflade til redigering af anmodninger og inspektion af svar. curl gør den samme HTTP-udveksling reproducerbar fra en terminal. Ingen af dem ændrer API’ens godkendelsesregler, forsendelsesdata eller behandlingsadfærd. Brug det værktøj, der hjælper dig med at undersøge anmodningen tydeligst, og genskab derefter den fungerende konfiguration i det andet værktøj.

Forbered dine legitimationsoplysninger, forsendelsen og anmodningsdetaljerne

Indsaml følgende, før du åbner en af klienterne:

  • En autoriseret API-legitimationsoplysning: Hent den via opsætningen af din 17TRACK API-konto. En forbrugerbaseret trackingsession kan ikke erstatte en API-legitimationsoplysning.
  • Et rigtigt trackingnummer: Brug en forsendelse, som du ejer eller har tilladelse til at tilgå. En forsendelse, der for nylig har været aktiv, er normalt mere nyttig end et opdigtet nummer ved test af faktiske trackingdata.
  • Transportøren, hvis den er kendt: Hav transportørens navn ved hånden til fejlfinding. Hvis der kræves en transportøridentifikator i dit tilfælde, skal du bruge den værdi og det felt, der er angivet i API-dokumentationen, i stedet for at gætte.
  • Den aktuelle anmodningskontrakt: Bekræft API-versionen, godkendelsesheaderen, anmodningsskemaet og eventuelle kontobegrænsninger.
  • Et sikkert arbejdsområde: Undgå at placere legitimationsoplysninger, kundedetaljer eller komplette tracking-svar i offentlige arkiver, skærmbilleder eller delte supportmeddelelser.

De minimale anmodningseksempler bruger disse indstillinger:

IndstillingEksempelkonfiguration
Base-URLhttps://api.17track.net/track/v2.2
RegistreringshandlingPOST /register
Handling for trackingoplysningerPOST /gettrackinfo
Godkendelsesheader17token: YOUR_API_TOKEN
Body-formatContent-Type: application/json, med et JSON-array af forsendelsesobjekter

Bevar trackingnumre som strenge. Hvis du konverterer et til en numerisk type, kan indledende nuller blive fjernet, eller værdien kan på anden måde blive ændret. Pladsholderen YOUR_TRACKING_NUMBER nedenfor skal erstattes med din faktiske testforsendelse; det er ikke et fungerende eksempelnummer.

Foretag registreringsanmodningen i Postman

1. Opret et lille testmiljø

Opret et miljø i Postman med tre variabler: base_url, tracking_token og tracking_number. Indstil base_url til base-URL’en ovenfor, og indtast dine legitimationsoplysninger og dit forsendelsesnummer i de to andre variabler. Vælg miljøet, før du sender anmodningen.

Brug Postmans tilgængelige kontroller til håndtering af hemmeligheder for tokenet, og kontrollér, hvad dit arbejdsområde deler eller synkroniserer. At skjule en værdi i grænsefladen er ikke en erstatning for at kontrollere, hvem der kan få adgang til den. Eksportér ikke udfyldte legitimationsoplysninger sammen med en collection, der er beregnet til kolleger eller offentlig dokumentation.

2. Konfigurer metode, URL og headers

Opret en HTTP-anmodning, vælg POST, og indtast {{base_url}}/register som URL. Tilføj følgende under fanen Headers:

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

I dette eksempel hører legitimationsoplysningen hjemme i den brugerdefinerede 17token-header. Erstat den ikke med en Bearer-tokenkonfiguration, blot fordi en anden API anvendte dette mønster. Kontrollér også, om nedarvede collection-indstillinger tilføjer en utilsigtet Authorization-header.

3. Tilføj JSON-bodyen

Åbn Body, vælg raw, og vælg JSON. Indtast:

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

De ydre firkantede parenteser er vigtige: Denne anmodning bruger et array, selv om det kun indeholder én forsendelse. Brug dobbelte anførselstegn, fjern afsluttende kommaer, og hold kommentarer ude af JSON’en. Hvis dokumentationen kræver yderligere oplysninger om din transportør eller forsendelse, skal du tilføje de dokumenterede felter, før du sender.

4. Send og kontrollér resultatet

Klik på Send. Kontrollér først, om du overhovedet modtog et HTTP-svar. En DNS-fejl, TLS-fejl, proxyfejl eller timeout er anderledes end et svar, der forklarer, at anmodningen var ugyldig. Undersøg derefter response-bodyen for resultatet af handlingen og eventuelle oplysninger om accept eller afvisning på forsendelsesniveau.

Gem anmodningen som “Register test shipment”. Notér HTTP-statussen, API-resultatet og eventuelle fejlmeddelelser uden at kopiere tokenet. Hvis registreringen mislykkes, skal du løse fejlen, før du går videre. Gentagne indsendelser af en uændret anmodning gør fejlfinding vanskeligere og kan bruge kontoresurser.

Genskab anmodningen med curl

De følgende kommandoer bruger en POSIX-lignende shell, f.eks. Bash eller Zsh. PowerShell og Windows Command Prompt har andre regler for anførselstegn og variabler. I PowerShell skal du om nødvendigt bruge curl.exe for at kalde curl-programmet i stedet for et shell-specifikt kommandoalias.

Indstil base-URL’en, og indlæs dine legitimationsoplysninger i en miljøvariabel via din normale arbejdsgang for håndtering af hemmeligheder:

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

En miljøvariabel holder legitimationsoplysningen ude af det genanvendelige eksempel, men den er ikke et komplet system til håndtering af hemmeligheder. Ved lokal test bør du undgå at skrive et rigtigt token i en kommando, som din shell-historik gemmer. Til automatisering skal du bruge din platforms secret store og begrænse logoutputtet.

Opret en fil med navnet shipment.json, og erstat pladsholderen med dit testtrackingnummer:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Send registreringsanmodningen:

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'

Dette gemmer response-bodyen i register-response.json og viser HTTP-statussen separat. Forbindelses- og samlede timeouts er valg til lokal test, ikke garantier fra 17TRACK-tjenesten. Åbn den gemte fil for at kontrollere API-resultatet; statuslinjen alene er utilstrækkelig.

curl kan fuldføre en overførsel korrekt, selv når serveren returnerer et HTTP-fejlsvar. Omvendt kan en transportfejl forhindre, at et brugbart API-svar overhovedet ankommer. Ved scripting skal du håndtere curls exit-status, HTTP-statussen og resultatet på applikationsniveau som separate signaler.

Anmod om forsendelsens trackingoplysninger

Når du har bekræftet registreringen, skal du duplikere Postman-anmodningen og ændre URL’en til {{base_url}}/gettrackinfo. Bevar POST-metoden, godkendelsesheaderen, content-typen og forsendelses-bodyen. Gem den separat, så du ikke ved et uheld registrerer forsendelsen igen, når du egentlig vil hente data.

Den tilsvarende curl-anmodning er:

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'

Antag ikke, at en nyligt registreret forsendelse straks returnerer en komplet hændelseshistorik. Datatilgængeligheden afhænger af forsendelsen og tjenestens behandling. Hvis oplysningerne endnu ikke er tilgængelige, skal du følge den dokumenterede vejledning om hentning og opdatering i stedet for gentagne gange at registrere det samme nummer eller køre en tæt polling-loop.

Læs svaret i tre lag

  1. Transport: Oprettede klienten forbindelse og modtog den et HTTP-svar?
  2. Handling: Accepterede API’en anmodningen, og lykkedes den enkelte forsendelse?
  3. Forsendelsesoplysninger: Identificerer de returnerede data den tilsigtede pakke, og hvad fastslår dens status eller hændelseshistorik faktisk?

Brug det officielle responseskema til at finde felter for status, transportør og hændelser. Bevar forskellen mellem en normaliseret forsendelsesstatus og transportørens oprindelige hændelsesbeskrivelse. Et vellykket opslag er ikke bevis på levering, og manglende hændelser er ikke bevis på, at en pakke er bortkommet.

Når du gemmer tidsstempler, skal du bevare de angivne oplysninger om tidszone eller offset. Undgå at sortere rå datostrings fra forskellige formater og antage, at de udgør en korrekt kronologisk rækkefølge. Skeln også mellem det tidspunkt, hvor din applikation hentede en post, og det tidspunkt, hvor forsendelseshændelsen fandt sted.

Fejlfind uden at ændre alt på én gang

  • Intet svar: Kontrollér værtsnavnet, netværksadgangen, proxyindstillingerne, TLS-konfigurationen og den lokale timeout. Deaktivér ikke certifikatverifikation som en rutinemæssig løsning.
  • Godkendelsesfejl: Bekræft, at tokenet er aktivt, at 17token-headeren er til stede, og at det valgte Postman-miljø løser variablen korrekt. Kontrollér utilsigtede mellemrum.
  • Ugyldig anmodning: Kontrollér API-versionen, handlingsstien, POST-metoden, content-typen og JSON-arraystrukturen i forhold til dokumentationen.
  • Forsendelse afvist: Læs den forsendelsesspecifikke fejl. Kontrollér nummeret og eventuelle påkrævede transportøroplysninger i stedet for at behandle enhver afvisning som et godkendelsesproblem.
  • Ingen trackinghændelser: Bekræft registreringen og den tilsigtede forsendelsesidentitet. Kontrollér, om transportøroplysninger er nødvendige, og om opdateringer er tilgængelige, før du prøver igen.
  • Postman fungerer, men curl fejler: Sammenlign den løste URL, de faktiske headers og body-bytes. Shell-anførselstegn og ikke-satte miljøvariabler er almindelige årsager til, at anmodningerne afviger.

Ændr én variabel pr. test, og før en kort oversigt over resultatet. Hvis du inspicerer Postmans konsol eller bruger curls verbose-output, skal du behandle outputtet som følsomt: Anmodningsheaders kan afsløre legitimationsoplysninger. Maskér hemmeligheder og kundeoplysninger, før du deler diagnosticering.

Vid, hvornår gennemgangen er færdig

Du har gennemført en meningsfuld første integrationstest, når begge klienter sender den tilsigtede anmodning, registreringen er forstået, hentningen returnerer et fortolkeligt resultat, og du kan skelne en API-fejl fra en forsendelse uden nye oplysninger. Ens HTTP-statuskoder alene fastslår ikke, at de to klienter opførte sig identisk.

Før du flytter arbejdsgangen ind i en applikation, skal du opbevare legitimationsoplysninger på serveren, validere input og bruge struktureret fejlhåndtering. Se de dokumenterede hastighedsgrænser, batchgrænser, retningslinjer for genforsøg og muligheder for levering af opdateringer for din konto. Antag ikke, at registrering uden videre kan gentages efter en timeout: Serveren kan have behandlet anmodningen, selv om din klient ikke modtog svaret.

Tilføj tests for en ugyldig legitimationsoplysning, ugyldig JSON, et ugyldigt forsendelsesnummer, en allerede registreret forsendelse, utilgængelige trackingdata og en netværkstimeout. Hvert tilfælde bør føre til et bevidst resultat i applikationen i stedet for en uhåndteret undtagelse eller en misvisende status, der vises til kunden.

FAQ

Kan jeg teste uden et rigtigt trackingnummer?

Du kan teste visse former for validering af anmodninger med en ugyldig værdi, men det verificerer ikke forsendelsessporing. Brug en autoriseret forsendelse eller en dokumenteret test-fixture, hvis tjenesten leverer en sådan, for at teste rigtige hændelser. Antag ikke, at vilkårlige eksempelnumre tilhører en sandbox.

Hvorfor indeholder et HTTP 200-svar stadig en fejl?

HTTP-status og applikationsresultater beskriver forskellige lag. En server kan modtage og behandle en anmodning korrekt, samtidig med at den rapporterer, at en individuel forsendelse blev afvist. Læs response-bodyen og det dokumenterede resultat på forsendelsesniveau – ikke kun HTTP-statussen.

Hvorfor bruges POST til at hente trackingoplysninger?

Brug den metode, der er angivet i endpointkontrakten. Dette eksempel på hentning accepterer forsendelsesidentifikatorer i en JSON-request-body via POST. Hvis du ændrer den til GET, fordi handlingen læser data, bevarer du ikke den dokumenterede anmodning.

Bør jeg placere API-tokenet i browser-JavaScript?

Indlejr ikke en privat API-legitimationsoplysning i offentligt leveret frontend-kode. Dirigér anmodninger gennem en autoriseret backend, der beskytter legitimationsoplysningen, validerer input og kontrollerer, hvilke forsendelsesoplysninger hver bruger kan tilgå.

Har jeg brug for både Postman og curl i produktion?

Nej. De er nyttige værktøjer til test og diagnosticering. Din produktionsapplikation kan bruge en passende HTTP-klient. Gem en renset Postman-anmodning eller curl-kommando som en reproducerbar reference uden et aktivt token eller unødvendige kundedata.

Kilder