Kaip naudoti siuntų sekimo API, kad būtų siunčiami išankstiniai pranešimai apie pristatymą
Norėdami siųsti aktyvius pristatymo pranešimus naudodami siuntos sekimo API, susiekite kiekvieną paketą su jo užsakymu, gaukite sekimo atnaujinimus, paverskite juos klientui reikšmingais įvykiais ir siųskite pranešimus per savo el. pašto, SMS arba programėlės pranešimų paslaugą. Tarp gaunamų sekimo duomenų ir siunčiamų pranešimų įdiekite patvarią eilę bei pasikartojimų tikrinimą, kad pasikartojantys arba pavėluoti atnaujinimai nesukeltų klaidinančių įspėjimų.
Šis vadovas skirtas kūrėjams ir el. prekybos operacijų komandoms, kuriančioms tokį procesą. Tikslas nėra persiųsti kiekvieną vežėjo nuskaitymą. Tikslas – informuoti klientus, kada įvyksta reikšmingas pokytis, ką jis reiškia ir ar reikia imtis veiksmų.
Suprojektuokite pranešimų procesą prieš prijungdami API
Siuntos sekimo API pateikia sekimo informaciją, o jūsų programa nusprendžia, kaip ją naudoti. Siuntos matomumą ir bendravimą su klientais laikykite atskiromis atsakomybėmis, net jei pasirinkta paslauga siūlo abi funkcijas.
Praktinę architektūrą sudaro šeši etapai:
- Užsakymo susiejimas: prireikus susiekite sekimo numerį ir vežėjo identifikatorių su vidiniu siuntos įrašu.
- Sekimo registravimas: pateikite arba užregistruokite siuntą pagal teikėjo integracijos reikalavimus.
- Atnaujinimų gavimas: gaukite žiniatinklio kablio atgalinius pranešimus, gaukite atnaujinimus per API užklausas arba derinkite abu būdus.
- Įvykių apdorojimas: patikrinkite, normalizuokite, pašalinkite pasikartojimus ir įvertinkite gaunamus įvykius.
- Sprendimas dėl pranešimo: nuspręskite, ar siųsti pranešimą, su kuo susisiekti ir kurį kanalą bei šabloną naudoti.
- Pranešimo pristatymas: išsiųskite pranešimą ir įrašykite pranešimų paslaugos atsakymą.
Klientų kontaktinę informaciją laikykite savo užsakymų arba pranešimų sistemoje, nebent integracijai iš tikrųjų būtina ja dalytis. Sekimo paslaugai paprastai nereikia kliento el. pašto adreso vien tam, kad jūsų programa susietų sekimo įvykį su užsakymu.
1. Patvirtinkite integracijos sutartį
Prieš rašydami gaviklį, patikrinkite teikėjo dokumentaciją dėl autentifikavimo, siuntų registravimo, vežėjo identifikavimo, palaikomų atnaujinimo būdų, atsakymų formatų, užklausų limitų ir klaidų tvarkymo. Jei naudojate žiniatinklio kablius, taip pat patikrinkite, kaip autentifikuojami atgaliniai pranešimai, koks atsakymas patvirtina gavimą ir kaip tvarkomi nesėkmingi pristatymai.
Įgyvendindami 17TRACK integraciją, pradėkite nuo 17TRACK Tracking API puslapio ir oficialios API dokumentacijos. Integracijai naudokite dokumentuotą sutartį, o ne šiame vadove pateiktus pavyzdinius laukų pavadinimus laikykite 17TRACK užklausų ar atsakymų laukais. Prieš įgyvendindami patvirtinkite atgalinių pranešimų nustatymus, saugumo reikalavimus ir paskyrai taikomus limitus.
Atnaujinimo būdą pasirinkite pagal integracijos sutartį:
- Žiniatinklio kabliai: naudokite atgalinius pranešimus, kai juos palaiko teikėjas ir jie tinka jūsų infrastruktūrai. Jie leidžia programai apdoroti atnaujinimus, kai teikėjas juos siunčia, neprašant pakartotinai tos pačios siuntos.
- Apklausos: gaukite sekimo informaciją pagal tvarkaraštį, kai atgaliniai pranešimai nepasiekiami arba netinka. Laikykitės dokumentuotuose limituose nustatyto tvarkaraščio.
- Derinamas būdas: įprastam apdorojimui naudokite atgalinius pranešimus, o pasirinktinį API gavimą – siuntoms, kurių atnaujinimai atrodo pasenę, suderinti, jei teikėjas palaiko tokį procesą.
Nežadėkite klientams momentinių pranešimų vien todėl, kad naudojate žiniatinklio kablius. Jūsų programa negali pranešti apie vežėjo įvykį anksčiau, nei aukštesnės grandies sekimo duomenys tampa prieinami.
2. Sukurkite siuntos įrašą, tinkantį realiems užsakymams
Kaip pagrindinę nuorodą naudokite vidinį siuntos ID, o ne vien sekimo numerį. Užsakyme gali būti keli paketai, todėl nereikėtų manyti, kad sekimo numeriai visada yra visuotinai unikalūs.
Naudingame vidiniame įraše yra:
- Vidinis užsakymo ID ir siuntos ID.
- Sekimo numeris ir vežėjo identifikatorius, jei žinomi.
- Teikėjo siuntos nuoroda, jei pateikta.
- Dabartinė normalizuota būsena ir naujausias reikšmingas įvykis.
- Vežėjo įvykio laikas, įskaitant laiko juostą arba poslinkį, jei prieinamas.
- Laikas, kada jūsų sistema gavo atnaujinimą.
- Nuoroda į kliento bendravimo nuostatas.
- Pranešimų istorija ir aktyvių išimčių eiga.
Įvykio laiką saugokite atskirai nuo gavimo laiko. Anksčiau įvykęs nuskaitymas gali būti gautas po naujesnio nuskaitymo. Jei programa rikiuoja tik pagal gavimo tvarką, ji gali klaidingai pakeisti pristatytos siuntos būseną į gabenamą.
Padalytų užsakymų atveju pranešimus susiekite su konkrečiu paketu. Kai kitas paketas vis dar gabenamas, „Vienas iš jūsų užsakymo paketų pristatytas“ yra tiksliau nei „Jūsų užsakymas pristatytas“.
3. Susiekite sekimo įvykius su klientų sprendimais
Vežėjų aprašymai yra operaciniai duomenys, o ne paruošti pranešimai klientams. Sukurkite normalizavimo sluoksnį, kuris išsaugotų pradinį įvykį ir priskirtų jam vidinę kategoriją, kurią suprastų jūsų pranešimų taisyklės.
Toliau pateiktos kategorijos yra siūlomos programos sąvokos, o ne universalus API būsenų žodynas:
| Vidinė kategorija | Sprendimas dėl pranešimo | Pranešimo ribos |
|---|---|---|
| Gauta siuntos informacija | Siųskite parengimo atnaujinimą tik tada, kai jis naudingas. | Nesudarykite įspūdžio, kad vežėjas fiziškai perėmė siuntą, vien dėl etiketės sukūrimo. |
| Gabenama | Apsvarstykite pranešimą apie pirmą reikšmingą judėjimą. | Nerodykite įprastų terminalo nuskaitymų, nebent jie pakeičia kitą kliento veiksmą. |
| Pristatyti išvežta | Praneškite, kai palaikomas įvykis rodo šią būseną. | Nepaverskite būsenos garantuotu pristatymo laiku. |
| Bandytas pristatymas arba būtinas atsiėmimas | Siųskite pranešimą, kuriame nurodyti veiksmai. | Terminą ar atsiėmimo instrukcijas įtraukite tik tada, kai jos patikrintos. |
| Pristatymo išimtis | Įvertinkite priežastį ir tai, ar klientas turi imtis veiksmų. | Neapibūdinkite kiekvienos išimties kaip prarasto paketo. |
| Pristatyta | Siųskite konkretaus paketo patvirtinimą. | Nesugalvokite gavėjo, pristatymo vietos ar pristatymo įrodymo. |
Išsaugokite neapibrėžtumą. Neatpažintas įvykis turėtų patekti į peržiūros arba atsarginį procesą, o ne būti priverstinai priskirtas artimiausiai pažįstamai kategorijai. Neapdorotą aprašymą palikite prieinamą pagalbos darbuotojams trikčių šalinimui.
4. Gaukite atnaujinimus neprarasdami ir nedubliuodami darbo
Jūsų žiniatinklio kablio galinis taškas turėtų patikrinti užklausą, patikimai išsaugoti priimtą atnaujinimą ir grąžinti teikėjo reikalaujamą patvirtinimą. Pranešimus generuokite asinchroniškai, o ne laukdami el. pašto ar SMS paslaugos atsakymo atgalinės užklausos metu.
Įgyvendinkite teikėjo dokumentuotą atgalinių pranešimų tikrinimo metodą. Nekurkite savo parašų antraštės ir nemanykite, kad visi teikėjai naudoja tą pačią autentifikavimo schemą. Taip pat užtikrinkite HTTPS, užklausų dydžio limitus, naudingosios apkrovos tikrinimą ir tinkamas prieigos kontrolės priemones.
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
Atominiai veiksmai yra svarbūs. Jei programa išsaugo būsenos pokytį, bet sugenda prieš sukurdama pranešimo užduotį, klientas gali niekada negauti įspėjimo. Viena iš galimybių – transakcinė išvesties eilė: išsaugokite būsenos pokytį ir laukiančią užduotį toje pačioje duomenų bazės transakcijoje, o tada leiskite darbuotojui išsiųsti užduotį.
Nežinomas siuntos nuorodas tvarkykite aiškiai. Izoliuokite jas tyrimui arba suderinimui, užuot spėlioję, kuriam klientui siųsti pranešimą.
5. Pridėkite pasikartojimų apsaugą ir chronologinius patikrinimus
Suprojektuokite gaviklį taip, kad jis toleruotų pasikartojančius atgalinius pranešimus ir darbuotojų pakartotinius bandymus. Jei dokumentuotas stabilus teikėjo įvykio identifikatorius, naudokite jį. Priešingu atveju sukurkite deterministinį įvykio pirštų atspaudą iš tinkamų laukų, pavyzdžiui, vidinio siuntos ID, įvykio kodo, įvykio laiko ir vietos. Prieš pasikliaudami juo patikrinkite šį pirštų atspaudą su tikromis naudingosiomis apkrovomis.
Įvykių pasikartojimų šalinimas ir pranešimų slopinimas sprendžia skirtingas problemas. Pasikartojimų šalinimas neleidžia tam pačiam įvykiui būti apdorotam du kartus. Slopinimas neleidžia keliems skirtingiems nuskaitymams sukurti iš esmės tokio paties pranešimo klientui.
Pranešimo tapatybę apibrėžkite pagal verslo įvykį. Pristatymo patvirtinimui gali būti naudojamas siuntos ID ir pristatymo etapas. Bandant pristatyti gali reikėti bandymui būdingos tapatybės, nes vėlesnis bandymas gali būti iš tikrųjų naujas įvykis.
Jei atnaujinimai pateikiami ne eilės tvarka, palyginkite įvykių laiko žymas ir įvertinkite leidžiamus būsenų perėjimus. Nemanykite, kad atgaliniame pranešime yra tik naujas nuskaitymas; patikrinkite, ar dokumentuota struktūra reiškia atskirą įvykį, momentinę kopiją ar istoriją. Prieštaringus atnaujinimus nukreipkite suderinimui, o ne tyliai išmeskite visus pataisymus.
6. Rašykite pranešimus, paaiškinančius, kas bus toliau
Kiekviename pranešime turi būti nurodytas atitinkamas paketas, patvirtintas pokytis ir kitas kliento veiksmas. Įtraukite saugią sekimo nuorodą ir atpažįstamą užsakymo nuorodą. SMS žinutėse ir užrakinto ekrano peržiūrose venkite rodyti visus adresus ar nereikalingą asmeninę informaciją.
Pavyzdžiui:
- Pristatyti išvežta: „Jūsų užsakymo {order_reference} paketas išvežtas pristatyti. Stebėkite jo eigą čia: {tracking_link}.“
- Bandytas pristatymas: „Vežėjas pranešė apie bandymą pristatyti jūsų paketą. Galimus tolesnius veiksmus rasite sekimo puslapyje: {tracking_link}.“
- Pristatyta: „Vežėjas pažymėjo, kad jūsų užsakymo {order_reference} paketas pristatytas. Peržiūrėkite prieinamą pristatymo informaciją: {tracking_link}.“
Vietos žymeklius atvaizduokite tik iš patvirtintų duomenų. Jei pristatymo įvertis prieinamas ir tinkamas rodyti, pažymėkite jį kaip įvertį. Jei jo nėra, praleiskite, o ne išgalvokite datą.
Išimčių atveju atskirkite siuntos problemą nuo kliento užduoties. Sutrikimui gali reikėti tik paaiškinimo, o patikrintai adreso problemai – veiksmo. Nesiųskite klientų į mokėjimo ar dokumentų įkėlimo puslapį vien remdamiesi nepatikimu laisvo teksto sekimo turiniu.
Kanalus rinkitės pagal klientų nuostatas, kanalų leidimus, skubumą ir taikomas taisykles. Peržiūrėkite sutikimo, atsisakymo ir ramybės valandų reikalavimus jurisdikcijose bei pranešimų kanaluose, kuriuos naudojate. Pristatymo paslaugų pranešimus laikykite atskirai nuo reklaminių kampanijų ir nemanykite, kad abiem taikomi tie patys leidimai.
7. Apibrėžkite, kas vyksta, kai sekimas nutyla
Aktyvus bendravimas turėtų apimti ne tik naujus įvykius, bet ir trūkstamą progresą, tačiau vien tyla neįrodo, kad siunta vėluoja ar yra prarasta.
Sukurkite pasenusio sekimo taisyklę pagal paslaugos lygį, maršrutą, paskutinį reikšmingą įvykį ir palaikomą pristatymo įvertį. Ribas nustatykite pagal savo veiklos duomenis ir pagalbos procesą, o ne taikykite vienodą laukimo laiką visoms siuntoms.
Kai taisyklė suveikia, patikrinkite, ar nebuvo praleistas apdorojimas, jei įmanoma, suderinkite su sekimo šaltiniu ir nuspręskite, ar reikia sukurti vidinę pagalbos užduotį. Jei pranešate klientui, vartokite tai, ką žinote, atspindinčią formuluotę: „Negavome naujo sekimo atnaujinimo“ skiriasi nuo „Jūsų paketas prarastas“.
Nepanaikintoms išimtims priskirkite atsakingą asmenį. Pranešimų sistema, kuri pakartotinai skelbia apie problemą nesukurdama jos sprendimo kelio, gali didinti klientų nepasitenkinimą.
8. Išbandykite visą kelią prieš įjungdami automatinį siuntimą
Pirmiausia paleiskite procesą šešėliniu režimu: gaukite tikrus arba patvirtintus bandymo įvykius, sugeneruokite siūlomus pranešimus ir patikrinkite rezultatus nesusisiekdami su klientais.
- Pakartokite identišką atgalinį pranešimą ir patvirtinkite, kad jis nesukuria kitos žinutės.
- Apdorokite senesnį gabenimo įvykį po pristatymo įvykio ir patikrinkite gautą būseną.
- Išbandykite trūkstamas laiko žymas, nežinomas būsenas ir netinkamas naudingąsias apkrovas.
- Imituokite duomenų bazės gedimą prieš patvirtinimą ir darbuotojo gedimą po išsaugojimo.
- Išbandykite pranešimų skirtuosius laikus, įskaitant neaiškų atsakymą, kai paslauga galėjo jau priimti žinutę.
- Patvirtinkite, kad padalytos siuntos sukuria paketui būdingas formuluotes.
- Patikrinkite atsisakiusius gavėjus, neteisingus kontaktinius duomenis ir ramybės valandų tvarkymą.
- Įsitikinkite, kad sekimo nuorodos neatskleidžia kito kliento užsakymo informacijos.
Stebėkite priimtus atgalinius pranešimus, apdorojimo klaidas, eilės amžių, pranešimų užduotis, pasikartojimų slopinimą ir pranešimų rezultatus. Apdorojimo delsą nuo jūsų sistemos gavimo laiko matuokite atskirai nuo vežėjo įvykio amžiaus. Šis skirtumas padeda nustatyti, ar lėtą pranešimą lėmė aukštesnės grandies duomenų prieinamumas, ar jūsų pačių procesas.
Pradėkite nuo nedidelio aiškiai suprantamų etapų rinkinio. Taisykles plėskite tik tada, kai pagalbos ir operacijų komandos sutinka, kad pranešimai yra tikslūs, pritaikomi veiksmams ir verti gauti.
DUK
Ar siuntos sekimo API automatiškai siunčia el. laiškus arba SMS žinutes?
Nebūtinai. Prieiga prie sekimo duomenų ir bendravimas su klientais yra atskiros funkcijos. Patikrinkite dokumentuotą paslaugos apimtį. Individualioje integracijoje jūsų programa gali apdoroti sekimo atnaujinimus ir siųsti pranešimus per atskirą pranešimų paslaugą.
Ar turėčiau pranešti klientams apie kiekvieną sekimo nuskaitymą?
Paprastai ne. Pirmenybę teikite reikšmingiems etapams ir įvykiams, kuriems reikia veiksmų. Keli terminalo nuskaitymai gali reikšti įprastą gabenimą ir nepakeisti to, ką klientas turi žinoti. Išsamią istoriją laikykite sekimo puslapyje.
Ar galiu garantuoti realaus laiko pristatymo pranešimus?
Galite nustatyti ir stebėti apdorojimo tikslą, skaičiuojamą nuo tada, kai jūsų sistema gauna atnaujinimą. Negalite garantuoti, kada vežėjas užregistruos arba paskelbs nuskaitymą. Paslaugą aprašykite sąlygomis, atspindinčiomis šią priklausomybę.
Kaip išvengti pasikartojančių pristatymo pranešimų?
Naudokite patvarų įvykių pasikartojimų šalinimą, atskirą kiekvieno verslo etapo pranešimo tapatybę ir transakcinį užduočių kūrimą. Jei pranešimų paslauga palaiko idempotentiškumą, naudokite jį kaip papildomą apsaugą. Vien atmintyje atliekamas pasikartojimų tikrinimas neišliks po paleidimo iš naujo ar naudojant kelis darbuotojus.
Kas turėtų įvykti, jei vežėjas pataiso pristatytos siuntos būseną?
Išsaugokite abu įvykius ir suderinkite siuntos būseną. Jei pataisymas reikšmingai veikia klientą, pagal savo taisykles išsiųskite aiškų pataisymą arba nukreipkite atvejį pagalbai. Nepaverskite pristatytos būsenos visam laikui negrįžtama vien tam, kad supaprastintumėte kodą.
Šaltiniai
Toliau pateikti oficialūs ištekliai yra pirmiau aptartos 17TRACK integracijos įgyvendinimo nuorodos. Šio vadovo vidinė schema, pranešimų taisyklės ir apdorojimo procesas yra architektūrinės rekomendacijos, o ne cituojamos API sutartys.
- 17TRACK Tracking API — oficialus pradinis taškas API integracijai įvertinti.
- 17TRACK API dokumentacija — teikėjo užklausų formatų, autentifikavimo, sekimo operacijų ir integracijos reikalavimų nuoroda.


