Kaip integruoti siuntų sekimo API į savo el. prekybos parduotuvę
Norėdami integruoti siuntų sekimo API į savo el. prekybos parduotuvę, prijunkite užsakymų sistemą prie sekimo paslaugų teikėjo, siųskite siuntos ir vežėjo duomenis per saugią serverio užklausą, išsaugokite normalizuotus sekimo įvykius ir rodykite gautą būseną klientų bei palaikymo sąsajose. Patikimas įgyvendinimas yra daugiau nei sekimo numerio lauko pridėjimas: jis turi apdoroti vežėjo pasirinkimą, būsenos atnaujinimus, pristatymo išimtis, pakartotinius bandymus, privatumą ir tai, kaip klientai iš tikrųjų naudoja informaciją po pirkimo.
Šiame vadove paaiškinamas praktiškas integravimo būdas parduotuvių savininkams, kūrėjams ir operacijų komandoms. Jame kaip atskaitos taškas naudojama oficiali 17TRACK Tracking API dokumentacija, tačiau tie patys planavimo principai taikomi vertinant ir kitą kelių vežėjų paslaugų teikėją.
Nuspręskite, ką turi pasiekti integracija
Pradėkite nuo verslo rezultato, o ne nuo API galinio taško. Dauguma parduotuvių siekia sumažinti užklausų „Kur yra mano užsakymas?“ skaičių, suteikti pirkėjams aiškų pristatymo vaizdą ir padėti operacijų komandai nustatyti vėluojančias siuntas prieš klientui pateikiant skundą. Šiems tikslams reikia skirtingų duomenų ir darbo eigų.
- Matomumas klientui: rodykite esamą siuntos būseną, numatomą pristatymo informaciją, kai ji prieinama, vežėjo duomenis ir naujausią reikšmingą įvykį.
- Veiklos matomumas: suteikite darbuotojams galimybę rasti vėluojančias, užstrigusias, grąžintas arba išimtį turinčias siuntas tarp skirtingų vežėjų.
- Automatinė komunikacija: inicijuokite patvirtintus el. laiškus, SMS ar kitus pranešimus, kai siunta pasiekia nustatytą būseną.
- Duomenų nuoseklumas: skirtingų vežėjų įvykių etiketes paverskite mažesniu būsenų rinkiniu, kurį jūsų parduotuvė gali patikimai naudoti.
Apibrėžkite šiuos rezultatus prieš pasirinkdami įgyvendinimo būdą. Sekimo API gali pateikti siuntos duomenis, tačiau ji automatiškai nenusprendžia, kurie įvykiai verti pranešimo klientui ar kaip jūsų parduotuvė turėtų spręsti adreso problemą.
Pasirinkite tinkamą integracijos architektūrą
Įprastą architektūrą sudaro keturi sluoksniai: prekybos platforma, integracijos paslauga, sekimo paslaugų teikėjas ir klientui skirta sąsaja. Integracijos paslauga gali būti vidinė programa, užsakymų valdymo sistema arba serverless darbo eiga. Šią logiką paprastai saugiau laikyti serveryje, o ne naršyklės kode, kuriame būtų API prisijungimo duomenys.
Pagrindinis procesas atrodo taip:
- Apmokėtas užsakymas įvykdomas ir gauna sekimo numerį bei vežėją.
- Jūsų vidinė sistema siunčia siuntos duomenis sekimo paslaugų teikėjui.
- Paslaugų teikėjas grąžina sekimo identifikatorių arba sekimo duomenis pagal savo API struktūrą.
- Jūsų sistema išsaugo paslaugų teikėjo nuorodą ir susieja siuntos įvykius su vidinėmis būsenomis.
- Suplanuotas atnaujinimo procesas arba palaikomas įvykių pranešimas atnaujina siuntos informaciją.
- Jūsų parduotuvė, užsakymo puslapis, palaikymo įrankiai ir pranešimų paslauga skaito jūsų pačių normalizuotus duomenis.
Neleiskite kiekvienam puslapio peržiūros veiksmui kreiptis į vežėjo ar sekimo API. Tokia struktūra gali lemti lėtą klientų patirtį, pasikartojančias užklausas, dažnio ribojimo problemas ir nenuoseklius rezultatus. Išsaugokite naujausią priimtą sekimo būseną savo duomenų bazėje ir atnaujinkite ją valdomomis foninėmis užduotimis arba paslaugų teikėjo palaikomu atnaujinimo mechanizmu.
Prieš programuodami patikrinkite paslaugų teikėjo dokumentaciją
Prieš įgyvendindami sprendimą peržiūrėkite oficialią paslaugų teikėjo API dokumentaciją, kurioje aprašomas autentifikavimas, užklausų formatai, atsakymo laukai, palaikomi vežėjai, klaidų apdorojimas, atnaujinimo mechanizmai ir paskyros reikalavimai. 17TRACK pateikia specialų Tracking API produkto puslapį ir kūrėjų dokumentaciją. Šiuos puslapius laikykite dabartinės API elgsenos autoritetu, o ne remkitės iš forumų ar senų integravimo vadovėlių nukopijuotais pavyzdžiais.
Remdamiesi dokumentacija sudarykite trumpą reikalavimų kontrolinį sąrašą:
- Kaip išduodami, saugomi, keičiami ir atšaukiami API prisijungimo duomenys?
- Ar užklausai reikalingas vežėjo kodas, ar paslauga gali nustatyti vežėją pagal sekimo numerį?
- Kurie atsakymo laukai nurodo siuntą, būseną, vietą, laiko žymas ir išimties pranešimą?
- Kaip pateikiami asinchroniniai atnaujinimai, jei paskyra juos palaiko?
- Kokie yra dokumentuoti užklausų limitai, atsiskaitymo taisyklės, skirtojo laiko lūkesčiai ir klaidų kodai?
- Kaip reikėtų apdoroti pasikartojančius sekimo numerius, negaliojančius numerius, nežinomus vežėjus ir pristatytas siuntas?
Nedarykite išvadų apie funkciją vien pagal produkto pavadinimą. Pavyzdžiui, „realusis laikas“ gali apibūdinti produkto pozicionavimą, o ne garantiją, kad kiekvienas vežėjo įvykis bus rodomas nedelsiant. Jūsų įgyvendinimas turėtų paaiškinti, kad vežėjo nuskaitymai gali vėluoti ir kad API negali sukurti nuskaitymo, apie kurį vežėjas nepranešė.
Paruoškite užsakymo ir siuntos duomenis
Dažniausiai tinkamiausias momentas sukurti sekimą yra siuntos įvykdymas, o ne užsakymo sukūrimas. Užsakymas gali būti apmokėtas, bet dar nesupakuotas, o sekimo numeris gali būti sugeneruotas dar prieš siuntinio priėmimą vežėjui. Nuspręskite, kuris įvykis jūsų įvykdymo darbo eigoje turėtų sukurti sekimo įrašą.
Mažiausiai jūsų vidiniame siuntos įraše turėtų būti atskirtos šios reikšmės:
- Vidinis užsakymo ID ir įvykdymo ID
- Sekimo numeris
- Vežėjo pavadinimas arba vežėjo kodas
- Paskirties šalis arba regionas, kai to reikia veiklai
- Paslaugų teikėjo sekimo ID arba prenumeratos nuoroda, jei grąžinama
- Dabartinė normalizuota būsena
- Paskutinio įvykio laiko žyma ir paskutinio sinchronizavimo laiko žyma
- Neapdorotas paslaugų teikėjo atsakymas arba kontroliuojama audito nuoroda
Užsakymo ir siuntos duomenis laikykite atskirai. Viename užsakyme gali būti keli paketai, dalinės siuntos arba skirtingi vežėjai. Prielaida, kad vienam užsakymui tenka vienas sekimo numeris, dažnai nepasiteisina, kai sandėlis siunčia prekes atskirai.
Naudokite idempotentinį procesą. Jei įvykdymo sistema pakartoja tą pačią užklausą, integracija turėtų atnaujinti esamą siuntą, o ne sukurti pasikartojančias prenumeratas ar pasikartojančius pranešimus klientams. Praktinis idempotentiškumo raktas gali būti sudarytas iš vidinio įvykdymo ID, vežėjo identifikatoriaus ir sekimo numerio, atsižvelgiant į paties paslaugų teikėjo reikalavimus.
Normalizuokite vežėjų būsenas klientams
Vežėjai naudoja skirtingas etiketes ir įvykių sekas. Jūsų parduotuvė turėtų palaikyti nedidelį vidinių būsenų modelį, pavyzdžiui, Informacija gauta, Vežama, Pristatyti, Pristatyta, Išimtis ir Grąžinta. Išsaugokite pradinį vežėjo įvykį palaikymo darbuotojams, tačiau parduotuvės logikoje naudokite normalizuotą būseną.
Normalizavimo taisyklės turėtų būti aiškios. Įvykis „etiketė sukurta“ neturėtų būti pateikiamas kaip įrodymas, kad siuntinys juda. „Pristatyta“ turėtų būti laikoma vežėjo praneštu įvykiu, o ne garantija, kad klientas fiziškai rado siuntinį. Išimtis neturėtų būti tyliai pakeista į „vežama“ vien todėl, kad siunta vėliau gali tęsti kelionę.
Taip pat apibrėžkite būsenų pirmumą ir regresijos apdorojimą. Vėluojantis vežėjo duomenų srautas gali atkeliauti ne eilės tvarka. Jei įmanoma, palyginkite įvykių laiko žymas, įrašykite neapdorotą įvykį ir nepakeiskite naujesnės pristatytos būsenos senesne vežimo būsena. Jei laiko žymų nėra arba jos neaiškios, pažymėkite įrašą konservatyviam atnaujinimui, o ne kurkite išgalvotą seką.
Sukurkite serverio užklausos srautą
Prieš kreipdamasi į sekimo paslaugų teikėją, jūsų vidinė sistema turėtų patikrinti gaunamus įvykdymo duomenis. Patikrinkite, ar yra sekimo numeris, pašalinkite atsitiktinius tarpus, prireikus patikrinkite numatomą formatą ir įsitikinkite, kad vežėjo reikšmė yra tinkama. Neatmeskite neįprastų, bet galiojančių sekimo numerių vien todėl, kad jie neatitinka siauros vietinės taisyklės.
Nepriklausomą nuo paslaugų teikėjo užklausos eigą galima pavaizduoti taip:
receive fulfillment event
validate order and shipment fields
check for an existing idempotency key
send the documented tracking request from the server
store the provider response and internal shipment record
queue a refresh or process the supported update event
publish only approved fields to the storefrontLaikiniems sutrikimams naudokite trumpus skirtuosius laikus, ribotą pakartojimų skaičių ir eksponentinį laukimo didinimą. Nekartokite kiekvienos klaidos. Autentifikavimo klaida, netinkama užklausa ar nepalaikomas vežėjas paprastai reikalauja pataisymo, o ne pakartotinių iškvietimų. Registruokite koreliacijos ID, užklausos rezultatą ir paslaugų teikėjo klaidos kategoriją, tačiau į programos žurnalus nerašykite API raktų, pilnų klientų adresų ar nereikalingos asmeninės informacijos.
Paslaugų teikėjo atsakymą laikykite atskirai nuo klientui skirto modelio. Taip bus lengviau pakeisti paslaugų teikėją, pataisyti susiejimo taisyklę ir apriboti viešame užsakymo puslapyje atskleidžiamą informaciją.
Sukurkite klientų sekimo patirtį
Sekimo puslapis turėtų greitai atsakyti į tris klausimus: kokia dabartinė būsena, kas įvyko paskiausiai ir ką klientas turėtų daryti toliau? Rodykite užsakymo nuorodą, privatumą užtikrinančia forma pateiktą siuntos numerį, vežėjo pavadinimą, naujausio įvykio laiką ir aiškų išimčių paaiškinimą.
Nerodykite tuščios laiko juostos taip, lyg tai būtų techninis gedimas. Prieš pirmąjį vežėjo nuskaitymą paaiškinkite, kad siuntimo informacija gauta, tačiau judėjimas dar gali būti nematomas. Išimties atveju pateikite paprastą paaiškinimą tik tada, kai šaltinio duomenys jį pagrindžia. Jei vežėjas praneša apie adreso problemą, pateikite nuorodą į palaikymo procesą arba klientų aptarnavimo veiksmą, kurį jūsų įmonė iš tikrųjų gali pasiūlyti.
Parduotuvėse, sukurtose naudojant Shopify ar kitą prekybos platformą, patikrinkite, kaip platforma pateikia įvykdymo įvykius, klientų paskyras, užsakymo būsenos puslapius ir pranešimų šablonus. Oficialioje Shopify kūrėjų dokumentacijoje pateikiami ištekliai apie webhook ir įvykdymo duomenis. Platformų API ir versijuota dokumentacija gali keistis, todėl prieš pradėdami darbus gamybinėje aplinkoje patvirtinkite, kurią versiją naudoja jūsų programa.
Atsargiai naudokite pranešimus
Siuntų įvykiai yra naudingi paleidikliai, tačiau pranešimo siuntimas apie kiekvieną vežėjo nuskaitymą gali sukelti pranešimų nuovargį. Apibrėžkite verslo taisykles, pavyzdžiui, pranešimus apie siuntos sukūrimą, reikšmingą judėjimą, siuntą, paruoštą pristatyti, pristatymą ir pasirinktas išimtis. Slopinkite pasikartojančius pranešimus ir nustatykite minimalų intervalą pakartotiniams pranešimams apie vėlavimą.
Veiklos įspėjimus atskirkite nuo pranešimų klientams. Palaikymo komandai gali reikėti žinoti, kad siunta kelias dienas nepasikeitė, o klientui gali reikėti pranešimo tik tada, kai vežėjas praneša apie konkrečią išimtį. Laiko slenkstis turėtų atspindėti paslaugos lygį, paskirties vietą, vežėją ir siuntimo būdą, o ne universalų skaičių, neturintį veiklos pagrindo.
Testuokite naudodami realius pristatymo scenarijus
Vieno sekimo numerio sėkmingo atsakymo nepakanka paleidimui gamybinėje aplinkoje. Sudarykite testavimo matricą, apimančią kelis vežėjus, šalis, siuntų tipus ir įvykių būsenas. Išbandykite bent:
- Naujai sukurtą siuntą, kurios vežėjas dar nenuskaitė
- Įprastą vežamą siuntą
- Siuntą, paruoštą pristatyti
- Pristatytą siuntą
- Išimtį arba su adresu susijusį įvykį
- Grąžintą siuntą
- Negaliojantį sekimo numerį
- Pasikartojantį įvykdymo įvykį
- Vėluojantį paslaugų teikėjo atsakymą arba skirtąjį laiką
- Ne eilės tvarka gautą įvykį
Matuokite daugiau nei API prieinamumą. Patikrinkite, ar atnaujinamas teisingas užsakymas, ar klientas mato suprantamą kalbą, ar slopinami pasikartojantys pranešimai ir ar palaikymo darbuotojai gali nustatyti pradinį vežėjo įvykį. Pirmiausia atlikite riboto masto paleidimą, išlaikykite veiklos atsarginį sprendimą ir po išleidimo stebėkite klaidų kategorijas.
Saugumas, privatumas ir priežiūra
Prisijungimo duomenis saugokite paslapčių valdymo sistemoje arba apsaugotame aplinkos kintamajame, o ne temos kode, mobiliajame kode, šaltinio kodo saugykloje ar naršyklės užklausose. Apribokite prieigą prie siuntų duomenų pagal vaidmenį, naudokite HTTPS ir peržiūrėkite, kiek laiko saugomi neapdoroti atsakymai bei su klientais susiję laukai.
Reguliariai peržiūrėkite paslaugų teikėjo dokumentaciją ir prekybos platformos API versiją. Gali keistis vežėjų palaikymas, įvykių pavadinimai, autentifikavimo reikalavimai ir platformos webhook veikimas. Paverskite būsenų susiejimo taisykles konfigūruojamomis, dokumentuokite jų prielaidas ir sudarykite galimybę pakartoti arba suderinti siuntą nesiunčiant kito pranešimo klientui.
17TRACK API yra tinkama galimybė vertinti, kai jūsų parduotuvei reikia specializuoto kelių vežėjų sekimo integravimo. Vis dėlto tinkamas pasirinkimas priklauso nuo jūsų naudojamų vežėjų, šalių, į kurias siunčiate, jūsų paskyrai dokumentuotos atnaujinimo elgsenos, numatomo užklausų kiekio ir veiklos kontrolės priemonių, kurių reikia jūsų komandai. Prieš įsipareigodami gamybiniam sprendimui patvirtinkite šiuos aspektus oficialioje dokumentacijoje ir kontroliuojamoje koncepcijos patikroje.
DUK
Ar sekimą reikėtų sukurti pateikus užsakymą?
Paprastai ne. Sukurkite arba aktyvinkite siuntos įrašą tada, kai jūsų įvykdymo darbo eiga turi vežėją ir sekimo numerį. Sukūrus jį atsiskaitymo metu, gali atsirasti įrašų apie vėliau atšauktus, neįvykdytus arba padalytus užsakymus.
Ar sekimo API gali garantuoti realiojo laiko pristatymo informaciją?
Ne. Jokia API negali garantuoti, kad kiekvienas vežėjo nuskaitymas bus matomas nedelsiant. Paslaugų teikėjas priklauso nuo vežėjo duomenų, o vežėjų sistemos gali pranešti apie įvykius su vėlavimais ar spragomis. Tiksliai pateikite laiko žymas ir būsenų tekstą bei nežadėkite tikslaus atnaujinimo laiko, nebent atitinkama dokumentacija ir paslaugų sutartis tokį pažadą pagrindžia.
Ar naršyklė turėtų tiesiogiai kreiptis į sekimo API?
Daugumoje įgyvendinimų – ne. Naudokite serverio integraciją, kad prisijungimo duomenys liktų apsaugoti, atsakymai galėtų būti normalizuojami, pakartotiniai bandymai kontroliuojami, o klientams skirti duomenys filtruojami. Parduotuvė paprastai turėtų skaityti patvirtintą siuntos vaizdą iš jūsų programos.
Kaip parduotuvė turėtų apdoroti kelis paketus viename užsakyme?
Kiekvieną įvykdymą arba paketą modeliuokite kaip atskirą siuntą, išsaugodami pagrindinio užsakymo ID. Užsakymo puslapyje galima rodyti bendrą suvestinę ir atskiras kiekvieno paketo laiko juostas. Taip išvengsite situacijos, kai vėluojantis paketas paslepiamas po kito paketo pristatymo būsena.
Kokią pirmą gamybinę metriką reikėtų stebėti?
Stebėkite visą srautą nuo įvykdymo sukūrimo iki teisingo klientui matomo atnaujinimo. Vien API sėkmės nepakanka. Sekite pasikartojančius įrašus, pasenusias siuntas, nesusietus įvykius, pranešimų klaidas ir siuntų, kurioms reikalingas rankinis taisymas, procentą.
