Kokius duomenis turėtų grąžinti sekimo API? 12 laukų, neapsiribojančių dabartine būsena?
Stebėjimo API turėtų grąžinti daugiau nei etiketę, pavyzdžiui, „Vežama“. Be dabartinės būsenos, ieškokite siuntos identifikatorių, vežėjo tapatybės, išsamios būsenos informacijos, originalių vežėjo pranešimų, įvykių istorijos, įvykių laiko žymų, vietų, numatomo pristatymo, išimčių, vežėjų perdavimų, pristatymo informacijos ir duomenų aktualumo metaduomenų. Kartu šios 12 duomenų grupių padeda kūrėjams kurti patikimus procesus ir suteikia operacijų komandoms pakankamai konteksto veiksmams atlikti.

Tai yra rekomenduojama atsakymo sutartis kūrėjams, techniniams pirkėjams ir el. prekybos operacijų komandoms, o ne teiginys, kad kiekvienas vežėjas ar API pateikia kiekvieną lauką. Kai kurios reikšmės pagrįstai gali būti nepasiekiamos. Geresnis sprendimas yra aiškiai nurodyti šias spragas, o ne užpildyti jas prielaidomis.
Kas daro stebėjimo duomenis naudingus?
Dabartinė būsena atsako į vieną siaurą klausimą: kokia yra apibendrinta siuntos būsena? Ji nebūtinai paaiškina, kas įvyko, kada tai įvyko, ar informacija yra nauja, arba ką reikėtų daryti toliau.
Pavyzdžiui, dvi siuntos gali rodyti „Vežama“, tačiau joms gali reikėti skirtingų veiksmų. Viena galėjo būti neseniai nuskenuota rūšiavimo centre ir neturėti praneštų problemų. Kitos įvykių istorijoje gali būti neišspręsta adreso problema. Programa, skaitanti tik pagrindinę būseną, gali nepastebėti šio skirtumo.
Įvertinkite atsakymą pagal tris praktines užduotis: susieti siuntą su teisingu užsakymu, tiksliai paaiškinti jos eigą ir nuspręsti, ar pagrįsta imtis veiksmų. Toliau pateikti laukai padeda atlikti šias užduotis. Laukų pavadinimai yra iliustraciniai; jie nėra universalus standartas ar konkretaus teikėjo schema.
12 laukų, kuriuos verta įvertinti be dabartinės būsenos
1. Siuntos ir stebėjimo identifikatoriai
Atsakymas turėtų identifikuoti aprašomą siuntą. Naudingos reikšmės apima pateiktą stebėjimo numerį, API stebėjimo įrašo identifikatorių ir kliento nuorodą, kurią jūsų sistema gali susieti su įvykdymo arba pakuotės įrašu.
Nedarykite prielaidos, kad vienas užsakymas reiškia vieną siuntą. Užsakymas gali būti padalytas į kelias pakuotes, o pakeitimas gali sukurti kitą siuntą. Stebėjimo įrašus saugokite pakuotės arba įvykdymo lygmeniu, tada susiekite juos su užsakymu. Stebėjimo numerius saugokite kaip eilutes, kad nebūtų prarastas formatavimas ir nuliniai skaitmenys pradžioje.
2. Vežėjo tapatybė
Ieškokite stabilaus vežėjo identifikatoriaus kartu su lengvai skaitomu vežėjo pavadinimu. Jei įmanoma, atsakyme turėtų būti atskirta, ar vežėją aiškiai nurodė jūsų programa, ar jis pasirinktas automatiškai aptikus vežėją.
Vežėjo kontekstas svarbus interpretuojant stebėjimo numerį ir jo įvykius. Jei aptikimas neaiškus, integracija turėtų suteikti galimybę tai išspręsti, o ne tyliai pateikti nepatvirtintą atitikmenį kaip patvirtintą. Paslaugos lygio informaciją laikykite atskirai: vien vežėjo pavadinimas neparodo, ar siuntai naudojama skubi, pašto ar kita paslauga.
3. Normalizuota būsenos informacija
Be pagrindinės būsenos, prašykite dokumentuoto išsamios būsenos kodo arba papildomos būsenos. Plati kategorija gali apibūdinti siuntą kaip išimtį, o išsami būsena nurodyti nesėkmingą pristatymą, adreso problemą ar su muitine susijusį sulaikymą.
Verslo logikai naudokite stabilius kodus, o pateikimui – lengvai skaitomas etiketes. Patikrinkite, kaip teikėjas susieja vežėjo įvykius su šiais kodais, įskaitant nežinomų ar nesusietų įvykių tvarkymą. Normalizuota etiketė palengvina skirtingų vežėjų informacijos naudojimą, tačiau neturėtų panaikinti skirtumų, kurių reikia pagalbos komandai.
4. Originalūs vežėjo pranešimai ir kodai
Kai jie pateikiami, išsaugokite originalų įvykio aprašą ir vežėjo įvykio kodą. Šios reikšmės suteikia pagalbos darbuotojams kontekstą, kurio gali nebūti normalizuotoje būsenoje, ypač kai vežėjas naudoja konkretų operacinį terminą.
Originalų tekstą laikykite atskirai nuo išverstų ar perrašytų aprašų. Priešingu atveju klientui skirtas paaiškinimas gali būti palaikytas tiksliu vežėjo tekstu. Rodydami vežėjo tekstą laikykite jį nepatikima įvestimi: tinkamai jį maskuokite ir nerodykite kaip vykdomo HTML.
5. Stebėjimo įvykių istorija
Naudingas atsakymas turėtų pateikti siuntos laiko juostą, o ne tik naujausią įvykį. Kiekviename įvykyje turėtų būti identifikatorius, būsena arba kodas, aprašas, laiko žyma ir, jei įmanoma, vietos informacija.
Patikrinkite, ar API grąžina visą istoriją, ribotą laikotarpį ar puslapiuojamus rezultatus. Taip pat nustatykite, kaip pateikiami pataisymai ir pasikartojantys stebėjimai. Programa neturėtų manyti, kad pirmas elementas visada yra naujausias, nebent atsakymo sutartis aiškiai garantuoja tokią tvarką.
6. Įvykių laiko žymos ir laiko juostų informacija
Įvykio laikas skiriasi nuo laiko, kada API jį gavo ar grąžino. Jei įmanoma, išsaugokite abu. Šis skirtumas padeda paaiškinti, kodėl ką tik gautas atnaujinimas gali apibūdinti tai, kas įvyko anksčiau.
Prašykite laiko žymų su aiškiu UTC poslinkiu arba UTC žyma. RFC 3339 apibrėžia interneto protokolams tinkamą laiko žymos formatą, įskaitant skaitinius laiko poslinkius. Jei šaltinis pateikia tik vietos laiką be žinomo poslinkio, išsaugokite šį neapibrėžtumą, o ne tyliai laikykite jį UTC. Niekada neimplikuokite sekundžių tikslumo, kai šaltinis pateikia tik datą.
7. Įvykių vietos ir siuntos geografija
Jei pateikiama, ieškokite struktūrinių vietos komponentų, tokių kaip miestas, regionas, šalis ir pašto kodas. Taip pat išsaugokite neapdorotą vietos eilutę, jei konvertuojant ją į struktūrinius laukus gali būti prarasta prasmė.
Skenavimo vieta nebūtinai yra faktinė pakuotės buvimo vieta. Taip pat paskutinis nurodytas rūšiavimo centras neįrodo, kad siunta vis dar yra ten. Klientams skirtuose puslapiuose apibūdinkite ją kaip paskutinę nurodytą vietą. Nedarykite išsamios koordinatės ar tikslaus pristatymo adreso iš neišsamaus skenavimo teksto.
8. Numatyta pristatymo data arba laikotarpis
Numatomo pristatymo laukas turėtų nurodyti, ar jame pateikta viena data, ar laikotarpis, kas jį sukūrė ir kada jis paskutinį kartą atnaujintas. Vežėjo pateiktas įvertis ir atskirai apskaičiuota prognozė turi būti atskiriami.
Nepaverskite tik datos turinčio įverčio tiksliu pristatymo laiku. Integracija taip pat turėtų apdoroti pakeistus ar atšauktus įverčius, nepalikdama pasenusio pažado stebėjimo puslapyje. Jei įverčio nėra, nurodykite, kad jis nepasiekiamas, o ne apskaičiuokite jį remdamiesi nepagrįsta prielaida.
9. Išimties priežastis ir reikalingas veiksmas
Išimties informacija turėtų paaiškinti problemą ir, jei šaltinis tai palaiko, nurodyti veiksmą, atsakingą šalį arba terminą. Bendras pranešimas apie vėlavimą operaciniu požiūriu skiriasi nuo prašymo pateikti gavėjo informaciją.
Praneštus faktus laikykite atskirai nuo savo procesų sprendimų. Pavyzdžiui, jūsų įmonė gali sukurti pagalbos užduotį praėjus nustatytam laikotarpiui be atnaujinimo. Tai yra vidinė eskalavimo taisyklė, o ne įrodymas, kad vežėjas paskelbė siuntą prarasta. Iš neaiškaus stebėjimo teksto negeneruokite mokėjimo instrukcijų ar prašymų pateikti neskelbtiną informaciją.
10. Vežėjų perdavimai ir susiję stebėjimo numeriai
Kai siunta perduodama tarp operatorių, naudingi duomenys apima kitą vežėją, susijusį stebėjimo numerį ir ryšį tarp pradinio bei tolesnio įrašo. Tai gali padėti išlaikyti tęstinumą, kai pristatymo etapas naudoja kitą identifikatorių.
Nurodytą perdavimą laikykite ryšiu, o ne perrašykite pradinį vežėją. Nejunkite įrašų vien todėl, kad jų paskirties vietos ar stebėjimo numeriai atrodo panašūs. Jei ryšys nepateiktas ar kitaip nepatvirtintas, palikite jį neišspręstą, o ne išgalvokite nenutrūkstamą kelionę.
11. Pristatymo rezultatas ir įrodymų nuorodos
Kai pranešama apie pristatymą, atsakyme turėtų būti užregistruotas pristatymo laikas ir bet kokia prieinama pristatymo informacija, pavyzdžiui, saugios vietos aprašas ar gavėjo kategorija. Pristatymo įrodymo nuoroda taip pat gali būti naudinga, jei ją pateikia vežėjas ir paslauga.
Pristatymo būsenos nereikėtų laikyti įrodymu, kad numatytas gavėjas asmeniškai priėmė siuntą. Parašuose, nuotraukose, varduose ir tiksliuose vietos duomenyse gali būti asmeninės informacijos. Apribokite prieigą, neskelbkite šių duomenų viešuose stebėjimo puslapiuose ir patikrinkite bet kokius įgaliojimo ar galiojimo pabaigos reikalavimus, taikomus įrodymų nuorodoms.
12. Aktualumas, gavimo būsena ir atsakymo metaduomenys
Prašykite pakankamai metaduomenų, kad būtų galima atskirti naujausią siuntos įvykį nuo paskutinio sėkmingo duomenų gavimo. Naudingos reikšmės apima paskutinį sėkmingą patikrinimą, paskutinį nesėkmingą bandymą, atsakymo sukūrimo laiką ir informaciją, ar grąžinti duomenys yra talpykliniai arba daliniai.
Sėkminga API užklausa savaime neįrodo, kad vežėjas paskelbė naują skenavimą. HTTP atsakymo semantika apibūdina užklausos rezultatą; siuntos eiga priklauso programos duomenims. Gavimo klaidas laikykite atskirai nuo siuntos išimčių, kad laikina ryšio problema nevirstų klaidingu pranešimu apie pristatymą.
Trūkstami duomenys turi turėti apibrėžtą reikšmę
Lauko buvimas yra tik viena sutarties dalis. Jūsų komanda taip pat turi suprasti, ką reiškia nesama reikšmė. Pristatymo įvertis gali būti nepasiekiamas šaltinyje, dar negautas arba nebetaikomas po pristatymo. Šios situacijos neturėtų automatiškai sukelti to paties pranešimo klientui.
- Nežinoma: reikšmė dar nenustatyta.
- Nepateikta: šaltinis nepateikė reikšmės gautuose duomenyse.
- Netaikoma: laukas netaikomas šiam įrašui arba būsenai.
- Gavimo klaida: sistema negalėjo užbaigti atitinkamos paieškos.
Tai yra rekomenduojami skirtumai, o ne privalomos pažodinės reikšmės. Kad ir kokį pateikimą pasirinktumėte, jį dokumentuokite. Venkite vietos rezervavimo datų, tuščių objektų, panašių į galiojančius įrašus, ir numatytųjų koordinačių, kurias būtų galima palaikyti tikromis vietomis.
Kaip išbandyti atsakymą prieš integruojant
Įvertinkite tikrus duomenų paketus iš vežėjų, paslaugų ir siuntimo maršrutų, kuriuos naudoja jūsų įmonė. Schema gali nurodyti pasirenkamą lauką negarantuodama, kad kiekvienas pagrindinis šaltinis jį užpildys. Integruodami 17TRACK naudokite oficialią Tracking API dokumentaciją, kad patikrintumėte atsakymo sutartį, o šiame vadove pateiktų konceptualių laukų pavadinimų nelaikykite paruoštais naudoti parametrais.
- Sukurkite reprezentatyvią imtį. Įtraukite naujai užregistruotas siuntas, aktyvias siuntas, bandymus pristatyti, užbaigtus pristatymus ir galimus perdavimo atvejus.
- Atsekite laukus iki įvykių. Patvirtinkite, kad rodoma būsena, naujausias įvykis ir pristatymo informacija apibūdina nuoseklų įrašą. Neatitikimus nagrinėkite, o ne slėpkite.
- Išbandykite uždelstus ir pasikartojančius atnaujinimus. Pakartotinai apdorokite tą patį duomenų paketą ir gaukite senesnį įvykį po naujesnio. Patvirtinkite, kad nė vienu atveju nesukuriami pasikartojantys pranešimai ir neteisingai nepakeičiama rodoma būsena.
- Išbandykite trūkstamas ir netinkamo formato reikšmes. Įtraukite nesamus įverčius, nežinomas vietas, nepažįstamus būsenos kodus ir neišsamias laiko žymas. Programa turi išlikti tinkama naudoti neišgalvodama pakaitinių reikšmių.
- Atskirkite perdavimo klaidas nuo stebėjimo rezultatų. Autentifikavimo klaida, skirtojo laiko viršijimas ar netinkamas atsakymas turi patekti į integracijos klaidos kelią, o ne į siuntos išimties procesą.
- Patikrinkite klientui rodomą vaizdą. Įsitikinkite, kad vidinės nuorodos, neapdorota diagnostinė informacija ir asmens duomenys nepatenka į viešus puslapius ar pranešimus.
Jei atnaujinimai pagrįsti saitynais, taip pat patikrinkite pristatymo identifikatorius, autentifikavimą, pakartotinių bandymų elgseną ir pakartotinio paleidimo tvarkymą teikėjo dokumentacijoje. Tai yra integracijos reikalavimai, o ne siuntos faktai. Jūsų imtuvas turėtų saugiai apdoroti pasikartojančius pristatymus ir neturėtų manyti, kad gavimo tvarka sutampa su įvykių tvarka.
Priimtinumo kriterijus turėtų būti praktinis: ar jūsų programa gali paaiškinti siuntos būseną nepateikdama nepagrįstų teiginių ir ar operacijų komanda gali nustatyti kitą pagrįstą veiksmą? Mažesnis, gerai apibrėžtas duomenų paketas gali būti naudingesnis už didesnį atsakymą, pilną nepaaiškintų pasirenkamų reikšmių.
DUK
Ar kiekvienai siuntai reikia užpildyti visas 12 duomenų grupių?
Ne. Pristatymo įrodymai, tolesni stebėjimo numeriai ir numatomos pristatymo datos gali būti nepasiekiami arba netaikomi. Reikalaukite aiškių laukų apibrėžimų ir nuspėjamos trūkstamų reikšmių elgsenos, o ne visuotinio užpildymo. Svarbiausius laukus patikrinkite pagal faktinį savo siuntų derinį.
Ar turėtume saugoti neapdorotą atsakymą, ar tik normalizuotus laukus?
Programos logikai saugokite normalizuotus laukus. Atitinkamų šaltinio duomenų paketų išsaugojimas taip pat gali padėti derinant ir keičiant susiejimą, atsižvelgiant į privatumo, saugumo, sutarties ir saugojimo reikalavimus. Apribokite prieigą ir nesaugokite neskelbtino turinio vien todėl, kad jis pateikiamas atsakyme.
Kuri laiko žyma turėtų nustatyti naujausią įvykį?
Vadovaukitės dokumentuota įvykių chronologija ir teikėjo rikiavimo taisyklėmis, atsižvelgdami į laiko juostas ir pataisymus. Gavimo laikas parodo, kada jūsų sistema sužinojo apie įvykį, o ne būtinai kada jis įvyko. Jei laiko žymos neišsamios ar prieštaringos, išsaugokite neapibrėžtumą, o ne teigkite, kad seka yra tiksli.
Ar stebėjimo API gali patvirtinti, kad siunta prarasta?
Praradimą laikykite vežėjo praneštu tik tada, kai šaltinis aiškiai palaiko tokį aiškinimą. Ilgas laikotarpis be skenavimų gali pagrįsti tyrimą pagal jūsų operacines taisykles, tačiau vien tyla neįrodo praradimo. „Pasenęs stebėjimas“ ir „pranešta apie praradimą“ turi likti atskiromis sąvokomis.
Ar pristatymo būsenos pakanka kliento skundui užbaigti?
Ne automatiškai. Ji nustato praneštą stebėjimo rezultatą, tačiau gali neišspręsti gavėjo ginčo. Peržiūrėkite prieinamą pristatymo informaciją, kliento paskyrą ir savo pagalbos procesą. Nelaikykite būsenos etiketės pakaitalu prieštaringos informacijos tyrimui.
Šaltiniai
- 17TRACK Tracking API dokumentacija — konkretaus produkto šaltinis, skirtas integracijos dokumentuotiems laukams ir elgsenai tikrinti; pirmiau pateiktos 12 grupių yra redakcinės rekomendacijos, o ne jos schemos kopija.
- RFC 3339: Data and Time on the Internet: Timestamps — laiko žymų pateikimas ir laiko poslinkių taisyklės.
- RFC 9110: HTTP Semantics — HTTP atsakymo semantika, atskirta nuo siuntos verslo būsenos.


