Skip to main content
PagrindinisTinklaraštisVadovaiKaip patikrinti siuntų sekimo numerius prieš pateikiant per API: 7 taisyklės, kurių reikia laikytis

Kaip patikrinti siuntų sekimo numerius prieš pateikiant per API: 7 taisyklės, kurių reikia laikytis

17TRACK

Prieš siunčiant siuntos numerį į siuntų sekimo API, patikrinkite jį keliais lygiais: normalizuokite įvestį, patikrinkite pagrindinę struktūrą, patvirtinkite vežėjo kontekstą, taikykite kontrolinę sumą tik tada, kai ją nurodo vežėjo dokumentacija, ir atmeskite akivaizdžiai nesaugius arba neišsamius duomenis. Nepasikliaukite viena universalia reguliariąja išraiška. Siuntų numerių formatai skiriasi pagal vežėją, paslaugą, šalį ir siuntos tipą, todėl veiksmingas tikrintuvas turėtų užkirsti kelią netinkamoms užklausoms, tačiau neatmesti teisėtų numerių, naudojančių nepažįstamą formatą.

Kaip patikrinti siuntų numerius prieš siunčiant juos į API: 7 taisyklės

Šis vadovas skirtas kūrėjams ir operacijų komandoms, integruojančioms siuntų sekimą į užsakymų valdymo sistemą, sandėlio darbo eigą, klientų portalą arba el. prekybos programą. Tikslas nėra prieš siunčiant užklausą įrodyti, kad siunta egzistuoja. Sintaksės tikrinimas ir siuntos būsenos tikrinimas yra atskiri etapai.

Ką tikrinimas gali ir ko negali patvirtinti

Prieš siunčiant užklausą tikrintuvas gali nustatyti dažnas įvesties problemas, pavyzdžiui, tuščią reikšmę, atsitiktinius tarpus, nepalaikomus simbolius, per didelį ilgį arba netinkamame lauke įvestą siuntos numerį. Jis taip pat gali nustatyti tikėtiną vežėją, kai vežėjas žinomas ir jo formatas aprašytas dokumentacijoje.

Paprastai jis negali patvirtinti, kad numeris priklauso tikrai siuntai, kad vežėjas priėmė siuntą arba kad numerį šiuo metu galima sekti. Šiems klausimams reikia vežėjo arba sekimo platformos paieškos. Numeris gali atitikti formato patikrą, tačiau vis tiek būti nepanaudotas, subtiliai įvestas neteisingai, pasibaigęs arba susietas su kita paslauga.

Septynios taisyklės

1. Normalizuokite reikšmę nekeisdami jos prasmės

Naudotojai ir ankstesnės sistemos dažnai prideda tarpus pradžioje arba pabaigoje, eilučių lūžius, nepertraukiamus tarpus arba formatavimo simbolius. Prieš tikrindami saugiai normalizuokite šiuos duomenis. Dažnas pirmasis žingsnis – pašalinti aplinkinius tarpus ir nematomus tarpus pakeisti įprastais tarpais. Jei vežėjo dokumentacijoje nurodytas formatas leidžia vidinius tarpus arba brūkšnelius, nuspręskite, ar juos pašalinti siunčiant užklausą į API, ar išsaugoti pradinę reikšmę rodymui ir auditui.

Kai praktiška, saugokite dvi reikšmes: pradinę įvestį ir kanoninę reikšmę. Pradinė reikšmė padeda pagalbos komandoms tirti duomenų kokybės problemas, o kanoninė naudojama tikrinimui ir siuntimui. Venkite transformacijų, galinčių pakeisti identifikatorius. Automatiškai nekeiskite raidžių į skaičius, nepakeiskite dviprasmiškų simbolių ir nepašalinkite visų skyrybos ženklų, nebent atitinkamo vežėjo arba API dokumentacija aiškiai palaiko tokį elgesį.

Svarbu atkreipti dėmesį į Unicode apdorojimą. Vizualiai panašus kitos abėcėlės simbolis gali būti nepriimtas API, nors atrodo kaip ASCII raidė arba skaitmuo. Apribojus kanoninę reikšmę iki pasirinktos integracijos leidžiamo simbolių rinkinio, galima išvengti painių vėlesnių klaidų.

2. Atmeskite reikšmes, neatitinkančias pagrindinių struktūros patikrų

Prieš taikydami konkretaus vežėjo logiką patikrinkite, ar reikšmė pateikta ir atrodo pagrįsta. Naudingos patikros apima minimalų ir maksimalų ilgį, leidžiamas simbolių klases ir patikrinimą, ar reikšmę sudaro tik tarpai arba vietaženklis, pavyzdžiui, „N/A“, „TBD“ arba „test“. Tikslūs apribojimai turėtų būti nustatyti API sutartyje arba vežėjo dokumentacijoje. Nekurkite universalaus maksimalaus ilgio vien todėl, kad dauguma pavyzdžių yra trumpi.

Struktūros patikra turėtų būti sąmoningai konservatyvi. Pavyzdžiui, taisyklė, leidžianti tik skaitmenis, atmes galiojančius raidinius ir skaitmeninius identifikatorius. Taisyklė, reikalaujanti vieno fiksuoto ilgio, gali atmesti paslaugų variantus arba tarptautinius formatus. Naudokite bendrąsias patikras akivaizdžioms klaidoms aptikti, o konkretesnes patikras taikykite tik tada, kai vežėjas ir paslauga yra žinomi.

Taip pat patikrinkite duomenų tipą programos riboje. Siuntos numeris paprastai turėtų būti laikomas eilute, o ne sveikuoju skaičiumi. Konvertuojant į skaičių gali būti pašalinti pradiniai nuliai ir kilti tikslumo problemų sistemose, naudojančiose fiksuoto pločio skaitinius tipus. Po patvirtinto normalizavimo išsaugokite reikšmę tiksliai kaip eilutę.

3. Naudokite vežėjo kontekstą, o ne spėliokite vien iš numerio

Siuntos numeris be vežėjo yra dviprasmiška įvestis. Skirtingi vežėjai gali naudoti sutampančius ilgius, priešdėlius arba simbolių rinkinius, o formatas, tinkamas vienam vežėjui, gali būti netinkamas kitam. Jei užsakymas, etiketė, sandėlio sistema arba prekybininko paskyra jau nurodo vežėją, kartu su siuntos numeriu perduokite šį kontekstą, kai tik API tai palaiko.

Vežėjo kontekstas pagerina tikrinimą ir nukreipimą. Jis leidžia programai pasirinkti atitinkamas formato taisykles, sumažina klaidingų atitikmenų skaičių ir padeda pateikti naudingesnius klaidų pranešimus. Be to, jis neleidžia automatinio aptikimo rezultatui būti laikomam faktu, kai panašią reikšmę galėtų priimti keli vežėjai.

Jei vežėjas nežinomas, naudokite dviejų etapų metodą. Pirmiausia atlikite bendrąsias saugumo patikras. Tada siųskite reikšmę tik per API eigą, kuri aiškiai palaiko vežėjo aptikimą, arba, kai to reikalauja verslo procesas, įdėkite ją į peržiūros eilę, kol vežėjas bus patvirtintas. Nepriskirkite vežėjo tyliai vien pagal priešdėlį, nebent toks susiejimas yra prižiūrimas ir dokumentuotas.

4. Kontrolines sumas taikykite tik tada, kai taisyklė dokumentuota

Kai kurios identifikatorių sistemos naudoja kontrolinius skaitmenis, tačiau siuntų numeriams netaikomas vienas universalus kontrolinės sumos standartas. Kontrolinė suma gali aptikti tam tikras perrašymo klaidas, tačiau neįrodo, kad siunta egzistuoja. Dar svarbiau, kad pritaikius netinkamą kontrolinės sumos algoritmą galima atmesti galiojančius numerius.

Kontrolinę sumą įgyvendinkite tik tada, kai atitinkamo vežėjo, paslaugos, etiketės specifikacijoje arba API dokumentacijoje apibrėžtas algoritmas ir jo tikrinama įvesties dalis. Užregistruokite taisyklės versiją ir patikrinkite ją pagal oficialius pavyzdžius. Jei nėra autoritetingos taisyklės, kontrolinės sumos netaikykite, užuot spėlioję pagal nedidelėje imtyje pastebėtus šablonus.

Kontrolinės sumos rezultatą laikykite vienu signalu, o ne galutiniu tikrinimo sprendimu. Nepavykusi patikra gali pateisinti užklausos blokavimą, kai taisyklė yra autoritetinga. Sėkminga patikra turėtų perkelti reikšmę į kitą etapą, bet ne pažymėti ją kaip aktyvią siuntą.

5. Atskirti formato tikrinimą nuo tinkamumo naudoti API

Reikšmė gali būti tinkamos struktūros, tačiau vis tiek netikti kviečiamam galiniam taškui. Prieš siųsdami užklausą patikrinkite API dokumentacijoje nurodytus privalomus laukus, priimamus vežėjų identifikatorius, autentifikavimo reikalavimus, užklausų ribojimus, pasikartojančių užklausų tvarkymą ir bet kokius paslaugų tipų arba paskirties vietų apribojimus. Tai yra integracijos, o ne siuntos numerio taisyklės, tačiau jos lemia, ar galiojantis identifikatorius gali būti sėkmingai apdorotas.

17TRACK Tracking API dokumentacija yra pavyzdys, kodėl šis skirtumas svarbus: kūrėjai turi vadovautis platformos užklausų modeliu ir palaikomu integracijos elgesiu, o ne kurti užklausą vien pagal siuntos numerio išvaizdą. Dabartinius galinių taškų reikalavimus ir atsakymų apdorojimą rasite 17TRACK API dokumentacijoje.

Tikrinimo klaidas atskirkite nuo perdavimo ir autentifikavimo klaidų. Pranešimai „Netinkamas siuntos numerio formatas“, „Nežinomas vežėjas“, „Pasiekta užklausų dažnio riba“ ir „Autorizacija nepavyko“ reikalauja skirtingų veiksmų. Vienas bendras pranešimas „Užklausa nepavyko“ daro pakartotinius bandymus ir veiklos ataskaitas mažiau patikimus.

6. Apsaugokite API ribodami įvestį, šalindami dublikatus ir saugiai kartodami užklausas

Tikrinimas taip pat yra veiklos apsaugos priemonė. Prieš analizuodami arba registruodami įvestį nustatykite jos maksimalų ilgį. Atmeskite valdymo simbolius ir netikėtas duomenų struktūras. Nustatykite dažnio ribojimą savo programos riboje, kad dėl klaidingo importo nekiltų nekontroliuojamas užklausų srautas.

Prieš siųsdami užklausą pašalinkite dublikatus, kai verslo procesas nereikalauja pakartotinės registracijos. Naudingą dublikatų šalinimo raktą gali sudaryti kanoninis siuntos numeris, vežėjas, paskyra ir siuntos kontekstas. Tinkamas raktas priklauso nuo darbo eigos; tas pats identifikatorius kartais gali būti pakartotinai naudojamas skirtingoms paslaugoms arba verslo įrašams, todėl nemanykite, kad vien numeris visada yra globaliai unikalus.

Laikinų klaidų atveju naudokite ribotą pakartotinių bandymų skaičių su laukimo tarpais ir nekartokite nuolatinių tikrinimo klaidų. Kai tai palaiko API ir jūsų architektūra, saugokite idempotentiškumo arba pateikimo įrašą. Registruokite pakankamai informacijos užklausai diagnozuoti, tačiau saugokite prisijungimo duomenis, klientų duomenis ir jautrią informaciją apie siuntas. Tikrintuvas turėtų sumažinti pasikartojančias klaidas, o ne sukurti antrą saugumo problemą dėl pernelyg išsamaus registravimo.

7. Po pateikimo patvirtinkite rezultatą ir stebėkite klaidingus teigiamus rezultatus

Paskutinė taisyklė – laikyti tikrinimą prieš pateikimą vartais, o ne galutiniu sprendimu. Priėmus užklausą, išnagrinėkite API atsakymą ir išsaugokite jo būseną, užklausos identifikatorių, sąsają su vežėju ir dokumentacijoje nurodytą klaidos kodą. Jei platforma priima užklausą, tačiau dar negali pateikti judėjimo įvykių, tai gali reikšti apdorojimo delsą, o ne netinkamą numerį.

Apibrėžkite tolesnių veiksmų politiką numeriams, kurie lieka neišspręsti. Laikotarpis turėtų atitikti vežėją, paslaugą, siuntos kilmę ir jūsų klientų aptarnavimo politiką; nėra universalaus laikotarpio, įrodančio, kad numeris negalioja. Eskaluokite įrašus, kuriuose nėra vežėjo, kartojasi teikėjo klaidos, nesutampa skirtingų vežėjų rezultatai arba būsena neatitinka užsakymo įrašo.

Matuokite klaidingus atmetimus ir klaidingus priėmimus. Griežta reguliarioji išraiška gali sumažinti netinkamų užklausų skaičių, tačiau kartu klaidingai blokuoti teisėtas siuntas. Per daug liberali patikra gali padidinti priimtų užklausų skaičių, bet sukelti triukšmą tolesniuose procesuose. Peržiūrėkite nesėkmingus pavyzdžius pagal vežėją ir paslaugą, atnaujinkite dokumentuotas taisykles naudodami versijų kontrolę ir išbandykite pakeitimus su reprezentatyviu, privatumą saugančiu testinių duomenų rinkiniu.

Praktinė tikrinimo seka

Prižiūrima realizacija gali naudoti tokią seką:

  1. Patikrinkite, ar užklausoje yra eilutės reikšmė ir galiojantis verslo įrašas.
  2. Išsaugokite pradinę įvestį, tada sukurkite dokumentuotą kanoninę formą.
  3. Atmeskite tuščias reikšmes, vietaženklius, nesaugius simbolius ir reikšmes, nepatenkančias į dokumentuotą ilgio intervalą.
  4. Nustatykite vežėją pagal patikimus užsakymo duomenis arba naudokite aiškiai palaikomą aptikimo eigą.
  5. Taikykite konkretaus vežėjo sintaksės ir kontrolinės sumos taisykles tik tada, kai jas palaiko autoritetinga dokumentacija.
  6. Patikrinkite galinio taško reikalavimus, dublikato būseną ir tinkamumą kartoti užklausą.
  7. Pateikite užklausą, suklasifikuokite atsakymą, išsaugokite rezultatą ir suplanuokite tolesnius veiksmus neišspręstiems įrašams.

Ši seka palengvina tikrintuvo testavimą, nes kiekvienas sprendimas turi skirtingą priežastį. Ji taip pat suteikia operacijų komandoms konkrečias nesėkmės kategorijas, o ne vieną neaiškią klaidą.

Įgyvendinimo kontrolinis sąrašas

  • Saugokite siuntų numerius kaip eilutes, kad būtų išsaugoti pradiniai nuliai.
  • Kai svarbus audituojamumas, atskirai saugokite pradines ir kanonines reikšmes.
  • Vežėjų taisykles tvarkykite kaip versijuojamą konfigūraciją, o ne kaip išsibarsčiusias programiniame kode įrašytas sąlygas.
  • Išbandykite raides, skaitmenis, brūkšnelius, tarpus, vizualiai panašius Unicode simbolius, vietaženklius ir ribines ilgio reikšmes.
  • Kai įmanoma, naudokite patikimą vežėjo kontekstą.
  • Nedarykite išvados, kad siunta egzistuoja, vien todėl, kad sėkmingai sutapo reguliarioji išraiška.
  • Nuolatines tikrinimo klaidas klasifikuokite atskirai nuo laikinų API arba tinklo klaidų.
  • Prieš keisdami formato taisykles arba užklausų logiką peržiūrėkite teikėjo dokumentaciją.

DUK

Ar reguliarioji išraiška gali patikrinti siuntos numerį?

Ji gali patikrinti ribotą šabloną, kai žinomas vežėjas ir paslaugos formatas. Ji negali įrodyti, kad numeris egzistuoja, priklauso konkrečiai siuntai arba šiuo metu yra aktyvus. Universali išraiška greičiausiai sukurs klaidingų atmetimų arba klaidingų atitikmenų.

Ar į API reikėtų siųsti numerį, kuris atrodo netinkamas?

Akivaizdžiai tuščias, nesaugias arba struktūriškai neįmanomas reikšmes paprastai reikėtų sustabdyti prieš siunčiant užklausą. Nepažįstamo, tačiau kitaip saugaus formato nereikėtų atmesti vien todėl, kad jis neatitinka vidinio spėjimo. Pirmiausia patikrinkite vežėjo dokumentaciją arba naudokite palaikomą aptikimo procesą.

Ar kontrolinės sumos pakanka siuntai patvirtinti?

Ne. Kai taikoma, kontrolinė suma tik patikrina, ar reikšmė atitinka matematinę taisyklę. Ji nepatvirtina, kad vežėjas išdavė numerį arba kad siunta pateko į tinklą.

Kas turėtų nutikti, kai vežėjas nežinomas?

Atlikite bendrąsias saugumo patikras ir naudokite API eigą, kuri aiškiai palaiko vežėjo aptikimą, jei tokia galimybė prieinama. Priešingu atveju išsaugokite įrašą papildymui arba rankinei peržiūrai, užuot tyliai spėlioję vežėją.

Kaip reikėtų tvarkyti API klaidas?

Klasifikuokite jas pagal priežastį. Ištaisykite netinkamą įvestį ir nepalaikomas vežėjo reikšmes; laikinas tinklo arba teikėjo klaidas kartokite ribotai ir su laukimo tarpais; autentifikavimo arba kvotos klaidas nukreipkite integracijos savininkui. Saugokite diagnozei reikalingą atsakymo informaciją neatskleisdami paslapčių.

Šaltiniai