Skip to main content
KezdőlapBlogÚtmutatókHogyan használjuk a szállítmánykövetési API-kat proaktív kézbesítési értesítések küldésére

Hogyan használjuk a szállítmánykövetési API-kat proaktív kézbesítési értesítések küldésére

17TRACK

Ahhoz, hogy egy szállítmánykövetési API-val proaktív kézbesítési értesítéseket küldjön, kapcsoljon minden csomagot a rendeléséhez, fogadja be a követési frissítéseket, alakítsa ezeket az ügyfelek számára releváns eseményekké, majd indítsa el az üzeneteket az e-mail-, SMS- vagy alkalmazásértesítési szolgáltatásán keresztül. A beérkező követési adatok és a kimenő üzenetek közé helyezzen tartós várólistát és duplikáció-ellenőrzéseket, hogy az ismétlődő vagy késve érkező frissítések ne eredményezzenek zavaró riasztásokat.

A szállítmánykövetési API-k használata proaktív kézbesítéshez

Ez az útmutató azoknak a fejlesztőknek és e-kereskedelmi üzemeltetési csapatoknak szól, akik ezt a munkafolyamatot építik. A cél nem az, hogy minden fuvarozói szkennelést továbbítsunk, hanem hogy tájékoztassuk az ügyfeleket arról, mikor történik érdemi változás, mit jelent ez a változás, és szükséges-e bármit tenniük.

Tervezze meg az értesítési munkafolyamatot az API csatlakoztatása előtt

A szállítmánykövetési API követési információkat biztosít; az alkalmazása dönti el, hogyan használja ezeket. A szállítmány láthatóságát és az ügyfélkommunikációt külön felelősségként kezelje, még akkor is, ha a választott szolgáltatás mindkettőt kínálja.

Egy praktikus architektúra hat szakaszból áll:

  1. Rendelés-hozzárendelés: szükség esetén kapcsolja a követési számot és a fuvarozó azonosítóját egy belső szállítmányrekordhoz.
  2. Követés regisztrálása: a szolgáltató integrációs követelményeinek megfelelően küldje be vagy regisztrálja a szállítmányt.
  3. Frissítések befogadása: fogadjon webhook-visszahívásokat, kérjen le frissítéseket API-kérésekkel, vagy kombinálja a két megközelítést.
  4. Eseményfeldolgozás: érvényesítse, normalizálja, szűrje ki a duplikátumokat, és értékelje a beérkező eseményeket.
  5. Értesítési döntés: döntse el, hogy küld-e értesítést, kit értesít, valamint melyik csatornát és sablont használja.
  6. Üzenetkézbesítés: küldje el az értesítést, és rögzítse az üzenetküldő szolgáltatás válaszát.

Az ügyfelek elérhetőségi adatait tartsa a saját rendelési vagy üzenetküldő rendszerében, kivéve, ha az integráció ténylegesen megköveteli azok megosztását. Egy követési szolgáltatásnak általában nincs szüksége az ügyfél e-mail-címére pusztán ahhoz, hogy az alkalmazás egy követési eseményt egy rendeléshez kapcsoljon.

1. Ellenőrizze az integrációs szerződést

A fogadó megírása előtt ellenőrizze a szolgáltató dokumentációjában a hitelesítést, a szállítmány regisztrációját, a fuvarozó azonosítását, a támogatott frissítési módszereket, a válaszformátumokat, a kéréskorlátokat és a hibakezelést. Webhook-integrációk esetén azt is ellenőrizze, hogyan hitelesítik a visszahívásokat, milyen válasz igazolja az átvételt, és hogyan kezelik a sikertelen kézbesítéseket.

17TRACK-megvalósítás esetén kezdje a 17TRACK Tracking API oldallal és annak hivatalos API-dokumentációjával. Az integrációhoz a dokumentált szerződést használja, és ne tekintse az útmutató szemléltető mezőneveit a 17TRACK kérés- vagy válaszmezőinek. A megvalósítás előtt erősítse meg a visszahívások beállítását, a biztonsági követelményeket és a fiókspecifikus korlátokat.

A frissítési módszert az integrációs szerződés alapján válassza ki:

  • Webhookok: használjon visszahívásokat, ha ezeket a szolgáltató támogatja, és megfelelnek az infrastruktúrájának. Így az alkalmazása akkor dolgozhatja fel a frissítéseket, amikor a szolgáltató elküldi őket, anélkül hogy ismételten le kellene kérnie ugyanazt a szállítmányt.
  • Polling: ütemezetten kérje le a követési információkat, ha a visszahívások nem érhetők el vagy nem megfelelőek. Az ütemezést tartsa a dokumentált kéréskorlátokon belül.
  • Kombinált megközelítés: használjon visszahívásokat a normál feldolgozáshoz, valamint szelektív API-lekéréseket az olyan szállítmányok egyeztetéséhez, amelyek frissítései elavultnak tűnnek, ha a szolgáltató támogatja ezt a munkafolyamatot.

Ne ígérjen az ügyfeleknek azonnali értesítéseket pusztán azért, mert webhookokat használ. Az alkalmazása nem jelenthet egy fuvarozói eseményt azelőtt, hogy a felsőbb szintű követési adatok elérhetővé tennék azt.

2. Építsen valódi rendelésekben is működő szállítmányrekordot

Elsődleges hivatkozásként belső szállítmányazonosítót használjon, ne csak a követési számot. Egy rendelés több csomagot is tartalmazhat, és nem szabad feltételezni, hogy a követési számok örökre globálisan egyediek.

Egy hasznos belső rekord a következőket tartalmazza:

  • Belső rendelésazonosító és szállítmányazonosító.
  • Követési szám és fuvarozói azonosító, ha ismert.
  • A szolgáltató által megadott szállítmányhivatkozás, ha van ilyen.
  • Aktuális normalizált állapot és legutóbbi érdemi esemény.
  • A fuvarozói esemény időpontja, lehetőség szerint az időzónával vagy eltolással együtt.
  • Az időpont, amikor a rendszer fogadta a frissítést.
  • Hivatkozás az ügyfél kommunikációs beállításaira.
  • Értesítési előzmények és minden aktív kivételkezelési munkafolyamat.

Az esemény időpontját a fogadás időpontjától elkülönítve tárolja. Egy korábban történt szkennelés egy újabb szkennelés után is megérkezhet. Ha az alkalmazása csak az érkezési sorrend alapján rendez, tévesen visszaállíthat egy kézbesített szállítmányt szállítás alatt álló állapotba.

Megosztott rendelések esetén az értesítéseket az érintett csomaghoz kapcsolja. A „Rendelésének egyik csomagja megérkezett” pontosabb, mint a „Rendelése megérkezett”, ha egy másik csomag még úton van.

3. Kapcsolja össze a követési eseményeket az ügyfél döntéseivel

A fuvarozói leírások működési adatok, nem pedig közvetlenül használható ügyfélüzenetek. Építsen normalizálási réteget, amely megőrzi az eredeti eseményt, miközben hozzárendel egy belső kategóriát, amelyet az értesítési szabályok értelmezni tudnak.

Az alábbi kategóriák javasolt alkalmazási fogalmak, nem pedig univerzális API-állapotok:

Belső kategóriaÉrtesítési döntésÜzenetküldési korlát
Szállítmányinformáció fogadvaCsak akkor küldjön előkészítési frissítést, ha az hasznos.Ne sugallja, hogy a fuvarozó fizikailag átvette a csomagot pusztán a címke létrehozása alapján.
Szállítás alattFontolja meg az értesítést az első érdemi mozgáskor.Ne küldjön rutinszerű létesítményi szkenneléseket, hacsak nem változtatják meg az ügyfél következő lépését.
Kézbesítés alattÉrtesítsen, amikor egy támogatott esemény ezt az állapotot jelzi.Ne alakítsa az állapotot garantált érkezési idővé.
Kézbesítési kísérlet vagy átvétel szükségesKüldjön konkrét teendőt tartalmazó értesítést.Határidőket vagy átvételi utasításokat csak ellenőrzött információ esetén adjon meg.
Kézbesítési kivételÉrtékelje az okot és azt, hogy az ügyfélnek kell-e cselekednie.Ne írjon le minden kivételt elveszett csomagként.
KézbesítveKüldjön csomagszintű megerősítést.Ne találjon ki címzettet, kézbesítési helyet vagy kézbesítési igazolást.

Őrizze meg a bizonytalanságot. Egy ismeretlen esemény kerüljön felülvizsgálati vagy tartalék útvonalra, ahelyett hogy a legközelebbi ismert kategóriába kényszerítené. A nyers leírást tegye elérhetővé az ügyfélszolgálat számára a hibaelhárításhoz.

4. Fogadjon frissítéseket a munka elvesztése vagy duplikálása nélkül

A webhook-végpontnak érvényesítenie kell a kérést, tartósan el kell mentenie az elfogadott frissítést, és vissza kell küldenie a szolgáltató által előírt visszaigazolást. Az üzenetek létrehozását aszinkron módon végezze, ne várjon e-mail- vagy SMS-szolgáltatásra a visszahívási kérés közben.

Alkalmazza a szolgáltató dokumentált visszahívás-ellenőrzési módszerét. Ne találjon ki aláírási fejlécet, és ne feltételezze, hogy minden szolgáltató ugyanazt a hitelesítési sémát használja. Emellett kényszerítse ki a HTTPS-t, a kérésméret-korlátokat, a hasznos adatok érvényesítését és a megfelelő hozzáférés-vezérlést.

Az egyszerűsített feldolgozási folyamat így néz ki. Ezek alkalmazásszintű műveletek, nem működő SDK-példa:

receive callback
  verify request using documented provider mechanism
  validate payload
  persist accepted payload and enqueue processing atomically
  return documented acknowledgment

process queued update
  find internal shipment
  normalize relevant events
  ignore already-processed events
  evaluate chronology and state transition
  create notification job if policy permits
  commit state and job together

send notification job
  check recipient preferences and suppression rules
  submit message to messaging service
  record result and retry only when appropriate

Az atomi lépések fontosak. Ha az alkalmazása menti az állapotváltozást, de összeomlik az értesítési feladat létrehozása előtt, az ügyfél soha nem kaphatja meg a riasztást. A tranzakciós outbox egy lehetséges megoldás: ugyanabban az adatbázis-tranzakcióban mentse az állapotváltozást és a függőben lévő feladatot, majd egy worker küldje el a feladatot.

Az ismeretlen szállítmányhivatkozásokat kezelje kifejezetten. Helyezze őket vizsgálati vagy egyeztetési karanténba ahelyett, hogy találgatna, melyik ügyfélnek kell értesítést kapnia.

5. Adjon hozzá duplikációvédelmet és időrendi ellenőrzéseket

Úgy tervezze meg a fogadót, hogy elviselje az ismétlődő visszahívásokat és a worker-újrapróbálkozásokat. Használjon stabil szolgáltatói eseményazonosítót, ha ezt dokumentálják. Ellenkező esetben hozzon létre determinisztikus esemény-ujjlenyomatot megfelelő mezőkből, például a belső szállítmányazonosítóból, az eseménykódból, az esemény időpontjából és a helyszínből. Mielőtt erre támaszkodna, tesztelje az ujjlenyomatot tényleges hasznos adatokon.

Az események duplikációszűrése és az értesítések elnyomása különböző problémákat old meg. A duplikációszűrés megakadályozza, hogy ugyanazt az eseményt kétszer dolgozza fel. Az elnyomás megakadályozza, hogy több különálló szkennelés lényegében ugyanazt az ügyfélüzenetet hozza létre.

Az értesítés identitását az üzleti esemény köré építse. Egy kézbesítési megerősítés használhatja a szállítmányazonosítót és a kézbesítési mérföldkövet. Egy kézbesítési kísérlethez kísérletspecifikus identitásra lehet szükség, mert egy későbbi kísérlet valóban új esemény lehet.

A sorrenden kívül érkező frissítéseknél hasonlítsa össze az események időbélyegeit, és értékelje az engedélyezett állapotátmeneteket. Ne feltételezze, hogy egy visszahívás csak új szkennelést tartalmaz; ellenőrizze, hogy dokumentált szerkezete egyedi eseményt, pillanatképet vagy előzményt jelent-e. Az ellentmondó frissítéseket küldje egyeztetésre ahelyett, hogy csendben eldobná az összes javítást.

6. Olyan üzeneteket írjon, amelyek elmagyarázzák a következő lépést

Minden értesítésnek meg kell neveznie az érintett csomagot, a megerősített változást és az ügyfél következő lépését. Tartalmazzon biztonságos követési linket és felismerhető rendelési hivatkozást. SMS-ekben és zárolt képernyős előnézetekben kerülje a teljes címek vagy szükségtelen személyes adatok megjelenítését.

Például:

  • Kézbesítés alatt: „A(z) {order_reference} rendeléshez tartozó csomagja kézbesítés alatt van. Kövesse az útját itt: {tracking_link}.”
  • Kézbesítési kísérlet történt: „A fuvarozó kézbesítési kísérletről számolt be a csomagja esetében. A lehetséges következő lépésekért tekintse meg a követési oldalt: {tracking_link}.”
  • Kézbesítve: „A fuvarozó kézbesítettként jelölte meg a(z) {order_reference} rendeléshez tartozó csomagját. Tekintse meg az elérhető kézbesítési részleteket: {tracking_link}.”

A helyőrzőket csak érvényesített adatokból jelenítse meg. Ha rendelkezésre áll és megjelenítésre alkalmas egy kézbesítési becslés, jelölje becslésként. Ha hiányzik, hagyja ki ahelyett, hogy dátumot találna ki.

Kivételeknél különböztesse meg a szállítmány problémáját az ügyfél teendőjétől. Egy fennakadás csak magyarázatot igényelhet; egy ellenőrzött címprobléma cselekvést tehet szükségessé. Ne irányítsa az ügyfeleket fizetési vagy dokumentumfeltöltési oldalra kizárólag megbízhatatlan, szabad szöveges követési tartalom alapján.

A csatornákat az ügyfélbeállítások, a csatornaengedélyek, a sürgősség és az alkalmazandó szabályok alapján válassza ki. Tekintse át az Ön által használt joghatóságokra és üzenetküldési csatornákra vonatkozó hozzájárulási, leiratkozási és csendes időszakokra vonatkozó követelményeket. A kézbesítési szolgáltatás értesítéseit tartsa elkülönítve a promóciós kampányoktól, és ne feltételezze, hogy ugyanazok az engedélyek mindkettőre érvényesek.

7. Határozza meg, mi történik, ha a követés elcsendesedik

A proaktív kommunikációnak a hiányzó előrehaladásra is ki kell terjednie az új események mellett, de a csend önmagában nem bizonyítja, hogy egy szállítmány késik vagy elveszett.

Hozzon létre elavult követésre vonatkozó szabályt a szolgáltatási szint, az útvonal, az utolsó érdemi esemény és az elérhető kézbesítési becslés alapján. A küszöbértékeket a működési adatokból és a támogatási folyamatból határozza meg, ahelyett hogy minden szállítmányra egyetlen általános várakozási időt alkalmazna.

Amikor a szabály aktiválódik, ellenőrizze a kihagyott feldolgozást, egyeztesse a követési forrással, ha ez támogatott, és döntse el, hogy létre kell-e hozni belső támogatási feladatot. Ha értesíti az ügyfelet, olyan megfogalmazást használjon, amely tükrözi, amit tud: „Nem kaptunk új követési frissítést” nem ugyanaz, mint „A csomagja elveszett”.

Rendeljen felelőst a megoldatlan kivételekhez. Egy olyan értesítési rendszer, amely ismételten bejelent egy problémát anélkül, hogy megoldási útvonalat biztosítana, növelheti az ügyfél frusztrációját.

8. Tesztelje a teljes útvonalat az automatikus küldés engedélyezése előtt

Először futtassa a munkafolyamatot árnyéküzemmódban: fogadjon be valódi vagy jóváhagyott teszteseményeket, hozzon létre javasolt értesítéseket, és vizsgálja meg az eredményeket az ügyfelek megkeresése nélkül.

  • Játsszon vissza egy azonos visszahívást, és erősítse meg, hogy nem hoz létre újabb üzenetet.
  • Dolgozzon fel egy régebbi szállítási eseményt egy kézbesítési esemény után, majd vizsgálja meg az eredményül kapott állapotot.
  • Tesztelje a hiányzó időbélyegeket, az ismeretlen állapotokat és a hibás hasznos adatokat.
  • Szimuláljon adatbázis-hibát a visszaigazolás előtt, valamint worker-hibát a tartós mentés után.
  • Tesztelje az üzenetküldési időtúllépéseket, beleértve azt a bizonytalan választ is, amikor a szolgáltató már elfogadhatta az üzenetet.
  • Erősítse meg, hogy a megosztott szállítmányok csomagspecifikus megfogalmazást eredményeznek.
  • Ellenőrizze a leiratkozott címzetteket, az érvénytelen elérhetőségeket és a csendes időszakok kezelését.
  • Ellenőrizze, hogy a követési linkek nem teszik-e elérhetővé más ügyfél rendelési adatait.

Figyelje az elfogadott visszahívásokat, a feldolgozási hibákat, a várólista korát, az értesítési feladatokat, a duplikációk elnyomását és az üzenetküldés eredményeit. A feldolgozási késleltetést a rendszer fogadási időpontjától külön mérje a fuvarozói esemény korától. Ez a különbség segít megállapítani, hogy a lassú értesítést a felsőbb szintű adatok elérhetősége vagy a saját folyamata okozta-e.

Kezdje néhány jól értelmezett mérföldkővel. Csak akkor bővítse a szabályokat, amikor a támogatási és üzemeltetési csapatok egyetértenek abban, hogy az üzenetek pontosak, konkrét teendőt tartalmaznak és érdemes fogadni őket.

GYIK

A szállítmánykövetési API automatikusan küld e-maileket vagy SMS-eket?

Nem feltétlenül. A követési adatok elérése és az ügyfélkommunikáció külön képességek. Ellenőrizze a szolgáltatás dokumentált hatókörét. Egy egyedi integrációban az alkalmazása feldolgozhatja a követési frissítéseket, és külön üzenetküldő szolgáltatáson keresztül küldhet értesítéseket.

Értesítsem az ügyfeleket minden követési szkennelésről?

Általában nem. Részesítse előnyben az érdemi mérföldköveket és a cselekvést igénylő eseményeket. Több létesítményi szkennelés normál szállítást jelenthet anélkül, hogy megváltoztatná azt, amit az ügyfélnek tudnia kell. A részletes előzményeket tartsa meg a követési oldalon.

Garantálhatom a valós idejű kézbesítési értesítéseket?

Beállíthat és figyelhet feldolgozási célt arra az időre, miután a rendszere megkap egy frissítést. Azt nem garantálhatja, hogy a fuvarozó mikor rögzít vagy tesz közzé egy szkennelést. A szolgáltatást e függőséget tükröző módon írja le.

Hogyan akadályozhatom meg a duplikált kézbesítési üzeneteket?

Használjon tartós esemény-duplikációszűrést, minden üzleti mérföldkőhöz külön értesítési identitást és tranzakciós feladat-létrehozást. Ha az üzenetküldő szolgáltatás támogatja az idempotenciát, használja további védelemként. Egyedül a memóriában végzett duplikáció-ellenőrzés nem éli túl az újraindításokat vagy több worker működését.

Mi történjen, ha a fuvarozó kijavít egy kézbesített állapotot?

Őrizze meg mindkét eseményt, és egyeztesse a szállítmány állapotát. Ha a javítás lényegesen érinti az ügyfelet, küldjön egyértelmű helyesbítést, vagy szabályzata szerint irányítsa az ügyet a támogatási csapathoz. Ne tegye a kézbesített állapotot véglegesen visszafordíthatatlanná pusztán a kód egyszerűsítése érdekében.

Források

Az alábbi hivatalos források szolgálnak a fent tárgyalt 17TRACK-integráció megvalósítási hivatkozásaiként. Az útmutató belső sémája, értesítési szabályai és feldolgozási folyamata architekturális ajánlások, nem idézett API-szerződések.

  • 17TRACK Tracking API — hivatalos kiindulópont az API-integráció értékeléséhez.
  • 17TRACK API-dokumentáció — hivatkozás a szolgáltató-specifikus kérésformátumokhoz, hitelesítéshez, követési műveletekhez és integrációs követelményekhez.