Skip to main content
HjemBloggVeiledningerDin første forespørsel til Tracking API: en gjennomgang av en REST-klient med Postman og Curl

Din første forespørsel til Tracking API: en gjennomgang av en REST-klient med Postman og Curl

17TRACK

For å sende din første forespørsel til sporings-API-et må du konfigurere endepunktet, autentiseringshodet og JSON-teksten i en REST-klient, sende forespørselen og kontrollere både HTTP-statusen og svarteksten. Denne gjennomgangen bruker 17TRACK’s Tracking API for å demonstrere den samme arbeidsflyten i Postman og curl: registrer en forsendelse, be om sporingsinformasjonen og kontroller om resultatet er klart til bruk i applikasjonen.

Your First Tracking API Request a Rest Client Walkthrough with

Målet er en liten, reproduserbar integrasjonstest – ikke en produksjonsdistribusjon. Du trenger en API-legitimasjon og et sporingsnummer du har tillatelse til å behandle. Kommandoene nedenfor bruker mønsteret for v2.2-endepunktet. Bekreft endepunktversjonen og de kontospesifikke kravene i 17TRACK API-dokumentasjonen før du kjører dem.

Forstå hva din første forespørsel skal oppnå

En integrasjon for forsendelsessporing har to separate oppgaver: å fortelle tjenesten hvilken forsendelse som skal spores, og å hente sporingsinformasjonen som er knyttet til denne forsendelsen. I arbeidsflyten som vises her, er dette separate forespørsler. Registrering betyr ikke at pakken allerede har begynt å bevege seg, og en vellykket registrering garanterer ikke at transportørhendelser blir tilgjengelige umiddelbart.

Til den første testen bør du bruke én forsendelse i stedet for en batch. Det gjør det enklere å isolere autentiseringsfeil, ugyldige sporingsnumre og tolkning av svar. Den første nyttige milepælen er ikke bare «Jeg mottok HTTP 200». Den er «API-et godtok den tiltenkte operasjonen, og jeg kan forklare resultatet på forsendelsesnivå.»

Postman gir deg et visuelt grensesnitt for å redigere forespørsler og kontrollere svar. curl gjør den samme HTTP-utvekslingen reproduserbar fra en terminal. Ingen av dem endrer API-ets autentiseringsregler, forsendelsesdata eller behandlingsatferd. Bruk det verktøyet som hjelper deg å undersøke forespørselen tydeligst, og gjenskap deretter den fungerende konfigurasjonen i det andre verktøyet.

Forbered legitimasjon, forsendelse og forespørselsdetaljer

Før du åpner noen av klientene, må du samle inn følgende:

  • En autorisert API-legitimasjon: skaff den gjennom oppsettet av 17TRACK API-kontoen din. En forbrukerøkt for sporing kan ikke erstatte en API-legitimasjon.
  • Et ekte sporingsnummer: bruk en forsendelse du eier eller har tillatelse til å få tilgang til. En nylig aktiv forsendelse er vanligvis mer nyttig enn et oppdiktet nummer når du tester faktiske sporingsdata.
  • Transportøren, hvis kjent: ha transportørnavnet tilgjengelig for feilsøking. Hvis en transportøridentifikator kreves i ditt tilfelle, bruker du verdien og feltet som er definert i API-dokumentasjonen, i stedet for å gjette.
  • Den gjeldende forespørselskontrakten: bekreft API-versjonen, autentiseringshodet, forespørselsskjemaet og eventuelle kontobegrensninger.
  • Et sikkert arbeidsområde: unngå å legge legitimasjon, kundeopplysninger eller komplette sporingssvar i offentlige repositorier, skjermbilder eller delte supportmeldinger.

De minimale forespørselseksemplene bruker disse innstillingene:

InnstillingEksempelkonfigurasjon
Basis-URLhttps://api.17track.net/track/v2.2
RegistreringsoperasjonPOST /register
Operasjon for sporingsinformasjonPOST /gettrackinfo
Autentiseringshode17token: YOUR_API_TOKEN
Format på tekstContent-Type: application/json, med en JSON-matrise av forsendelsesobjekter

Behold sporingsnumre som strenger. Hvis du konverterer et til en numerisk type, kan innledende nuller forsvinne eller verdien på annen måte bli endret. Plassholderen YOUR_TRACKING_NUMBER nedenfor må erstattes med testforsendelsen din; det er ikke et fungerende eksempelnummer.

Send registreringsforespørselen i Postman

1. Opprett et lite testmiljø

I Postman oppretter du et miljø med tre variabler: base_url, tracking_token og tracking_number. Angi base_url til basis-URL-en ovenfor, og skriv inn legitimasjonen og forsendelsesnummeret ditt i de andre variablene. Velg dette miljøet før du sender forespørselen.

Bruk Postmans tilgjengelige kontroller for sikker håndtering av hemmeligheter for tokenet, og kontroller hva arbeidsområdet ditt deler eller synkroniserer. Å skjule en verdi i grensesnittet er ikke en erstatning for å kontrollere hvem som har tilgang til den. Ikke eksporter utfylte legitimasjoner med en samling som er ment for kolleger eller offentlig dokumentasjon.

2. Konfigurer metode, URL og hoder

Opprett en HTTP-forespørsel, velg POST, og skriv inn {{base_url}}/register som URL. Legg til følgende i fanen Headers:

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

I dette eksempelet skal legitimasjonen ligge i det egendefinerte 17token-hodet. Ikke erstatt det med en Bearer-token-konfigurasjon bare fordi et annet API bruker dette mønsteret. Kontroller også om nedarvede innstillinger for samlingen legger til et utilsiktet Authorization-hode.

3. Legg til JSON-teksten

Åpne Body, velg raw, og velg JSON. Skriv inn:

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

De ytre hakeparentesene er viktige: denne forespørselen bruker en matrise, selv om den bare inneholder én forsendelse. Bruk doble anførselstegn, fjern avsluttende kommaer, og ikke ta med kommentarer i JSON-en. Hvis dokumentasjonen krever ytterligere informasjon for transportøren eller forsendelsen din, legger du til de dokumenterte feltene før sending.

4. Send og kontroller resultatet

Klikk på Send. Kontroller først om du i det hele tatt mottok et HTTP-svar. En DNS-feil, TLS-feil, proxy-problem eller tidsavbrudd er forskjellig fra et svar som forklarer at forespørselen var ugyldig. Kontroller deretter svarteksten for operasjonsresultatet og eventuell informasjon om godkjenning eller avvisning på forsendelsesnivå.

Lagre forespørselen som «Register test shipment». Registrer HTTP-statusen, API-resultatet og eventuelle feilmeldinger uten å kopiere tokenet. Hvis registreringen mislykkes, må du løse feilen før du går videre. Gjentatte innsendinger av en uendret forespørsel gjør feilsøkingen vanskeligere og kan bruke kontoresurser.

Gjenskap forespørselen med curl

De følgende kommandoene bruker et POSIX-lignende skall, for eksempel Bash eller Zsh. PowerShell og Windows Command Prompt har andre regler for anførselstegn og variabler. I PowerShell bruker du curl.exe ved behov for å starte curl-programmet i stedet for et skallspesifikt kommandoalias.

Angi basis-URL-en og last inn legitimasjonen i en miljøvariabel gjennom din vanlige arbeidsflyt for sikker håndtering av hemmeligheter:

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

En miljøvariabel holder legitimasjonen ute av det gjenbrukbare eksempelet, men den er ikke et komplett system for håndtering av hemmeligheter. Ved lokal testing bør du unngå å skrive et ekte token i en kommando som beholdes i skallhistorikken. For automatisering bruker du plattformens hemmelighetslager og begrenser loggutdata.

Opprett en fil med navnet shipment.json og erstatt plassholderen med testsporingsnummeret ditt:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Send registreringsforespørselen:

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 lagrer svarteksten i register-response.json og skriver ut HTTP-statusen separat. Tilkoblings- og total tidsavbrudd er valg for lokal testing, ikke garantier fra 17TRACK-tjenesten. Åpne den lagrede filen for å kontrollere API-resultatet; statuslinjen alene er utilstrekkelig.

curl kan fullføre en overføring selv om serveren returnerer et HTTP-feilsvar. Omvendt kan en transportfeil hindre at et brukbart API-svar kommer frem. Ved skripting må du behandle curl-avslutningsstatusen, HTTP-statusen og resultatet på applikasjonsnivå som separate signaler.

Be om forsendelsens sporingsinformasjon

Når registreringen er bekreftet, dupliserer du Postman-forespørselen og endrer URL-en til {{base_url}}/gettrackinfo. Behold POST-metoden, autentiseringshodet, innholdstypen og forsendelsesteksten. Lagre den separat slik at du ikke ved et uhell registrerer forsendelsen på nytt når du egentlig vil hente data.

Den tilsvarende curl-forespørselen 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'

Ikke anta at en nylig registrert forsendelse umiddelbart vil returnere en komplett hendelseshistorikk. Datatilgjengeligheten avhenger av forsendelsen og tjenestens behandling. Hvis informasjonen ikke er tilgjengelig ennå, følger du den dokumenterte veiledningen for henting og oppdatering i stedet for gjentatte ganger å registrere samme nummer eller kjøre en tett polling-løkke.

Les svaret i tre lag

  1. Transport: koblet klienten til og mottok et HTTP-svar?
  2. Operasjon: godtok API-et forespørselen, og lyktes den enkelte forsendelsen?
  3. Forsendelsesinformasjon: identifiserer de returnerte dataene den tiltenkte pakken, og hva fastslår statusen eller hendelseshistorikken faktisk?

Bruk det offisielle svarskjemaet for å finne status-, transportør- og hendelsesfelter. Oppretthold skillet mellom en normalisert forsendelsesstatus og transportørens opprinnelige hendelsesbeskrivelse. Et vellykket oppslag er ikke bevis på levering, og manglende hendelser er ikke bevis på at en pakke er tapt.

Når du lagrer tidsstempler, må du beholde den medfølgende tidssonen eller forskyvningen. Unngå å sortere rå datostrenger fra ulike formater og anta at de representerer en korrekt kronologisk rekkefølge. Skill også mellom tidspunktet applikasjonen hentet en post og tidspunktet forsendelseshendelsen inntraff.

Feilsøk uten å endre alt samtidig

  • Ingen svar: kontroller vertsnavnet, nettverkstilgang, proxy-innstillinger, TLS-konfigurasjon og lokalt tidsavbrudd. Ikke deaktiver sertifikatverifisering som en standardløsning.
  • Autentiseringsfeil: bekreft at tokenet er aktivt, at 17token-hodet finnes, og at det valgte Postman-miljøet løser variabelen riktig. Se etter utilsiktede mellomrom.
  • Ugyldig forespørsel: kontroller API-versjonen, operasjonsbanen, POST-metoden, innholdstypen og JSON-matrisens struktur mot dokumentasjonen.
  • Forsendelse avvist: les den forsendelsesspesifikke feilen. Kontroller nummeret og eventuell nødvendig transportørinformasjon i stedet for å behandle alle avvisninger som autentiseringsproblemer.
  • Ingen sporingshendelser: bekreft registreringen og identiteten til den tiltenkte forsendelsen. Kontroller om transportørinformasjon kreves, og om oppdateringer er tilgjengelige før du prøver på nytt.
  • Postman fungerer, men curl mislykkes: sammenlign den løste URL-en, de faktiske hodene og byte-innholdet. Skallanførselstegn og miljøvariabler som ikke er satt, er vanlige steder der forespørslene skiller seg fra hverandre.

Endre én variabel per test og før en kort oversikt over resultatet. Hvis du kontrollerer Postman-konsollen eller bruker curl med detaljert utdata, må du behandle utdataene som sensitive: forespørselsforespørsler kan avsløre legitimasjon. Fjern hemmeligheter og kundeinformasjon før du deler diagnostikk.

Vit når gjennomgangen er fullført

Du har fullført en meningsfull første integrasjonstest når begge klientene sender den tiltenkte forespørselen, registreringen er forstått, henting returnerer et tolkbart resultat, og du kan skille en API-feil fra en forsendelse uten ny informasjon. Samsvarende HTTP-statuskoder alene fastslår ikke at de to klientene oppførte seg identisk.

Før du flytter arbeidsflyten inn i en applikasjon, må du oppbevare legitimasjon på serveren, validere inndata og bruke strukturert feilhåndtering. Se de dokumenterte hastighetsgrensene, batchgrensene, veiledningen for nye forsøk og alternativene for levering av oppdateringer for kontoen din. Ikke anta at registrering er trygt å gjenta blindt etter et tidsavbrudd: serveren kan ha behandlet forespørselen selv om klienten ikke mottok svaret.

Legg til tester for ugyldig legitimasjon, feilformatert JSON, et ugyldig forsendelsesnummer, en allerede registrert forsendelse, utilgjengelige sporingsdata og et nettverkstidsavbrudd. Hvert tilfelle bør føre til et bevisst applikasjonsresultat i stedet for et uhåndtert unntak eller en misvisende status som vises til kunden.

Vanlige spørsmål

Kan jeg teste uten et ekte sporingsnummer?

Du kan teste noe av valideringsatferden for forespørselen med en ugyldig verdi, men det verifiserer ikke forsendelsessporing. For å teste ekte hendelser bruker du en autorisert forsendelse eller en dokumentert testpakke hvis tjenesten tilbyr en. Ikke anta at vilkårlige eksempelnumre tilhører en sandkasse.

Hvorfor inneholder et HTTP 200-svar fortsatt en feil?

HTTP-status og applikasjonsresultater beskriver ulike lag. En server kan motta og behandle en forespørsel riktig, samtidig som den rapporterer at en individuell forsendelse ble avvist. Les svarteksten og det dokumenterte resultatet på forsendelsesnivå, ikke bare HTTP-statusen.

Hvorfor brukes POST til å hente sporingsinformasjon?

Bruk metoden som er angitt i endepunktkontrakten. Dette henteeksempelet godtar forsendelsesidentifikatorer i en JSON-tekst gjennom POST. Hvis du endrer den til GET fordi operasjonen leser data, følger du ikke lenger den dokumenterte forespørselen.

Bør jeg legge API-tokenet i JavaScript i nettleseren?

Ikke bygg inn en privat API-legitimasjon i frontend-kode som leveres offentlig. Send forespørsler gjennom en autorisert backend som beskytter legitimasjonen, validerer inndata og kontrollerer hvilken forsendelsesinformasjon hver bruker kan få tilgang til.

Trenger jeg både Postman og curl i produksjon?

Nei. De er nyttige verktøy for testing og diagnostikk. Produksjonsapplikasjonen kan bruke en passende HTTP-klient. Oppbevar en renset Postman-forespørsel eller curl-kommando som en reproduserbar referanse, uten et aktivt token eller unødvendige kundeopplysninger.

Kilder