Skip to main content
KezdőlapBlogÚtmutatókAz első Tracking API-kérésed: Rest Client útmutató Postman és Curl használatával

Az első Tracking API-kérésed: Rest Client útmutató Postman és Curl használatával

17TRACK

Az első tracking API-kérés elküldéséhez állítsa be a végpontot, a hitelesítési fejlécet és a JSON-törzset egy REST-kliensben, küldje el a kérést, majd vizsgálja meg a HTTP-állapotot és a válasz törzsét is. Ez az útmutató a 17TRACK Tracking API használatával mutatja be ugyanezt a munkafolyamatot Postmanben és curlben: regisztráljon egy küldeményt, kérje le a hozzá tartozó nyomkövetési információkat, és ellenőrizze, hogy az eredmény készen áll-e az alkalmazás általi használatra.

Az első Tracking API-kérés REST-kliensben – bemutató

A cél egy kisméretű, reprodukálható integrációs teszt, nem pedig éles telepítés. Szüksége lesz egy API-hitelesítő adatra és egy olyan nyomkövetési számra, amelynek feldolgozására jogosult. Az alábbi parancsok a v2.2 végpontmintát használják; futtatásuk előtt erősítse meg a végpont verzióját és a fiókspecifikus követelményeket a 17TRACK API-dokumentációban.

Értse meg, mit kell elérnie az első kérésnek

A küldeménykövetési integráció két külön feladatból áll: meg kell adni a szolgáltatásnak, hogy melyik küldeményt kövesse, majd le kell kérni az ahhoz a küldeményhez tartozó nyomkövetési információkat. Az itt bemutatott munkafolyamatban ezek külön kérések. A regisztráció nem jelenti azt, hogy a csomag már elindult, és a sikeres regisztráció nem garantálja, hogy a fuvarozói események azonnal elérhetők lesznek.

Az első teszthez egyetlen küldeményt használjon köteg helyett. Így könnyebb elkülöníteni a hitelesítési hibákat, az érvénytelen nyomkövetési számokat és a válasz értelmezését. Az első hasznos mérföldkő nem egyszerűen az, hogy „HTTP 200-at kaptam”. Hanem az, hogy „az API elfogadta a kívánt műveletet, és meg tudom magyarázni a küldeményszintű eredményt”.

A Postman vizuális felületet biztosít a kérések szerkesztéséhez és a válaszok vizsgálatához. A curl ugyanazt a HTTP-kommunikációt teszi reprodukálhatóvá a terminálból. Egyik sem módosítja az API hitelesítési szabályait, a küldemény adatait vagy a feldolgozás működését. Használja azt, amelyik segít tisztábban megvizsgálni a kérést, majd reprodukálja a működő konfigurációt a másik eszközben is.

Készítse elő a hitelesítő adatot, a küldeményt és a kérés részleteit

Mielőtt megnyitná bármelyik klienst, gyűjtse össze a következőket:

  • Engedélyezett API-hitelesítő adat: szerezze be a 17TRACK API-fiók beállításán keresztül. A fogyasztói nyomkövetési munkamenet nem helyettesíti az API-hitelesítő adatot.
  • Valós nyomkövetési szám: olyan küldeményt használjon, amely az Ön tulajdona, vagy amelyhez hozzáférési engedéllyel rendelkezik. A tényleges nyomkövetési adatok tesztelésekor egy nemrég aktív küldemény általában hasznosabb, mint egy kitalált szám.
  • A fuvarozó, ha ismert: a diagnosztika érdekében tartsa kéznél a fuvarozó nevét. Ha az Ön esetében fuvarozóazonosító szükséges, találgatás helyett a dokumentációban meghatározott értéket és mezőt használja.
  • Az aktuális kérési szerződés: erősítse meg az API-verziót, a hitelesítési fejlécet, a kérés sémáját és az esetleges fiókkorlátozásokat.
  • Biztonságos munkaterület: ne helyezzen hitelesítő adatokat, ügyféladatokat vagy teljes nyomkövetési válaszokat nyilvános tárolókba, képernyőképekre vagy megosztott támogatási üzenetekbe.

A minimális kérési példák az alábbi beállításokat használják:

BeállításPéldakonfiguráció
Alap URLhttps://api.17track.net/track/v2.2
Regisztrációs műveletPOST /register
Nyomkövetési információs műveletPOST /gettrackinfo
Hitelesítési fejléc17token: YOUR_API_TOKEN
TörzsformátumContent-Type: application/json, küldeményobjektumok JSON-tömbjével

A nyomkövetési számokat karakterláncként kezelje. Ha numerikus típussá alakítja őket, eltűnhetnek a kezdő nullák, vagy az érték más módon módosulhat. Az alábbi YOUR_TRACKING_NUMBER helyőrzőt a tényleges tesztküldeményével kell helyettesíteni; ez nem működő mintaszám.

A regisztrációs kérés létrehozása Postmanben

1. Hozzon létre egy kis tesztkörnyezetet

A Postmanben hozzon létre egy környezetet három változóval: base_url, tracking_token és tracking_number. Állítsa a base_url értékét a fenti alap URL-re, majd írja be hitelesítő adatát és a küldemény számát a másik két változóba. A kérés elküldése előtt válassza ki ezt a környezetet.

A tokenhez használja a Postman rendelkezésre álló titkosadat-kezelési vezérlőit, és ellenőrizze, hogy a munkaterülete mit oszt meg vagy szinkronizál. Egy érték elrejtése a felületen nem helyettesíti annak szabályozását, hogy ki férhet hozzá. Ne exportáljon kitöltött hitelesítő adatokat olyan gyűjteménnyel együtt, amelyet munkatársaknak vagy nyilvános dokumentációhoz szán.

2. Állítsa be a metódust, az URL-t és a fejléceket

Hozzon létre egy HTTP-kérést, válassza a POST metódust, és URL-ként adja meg a {{base_url}}/register címet. A Headers lapon adja hozzá:

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

Ebben a példában a hitelesítő adat az egyéni 17token fejlécbe kerül. Ne cserélje le Bearer-token konfigurációra csak azért, mert egy másik API ezt a mintát használta. Ellenőrizze azt is, hogy az örökölt gyűjteménybeállítások nem vezetnek-e be véletlenül Authorization fejlécet.

3. Adja hozzá a JSON-törzset

Nyissa meg a Body részt, válassza a raw lehetőséget, majd a JSON formátumot. Írja be:

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

A külső szögletes zárójelek fontosak: ez a kérés tömböt használ, még akkor is, ha csak egy küldeményt tartalmaz. Használjon dupla idézőjeleket, távolítsa el a záró vesszőket, és ne tegyen megjegyzéseket a JSON-ba. Ha a dokumentáció további adatokat ír elő az Ön fuvarozójához vagy küldeményéhez, elküldés előtt adja hozzá a dokumentált mezőket.

4. Küldje el és vizsgálja meg az eredményt

Kattintson a Send gombra. Először ellenőrizze, hogy egyáltalán kapott-e HTTP-választ. A DNS-hiba, a TLS-hiba, a proxyprobléma vagy az időtúllépés különbözik attól a választól, amely megmagyarázza, hogy a kérés érvénytelen volt. Ezután vizsgálja meg a válasz törzsét a művelet eredménye, valamint a küldeményszintű elfogadási vagy elutasítási információk miatt.

Mentse a kérést „Register test shipment” néven. Jegyezze fel a HTTP-állapotot, az API eredményét és az esetleges hibaüzenetet, de ne másolja ki a tokent. Ha a regisztráció sikertelen, oldja meg a hibát, mielőtt továbblépne. Egy változatlan kérés ismételt elküldése megnehezíti a diagnosztikát, és fiókerőforrásokat is felhasználhat.

A kérés reprodukálása curl segítségével

Az alábbi parancsok POSIX-stílusú parancsértelmezőt, például Basht vagy Zsht használnak. A PowerShell és a Windows Command Prompt eltérő idézőjel- és változószabályokkal rendelkezik. PowerShellben szükség esetén használja a curl.exe parancsot a curl futtatható fájl meghívásához a shell-specifikus parancs-álnevek helyett.

Állítsa be az alap URL-t, és a szokásos titkosadat-kezelési munkafolyamatán keresztül töltse be a hitelesítő adatot egy környezeti változóba:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# A folytatás előtt biztonságosan állítsa be a TRACKING_API_TOKEN változót.

A környezeti változó távol tartja a hitelesítő adatot az újrafelhasználható példától, de nem teljes titkosadat-kezelési rendszer. Helyi teszteléskor ne írjon be valódi tokent olyan parancsba, amelyet a parancsértelmező előzményei megőriznek. Automatizáláskor használja a platform titkosadat-tárolóját, és korlátozza a naplók kimenetét.

Hozzon létre egy shipment.json nevű fájlt, és helyettesítse a helyőrzőt a teszt nyomkövetési számával:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Küldje el a regisztrációs kérést:

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'

Ez a válasz törzsét a register-response.json fájlba menti, és külön kiírja a HTTP-állapotot. A kapcsolati és teljes időtúllépések helyi tesztelési beállítások, nem a 17TRACK szolgáltatási garanciái. Nyissa meg a mentett fájlt az API eredményének vizsgálatához; önmagában az állapotsor nem elegendő.

A curl akkor is sikeresen befejezheti az átvitelt, ha a szerver HTTP-hibaválaszt ad vissza. Ezzel szemben egy átviteli hiba megakadályozhatja, hogy használható API-válasz érkezzen. Szkripteléskor a curl kilépési állapotát, a HTTP-állapotot és az alkalmazásszintű eredményt külön jelzésként kezelje.

A küldemény nyomkövetési információinak lekérése

A regisztráció megerősítése után másolja le a Postman-kérést, és módosítsa az URL-t {{base_url}}/gettrackinfo értékre. Tartsa meg a POST metódust, a hitelesítési fejlécet, a tartalomtípust és a küldeménytörzset. Mentse külön, hogy ne regisztrálja véletlenül újra a küldeményt, amikor adatokat szeretne lekérni.

A megfelelő curl-kérés:

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'

Ne feltételezze, hogy egy újonnan regisztrált küldemény azonnal teljes eseménytörténetet ad vissza. Az adatok elérhetősége a küldeménytől és a szolgáltatás feldolgozásától függ. Ha az információ még nem érhető el, kövesse a dokumentált lekérési és frissítési útmutatást ahelyett, hogy ismételten regisztrálná ugyanazt a számot, vagy szoros lekérdezési ciklust futtatna.

A válasz értelmezése három rétegben

  1. Átvitel: csatlakozott-e a kliens, és kapott-e HTTP-választ?
  2. Művelet: elfogadta-e az API a kérést, és sikeres volt-e az egyes küldemény feldolgozása?
  3. Küldeményinformáció: a visszaadott adatok azonosítják-e a kívánt csomagot, és mit állapít meg ténylegesen az állapota vagy eseménytörténete?

A hivatalos válaszséma segítségével keresse meg az állapot-, fuvarozó- és eseménymezőket. Őrizze meg a különbséget a normalizált küldeményállapot és a fuvarozó eredeti eseményleírása között. A sikeres lekérdezés nem bizonyítja a kézbesítést, a hiányzó események pedig nem bizonyítják, hogy a csomag elveszett.

Időbélyegek tárolásakor őrizze meg a megadott időzónára vagy eltolásra vonatkozó információt. Ne rendezzen különböző formátumú nyers dátumkarakterláncokat úgy, hogy közben feltételezi a helyes időrendi sorrendet. Különböztesse meg továbbá azt az időpontot, amikor az alkalmazás lekérte a rekordot, attól az időponttól, amikor a küldemény eseménye történt.

Hibaelhárítás anélkül, hogy mindent egyszerre módosítana

  • Nincs válasz: ellenőrizze a gazdagépnevet, a hálózati hozzáférést, a proxybeállításokat, a TLS-konfigurációt és a helyi időtúllépést. Ne tiltsa le rutinszerű javításként a tanúsítvány-ellenőrzést.
  • Hitelesítési hiba: erősítse meg, hogy a token aktív, a 17token fejléc jelen van, és a kiválasztott Postman-környezet megfelelően oldja fel a változót. Ellenőrizze a véletlen szóközöket.
  • Érvénytelen kérés: a dokumentáció alapján ellenőrizze az API-verziót, a művelet útvonalát, a POST metódust, a tartalomtípust és a JSON-tömb szerkezetét.
  • Elutasított küldemény: olvassa el a küldeményspecifikus hibát. Ellenőrizze a számot és a szükséges fuvarozói információkat, ahelyett hogy minden elutasítást hitelesítési problémaként kezelne.
  • Nincsenek nyomkövetési események: erősítse meg a regisztrációt és a kívánt küldeményazonosságot. Ellenőrizze, hogy szükség van-e fuvarozói információra, és hogy elérhetők-e frissítések az újrapróbálkozás előtt.
  • A Postman működik, de a curl nem: hasonlítsa össze a feloldott URL-t, a tényleges fejléceket és a törzs bájtjait. A shell-idézőjelek és a be nem állított környezeti változók gyakori okai annak, hogy a kérések eltérnek.

Tesztenként egy változót módosítson, és vezessen rövid feljegyzést az eredményről. Ha megvizsgálja a Postman konzolját, vagy a curl részletes kimenetét használja, kezelje a kimenetet érzékeny adatként: a kérés fejlécei hitelesítő adatokat fedhetnek fel. Diagnosztikai adatok megosztása előtt takarja ki a titkokat és az ügyfél-információkat.

Tudja, mikor teljes az útmutatóban bemutatott folyamat

Akkor hajtott végre értelmes első integrációs tesztet, ha mindkét kliens a kívánt kérést küldi, a regisztráció eredménye érthető, a lekérés értelmezhető eredményt ad, és meg tudja különböztetni az API-hibát attól az esettől, amikor a küldeményhez nincs új információ. Önmagában az egyező HTTP-állapotkódok nem bizonyítják, hogy a két kliens azonosan működött.

Mielőtt a munkafolyamatot alkalmazásba helyezné, tartsa a hitelesítő adatokat a szerveren, ellenőrizze a bemeneteket, és használjon strukturált hibakezelést. Tekintse át a dokumentált sebességkorlátokat, kötegkorlátokat, újrapróbálkozási útmutatást és a frissítések kézbesítési lehetőségeit a fiókjához. Ne feltételezze, hogy időtúllépés után a regisztráció gondolkodás nélkül biztonságosan újrapróbálható: előfordulhat, hogy a szerver feldolgozta a kérést, miközben a kliens nem kapta meg a választ.

Adjon teszteket érvénytelen hitelesítő adathoz, hibás JSON-hoz, érvénytelen küldeményszámhoz, már regisztrált küldeményhez, nem elérhető nyomkövetési adatokhoz és hálózati időtúllépéshez. Mindegyik esetnek szándékos alkalmazásszintű eredményhez kell vezetnie, nem pedig kezeletlen kivételhez vagy félrevezető, ügyfél felé megjelenő állapothoz.

GYIK

Tesztelhetek valódi nyomkövetési szám nélkül?

Érvénytelen értékkel tesztelheti a kérés érvényesítésének bizonyos részeit, de ez nem ellenőrzi a küldeménykövetést. Valós események teszteléséhez használjon engedélyezett küldeményt, vagy dokumentált tesztkörnyezetet, ha a szolgáltatás biztosít ilyet. Ne feltételezze, hogy a tetszőleges mintaszámok sandboxhoz tartoznak.

Miért tartalmaz mégis hibát egy HTTP 200-válasz?

A HTTP-állapot és az alkalmazási eredmény különböző rétegeket ír le. A szerver sikeresen fogadhatja és feldolgozhatja a kérést, miközben jelzi, hogy egy adott küldeményt elutasított. Ne csak a HTTP-állapotot, hanem a válasz törzsét és a dokumentált küldeményszintű eredményt is olvassa el.

Miért POST-tal kérjük le a nyomkövetési információkat?

A végpont szerződésében meghatározott metódust használja. Ez a lekérési példa POST-tal fogadja a küldeményazonosítókat egy JSON-kéréstörzsben. Ha GET-re módosítja, mert a művelet adatokat olvas, nem tartja meg a dokumentált kérést.

Elhelyezhetem az API-tokent böngészőben futó JavaScriptben?

Ne ágyazzon be privát API-hitelesítő adatot nyilvánosan kézbesített frontendkódba. A kéréseket irányítsa engedélyezett backendhez, amely védi a hitelesítő adatot, ellenőrzi a bemeneteket, és szabályozza, hogy az egyes felhasználók mely küldeményinformációkhoz férhetnek hozzá.

Szükségem van a Postmanre és a curlre is éles környezetben?

Nem. Ezek hasznos tesztelési és diagnosztikai eszközök. Az éles alkalmazás megfelelő HTTP-klienst használhat. Tartson meg egy megtisztított Postman-kérést vagy curl-parancsot reprodukálható referenciaként, élő token és szükségtelen ügyféladatok nélkül.

Források