Hogyan kapcsoljuk össze a szállítmánykövetési adatokat az Oms rendszerrel: Rendelés-hozzárendelés és szinkronizálási szabályok
A szállítmánykövetési adatok rendeléskezelő rendszerhez (OMS) való csatlakoztatásához rendeljen minden követett csomagot egy belső szállítmányrekordhoz, majd kapcsolja ezt a szállítmányt a rendeléséhez és teljesítési soraihoz. A követési frissítéseket a szolgáltató által támogatott felületen keresztül fogadja, őrizze meg az eredeti eseményeket, és alkalmazzon egyértelmű szabályokat a duplikátumokra, a késői frissítésekre, a szállítmány állapotára és a rendelés lezárására. Ne használja önmagában a követési számot a rendelés azonosítójaként, és ne engedje, hogy egyetlen kézbesítési esemény automatikusan lezárjon egy többcsomagos rendelést.

Ez az útmutató az integrációs mérnököknek és az ecommerce-működési csapatoknak szól, akik ezt a kapcsolatot valósítják meg. Az ajánlott kialakítás elválasztja a fuvarozói megfigyeléseket az üzleti döntésektől: a követési adatok egy csomag útját írják le, míg az OMS dönti el, hogy ez az út mit jelent a teljesítés, az ügyfélkommunikáció és a rendelés lezárása szempontjából.
Határozza meg, melyik rendszer birtokolja az egyes rekordokat
Mielőtt API-kapcsolatot építene, egyeztessen a tulajdonjogról az OMS-adminisztrátorral, a teljesítési csapattal és az ügyfélszolgálattal. Ellenkező esetben egy műszakilag sikeres integráció is felülírhat érvényes üzleti adatokat.
- OMS: A rendelések, a rendelési sorok, a szükséges mennyiségek, a törlések és a rendelés teljesítésére vonatkozó szabályok tulajdonosa.
- Teljesítési rendszer: Az általa létrehozott szállítmány- vagy csomagrekordok tulajdonosa, beleértve a csomagolási hozzárendeléseket és a címkekiosztásokat. Ez lehet maga az OMS vagy egy külön raktári rendszer.
- Követési szolgáltató: Követési megfigyeléseket és a szolgáltató által meghatározott állapotbesorolásokat biztosít.
- Integrációs réteg: Azonosító-kereszthivatkozások, eseményfeldolgozás, normalizálás, újrapróbálás-kezelés és szinkronizálási auditrekordok tulajdonosa.
Ezeket ajánlott határokként kezelje, ne a szoftverével kapcsolatos feltételezésként. Dokumentálja a kivételeket. Ha például a raktár lecserélhet egy szállítási címkét, az integrációnak kifejezett frissítést kell kapnia ettől a rendszertől, ahelyett hogy azt feltételezné, hogy egy újonnan észlelt szám felváltja a régit.
Építse ki a rendelés–csomag hozzárendelést az állapotok szinkronizálása előtt
Egy praktikus kapcsolat: rendelés → teljesítés → csomag → követési hozzárendelés. Az OMS eltérő neveket használhat, vagy egyes rekordokat összevonhat. Őrizze meg a kapcsolatokat akkor is, ha az adatbázis szerkezete eltérő.
Egy rendeléshez több teljesítés is tartozhat, és egy teljesítés több csomagot is tartalmazhat. Egy csomag új követési hozzárendelést vagy kapcsolódó utolsó mérföldes azonosítót is kaphat. Ezek az azonosítók nem hozhatnak létre további rendelt mennyiségeket.
| Rekord | Ajánlott mezők | Cél |
|---|---|---|
| Rendelés | Bérlő- vagy üzletazonosító, megváltoztathatatlan OMS-rendelésazonosító | Elkülöníti a kereskedőket, és elkerüli a megjelenített rendelési számoktól való függést. |
| Teljesítés | Teljesítési azonosító, rendelésazonosító, hozzárendelt sorazonosítók és mennyiségek | Azonosítja, mely megvásárolt tételek teljesítése zajlik. |
| Csomag | Belső csomagazonosító, teljesítési azonosító, ahol elérhető, csomaghozzárendelések | Stabil identitást biztosít a követési címkéktől függetlenül. |
| Követési hozzárendelés | Hozzárendelési azonosító, csomagazonosító, szolgáltatói fiók, fuvarozói azonosító, követési szám, aktív időszak | A beérkező követési megfigyeléseket a megfelelő csomaghoz és hozzárendelési életciklushoz kapcsolja. |
A frissítéseket tárolt kereszthivatkozáson keresztül párosítsa
Amikor létrehoz egy szállítmányt, tárolja a belső azonosítóit, mielőtt regisztrálná azt követésre. Tárolja a dokumentált regisztrációs folyamat által visszaadott, szolgáltató által kiadott követési rekordazonosítót is. Ha a szolgáltató támogat kereskedői hivatkozást, használjon átláthatatlan belső hivatkozást, és helyben őrizze meg a hozzárendelést.
A beérkező frissítéseknél először oldja fel a tárolt szolgáltatói rekordazonosítót a megfelelő szolgáltatói fiókon és bérlőn belül. Ha ez az azonosító nem érhető el, használja a követési szám, a fuvarozó identitása, a fiókkörnyezet és a hozzárendelési előzmények dokumentált kombinációját. Ezt keresési stratégiának tekintse, ne annak garanciájaként, hogy a kombináció globálisan egyedi.
Ne párosítson ügyfélnév, e-mail-cím vagy hatókör nélküli megjelenített rendelési szám alapján. A követési számokat karakterláncként tárolja, hogy a kezdő nullák megmaradjanak. Ne távolítson el karaktereket és ne módosítsa a kis- és nagybetűket, kivéve, ha az adott fuvarozói vagy szolgáltatói szerződés engedélyezi ezt a normalizálást.
Ha a keresés nem ad egyezést, vagy több lehetséges egyezést ad vissza, helyezze a frissítést vizsgálati karanténba. Egy fel nem oldott esemény biztonságosabb, mint egy magabiztos, de rossz ügyfél rendelésére végrehajtott frissítés.
Kezelje a megosztott rendeléseket csomaghozzárendelések kitalálása nélkül
Vegyünk példaként egy három darabot tartalmazó rendelést. Az A csomag két darabot, a B csomag pedig egyet szállít. Az A csomag kézbesítése azt jelenti, hogy két darabról van kézbesítési bizonyíték; nem jelenti azt, hogy a teljes rendelés kézbesítve lett.
Ha a teljesítési rendszer csak azt rögzíti, hogy mindkét csomag ugyanahhoz a teljesítéshez tartozik, ne találjon ki darabszintű hozzárendeléseket. Továbbra is kiszámíthatja, hogy minden szükséges csomag kézbesítve lett-e, de a tételszintű kézbesítési jelentésnek elérhetetlennek vagy kifejezetten bizonytalannak kell maradnia, amíg nem áll rendelkezésre hozzárendelési adat.
Csatlakoztassa a követési API-t tartós adatbeviteli rétegen keresztül
Olyan folyamatot használjon, amely elkülöníti a szolgáltatóval folytatott kommunikációt az OMS-be írástól:
Szállítmány létrehozása → követési regisztráció → beérkező frissítés vagy ütemezett lekérés → tartós eseménytárolás → hozzárendelés és normalizálás → OMS-frissítés → egyeztetés
17TRACK-megvalósítás esetén a Tracking API termékoldala és a hivatalos API-dokumentáció a releváns kiindulópont. Az adapter megvalósítása előtt erősítse meg az alkalmazandó regisztrációs felületet, a fuvarozói azonosítókat, a frissítések kézbesítési lehetőségeit, a hitelesítési követelményeket, az állapotdefiníciókat és a fiókkorlátokat. Az útmutató adatmodellje integrációs ajánlás, nem azt állítja, hogy a 17TRACK ezeket a mezőneveket használja, vagy natív csatlakozót biztosít az Ön OMS-éhez.
Ha a kiválasztott szolgáltató támogat webhookokat, hitelesítse a beérkező kéréseket a dokumentált mechanizmusával, és az elfogadott üzeneteket tartósan tárolja, mielőtt visszaigazolná őket. A lassú OMS-műveleteket tartsa a kérési útvonalon kívül. Kövesse a szolgáltató tényleges visszaigazolási és újrapróbálási szerződését, ne feltételezzen konkrét választestet vagy időkorlátot.
Ha lekérdezés szükséges, tárolja a lekérdezési előrehaladást ott, ahol az API támogatja, szabályozza a párhuzamosságot, és kövesse a dokumentált sebességkorlátokat. Sem a webhook fogadása, sem a sikeres lekérdezés nem bizonyítja, hogy az OMS frissült; ezeket az eredményeket külön rögzítse.
Határozzon meg olyan szinkronizálási szabályokat, amelyek ellenállnak az újrapróbálásoknak és a késői eseményeknek
1. Tegye idempotenssé a feldolgozást
Ugyanazon megfigyelés kétszeri feldolgozása nem duplikálhat szállítmányt, nem növelheti kétszer a mennyiségeket, és nem küldheti el újra ugyanazt az ügyfélértesítést. A HTTP önmagában nem tesz idempotenssé egy tetszőleges POST-műveletet; az integrációnak kell megvalósítania a duplikációvédelmet. Az RFC 9110 ismerteti a HTTP-metódusok idempotenciáját.
Használjon stabil szolgáltatói eseményazonosítót, ha azt dokumentálják és elérhető. Ellenkező esetben határozzon meg ujjlenyomatot a hozzárendelési azonosítóból és a releváns eseménymezőkből, például az esemény időbélyegéből, a forrásállapotból és a helyszínből. Dokumentálja az ütközések vagy a módosult eseményleírások lehetőségét. Őrizze meg a nyers megfigyelést akkor is, ha az nem eredményez újabb OMS-műveletet.
Minden mellékhatást külön védjen. Például az OMS-állapot írásához és az e-mailes értesítéshez saját deduplikációs vezérlés szükséges. Használjon tranzakciós outboxot vagy ezzel egyenértékű tartós munkarekordot, hogy egy folyamat összeomlása ne hagyhasson ütemezett frissítés nélkül elfogadott eseményt.
2. Az esemény idejét és a fogadás idejét külön tárolja
Az esemény bekövetkezési ideje és az integráció általi fogadás ideje különböző kérdésekre válaszol. Tárolja mindkettőt az eredeti időbélyeg-ábrázolással és a megadott időzónaeltolással együtt. Ne rendeljen csendben raktári időzónát olyan eseményhez, amelynek időzónája ismeretlen.
A későn érkező, úton lévő csomagról szóló szkennelésnek általában gazdagítania kell az előzményeket, nem pedig felülírnia egy újabb kézbesített állapotot. Az időbélyegek önmagukban azonban nem elegendők: a szolgáltató javítást adhat ki, és az események időadatai hiányosak lehetnek. Használjon dokumentált sorrend- vagy revíziós mezőket, ha elérhetők, és alkalmazzon kifejezett javítási szabályzatot.
3. Normalizálja az állapotokat a forrás részleteinek törlése nélkül
Hozzon létre egy kis belső szókészletet, amelyet az OMS ért, például: fuvarozói átvételre vár, úton van, kézbesítés alatt, kézbesítve, kivétel és visszaküldés alatt. A szolgáltató dokumentált állapotait képezze le ebbe. Ezek javasolt belső kategóriák, nem univerzális fuvarozói definíciók.
Tárolja az eredeti állapotkódot, leírást, eseményhelyet, szolgáltatói rekordhivatkozást és a leképezési szabály verzióját. A le nem képezett érték felülvizsgálható állapotot hozzon létre, ne automatikusan kézbesített vagy sikertelen állapotot. A címke létrehozása nem tekinthető a fuvarozó fizikai átvétele bizonyítékának, kivéve, ha a forrásesemény kifejezetten alátámasztja ezt az értelmezést.
4. Átmeneti szabályokat használjon egyszerű numerikus rangsor helyett
A szállítmányállapotok nem mindig alkotnak egyenes vonalat. Egy kivételt normál szállítás követhet, és a kézbesítési kísérlet nem kézbesítés. A visszaküldési folyamat egy korábbi kézbesítési esemény után is megkezdődhet.
- Engedélyezze a kivétel megszűnését, ha a későbbi bizonyítékok folytatódó mozgást támasztanak alá.
- Akadályozza meg, hogy egy szokásos történeti szkennelés csendben felülírja a kézbesített állapotot.
- Engedélyezze a dokumentált javítást ellenőrzött revíziós folyamaton keresztül.
- A visszaküldési mozgást külön kövesse a kimenő teljesítéstől, ha az OMS támogatja.
- Az egyértelműtlen vagy ellentmondó bizonyítékokat irányítsa működési sorba.
Verziózza ezeket a szabályokat. Ha egy leképezés megváltozik, döntse el, hogy csak az új eseményekre vonatkozik-e, vagy a korábbi rekordok ellenőrzött újraszámítása is szükséges.
Számítsa ki a rendelés állapotát a szükséges teljesítési kötelezettségek alapján
A csomagállapot és a rendelésállapot külön mező legyen. A kézbesítettként jelölt csomag bizonyítékot szolgáltat az adott csomagról; a rendelés teljesítése a fennmaradó szükséges mennyiségektől és az üzleti szabályzattól függ.
Hasznos alapértelmezés, hogy a rendelést csak akkor jelölje teljesen kézbesítettként, ha minden kézbesítésköteles mennyiséghez érvényes csomagszintű kézbesítési bizonyíték tartozik, és nem maradt feloldatlan szükséges hozzárendelés. A törölt mennyiségeket az OMS törlési szabályai szerint zárja ki. A digitális tételeket, átvételi rendeléseket és egyéb nem szállítási kötelezettségeket saját teljesítési feltételeik alapján kezelje.
A csere-szállítmányok kifejezett kapcsolatokat igényelnek. Ha egy elveszett csomagot pótolnak, döntse el, hogy a pótlás felülírja-e az eredeti kézbesítési kötelezettséget. Ellenkező esetben az eredeti csomag határozatlan ideig akadályozhatja a lezárást, vagy mindkét csomag beleszámíthat a teljesítésbe. A döntést rögzítse, ne kizárólag a követési állapotból vezesse le.
A kézbesítés lezárását tartsa külön a pénzügyi lezárástól, a visszatérítési jogosultságtól és a reklamáció rendezésétől. A fuvarozó kézbesítési eseménye nem engedélyezhet automatikusan visszatérítést, és nem rendezhet ügyfélreklamációt.
Álljon helyre hibákból az auditnyomvonal elvesztése nélkül
Az átmeneti hibákat korlátozott visszalépéssel és a dokumentált újrapróbálási útmutatással kezelje. Különítse el az ideiglenes kapcsolati hibákat az érvénytelen azonosítóktól, a lejárt hitelesítő adatoktól, a jogosultsági hibáktól és a sémakompatibilitási problémáktól. Ez utóbbiak javító intézkedést igényelnek, nem végtelen újrapróbálást.
Tartson fenn sikertelen munkákhoz tartozó sort, amely tartalmazza az érintett bérlőt, csomagot, eseményhivatkozást, megkísérelt műveletet, hibabesorolást és következő műveletet. Elegendő környezetet naplózzon a vizsgálathoz, de ne másoljon szükségtelen ügyféladatokat vagy hitelesítő adatokat a naplókba.
A normál frissítési útvonal mellett futtasson egyeztetést is. Vizsgálja át az elavult követési információval rendelkező aktív szállítmányokat, az elfogadott, de sikertelen OMS-írásokat, a nem párosított megfigyeléseket, valamint az integráció által számított állapot és az OMS közötti eltéréseket. A felülvizsgálat gyakoriságát a kézbesítési kötelezettségek, az API-korlátok és a működési kockázat alapján válassza meg, ne önkényes, mindenhol azonos ütemezést alkalmazzon.
Rendeljen felelőst: a mérnöki csapat kezeli az adatbeviteli és írási hibákat; a teljesítési műveletek oldják meg a hiányzó csomagkapcsolatokat; az ügyfélszolgálat vizsgálja az ügyfélkommunikációt igénylő kivételeket. A felelős nélkül működő sor csupán tárolási hely.
Indítás előtt tesztelje a leképezést és az üzleti szabályokat
Használjon ellenőrzött tesztadatokat és korlátozott éles bevezetést. Tesztelje a következő eseteket mind az eseményelőzmények, mind az eredményül kapott OMS-rekord alapján:
- Egy egycsomagos rendelés normálisan eljut a kézbesítésig.
- Egy megosztott rendelés egyik csomagja kézbesített, a másik még úton van.
- Ugyanazt az eseményt többször fogadják, duplikált mellékhatások nélkül.
- Egy régebbi útközbeni szkennelés a kézbesítés után érkezik.
- Ismeretlen fuvarozó vagy állapot kerül a felülvizsgálati sorba.
- Egy címkét lecserélnek anélkül, hogy új teljesítési kötelezettség jönne létre.
- Egy pótló szállítmány jóváhagyott szabály alapján felülírja az eredeti csomagot.
- Az OMS nem érhető el egy esemény elfogadása után.
- Egy folyamat újraindul egy OMS-írás és annak visszaigazolása között.
- Ugyanaz a megjelenített rendelési szám két üzletben is létezik, keresztenanténes párosítás nélkül.
Akkor indítsa el a rendszert, ha minden elfogadott eseményhez nyomon követhető feldolgozási eredmény tartozik, a bizonytalan egyezések nem frissíthetik automatikusan a rendeléseket, és az üzemeltetők biztonságosan újrajátszhatják a sikertelen munkákat. Ezek hasznosabb elfogadási feltételek annál, mint egyszerűen bemutatni, hogy egy API-kérés sikeres.
GYIK
Összekapcsolhatom közvetlenül a követési számokat a rendelésekkel?
Szigorúan egycsomagos munkafolyamatban kezdetben elegendő lehet a közvetlen kapcsolat. Ennek ellenére használjon belső szállítmányazonosítót a rendelés és a követési hozzárendelés között. Ez migrációs útvonalat biztosít a megosztott szállítmányokhoz, az újracímkézéshez és a pótlásokhoz anélkül, hogy módosítaná a rendelési rekord jelentését.
Webhookokat vagy lekérdezést használjon az integráció?
Használja a szolgáltató által támogatott és az infrastruktúrájával kompatibilis kézbesítési mechanizmust. A webhookok csökkenthetik az ismételt lekéréseket, míg a lekérdezés támogatja a lekérésalapú munkafolyamatokat és az egyeztetést, ahol elérhető. Egyik megközelítés sem szünteti meg a tartós tárolás, a duplikátumkezelés és a helyreállítás szükségességét.
Mi történjen, ha egy követési eseményhez nem található rendelés?
Tárolja egy nem párosított eseményeket tartalmazó sorban, és vizsgálja meg a regisztrációs rekordot, a bérlői környezetet, a fuvarozó identitását és a szállítmány létrehozásának időzítését. Ne hozzon létre automatikusan rendelést, és ne kapcsolja az eseményt egy valószínűnek tűnő ügyfélhez. A hozzárendelés javítása után játssza újra.
A kézbesítési értesítések az OMS-ből vagy a követési rendszerből érkezzenek?
Válasszon egy tulajdonost minden értesítéstípushoz és kiváltó eseményhez. Ha két rendszer is küldheti ugyanazt az üzenetet, tiltsa le az egyik útvonalat, vagy osszon meg tartós értesítési főkönyvet. Azt is döntse el, hogy az üzenet egy csomagra vagy a teljes rendelésre vonatkozik-e, különösen megosztott teljesítés esetén.
A kivételállapot azt jelenti, hogy a rendelés sikertelen?
Nem. A kivétel értelmezést igénylő megfigyelés, nem feltétlenül végleges eredmény. Őrizze meg az okot, kövesse a későbbi eseményeket, és az eszkalációs szabályzat alapján döntse el, mikor kell beavatkozni.
Források
- 17TRACK Tracking API — hivatalos termékreferencia az API-integráció kiindulópontjához.
- 17TRACK API-dokumentáció — megvalósítási referencia a szolgáltató-specifikus szerződéshez; telepítés előtt ellenőrizze az alkalmazandó felületeket és fiókkövetelményeket.
- RFC 9110, 9.2.2. szakasz: Idempotens metódusok — a HTTP-szemantika alapot ad a metódusszintű idempotencia és az alkalmazásszintű duplikációvédelem megkülönböztetéséhez.


