Hogyan kérhető le a küldemény legfrissebb állapota API-n keresztül webhookra várakozás nélkül
A legfrissebb elérhető szállítási állapot lekéréséhez webhookra való várakozás nélkül küldj hitelesített kérést a nyomkövetési szolgáltatód szállítmány-lekérdező API-jához. A választ használd az alkalmazásod azonnali frissítésére, majd hagyd engedélyezve a webhookokat a későbbi változásokhoz. A fontos különbség az, hogy egy lekérdezés általában a szolgáltató legutóbb tárolt nyomkövetési adatait kéri le; nem feltétlenül indít új ellenőrzést a fuvarozónál.

Ez a megközelítés akkor hasznos, amikor egy ügyfél megnyit egy rendelési oldalt, egy ügyfélszolgálati munkatársnak frissítésre van szüksége, vagy a rendszerednek helyre kell állnia egy kihagyott értesítés után. A megbízható megvalósítás az igény szerinti lekérdezéseket, az egyértelmű frissességi jelzőket, valamint a duplikált vagy sorrenden kívül érkező frissítések elleni védelmet ötvözi.
Döntsd el, mit jelent a „legfrissebb szállítási állapot”
Mielőtt végpontot választasz, különítsd el egymástól azt a három műveletet, amelyek hasonlónak tűnhetnek, de eltérő eredményeket adnak.
| Művelet | Mit tesz | Mit nem állapít meg |
|---|---|---|
| Saját adatbázis olvasása | Visszaadja azokat a nyomkövetési adatokat, amelyeket az alkalmazásod már tárol. | Azt, hogy a szolgáltató kapott-e újabb frissítést. |
| A nyomkövetési API lekérdezése | Lekéri a szolgáltató lekérdezési műveletén keresztül elérhető adatokat. | Azt, hogy történt-e új fuvarozói lekérdezés a kérés során. |
| Nyomkövetés frissítésének kérése | Újabb upstream ellenőrzést kér, ha a szolgáltató ezt a műveletet biztosítja. | Azt, hogy a fuvarozónál van-e új szkennelés, illetve hogy a frissítés szinkron módon befejeződik-e. |
Használj lekérdezést, amikor azonnali válaszra van szükséged. Frissítési műveletet csak akkor vizsgálj, ha azt szeretnéd, hogy a szolgáltató újabb upstream ellenőrzést próbáljon végrehajtani. Ne feltételezd, hogy egy cache-megkerülő paraméter hozzáadása, egy kérés megismétlése vagy egy HTTP cache-control fejléc elküldése arra kényszeríti a fuvarozót, hogy új adatokat szolgáltasson.
A szállítmány láthatóságának több szakasza van: a fuvarozó rögzít egy eseményt, a nyomkövetési szolgáltató megszerzi azt, az alkalmazásod pedig fogadja vagy lekéri. A közvetlen API-kérés megkerülheti az értesítés kézbesítésére való várakozást, de a lánc korábbi szakaszaiban fellépő késedelmeket nem szüntetheti meg.
Ellenőrizd a lekérdezési szerződést a kód írása előtt
A nyomkövetési szolgáltatást integráló fejlesztő felel ezért a munkafolyamatért. A szolgáltató aktuális dokumentációjával kezdd, ne egy régi integrációs példából kimásolt végponttal. Erősítsd meg a következő részleteket:
- Szállítmányazonosítás: A lekérdezés nyomkövetési számot, belső szállítmányazonosítót vagy fuvarozóazonosítóval együtt megadott nyomkövetési számot fogad el?
- Regisztrációs követelmények: Regisztrálni kell a szállítmányt a lekérdezés előtt?
- Hitelesítés: Melyik fejléc vagy hitelesítési mechanizmus szükséges?
- A válasz jelentése: A művelet tárolt adatokat ad vissza, adatgyűjtést indít, vagy később ellenőrizendő feladatot ad vissza?
- Eredmény kezelése: Tartalmazhat-e egy sikeres HTTP-válasz szállítmányszintű hibát vagy függőben lévő eredményt?
- Használati korlátozások: Milyen sebességkorlátok, kötegméret-korlátok és fiókspecifikus korlátozások érvényesek?
- Frissességi mezők: Mely időbélyegek jelölik a fuvarozói eseményeket, a szolgáltatói frissítéseket és a válasz létrehozását?
17TRACK-integráció esetén a Tracking API a megfelelő termék, nem pedig a fogyasztói nyomkövetési oldal vagy az áruház nyomkövetési felülete. Használd a hivatalos API-dokumentációt az integrációhoz szükséges nyomkövetési információs lekérdezési művelet, hitelesítés, kérésmezők és válaszstruktúra megerősítéséhez. A lekérdezést és a webhookok kezelését külön alkalmazási útvonalként kezeld, amelyek ugyanazt a szállítmányrekordot frissítik.
Kerüld a frissítési viselkedéssel vagy a lekérdezések gyakoriságával kapcsolatos feltételezések rögzítését a kódban. Ezeknek a részleteknek meg kell felelniük az általad ténylegesen használt műveletnek és szolgáltatási feltételeknek.
Építs igény szerinti lekérdezést a háttérrendszereden keresztül
Gyakorlati megoldásként hozz létre hitelesített végpontot a saját alkalmazásodban. A böngésző ezen a végponton keresztül kér frissítést a szállítmányról; a szerver ellenőrzi a jogosultságot, eldönti, szükséges-e szolgáltatói lekérdezés, majd normalizált eredményt ad vissza.
A következő útvonal egy példa az alkalmazásodban létrehozható végpontra. Ez nem 17TRACK-végpont és nem szolgáltatói kérés-specifikáció.
GET /api/orders/{order_id}/shipment-statusHasználd a rendelésazonosítót a szállítmány szerveroldali kikereséséhez. Ne engedd, hogy egy hívó pusztán egy nyomkövetési szám kérésben történő lecserélésével lekérhesse egy másik ügyfél nyomkövetési előzményeit. A szolgáltatói API-hitelesítő adatot a háttérrendszeren tartsd, ne a böngésző JavaScript-kódjában vagy egy mobilalkalmazás csomagjában.
Megvalósítható kérésfolyamat
- Hozzáférés engedélyezése. Erősítsd meg, hogy az ügyfél vagy a munkatárs megtekintheti a rendelést.
- A szállítmány feloldása. Olvasd ki a tárolt nyomkövetési azonosítót és adott esetben a fuvarozói információkat.
- Helyi frissesség ellenőrzése. Ha már létezik friss sikeres lekérdezés, használd újra az alkalmazás frissességi szabályzata szerint.
- A szolgáltató lekérdezése szükség esetén. Használd a dokumentált műveletet és korlátozott kérési időkorlátot.
- Az eredmény érvényesítése. Ellenőrizd a HTTP-eredményt és a szállítmányszintű eredményt is.
- Az információk egyesítése. Alkalmazd ugyanazokat a normalizálási és egyeztetési szabályokat, mint a webhook-eseményeknél.
- Állapot és frissesség visszaadása. Add vissza a legutóbbi esemény időpontját és az utolsó sikeres szolgáltatói ellenőrzés időpontját, ha elérhetők.
A helyi frissességi szabályzat mérnöki döntés, nem a fuvarozói frissítések gyakoriságára vonatkozó állítás. Az interfész követelményei, a szolgáltatói korlátok, a szállítmányok mennyisége és a lekérdezések megfigyelt hasznossága alapján válaszd ki. Egy frissítési gombra ismételten kattintó ügyfél nem hozhat létre korlátlan upstream-kéréssorozatot.
Normalizáld a választ a frissesség kitalálása nélkül
Az alkalmazásod stabil belső formátumot adhat vissza akkor is, ha a szolgáltatói válaszstruktúrák eltérnek. Ez a szemléltető objektum a saját alkalmazási szerződésed, nem tényleges szolgáltatói hasznos teher:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}Minden időbélyeget csak akkor tölts ki, ha ismert a jelentése. Azt az időpontot, amikor a szervered megkapta a választ, a lekérdezési metaadatok között kell tárolni; nem szabad úgy megjeleníteni, mintha ez lenne a csomag mozgásának időpontja. Ha a szolgáltató nem ad szolgáltatói frissítési időbélyeget, hagyd ki ezt a mezőt vagy állítsd null értékre, ahelyett hogy másik időbélyeget helyettesítenél be.
Az ügyfélfelületen válaszd külön az üzeneteket: a „Legutóbbi fuvarozói esemény” a szállítmány tevékenységét írja le, míg a „Nyomkövetés ellenőrizve” az alkalmazásod lekérési tevékenységét jelzi. Ez a megkülönböztetés megakadályozza, hogy egy változatlan szkennelés újonnan rögzített eseménynek tűnjön.
Akadályozd meg, hogy az API-lekérdezések és a webhookok felülírják egymást
Amikor mindkét mechanizmus aktív, ugyanaz az esemény lekérdezésen és webhookon keresztül is megérkezhet. Az is előfordulhat, hogy a befejezésük sorrendje eltér az indításuk sorrendjétől. Egy előbb indított lekérdezés akkor fejeződhet be, amikor egy webhook már újabb információt szolgáltatott.
Ne használj „az utolsó válasz nyer” logikát. A legutóbb beérkezett hasznos teher nem feltétlenül a legfrissebb szállítmányállapot.
- Osztozzon minden frissítés egyetlen feldolgozási folyamaton. A lekérdezési eredményeket és a webhook-terheket ugyanazokon az érvényesítési, normalizálási és perzisztálási függvényeken keresztül küldd.
- Szűrd ki a duplikált eseményeket. Előnyben részesítsd a dokumentált eseményazonosítót. Ha nincs ilyen, gondosan meghatározott ujjlenyomatot készíts az elérhető mezőkből, például az esemény idejéből, állapotából, helyéből és leírásából.
- Használj ismert jelentésű sorrendezési mezőket. A dokumentált revízió vagy sorszám hasznosabb annál, mint annak feltételezése, hogy a beérkezési idő jelenti az esemény sorrendjét.
- Őrizd meg az előzményeket. Egy újonnan beérkezett esemény kitölthet egy korábbi hiányt anélkül, hogy megváltoztatná az aktuális szállítmány-összegzést.
- Engedélyezd a korrekciókat. Az állapotok nem alkotnak univerzális, lineáris létrát. Kövesd a dokumentált korrekciós viselkedést ahelyett, hogy végleg elutasítanál minden látszólagos visszalépést.
Ha az események sorrendje bizonytalan, őrizd meg az eredeti hasznos terhet és annak eredetét a vizsgálathoz. Ne oldd fel a bizonytalanságot esemény-időbélyeg kitalálásával, és ne feltételezd, hogy minden fuvarozói időbélyeg ugyanahhoz az időzónához tartozik.
Kezeld eltérően a hiányzó adatokat és a sikertelen kéréseket
Az üres eredmény, a változatlan eredmény és a sikertelen kérés nem eredményezheti ugyanazt az ügyfélüzenetet.
A lekérdezés sikeres, de az állapot nem változott
Tartsd meg a meglévő szállítmányállapotot, és frissítsd az utolsó sikeres lekérdezés időpontját. Ne hozz létre új szállítmányeseményt pusztán azért, mert egy újabb lekérdezés befejeződött. Ha az ügyfélnek további részletekre van szüksége, jelenítsd meg a meglévő eseményelőzményeket, és jelezd, hogy nem érkezett újabb nyomkövetési esemény.
A szállítmányhoz még nincs nyomkövetési információ
Ellenőrizd, hogy szükséges-e a regisztráció, helyes-e az azonosító és a fuvarozó, valamint hogyan jelzi a szolgáltató a függőben lévő adatgyűjtést. Az események hiánya önmagában nem bizonyítja, hogy a nyomkövetési szám érvénytelen vagy hogy a csomag elveszett. Őrizd meg a szolgáltató különbségtételét az ismeretlen azonosító, információra váró regisztrált szállítmány és a feldolgozhatatlan kérés között.
A szolgáltatói kérés időtúllép vagy meghiúsul
Ha van korábbi érvényes állapotod, azt add vissza egyértelmű jelzéssel arról, hogy a legutóbbi ellenőrzés sikertelen volt. A korábbi sikeres lekérdezés időbélyegét hagyd változatlanul. A hálózati hiba nem kézbesítési kivétel, ezért nem változtathatja meg a csomag üzleti állapotát.
Megfelelő átmeneti hibák esetén használj korlátozott számú, visszalépéssel és véletlenszerű késleltetéssel végzett újrapróbálkozást. Ne próbáld ismételten a hibás hitelesítő adatokat vagy formailag hibás kéréseket. Ha a válasz Retry-After értéket ad, a szolgáltatói szerződés és a HTTP-szemantika szerint értelmezd. A HTTP-specifikáció szerint ez az érték másodpercben megadott késleltetésként vagy HTTP-dátumként is kifejezhető.
Több kérés érkezik ugyanahhoz a szállítmányhoz
Vond össze az egyidejű lekérdezéseket, hogy egyetlen upstream-kérést oszthassanak meg. Alkalmazz fiók- és szállítmányszintű korlátozásokat, és akadályozd meg, hogy egy automatikus újrapróbálkozás több alkalmazási rétegen keresztül megsokszorozódjon. Ha a kötegelt feldolgozás támogatott, minden szállítmány eredményét külön vizsgáld meg ahelyett, hogy az egész köteget sikeresnek tekintenéd csak azért, mert a HTTP-kérés befejeződött.
Használd a lekérdezést ellenőrzött tartalékként
Webhookok nélkül az ütemezett lekérdezés naprakészen tarthatja az adatbázisodat, de ehhez kifejezett üzemeltetési szabályzatra van szükség. Döntsd el, mely szállítmányok maradnak jogosultak, hogyan befolyásolják a hibák az ütemezést, és mikor áll le a rutinszerű lekérdezés.
A legtöbb integráció esetén ésszerű kiindulópont a hibrid kialakítás: a webhookok kezelik a háttérben történő változásokat, az igény szerinti lekérdezések szolgálják az interaktív kéréseket, az egyeztetési feladatok pedig ellenőrzik a figyelmet igénylő rekordokat. Ez architekturális ajánlás, nem garancia arra, hogy minden fiók esetében ez minimalizálja a költségeket.
- Részesítsd előnyben az aktív szállítmányokat és a megoldatlan lekérési hibákat tartalmazó rekordokat.
- Kerüld minden korábbi szállítmány lekérdezését minden ütemezett futtatáskor.
- Határozd meg a befejezett szállítmányok kezelését, beleértve az üzleti folyamat által megkövetelt korrekciós időablakot.
- Kövesd nyomon, hogy a lekérdezések milyen gyakran találnak valóban új információt.
- Az egyre gyakoribb lekérdezéssel való elfedés helyett vizsgáld ki a webhook-kézbesítési problémákat.
Figyeld a szolgáltatói kérések késleltetését, a sikertelen lekérdezéseket, a sebességkorlát-válaszokat, valamint a lekérdezett adatok és a webhookokkal betöltött rekordok közötti különbségeket. Külön figyeld a legutóbbi fuvarozói esemény korát. Sikeres API-válaszok mellett is előfordulhat, hogy a nyomkövetési információ nem változott.
Teszteld a munkafolyamatot kiadás előtt
A sikeres kérés csak az első teszt. Ellenőrizd azokat a helyzeteket is, amelyek egyébként félrevezető állapotfrissítéseket okozhatnak:
- Egy webhook akkor érkezik, amikor az igény szerinti lekérdezés még fut.
- Két ügyfél vagy munkamenet egyszerre kéri le ugyanazt a szállítmányt.
- A szolgáltató HTTP-sikert ad vissza, de szállítmányszintű hibát jelent.
- A kérés meghiúsul, miután az alkalmazásod már érvényes nyomkövetési információval rendelkezik.
- Egy eseményből hiányzik az időzóna, vagy ismeretlen állapotkódot tartalmaz.
- Egy fuvarozói korrekció megváltoztat egy korábban megjelenített eredményt.
- Egy felhasználó egy másik fiókhoz tartozó szállítmányhoz próbál hozzáférni.
A kiadás feltétele az legyen, hogy az alkalmazás a legjobb ismert szállítmány-információt adja vissza, pontosan ismertesse annak frissességét, és ne rontsa el ezeket az adatokat akkor sem, ha a kérések meghiúsulnak vagy sorrenden kívül érkeznek.
GYIK
Rákényszeríti a fuvarozót az API lekérdezése arra, hogy beszkennelje vagy frissítse a csomagot?
Nem. A nyomkövetési információ lekérése nem idézhet elő fizikai szkennelést. Az, hogy egy kérés indít-e upstream-lekérdezést, a dokumentált művelettől függ. Még egy támogatott frissítés is változatlan adatokat adhat vissza, ha a fuvarozónál nincs újabb esemény.
Használhatok API-lekérdezéseket webhookok beállítása nélkül?
Ha a szolgáltató támogatja a szükséges lekérdezési munkafolyamatot, igény szerinti kérésekre vagy lekérdezésre épülő integrációt készíthetsz. Először erősítsd meg a regisztrációs és lekérdezési követelményeket. Ezután az alkalmazásod feladata lesz eldönteni, mikor ellenőrizzen, szabályozni a kérések mennyiségét és észlelni a változásokat.
Milyen gyakran kérdezzem le a szállítmány állapotát?
Nincs univerzális időköz. Olyan ütemezést válassz, amely megfelel a szolgáltatói korlátoknak, a szállítmányok mennyiségének és annak üzleti értékének, hogy mennyivel korábban találod meg a frissítéseket. Mérd meg, milyen gyakran ad vissza a lekérdezés új eseményeket, majd ennek megfelelően módosíts, ahelyett hogy azt feltételeznéd: a gyakoribb kérések frissebb fuvarozói adatokat eredményeznek.
Miért ad vissza az API olyan információt, amelyet már webhookon keresztül megkaptam?
Mindkét útvonal ugyanazt a mögöttes szállítmányrekordot teheti elérhetővé. A webhook értesítést kézbesít, míg a lekérdezés igény szerint kér le információt. Ugyanazon esemény mindkét csatornán történő fogadása nem feltétlenül hiba; az alkalmazásodnak ki kell szűrnie a duplikációt.
A frissítési gomb felirata legyen „Nyomkövetés frissítése”?
Csak akkor, ha ez a megfogalmazás pontosan írja le a műveletet. Ha a gomb a szolgáltató tárolt adatait kéri le, a „Frissítések keresése” egyértelműbb. A legutóbbi fuvarozói eseményt külön jelenítsd meg attól az időponttól, amikor az alkalmazásod legutóbb sikeresen befejezett egy ellenőrzést.
Források
- 17TRACK Tracking API — a jelen útmutatóban tárgyalt nyomkövetési API-integráció hivatalos termékreferenciája.
- 17TRACK API documentation — referencia a szolgáltatóspecifikus műveletekhez, hitelesítéshez, kérésmezőkhöz és válaszkezeléshez.
- RFC 9110, 10.2.3. szakasz: Retry-After — meghatározza a HTTP-fejléc késleltetési másodpercben és HTTP-dátumban megadott formáit.


