Kako preveriti sledilne številke pred oddajo prek API-ja: 7 pravil, ki jih je treba upoštevati
Pred pošiljanjem sledilne številke v API za sledenje jo preverite v več korakih: normalizirajte vnos, preverite njegovo osnovno strukturo, potrdite kontekst prevoznika, uporabite kontrolno vsoto samo, kadar jo prevoznik dokumentira, ter zavrnite vrednosti, ki so očitno nevarne ali nepopolne. Ne zanašajte se na en univerzalni regularni izraz. Oblike sledilnih številk se razlikujejo glede na prevoznika, storitev, državo in vrsto pošiljke, zato mora učinkovit validator preprečiti nepravilne zahteve, ne da bi blokiral veljavne številke z neznano obliko.

Ta priročnik je namenjen razvijalcem in operativnim ekipam, ki sledenje pošiljk vključujejo v sistem za upravljanje naročil, skladiščni proces, portal za stranke ali aplikacijo za e-trgovino. Cilj ni dokazati, da paket obstaja, preden ga pošljete. Sintaktično preverjanje in preverjanje stanja pošiljke sta ločena koraka.
Kaj lahko preverjanje potrdi – in česa ne more
Validator pred pošiljanjem lahko prepozna pogoste težave z vnosom, kot so prazna vrednost, nenamerni presledki, nepodprti znaki, pretirana dolžina ali sledilna številka v napačnem polju. Prav tako lahko prepozna verjetnega prevoznika, kadar je prevoznik znan in je oblika dokumentirana.
Običajno ne more potrditi, da številka pripada resnični pošiljki, da je prevoznik paket sprejel ali da je številki trenutno mogoče slediti. Za ta vprašanja je potrebno iskanje pri prevozniku ali na platformi za sledenje. Številka lahko prestane preverjanje oblike, vendar je še vedno neuporabljena, subtilno napačno vnesena, potekla ali povezana z drugo storitvijo.
Sedem pravil
1. Normalizirajte vrednost, ne da bi spremenili njen pomen
Uporabniki in nadrejeni sistemi pogosto dodajo začetne ali končne presledke, prelome vrstic, neprelomne presledke ali oblikovne znake. Pred preverjanjem jih varno normalizirajte. Pogost prvi korak je odstranitev okoliških presledkov in pretvorba neizpisljivih presledkov v običajne presledke. Če dokumentirana oblika prevoznika dovoljuje notranje presledke ali vezaje, določite, ali jih boste za zahtevo API odstranili ali pa izvirno vrednost ohranili za prikaz in revizijo.
Kadar je praktično, hranite dve vrednosti: izvirni vnos in kanonično vrednost. Izvirnik pomaga ekipam za podporo pri preiskovanju težav s kakovostjo podatkov; kanonična vrednost se uporablja za preverjanje in pošiljanje. Izogibajte se pretvorbam, ki lahko spremenijo identifikatorje. Črk ne pretvarjajte samodejno v številke, ne zamenjujte dvoumnih znakov in ne odstranjujte vseh ločil, razen če ustrezna dokumentacija prevoznika ali API-ja to izrecno podpira.
Obravnavi Unicode namenite posebno pozornost. Vizualno podoben znak iz druge abecede morda ne bo sprejet v API-ju, čeprav je videti kot črka ali številka ASCII. Če kanonično vrednost omejite na nabor znakov, ki ga dovoljuje izbrana integracija, lahko preprečite zavajajoče napake v nadaljnjih sistemih.
2. Zavrnite vrednosti, ki ne prestanejo osnovnih strukturnih preverjanj
Pred uporabo logike, specifične za prevoznika, preverite, ali je vrednost prisotna in verjetna. Koristna preverjanja vključujejo najmanjšo in največjo dolžino, dovoljene razrede znakov ter preverjanje, ali vrednost vsebuje samo presledke ali nadomestno vrednost, kot so »N/A«, »TBD« ali »test«. Natančne omejitve naj izhajajo iz pogodbe API-ja ali dokumentacije prevoznika. Ne izmišljajte univerzalne največje dolžine samo zato, ker je večina primerov kratkih.
Strukturno preverjanje mora biti namerno zadržano. Pravilo, ki dovoljuje samo številke, bo na primer zavrnilo veljavne alfanumerične identifikatorje. Pravilo, ki zahteva eno samo določeno dolžino, lahko zavrne različice storitev ali mednarodne oblike. Z generičnimi preverjanji zaznajte očitne napake, nato pa natančnejša preverjanja uporabite le, kadar sta prevoznik in storitev znana.
Preverite tudi podatkovni tip na meji aplikacije. Sledilna številka naj bo običajno obravnavana kot niz, ne kot celo število. Pretvorba v število lahko odstrani začetne ničle in povzroči težave z natančnostjo v sistemih s številskimi tipi fiksne širine. Po odobreni normalizaciji vrednost ohranite natančno kot niz.
3. Uporabite kontekst prevoznika namesto ugibanja samo na podlagi številke
Sledilna številka brez prevoznika je dvoumen vnos. Različni prevozniki lahko uporabljajo enake dolžine, predpone ali nabore znakov, oblika, ki je verjetna pri enem prevozniku, pa je lahko pri drugem neveljavna. Če naročilo, oznaka, skladiščni sistem ali račun trgovca že določa prevoznika, ta kontekst pošljite skupaj s sledilno številko, kadar ga API podpira.
Kontekst prevoznika izboljša preverjanje in usmerjanje. Aplikaciji omogoča izbiro ustreznih pravil za obliko, zmanjša število napačnih ujemanj in naredi sporočila o napakah uporabnejša. Prav tako prepreči, da bi bil rezultat samodejnega zaznavanja obravnavan kot dejstvo, kadar bi lahko podobno vrednost sprejelo več prevoznikov.
Če prevoznik ni znan, uporabite pristop v dveh fazah. Najprej izvedite generična varnostna preverjanja. Nato vrednost pošljite samo prek toka API, ki izrecno podpira zaznavanje prevoznika, ali jo uvrstite v čakalno vrsto za pregled, kadar poslovni proces zahteva potrjenega prevoznika. Prevoznika ne dodelite tiho samo na podlagi predpone, razen če je ta preslikava vzdrževana in dokumentirana.
4. Kontrolne vsote uporabite samo, kadar je pravilo dokumentirano
Nekateri sistemi identifikatorjev uporabljajo kontrolne številke, vendar sledilnih številk ne ureja enoten univerzalni standard kontrolnih vsot. Kontrolna vsota lahko zazna nekatere napake pri prepisovanju, vendar ne dokazuje, da pošiljka obstaja. Še pomembneje, uporaba napačnega algoritma kontrolne vsote lahko zavrne veljavne številke.
Kontrolno vsoto uvedite samo, kadar ustrezna dokumentacija prevoznika, storitve, specifikacija oznake ali API-ja določa algoritem in del vnosa, ki ga algoritem zajema. Zabeležite različico pravila in ga preizkusite na uradnih primerih. Če verodostojno pravilo ni na voljo, kontrolno vsoto preskočite, namesto da bi ugibali na podlagi vzorcev iz majhnega vzorca.
Rezultat kontrolne vsote obravnavajte kot en signal, ne kot popolno odločitev o veljavnosti. Neuspešno preverjanje lahko upraviči blokiranje pošiljanja, kadar je pravilo avtoritativno. Uspešno preverjanje mora vrednost premakniti v naslednjo fazo, ne pa je označiti kot aktivno pošiljko.
5. Ločite preverjanje oblike od upravičenosti za API
Vrednost je lahko pravilno oblikovana, vendar še vedno neprimerna za končno točko, ki jo kličete. Pred pošiljanjem preverite dokumentacijo API-ja glede zahtevanih polj, sprejetih identifikatorjev prevoznikov, zahtev za preverjanje pristnosti, omejitev zahtev, obravnave dvojnikov ter morebitnih omejitev glede vrst storitev ali destinacij. To so integracijska pravila, ne pravila sledilnih številk, vendar določajo, ali je mogoče veljaven identifikator uspešno obdelati.
Dokumentacija API-ja za sledenje 17TRACK je primer, zakaj je ta razlika pomembna: razvijalci morajo upoštevati model zahtev platforme in podprto vedenje integracije, namesto da bi zahtevo izumili na podlagi videza sledilne številke. Za zahteve končne točke in obravnavo odgovorov si oglejte trenutno dokumentacijo na dokumentaciji API-ja 17TRACK.
Napake pri preverjanju ločite od napak prenosa in preverjanja pristnosti. »Neveljavna oblika sledilne številke«, »neznan prevoznik«, »omejitev hitrosti je dosežena« in »preverjanje pristnosti ni uspelo« zahtevajo različna dejanja. Enotno splošno sporočilo »pošiljanje ni uspelo« naredi ponovne poskuse in operativno poročanje manj zanesljive.
6. Zaščitite API z omejenimi vnosi, odstranjevanjem dvojnikov in varnimi ponovnimi poskusi
Preverjanje je tudi operativni zaščitni ukrep. Pred razčlenjevanjem ali beleženjem uveljavite omejeno dolžino vnosa. Zavrnite kontrolne znake in nepričakovane strukture vsebine. Na meji lastne aplikacije uporabite omejitve hitrosti, da napačen uvoz ne more ustvariti nenadzorovanega vala zahtev.
Pred pošiljanjem odstranite dvojnike, kadar poslovni proces ne zahteva ponovne registracije. Uporabni ključ za odstranjevanje dvojnikov lahko vključuje kanonično sledilno številko, prevoznika, račun in kontekst pošiljke. Pravilen ključ je odvisen od vašega procesa; isti identifikator je včasih mogoče ponovno uporabiti pri različnih storitvah ali poslovnih zapisih, zato ne domnevajte, da je številka sama vedno globalno edinstvena.
Za začasne napake uporabite omejeno število ponovnih poskusov z naraščajočim zamikom in se izogibajte ponavljanju trajnih napak pri preverjanju. Ko to podpirata API in vaša arhitektura, shranite zapis o idempotentnosti ali pošiljanju. Zabeležite dovolj informacij za odpravljanje težav, vendar zaščitite poverilnice, podatke strank in občutljive podatke o pošiljkah. Validator mora zmanjšati ponavljajoče se napake, ne pa ustvariti druge varnostne težave zaradi pretiranega beleženja.
7. Po pošiljanju potrdite rezultat in spremljajte napačne pozitivne rezultate
Zadnje pravilo je, da preverjanje pred pošiljanjem obravnavate kot zapornico, ne kot sodbo. Ko je zahteva sprejeta, preglejte odgovor API-ja in shranite njegovo stanje, identifikator zahteve, povezavo s prevoznikom ter morebitno dokumentirano kodo napake. Če platforma sprejme zahtevo, vendar še ne more vrniti dogodkov premikanja, lahko to pomeni zamudo pri obdelavi in ne neveljavne številke.
Določite nadaljnji postopek za številke, ki ostanejo nerešene. Časovno obdobje mora odražati prevoznika, storitev, izvor pošiljke in vašo politiko podpore strankam; ni univerzalnega obdobja, ki bi dokazovalo, da je številka neveljavna. Stopnjujte zapise z manjkajočim prevoznikom, ponavljajočimi se napakami ponudnika, nasprotujočimi rezultati prevoznikov ali stanjem, ki se ne ujema z zapisom naročila.
Merite napačne zavrnitve in napačne sprejeme. Strogi regularni izraz lahko zmanjša število nepravilnih pošiljanj, hkrati pa napačno blokira legitimne pošiljke. Prizanesljiv validator lahko poveča število sprejetih zahtev, vendar ustvari več šuma v nadaljnjih sistemih. Pregledujte neuspešne primere po prevozniku in storitvi, posodabljajte dokumentirana pravila z nadzorom različic ter spremembe preizkušajte na reprezentativnem naboru testnih podatkov, ki varuje zasebnost.
Praktično zaporedje preverjanja
Vzdržljiva implementacija lahko uporablja naslednje zaporedje:
- Preverite, ali zahteva vsebuje niz in veljaven poslovni zapis.
- Shranite izvirni vnos, nato ustvarite dokumentirano kanonično obliko.
- Zavrnite prazne vrednosti, nadomestne vrednosti, nevarne znake in vrednosti zunaj dokumentiranega razpona dolžin.
- Prevoznika določite iz zaupanja vrednih podatkov naročila ali uporabite izrecno podprt tok zaznavanja.
- Pravila sintakse in kontrolne vsote, specifična za prevoznika, uporabite samo, kadar jih podpira verodostojna dokumentacija.
- Preverite zahteve končne točke, stanje dvojnikov in upravičenost za ponovni poskus.
- Pošljite zahtevo, razvrstite odgovor, shranite rezultat in načrtujte nadaljnje ukrepanje za nerešene zapise.
To zaporedje olajša testiranje validatorja, saj ima vsaka odločitev drugačen razlog. Operativnim ekipam prav tako zagotavlja uporabne kategorije napak namesto ene same nejasne napake.
Kontrolni seznam za implementacijo
- Sledilne številke shranjujte kot nize, da ohranite začetne ničle.
- Kadar je pomembna revizijska sledljivost, ločeno hranite izvirne in kanonične vrednosti.
- Pravila prevoznikov vzdržujte kot konfiguracijo z različicami, ne kot razpršene trdo kodirane pogoje.
- Preizkusite črke, številke, vezaje, presledke, vizualno podobne znake Unicode, nadomestne vrednosti in mejne dolžine.
- Kadar je na voljo, uporabite zaupanja vreden kontekst prevoznika.
- Obstoja pošiljke ne sklepajte na podlagi uspešnega ujemanja z regularnim izrazom.
- Trajne napake pri preverjanju razvrstite ločeno od začasnih napak API-ja ali omrežja.
- Pred spreminjanjem pravil oblike ali logike zahtev preglejte dokumentacijo ponudnika.
Pogosta vprašanja
Ali lahko regularni izraz preveri sledilno številko?
Preveri lahko omejen vzorec, kadar sta oblika prevoznika in storitve znani. Ne more dokazati, da številka obstaja, pripada določeni pošiljki ali je trenutno aktivna. Univerzalni izraz bo verjetno ustvaril napačne zavrnitve ali napačna ujemanja.
Ali je treba številko, ki je videti neveljavna, poslati v API?
Očitno prazne, nevarne ali strukturno nemogoče vrednosti je običajno treba ustaviti pred pošiljanjem. Neznane, vendar sicer varne oblike ne smete zavrniti samo zato, ker se ne ujemajo z interno domnevo. Najprej preverite dokumentacijo prevoznika ali uporabite podprt postopek zaznavanja.
Ali je kontrolna vsota dovolj za potrditev pošiljke?
Ne. Kontrolna vsota, kadar se uporablja, preverja le, ali vrednost izpolnjuje matematično pravilo. Ne potrjuje, da je prevoznik številko izdal ali da je paket vstopil v omrežje.
Kaj se mora zgoditi, ko prevoznik ni znan?
Izvedite generična varnostna preverjanja in uporabite tok API, ki izrecno podpira zaznavanje prevoznika, če je na voljo. V nasprotnem primeru zapis obdržite za dopolnitev podatkov ali ročni pregled, namesto da bi prevoznika tiho ugibali.
Kako je treba obravnavati napake API-ja?
Razvrstite jih glede na vzrok. Popravite nepravilne vnose in nepodprte vrednosti prevoznikov; začasne omrežne napake ali napake ponudnika ponovite z omejitvami in zamikom; napake preverjanja pristnosti ali kvote pa usmerite k lastniku integracije. Shranite podrobnosti odgovora, potrebne za diagnostiko, ne da bi razkrili skrivnosti.
Viri
- Dokumentacija API-ja 17TRACK — navodila za zahteve in integracijo za razvijalce API-jev za sledenje.
- API za sledenje 17TRACK — uradne informacije o izdelku in primeri uporabe API-ja.
- Sledenje USPS — uradna vstopna točka za sledenje prevoznika in navodila za stranke.
- Sledenje UPS — uradna vstopna točka za sledenje prevoznika.


