Skip to main content
KezdőlapBlogÚtmutatókA szállítmánykövetési API munkafolyamata: a szállítmány regisztrálásától a nyomonkövetési részletek lekéréséig

A szállítmánykövetési API munkafolyamata: a szállítmány regisztrálásától a nyomonkövetési részletek lekéréséig

17TRACK

A küldeménykövetési API-munkafolyamat egy nyomkövetési szám és a szükséges fuvarozói adatok elküldésével kezdődik, majd annak ellenőrzésével folytatódik, hogy sikeres volt-e a regisztráció, a követési adatok elérhetővé válásának megvárásával, végül pedig a küldemény állapotának és eseményelőzményeinek lekérésével. Éles integráció esetén a fejlesztőknek minden követési rekordot egy rendeléshez is hozzá kell kapcsolniuk, kezelniük kell a részleges hibákat, biztonságosan kell feldolgozniuk a frissítéseket, valamint meg kell különböztetniük az elfogadott regisztrációt a fuvarozó tényleges szkennelésétől.

A küldeménykövetési API munkafolyamata a küldemény regisztrációjától a lekérésig

Ez az útmutató ezt a munkafolyamatot ismerteti az ecommerce-platformhoz, rendeléskezelő rendszerhez, raktári alkalmazáshoz vagy ügyfélszolgálati eszközhöz kapcsolódó fejlesztők számára. Elkülöníti az alkalmazástervezési ajánlásokat a szolgáltatóspecifikus API-követelményektől. 17TRACK-integráció esetén az alábbi példák megvalósítása előtt tekintsd meg a hivatalos API-dokumentációt a kérés sémájának, a hitelesítésnek, a támogatott műveleteknek és a válaszmezőknek a megerősítéséhez.

Értsd meg, mit tesz és mit nem tesz a regisztráció

Egy küldemény nyomkövetési szolgáltatásnál történő regisztrációja azt jelenti, hogy egy azonosítót küldesz el, hogy a szolgáltatás az API-szerződésének megfelelően követhesse vagy kezelhesse a küldeményt. Ez nem azonos a postaköltség megvásárlásával, a szállítási címke létrehozásával, a felvétel lefoglalásával vagy a csomag fuvarozónak történő átadásával.

Az alkalmazásban különítsd el a következő három eredményt:

  • Kérés fogadva: Az API választ adott a HTTP-kérésedre.
  • Regisztráció elfogadva: A szolgáltatás elfogadta az egyedi követési rekordot feldolgozásra.
  • Követési információ elérhető: A szolgáltatás rendelkezik olyan küldeményinformációval, amelyet az alkalmazásod lekérhet vagy fogadhat.

Ezeket az eredményeket nem szabad egyetlen „sikeres” jelzőbe összevonni. Egy elfogadott nyomkövetési számhoz még nem feltétlenül tartozik fuvarozói esemény. Ugyanígy egy kötegelt kérés sikeres HTTP-válasza sem bizonyítja, hogy a köteg minden eleme elfogadásra került; vizsgáld meg a szolgáltató által meghatározott alkalmazásszintű eredményszerkezetet.

1. Készítsd elő a küldeményazonosítót és az API-konfigurációt

Mielőtt regisztrációs kérést küldenél, döntsd el, hogyan azonosítod a küldeményt a saját rendszeredben. Önmagában általában nem elegendő a rendelésazonosító, mert egy rendelés több csomagra is felosztható. Minden küldeményhez vagy csomaghoz hozz létre saját belső rekordot, és társítsd azt a megfelelő rendeléshez.

Egy hasznos belső rekord a következő információkat tartalmazza. Ezek javasolt alkalmazásmezők, nem a 17TRACK kérési sémájának részei.

  • Belső küldeményazonosító: A csomag stabil azonosítója.
  • Rendelési hivatkozás: A rendelés- vagy teljesítési rekord, amelyhez tartozik.
  • Nyomkövetési szám: A fuvarozó által kiadott azonosító, szövegként tárolva a kezdő nullák megőrzése érdekében.
  • Fuvarozói adatok: A teljesítési rendszer által megadott fuvarozóazonosító, ha ismert.
  • Szolgáltatói hivatkozás: A nyomkövetési szolgáltatás által visszaadott, későbbi műveletekhez szükséges azonosító.
  • Regisztrációs állapot: Annak nyilvántartása, hogy a beküldés függőben van, elfogadott, elutasított vagy egyeztetésre vár.
  • Követési állapot: A legutóbbi küldeményállapot, a regisztrációs állapottól elkülönítve kezelve.

Beküldés előtt ellenőrizd a bemenetet. Távolítsd el a véletlenül hozzáadott környező szóközöket, de ne írd át a nyomkövetési számot a fuvarozó formátumára vonatkozó feltételezések alapján. Hibaelhárítás céljából őrizd meg az eredeti értéket. Ha a fuvarozó ismert, a szolgáltató dokumentációjában szereplő azonosítóra képezd le, ne egy informális megjelenítési nevet küldj.

A hitelesítést szerveroldalon konfiguráld. A hitelesítő adatokat tartsd a forráskód-kezelésen kívül, válaszd külön a fejlesztési és éles konfigurációt, és rejtsd el a titkokat a naplókból. Ahelyett, hogy egy másik integráció értékeit vennéd át, erősítsd meg a dokumentált API-verziót, kéréskorlátokat, kötegkorlátokat és fiókkövetelményeket.

2. Regisztráld a küldeményt, és rögzítsd az elemenkénti eredményt

A követési rekordot a szolgáltatód dokumentációjában ismertetett regisztrációs művelettel küldd be. Csak a kötelező mezőket és azokat az opcionális adatokat add meg, amelyeknek meghatározott céljuk van. Ne küldj ügyfélneveket, címeket vagy más személyes adatokat csupán azért, mert rendelkezésre állnak a rendelési adatbázisodban.

A következő pszeudokód az alkalmazás sorrendjét szemlélteti. A függvénynevek csak példák; nem API-végpontok és nem SDK-metódusok.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Annyi információt ments el, hogy rekonstruálható legyen, mi történt: a belső küldeményazonosítót, a beküldés idejét, a próbálkozás számát, az elemenkénti eredményt és a szolgáltató kérési hivatkozását. Ne hagyatkozz kizárólag egy átmeneti munkafolyamat-naplóra. Az ügyfélszolgálati és operációs csapatoknak tartós választ kell kapniuk arra, hogy a küldemény regisztrációja sikeres volt-e.

Kezeld külön a kötegelt beküldéseket

Ha az API támogatja a kötegelt regisztrációt, minden visszaküldött elemet kapcsolj össze az eredeti küldeménnyel. Ne jelöld az egész köteget elfogadottnak csak azért, mert a HTTP-kérés sikeresen befejeződött. Mentsd az elfogadott elemeket, különítsd el az elutasítottakat, és vizsgáld meg külön a bizonytalan eredményeket.

Ezzel megakadályozod, hogy egy hibás nyomkövetési szám miatt szükségtelenül újrapróbáld a már sikeres rekordokat. Emellett a műveleti munkatársak számára végrehajtható listát biztosítasz a javítást igénylő rekordokról.

A hálózati időtúllépéseket tekintsd ismeretlen eredménynek

Az időtúllépés nem bizonyítja, hogy a regisztráció sikertelen volt. Előfordulhat, hogy a szolgáltató elfogadta a kérést, mielőtt megszakadt a kapcsolatod. Az újraküldés előtti egyeztetéshez használd a dokumentált idempotencia-viselkedést, a duplikátumkezelést vagy a lekérdezési műveleteket.

Ha a szolgáltató duplikátumkezelése nem egyértelmű, teszteld ellenőrzött rekordokkal, és az automatikus újrapróbálkozások engedélyezése előtt erősítsd meg a szerződést. A regisztrációs feladatok belső duplikációszűrése továbbra is hasznos, de nem helyettesíti annak megértését, hogyan kezeli a távoli szolgáltatás az ismételt kéréseket.

3. Számolj az első követési információk megérkezésével

A regisztráció elfogadása után a követési adatok nem feltétlenül válnak azonnal elérhetővé. A címke már létezhet, mielőtt a fuvarozó rögzítené a fizikai kezelési eseményt. A hiányzó információk miatt szükség lehet a nyomkövetési szám, a fuvarozó kiválasztásának vagy a küldeményspecifikus lekérdezési követelményeknek az ellenőrzésére is.

Ezt az állapotot jelenítsd meg egyértelműen. A „Regisztrálva; követési információra vár” pontosabb, mint akár az „Úton”, akár a „Regisztráció sikertelen”. Ne találj ki kézbesítési becslést vagy mozgási eseményt egy üres felület kitöltésére.

Ha egy rekord üres marad, vizsgáld meg a következő sorrendben:

  1. Erősítsd meg, hogy az egyedi regisztrációt elfogadták.
  2. Hasonlítsd össze a beküldött nyomkövetési számot a teljesítési rekorddal.
  3. Ellenőrizd a fuvarozói leképezést és a dokumentált további lekérdezési követelményeket.
  4. Ellenőrizd ugyanennek a küldeménynek a fuvarozói saját követési oldalát.
  5. Ha a fuvarozónál vannak események, az integrációdban viszont nincsenek, vizsgáld meg a lekérdezési válaszokat, és lépj kapcsolatba az API-szolgáltatóval anonimizált diagnosztikai információk felhasználásával.

Ne alkalmazz bizonyíték nélküli, univerzális várakozási időt. Az eszkalációs szabályoknak tükrözniük kell a szállítási szolgáltatást, a várt átadási folyamatot és a saját operációs vállalásaidat.

4. Kérd le helyesen és értelmezd megfelelően a követési adatokat

Amint a rekord elérhetővé válik, hívd meg a dokumentált követésiadat-lekérdezési műveletet a szükséges azonosítókkal. Ne feltételezd, hogy a regisztráció és a lekérés azonos mezőket fogad el. Egyes API-szerződések különbséget tesznek a nyomkövetési számok, a fuvarozói azonosítók és a szolgáltató által létrehozott rekordhivatkozások között.

Az alkalmazásodnak az információ három rétegét kell elkülönítenie:

  • Küldemény-összefoglaló: Az irányítópultokon, rendelési oldalakon és operációs szűrőkben használt átfogó állapot.
  • Eseményelőzmények: Az egyes megfigyelések, beleértve az eseményleírásokat, időbélyegeket és a megadott helyszíneket.
  • Lekérdezési metaadatok: Mikor kapta vagy kérte le az alkalmazásod az információt, és sikeresen befejeződött-e a kérés.

A sikeres lekérdezés azt jelenti, hogy a lekérdezési művelet sikerült. Nem jelenti azt, hogy a csomag az előző lekérdezés óta mozgott. Értesítés vagy további munkafolyamat indítása előtt hasonlítsd össze a visszaküldött követési adatokat a tárolt rekorddal.

Különítsd el az esemény idejét a lekérés idejétől

A fuvarozói eseményhez tartozó időt külön tárold attól az időtől, amikor a rendszered megkapta azt. A ma délután lekért esemény egy korábbi szkennelést is leírhat. Ha az esemény idejét a lekérés idejével helyettesíted, egy régi frissítés új fizikai mozgásnak tűnhet.

Őrizd meg az eredeti időbélyeget és minden megadott időzónaeltolást. Összehasonlítás céljából csak akkor normalizáld az időbélyegeket, ha az időzóna ismert. Ha egy eseményhez nem tartozik időzónainformáció, őrizd meg ezt a bizonytalanságot, ahelyett hogy csendben a szervered időzónáját rendelnéd hozzá.

Őrizd meg a nyers jelentést a normalizált állapot mellett

A normalizált állapot hasznos a fuvarozók közötti csoportosításhoz, de az eredeti eseményleírás pontosabban magyarázhat egy operációs problémát. Ahol elérhető, mindkettőt tartsd meg. Egy általános kivételkategória önmagában nem feltétlenül árulja el az ügyfélszolgálati munkatársnak, hogy a következő lépés a cím ellenőrzése, a címzett megkeresése vagy egy újabb frissítés megvárása.

Ne vezess le homályos állapotból kézbesítési garanciát, megerősített elvesztést vagy konkrét vámkezelési eredményt. Az alapul szolgáló információ és a működési szabályzatod alapján eszkalálj.

5. Tartsd naprakészen a rekordokat lekérdezéssel vagy webhookokkal

Az adatok egyszeri lekérése elegendő a kapcsolat teszteléséhez, de nem elegendő a küldemények láthatóságának fenntartásához. Éles rendszerednek frissítési mechanizmusra van szüksége. Erősítsd meg a választott szolgáltató által támogatott mechanizmusokat és az azokhoz kapcsolódó feltételeket.

Lekérdezés esetén az alkalmazásod ütemezetten kérdezi le a követési adatokat. A kéréseket a dokumentált korlátokon belül ütemezd, ok nélkül ne kérdezd le ismételten a változatlan rekordokat, és újrapróbálható hibák esetén alkalmazz késleltetést. Egy rendelési oldal megnyitása ne indítson automatikusan korlátlan upstream-kérést; a tárolt követési nézet kiszolgálhatja az oldalt, miközben egy szabályozott háttérfolyamat frissíti azt.

Webhookok használata esetén a szolgáltató dokumentált ellenőrzési mechanizmusával validáld a beérkező kéréseket. A webhook-szerződésnek megfelelően az elfogadott üzeneteket mentés vagy tartós sorba helyezés után nyugtázd, majd aszinkron módon dolgozd fel az eseményeket.

A fogadót úgy építsd fel, hogy kezelje a duplikátumokat és a nem várt érkezési sorrendet, kivéve, ha a dokumentált kézbesítési szerződés mást garantál. Ha elérhető, a duplikációszűréshez használj szolgáltatói eseményazonosítót. Ellenkező esetben határozz meg és tesztelj megfelelő eseménymezőkön alapuló ujjlenyomatot, figyelembe véve, hogy az adataidhoz későbbi módosításokra lehet szükség.

A webhook-alapú integráció szabályozott lekérést is használhat egyeztetéshez. Például egy helyreállítási feladat ellenőrizheti a fogadó kiesése által érintett rekordokat. Ez ellenállóképességi minta, nem engedély a sebességkorlátok vagy a szolgáltatóspecifikus útmutatás figyelmen kívül hagyására.

6. Alakítsd a követési információkat biztonságos üzleti műveletekké

Az ügyfél felé irányuló műveletek elindítása előtt frissítsd a belső küldeményrekordot. Tarts fenn tartós nyilvántartást az értesítésekről és a munkafolyamat-átmenetekről, hogy egy ismétlődő esemény ne küldjön ismételt üzeneteket.

Az üzleti műveleteket érdemi változásokhoz, ne minden API-válaszhoz rendeld. Egy újonnan észlelt kézbesítési esemény indokolhat kézbesítési értesítést. Egy ugyanazt az eseményt tartalmazó ismételt válasz azonban nem. Egy kivétel indokolhat belső felülvizsgálatot, de az ügyfélnek küldött üzenetnek azt kell tükröznie, amit az esemény ténylegesen közöl.

Határozd meg, hogyan kezeled a küldemény befejezettnek tekintése után érkező eseményeket. Ne töröld az eseményelőzményeket, és ne tiltsd le végleg az összes későbbi frissítést csak azért, mert az összefoglaló elérte a végállapotot. A megőrzési, egyeztetési és értesítési szabályaidnak kezelniük kell a jogos korrekciókat anélkül, hogy ismételten újranyitnák a befejezett munkafolyamatokat.

A munkafolyamat alkalmazása 17TRACK-integrációra

Egy egyedi követési integráció esetén a releváns kiindulópontok a 17TRACK Tracking API oldala és annak fejlesztői dokumentációja. A termékoldalt az ajánlat értékelésére, a dokumentációt pedig a tényleges integrációs szerződés meghatározására használd. A fogyasztói követési oldalak nem helyettesítik az API-specifikációkat.

Az adapter megírása előtt erősítsd meg a hitelesítési formátumot, a regisztrációs és lekérdezési műveleteket, a fuvarozó-azonosítási szabályokat, az elemenkénti válaszkezelést és az érvényes kéréskorlátokat. Webhook-alapú feldolgozás esetén erősítsd meg a hasznos adatok sémáját, az ellenőrzési folyamatot, a nyugtázási követelményeket és az újrapróbálkozási viselkedést is.

Ezeket a szolgáltatóspecifikus részleteket tartsd egy adapterben, ahelyett hogy a válaszmezőkre vonatkozó feltételezéseket szétszórnád a rendelési rendszerben. Így az alkalmazás többi része olyan belső fogalmakkal dolgozhat, mint a regisztráció eredménye, a küldemény állapota, az eseményelőzmények és az utolsó sikeres szinkronizálás.

Indítás előtti ellenőrzések a költséges hibák felismeréséhez

  • Elfogadott, de üres rekord: A felület azt mutatja, hogy a követési információ függőben van, nem azt, hogy a csomag mozgásban van.
  • Vegyes kötegeredmény: Minden küldemény saját mentett eredményt kap.
  • Beküldés utáni időtúllépés: A munkafolyamat egyezteti a bizonytalan eredményt, ahelyett hogy automatikusan sikertelennek tekintené.
  • Ismétlődő esemény: A küldemény idővonala és az ügyfélértesítés duplikációmentes marad.
  • Később érkező régebbi esemény: Az esemény megmarad anélkül, hogy vakon felülírná az újabb összefoglalót.
  • Nem elérhető upstream-szolgáltatás: Az ügyféloldal megfelelő frissességi jelzéssel megjelenítheti az utolsó tárolt eredményt.
  • Helytelen fuvarozói leképezés: A rekord dokumentált helyreállítási útvonalon javítható.
  • Felosztott rendelés: Minden csomag megőrzi saját követési állapotát és eseményelőzményeit.
  • Hitelesítő adat vagy hasznos adat kiszivárgása: A naplók diagnosztikai hivatkozásokat tartalmaznak, de nem fednek fel titkokat vagy szükségtelen személyes adatokat.

A gyakorlati befejezési feltétel nem egyszerűen egy sikeres regisztrációs válasz fogadása. Az a képesség, hogy a csomag útja a beküldéstől a frissítésekig nyomon követhető legyen, megmagyarázható legyen az üres vagy hibás eredmény, és a megszakadt feldolgozásból eseményvesztés vagy ismételt ügyfélműveletek nélkül lehessen helyreállni.

GYIK

Létrehoz küldeményt a nyomkövetési szám regisztrációja?

Az itt ismertetett munkafolyamatban nem. A követési regisztráció egy meglévő azonosítót küld el egy követési szolgáltatásnak. A címkelétrehozás, a postaköltség megvásárlása és a fuvarozói foglalás külön műveletek, kivéve, ha egy adott API kifejezetten egyesíti őket.

Miért üresek a követési adatok a sikeres regisztráció után?

A regisztráció elfogadása és a követési adatok elérhetősége különböző feltételek. Előfordulhat, hogy a fuvarozó még nem rögzített eseményt, vagy ellenőrizni kell a nyomkövetési számot, a fuvarozói leképezést vagy a további lekérdezési adatokat. Mielőtt a rekordot sikeresen regisztráltnak tekintenéd, vizsgáld meg az elemenkénti eredményt.

Minden alkalommal regisztrálnom kell a küldeményt, amikor lekérem az állapotát?

Ne használd az ismételt regisztrációt alapértelmezett frissítési mechanizmusként. Tárold az elfogadott regisztrációs állapotot, és használd a dokumentált lekérdezési vagy frissítési mechanizmust. Korrekciók, újraaktiválás vagy duplikált beküldések esetén kövesd a szolgáltató kifejezett szabályait.

Lekérdezést vagy webhookokat használjak?

Azt a mechanizmust használd, amely megfelel a dokumentált API-szerződésnek és a működési követelményeidnek. A lekérdezés szabályozott kérési ütemezést igényel. A webhookok biztonságos, tartós fogadót és duplikációbiztos feldolgozást igényelnek. Ha támogatott, a webhook-frissítések célzott egyeztetéssel praktikus helyreállítási utat biztosíthatnak.

Használhatom a nyomkövetési számot az adatbázisom egyetlen küldeményazonosítójaként?

Ehelyett használj belső küldeményazonosítót. A nyomkövetési számot és a releváns fuvarozói környezetet a rekord attribútumaiként tárold. Ez megkönnyíti a felosztott rendelések, a javított nyomkövetési számok és a szolgáltatóspecifikus hivatkozások kezelését anélkül, hogy megváltoztatnád a belső küldeményazonosítót.

Források

  • 17TRACK Tracking API — hivatalos termékbelépési pont egy 17TRACK API-integráció értékeléséhez.
  • 17TRACK API-dokumentáció — hivatalos referencia a megvalósításspecifikus kérésformátumokhoz, műveletekhez, válaszokhoz és integrációs követelményekhez. Az útmutatóban szereplő pszeudokód és belső mezőjavaslatok alkalmazástervezési példák, nem ennek az API-szerződésnek az idézetei.