Skip to main content
EtusivuBlogiOppaatEnsimmäinen Tracking API -rajapintapyyntösi: REST-asiakasohjelman esittely Postmanin ja Curlin avulla

Ensimmäinen Tracking API -rajapintapyyntösi: REST-asiakasohjelman esittely Postmanin ja Curlin avulla

17TRACK

Ensimmäisen tracking API -pyyntösi tekeminen edellyttää päätepisteen, todennusotsakkeen ja JSON-rungon määrittämistä REST-asiakasohjelmassa, pyynnön lähettämistä sekä HTTP-tilan ja vastausrungon tarkastamista. Tässä ohjeessa käytetään 17TRACKin Tracking APIa saman työnkulun esittelemiseen Postmanissa ja curlissa: rekisteröi lähetys, pyydä sen seurantatiedot ja tarkista, ovatko tulokset valmiita sovelluksesi käyttöön.

Your First Tracking API Request a Rest Client Walkthrough with

Tavoitteena on pieni, toistettavissa oleva integraatiotesti — ei tuotantoon käyttöönotto. Tarvitset API-tunnistetiedot ja seurantanumeron, jonka käsittelyyn sinulla on oikeus. Alla olevissa komennoissa käytetään v2.2-päätepistemallia; vahvista päätepisteen versio ja tiliä koskevat vaatimukset 17TRACK API -dokumentaatiosta ennen komentojen suorittamista.

Ymmärrä, mitä ensimmäisen pyyntösi tulee saada aikaan

Lähetyksen seurantaintegraatiossa on kaksi erillistä tehtävää: palvelulle ilmoitetaan, mitä lähetystä seurataan, ja haetaan kyseiseen lähetykseen liittyvät seurantatiedot. Tässä esitellyssä työnkulussa nämä ovat erillisiä pyyntöjä. Rekisteröinti ei tarkoita, että paketti olisi jo liikkeellä, eikä onnistunut rekisteröinti takaa, että kuljetusliikkeen tapahtumat ovat heti saatavilla.

Käytä ensimmäisessä testissä yhtä lähetystä erän sijaan. Näin todennusvirheet, virheelliset seurantanumerot ja vastausten tulkinta on helpompi erottaa toisistaan. Ensimmäinen hyödyllinen virstanpylväs ei ole pelkästään ”sain HTTP 200 -vastauksen”, vaan ”API hyväksyi tarkoittamani toiminnon ja osaan selittää lähetyksen tason tuloksen”.

Postman tarjoaa visuaalisen käyttöliittymän pyyntöjen muokkaamiseen ja vastausten tarkasteluun. curl tekee samasta HTTP-vaihdosta toistettavan päätelaitteessa. Kumpikaan ei muuta API:n todennussääntöjä, lähetystietoja tai käsittelytapaa. Käytä sitä, jonka avulla voit tutkia pyyntöä selkeämmin, ja toista toimiva määritys sen jälkeen toisessa työkalussa.

Valmistele tunnistetiedot, lähetys ja pyynnön tiedot

Kerää ennen kumman tahansa asiakasohjelman avaamista seuraavat tiedot:

  • Valtuutetut API-tunnistetiedot: hanki ne 17TRACK API -tilisi määrityksen kautta. Kuluttajille tarkoitettu seurantatunnus ei korvaa API-tunnistetietoja.
  • Oikea seurantanumero: käytä lähetystä, jonka omistat tai johon sinulla on käyttöoikeus. Äskettäin aktiivinen lähetys on yleensä hyödyllisempi kuin keksitty numero todellisia seurantatietoja testattaessa.
  • Kuljetusliike, jos tiedossa: pidä kuljetusliikkeen nimi saatavilla vianmääritystä varten. Jos tapauksesi edellyttää kuljetusliikkeen tunnistetta, käytä API-dokumentaatiossa määritettyä arvoa ja kenttää arvailun sijaan.
  • Nykyinen pyyntösopimus: vahvista API-versio, todennusotsake, pyyntöskeema ja mahdolliset tiliä koskevat rajoitukset.
  • Turvallinen työtila: vältä tunnistetietojen, asiakastietojen tai täydellisten seurantavastausten sijoittamista julkisiin repositorioihin, kuvakaappauksiin tai jaettuihin tukiviesteihin.

Vähimmäispyyntöesimerkeissä käytetään seuraavia asetuksia:

AsetusEsimerkkimääritys
Perus-URLhttps://api.17track.net/track/v2.2
RekisteröintitoimintoPOST /register
SeurantatietotoimintoPOST /gettrackinfo
Todennusotsake17token: YOUR_API_TOKEN
Rungon muotoContent-Type: application/json, jossa on lähetysobjektien JSON-taulukko

Säilytä seurantanumerot merkkijonoina. Numerotyypiksi muuntaminen voi poistaa alussa olevat nollat tai muuttaa arvoa muulla tavalla. Alla oleva paikkamerkki YOUR_TRACKING_NUMBER on korvattava varsinaisen testilähetyksesi numerolla; se ei ole toimiva esimerkkinumero.

Tee rekisteröintipyyntö Postmanissa

1. Luo pieni testiympäristö

Luo Postmanissa ympäristö, jossa on kolme muuttujaa: base_url, tracking_token ja tracking_number. Aseta base_url yllä olevaan perus-URL-osoitteeseen ja syötä tunnistetietosi sekä lähetysnumero kahteen muuhun muuttujaan. Valitse tämä ympäristö ennen pyynnön lähettämistä.

Käytä Postmanin käytettävissä olevia salaisuuksien käsittelytoimintoja tunnisteelle ja tarkista, mitä työtilasi jakaa tai synkronoi. Arvon piilottaminen käyttöliittymässä ei korvaa sen hallintaa, kenellä on siihen pääsy. Älä vie täytettyjä tunnistetietoja kokoelman mukana, jos kokoelma on tarkoitettu kollegoille tai julkiseen dokumentaatioon.

2. Määritä menetelmä, URL ja otsakkeet

Luo HTTP-pyyntö, valitse POST ja syötä URL-osoitteeksi {{base_url}}/register. Lisää Headers-välilehdellä seuraavat otsakkeet:

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

Tässä esimerkissä tunnistetieto kuuluu mukautettuun 17token-otsakkeeseen. Älä korvaa sitä Bearer-token-määrityksellä vain siksi, että jokin toinen API käyttää kyseistä mallia. Tarkista myös, lisäävätkö perityt kokoelma-asetukset tahattoman Authorization-otsakkeen.

3. Lisää JSON-runko

Avaa Body, valitse raw ja sitten JSON. Syötä:

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

Ulommat hakasulkeet ovat tärkeitä: tämä pyyntö käyttää taulukkoa, vaikka siinä olisi vain yksi lähetys. Käytä lainausmerkkejä, poista ylimääräiset pilkut äläkä lisää kommentteja JSONiin. Jos dokumentaatio edellyttää kuljetusliikkeeltäsi tai lähetykseltäsi lisätietoja, lisää dokumentaatiossa määritetyt kentät ennen lähettämistä.

4. Lähetä pyyntö ja tarkastele tulosta

Napsauta Send. Tarkista ensin, saitko lainkaan HTTP-vastausta. DNS-virhe, TLS-virhe, välityspalvelinongelma tai aikakatkaisu eroaa vastauksesta, joka ilmoittaa pyynnön olevan virheellinen. Tarkastele seuraavaksi vastausrungosta toiminnon tulosta ja lähetyskohtaisia hyväksymis- tai hylkäystietoja.

Tallenna pyyntö nimellä ”Register test shipment”. Kirjaa HTTP-tila, API-tulos ja mahdollinen virheilmoitus kopioimatta tokenia. Jos rekisteröinti epäonnistuu, ratkaise virhe ennen etenemistä. Muuttumattoman pyynnön toistuva lähettäminen vaikeuttaa vianmääritystä ja saattaa kuluttaa tilin resursseja.

Toista pyyntö curlilla

Seuraavissa komennoissa käytetään POSIX-tyylistä komentotulkkia, kuten Bashia tai Zsh:ta. PowerShellissä ja Windowsin komentokehotteessa lainaus- ja muuttujasäännöt ovat erilaiset. Käytä PowerShellissä tarvittaessa komentoa curl.exe kutsuaksesi curl-suoritettavaa tiedostoa komentotulkille ominaisen aliaksen sijaan.

Aseta perus-URL ja lataa tunnistetietosi ympäristömuuttujaan tavanomaisen salaisuuksien käsittelyprosessisi kautta:

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

Ympäristömuuttuja pitää tunnistetiedon poissa uudelleenkäytettävästä esimerkistä, mutta se ei ole täydellinen salaisuuksien hallintajärjestelmä. Vältä paikallisessa testauksessa oikean tokenin kirjoittamista komentoon, jonka komentotulkki tallentaa historiaan. Käytä automaatiossa alustasi salaisuussäilöä ja rajoita lokitulosteita.

Luo tiedosto nimeltä shipment.json ja korvaa paikkamerkki testisi seurantanumerolla:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Lähetä rekisteröintipyyntö:

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'

Tämä tallentaa vastausrungon tiedostoon register-response.json ja tulostaa HTTP-tilan erikseen. Yhteys- ja kokonaisaikakatkaisut ovat paikallisen testauksen valintoja, eivät 17TRACK-palvelun takuita. Avaa tallennettu tiedosto API-tuloksen tarkastelemiseksi; pelkkä tilarivi ei riitä.

curl voi suorittaa siirron onnistuneesti, vaikka palvelin palauttaisi HTTP-virhevastausen. Vastaavasti siirtovirhe voi estää käyttökelpoisen API-vastauksen saapumisen. Kun kirjoitat skriptejä, käsittele curlin poistumistila, HTTP-tila ja sovellustason tulos erillisinä signaaleina.

Pyydä lähetyksen seurantatiedot

Kun olet vahvistanut rekisteröinnin, kopioi Postman-pyyntö ja vaihda URL-osoitteeksi {{base_url}}/gettrackinfo. Säilytä POST-menetelmä, todennusotsake, sisältötyyppi ja lähetyksen runko. Tallenna pyyntö erikseen, jotta et vahingossa rekisteröi lähetystä uudelleen silloin, kun aiot hakea tietoja.

Vastaava curl-pyyntö on:

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'

Älä oleta, että juuri rekisteröity lähetys palauttaa heti täydellisen tapahtumahistorian. Tietojen saatavuus riippuu lähetyksestä ja palvelun käsittelystä. Jos tietoja ei ole vielä saatavilla, noudata dokumentoitua haku- ja päivitysohjetta sen sijaan, että rekisteröisit saman numeron toistuvasti tai käyttäisit tiheää kyselysilmukkaa.

Lue vastaus kolmella tasolla

  1. Siirtotaso: muodostiko asiakas yhteyden ja saiko se HTTP-vastauksen?
  2. Toimintotaso: hyväksyikö API pyynnön ja onnistuiko yksittäinen lähetys?
  3. Lähetystiedot: tunnistavatko palautetut tiedot tarkoitetun paketin, ja mitä sen tila tai tapahtumahistoria todella osoittaa?

Etsi tila-, kuljetusliike- ja tapahtumakentät virallisesta vastausskeemasta. Säilytä ero normalisoidun lähetyksen tilan ja kuljetusliikkeen alkuperäisen tapahtumakuvauksen välillä. Onnistunut haku ei osoita toimitusta, eivätkä puuttuvat tapahtumat osoita paketin kadonneen.

Säilytä aikaleimoja tallentaessasi mukana toimitettu aikavyöhyke tai siirtymä. Vältä eri muodoissa olevien raakojen päivämäärämerkkijonojen lajittelua ja oletusta, että ne muodostavat oikean aikajärjestyksen. Erota myös aika, jolloin sovelluksesi haki tietueen, ajasta, jolloin lähetystapahtuma tapahtui.

Selvitä ongelmat muuttamatta kaikkea kerralla

  • Ei vastausta: tarkista isäntänimi, verkkoyhteys, välityspalvelinasetukset, TLS-määritys ja paikallinen aikakatkaisu. Älä poista sertifikaatin vahvistusta käytöstä rutiininomaisena korjauksena.
  • Todennus epäonnistui: varmista, että token on aktiivinen, 17token-otsake on mukana ja että valittu Postman-ympäristö ratkaisee muuttujan oikein. Tarkista tahattomat välilyönnit.
  • Virheellinen pyyntö: tarkista API-versio, toimintopolku, POST-menetelmä, sisältötyyppi ja JSON-taulukon rakenne dokumentaatiota vasten.
  • Lähetys hylättiin: lue lähetyskohtainen virhe. Tarkista numero ja mahdolliset vaaditut kuljetusliiketiedot sen sijaan, että käsittelisit jokaista hylkäystä todennusongelmana.
  • Seurantatapahtumia ei ole: vahvista rekisteröinti ja tarkoitetun lähetyksen identiteetti. Tarkista, tarvitaanko kuljetusliikkeen tiedot ja ovatko päivitykset saatavilla ennen uutta yritystä.
  • Postman toimii, mutta curl ei: vertaa ratkaistua URL-osoitetta, todellisia otsakkeita ja rungon tavuja. Komentotulkin lainausmerkit ja määrittämättömät ympäristömuuttujat ovat tavallisia syitä pyyntöjen eroamiseen.

Muuta yksi muuttuja testiä kohden ja pidä lyhyt kirjaus tuloksesta. Jos tarkastelet Postmanin konsolia tai käytät curlin verbose-tulostetta, käsittele tulostetta arkaluonteisena: pyyntöotsakkeet voivat paljastaa tunnistetietoja. Peitä salaisuudet ja asiakastiedot ennen diagnostiikkatietojen jakamista.

Tiedä, milloin ohje on valmis

Olet suorittanut merkityksellisen ensimmäisen integraatiotestin, kun molemmat asiakasohjelmat lähettävät tarkoitetun pyynnön, rekisteröinti on ymmärretty, haku palauttaa tulkittavan tuloksen ja osaat erottaa API-virheen lähetyksestä, jolla ei ole uutta tietoa. Pelkät vastaavat HTTP-tilakoodit eivät osoita, että asiakasohjelmat toimivat samalla tavalla.

Ennen työnkulun siirtämistä sovellukseen säilytä tunnistetiedot palvelimella, validoi syötteet ja käytä jäsenneltyä virheenkäsittelyä. Tutustu tilisi dokumentoituihin nopeusrajoihin, erärajoihin, uudelleenyritysohjeisiin ja päivitysten toimitusvaihtoehtoihin. Älä oleta, että rekisteröinti on turvallista yrittää uudelleen sokeasti aikakatkaisun jälkeen: palvelin on saattanut käsitellä pyynnön, vaikka asiakas ei saanut vastausta.

Lisää testit virheellisille tunnistetiedoille, virheelliselle JSONille, virheelliselle lähetysnumerolle, jo rekisteröidylle lähetykselle, puuttuville seurantatiedoille ja verkkoyhteyden aikakatkaisulle. Jokaisen tapauksen tulee johtaa harkittuun sovelluksen toimintaan käsittelemättömän poikkeuksen tai harhaanjohtavan asiakasnäytön sijaan.

Usein kysytyt kysymykset

Voinko testata ilman oikeaa seurantanumeroa?

Voit testata joitakin pyynnön validointitoimintoja virheellisellä arvolla, mutta se ei vahvista lähetysten seurantaa. Testaa todellisia tapahtumia käyttämällä valtuutettua lähetystä tai dokumentoitua testikohdetta, jos palvelu tarjoaa sellaisen. Älä oleta satunnaisten esimerkkienumeroiden kuuluvan hiekkalaatikkoon.

Miksi HTTP 200 -vastaus sisältää silti virheen?

HTTP-tila ja sovellustason tulokset kuvaavat eri tasoja. Palvelin voi vastaanottaa ja käsitellä pyynnön onnistuneesti samalla, kun se ilmoittaa yksittäisen lähetyksen hylkäämisestä. Lue vastausrunko ja dokumentoitu lähetyskohtainen tulos, älä pelkkää HTTP-tilaa.

Miksi seurantatietojen hakemiseen käytetään POSTia?

Käytä päätepistesopimuksessa määritettyä menetelmää. Tämä hakuesimerkki hyväksyy lähetyksen tunnisteet JSON-pyynnön rungossa POSTin kautta. Sen vaihtaminen GETiksi vain siksi, että toiminto lukee tietoja, ei säilytä dokumentoitua pyyntöä.

Pitäisikö API-token sijoittaa selaimen JavaScriptiin?

Älä upota yksityisiä API-tunnistetietoja julkisesti toimitettavaan frontend-koodiin. Reititä pyynnöt valtuutetun taustapalvelun kautta, joka suojaa tunnistetiedon, validoi syötteet ja hallitsee, mitä lähetystietoja kukin käyttäjä voi käyttää.

Tarvitsenko sekä Postmania että curlia tuotantoon?

Et. Ne ovat hyödyllisiä testaus- ja diagnostiikkatyökaluja. Tuotantosovelluksesi voi käyttää sopivaa HTTP-asiakasohjelmaa. Säilytä puhdistettu Postman-pyyntö tai curl-komento toistettavana viitteenä ilman aktiivista tokenia tai tarpeettomia asiakastietoja.

Lähteet