Skip to main content
KezdőlapBlogÚtmutatókHogyan kérhető le a küldemény legfrissebb állapota API-n keresztül webhookra várakozás nélkül

Hogyan kérhető le a küldemény legfrissebb állapota API-n keresztül webhookra várakozás nélkül

17TRACK

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.

A legfrissebb szállítási állapot lekérése API-n keresztül várakozás nélkü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űveletMit teszMit nem állapít meg
Saját adatbázis olvasásaVisszaadja 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éseLeké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-status

Haszná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

  1. Hozzáférés engedélyezése. Erősítsd meg, hogy az ügyfél vagy a munkatárs megtekintheti a rendelést.
  2. 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.
  3. 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.
  4. 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.
  5. Az eredmény érvényesítése. Ellenőrizd a HTTP-eredményt és a szállítmányszintű eredményt is.
  6. Az információk egyesítése. Alkalmazd ugyanazokat a normalizálási és egyeztetési szabályokat, mint a webhook-eseményeknél.
  7. Á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