Skip to main content
ПочетакБлогVodičiКако проверити бројеве за праћење пре слања путем API-ја: 7 правила којих се треба придржавати

Како проверити бројеве за праћење пре слања путем API-ја: 7 правила којих се треба придржавати

17TRACK

Validirajte broj za praćenje u više slojeva pre nego što ga pošaljete API-ju za praćenje: normalizujte unos, proverite njegovu osnovnu strukturu, potvrdite kontekst prevoznika, primenite kontrolnu sumu samo kada je prevoznik dokumentuje i odbacite vrednosti koje su očigledno nebezbedne ili nepotpune. Nemojte se oslanjati na jedan univerzalni regularni izraz. Formati brojeva za praćenje razlikuju se u zavisnosti od prevoznika, usluge, zemlje i vrste pošiljke, pa efikasan validator treba da spreči neispravne zahteve bez blokiranja legitimnih brojeva koji koriste nepoznat format.

Kako validirati brojeve za praćenje pre slanja API-ju: 7 pravila

Ovaj vodič je namenjen programerima i operativnim timovima koji integrišu praćenje pošiljki u sistem za upravljanje porudžbinama, skladišni tok rada, korisnički portal ili aplikaciju za elektronsku trgovinu. Cilj nije dokazati da paket postoji pre slanja. Sintaktička validacija i validacija statusa pošiljke predstavljaju odvojene korake.

Šta validacija može — a šta ne može — da potvrdi

Validator pre slanja može da prepozna uobičajene probleme sa unosom, kao što su prazna vrednost, slučajni razmaci, nepodržani znakovi, prekomerna dužina ili broj za praćenje unet u pogrešno polje. Takođe može da prepozna verovatnog prevoznika kada je prevoznik poznat, a format dokumentovan.

On obično ne može da potvrdi da broj pripada stvarnoj pošiljci, da je prevoznik prihvatio paket ili da se broj trenutno može pratiti. Za ta pitanja potrebna je provera kod prevoznika ili platforme za praćenje. Broj može proći proveru formata, a da i dalje nije korišćen, da sadrži suptilnu grešku u kucanju, da je istekao ili da je povezan sa drugom uslugom.

Vlade pravila

1. Normalizujte vrednost bez promene njenog značenja

Korisnici i sistemi iz kojih podaci potiču često dodaju razmake na početku ili kraju, prelome redova, neprelomive razmake ili znakove za formatiranje. Bezbedno normalizujte ove elemente pre validacije. Uobičajen prvi korak je uklanjanje okolnih praznina i pretvaranje neštampajućih razmaka u obične razmake. Ako dokumentovani format prevoznika dozvoljava unutrašnje razmake ili crtice, odlučite da li ćete ih ukloniti za API zahtev ili sačuvati originalnu vrednost radi prikaza i revizije.

Kada je praktično, čuvajte dve vrednosti: originalni unos i kanonsku vrednost. Original pomaže timovima za podršku da istraže probleme sa kvalitetom podataka, dok se kanonska vrednost koristi za validaciju i slanje. Izbegavajte transformacije koje mogu promeniti identifikatore. Nemojte automatski pretvarati slova u brojeve, menjati dvosmislene znakove ili uklanjati sve znakove interpunkcije, osim ako relevantna dokumentacija prevoznika ili API-ja izričito podržava takvo ponašanje.

Obradi Unicode-a treba posvetiti pažnju. Vizuelno sličan znak iz drugog pisma možda neće biti prihvaćen u API-ju iako izgleda kao ASCII slovo ili cifra. Ograničavanje kanonske vrednosti na skup znakova koji dozvoljava izabrana integracija može sprečiti zbunjujuće greške u narednim sistemima.

2. Odbacite vrednosti koje ne prolaze osnovne strukturne provere

Pre primene logike specifične za prevoznika proverite da li je vrednost prisutna i verovatna. Korisne provere obuhvataju minimalnu i maksimalnu dužinu, dozvoljene klase znakova i proveru da li vrednost sadrži samo praznine ili rezervisanu vrednost kao što su „N/A“, „TBD“ ili „test“. Tačna ograničenja treba da potiču iz ugovora API-ja ili dokumentacije prevoznika. Nemojte izmišljati univerzalnu maksimalnu dužinu samo zato što je većina primera kratka.

Strukturna provera treba da bude namerno konzervativna. Na primer, pravilo koje dozvoljava samo cifre odbaciće važeće alfanumeričke identifikatore. Pravilo koje zahteva jednu fiksnu dužinu može odbaciti varijante usluga ili međunarodne formate. Koristite opšte provere za očigledne greške, a zatim primenite konkretnije provere samo kada su prevoznik i usluga poznati.

Takođe proverite tip podataka na granici aplikacije. Broj za praćenje obično treba tretirati kao nisku, a ne kao ceo broj. Pretvaranje u numerički tip može ukloniti početne nule i izazvati probleme sa preciznošću u sistemima koji koriste numeričke tipove fiksne širine. Nakon odobrene normalizacije sačuvajte vrednost tačno kao nisku.

3. Koristite kontekst prevoznika umesto nagađanja samo na osnovu broja

Broj za praćenje bez prevoznika predstavlja dvosmislen unos. Različiti prevoznici mogu koristiti preklapajuće dužine, prefikse ili skupove znakova, a format koji deluje verovatno za jednog prevoznika može biti nevažeći za drugog. Ako porudžbina, nalepnica, skladišni sistem ili nalog trgovca već identifikuje prevoznika, prosledite taj kontekst zajedno sa brojem za praćenje kad god ga API podržava.

Kontekst prevoznika poboljšava i validaciju i usmeravanje. Omogućava aplikaciji da izabere relevantna pravila formata, smanjuje broj pogrešnih podudaranja i čini poruke o greškama korisnijim. Takođe sprečava da se rezultat automatskog otkrivanja tretira kao činjenica kada bi više prevoznika moglo prihvatiti vrednost sličnog izgleda.

Ako je prevoznik nepoznat, koristite pristup u dva koraka. Najpre izvršite opšte bezbednosne provere. Zatim pošaljite vrednost samo kroz tok API-ja koji izričito podržava otkrivanje prevoznika ili je stavite u red za proveru kada poslovni proces zahteva potvrđenog prevoznika. Nemojte tiho dodeljivati prevoznika samo na osnovu prefiksa, osim ako je to mapiranje održavano i dokumentovano.

4. Primenujte kontrolne sume samo kada je pravilo dokumentovano

Neki sistemi identifikatora koriste kontrolne cifre, ali brojevi za praćenje nisu uređeni jednim univerzalnim standardom kontrolne sume. Kontrolna suma može otkriti određene greške pri prepisivanju, ali ne dokazuje da pošiljka postoji. Štaviše, primena pogrešnog algoritma kontrolne sume može odbaciti važeće brojeve.

Kontrolnu sumu implementirajte samo kada relevantni prevoznik, usluga, specifikacija nalepnice ili dokumentacija API-ja definiše algoritam i deo unosa na koji se on primenjuje. Zabeležite verziju pravila i testirajte ga na zvaničnim primerima. Ako ne postoji merodavno pravilo, preskočite kontrolnu sumu umesto da nagađate na osnovu obrazaca uočenih na malom uzorku.

Rezultat kontrolne sume tretirajte kao jedan signal, a ne kao potpunu odluku o validaciji. Neuspešna provera može opravdati blokiranje slanja kada je pravilo merodavno. Uspešna provera treba da pomeri vrednost u sledeću fazu, a ne da je označi kao aktivnu pošiljku.

5. Odvojite validaciju formata od podobnosti za API

Vrednost može biti pravilno oblikovana, a ipak neprikladna za krajnju tačku koju pozivate. Pre slanja proverite dokumentaciju API-ja u vezi sa obaveznim poljima, prihvaćenim identifikatorima prevoznika, zahtevima za autentifikaciju, ograničenjima zahteva, ponašanjem pri duplikatima i eventualnim ograničenjima za tipove usluga ili odredišta. To su pravila integracije, a ne pravila broja za praćenje, ali ona određuju da li se važeći identifikator može uspešno obraditi.

Dokumentacija 17TRACK Tracking API-ja primer je zašto je ova razlika važna: programeri treba da prate model zahteva platforme i podržano ponašanje integracije, a ne da izmišljaju zahtev na osnovu izgleda broja za praćenje. Aktuelne zahteve krajnjih tačaka i obradu odgovora potražite u dokumentaciji 17TRACK API-ja.

Greške validacije držite odvojeno od grešaka prenosa i autentifikacije. „Nevažeći format broja za praćenje“, „nepoznat prevoznik“, „dostignuto ograničenje brzine“ i „autorizacija nije uspela“ zahtevaju različite postupke. Jedna opšta poruka „slanje nije uspelo“ čini ponovne pokušaje i operativno izveštavanje manje pouzdanim.

6. Zaštitite API ograničenim unosima, uklanjanjem duplikata i bezbednim ponovnim pokušajima

Validacija je i operativna zaštita. Nametnite ograničenu dužinu unosa pre parsiranja ili evidentiranja. Odbacite kontrolne znakove i neočekivane strukture sadržaja. Primenite ograničenja brzine na granici sopstvene aplikacije kako neispravan uvoz ne bi proizveo nekontrolisani nalet zahteva.

Uklonite duplikate pre slanja kada poslovni proces ne zahteva ponovnu registraciju. Koristan ključ za uklanjanje duplikata može obuhvatati kanonski broj za praćenje, prevoznika, nalog i kontekst pošiljke. Ispravan ključ zavisi od vašeg toka rada; isti identifikator ponekad može biti ponovo korišćen za različite usluge ili poslovne zapise, pa nemojte pretpostaviti da je sam broj uvek globalno jedinstven.

Koristite ograničene ponovne pokušaje sa povećanjem intervala za privremene greške i izbegavajte ponavljanje trajnih grešaka validacije. Čuvajte zapis o idempotentnosti ili slanju kada ga API i vaša arhitektura podržavaju. Zabeležite dovoljno informacija za rešavanje problema, ali zaštitite akreditive, podatke o korisnicima i sve osetljive detalje pošiljke. Validator treba da smanji ponovljene greške, a ne da prekomernim evidentiranjem stvori drugi bezbednosni problem.

7. Potvrdite rezultat nakon slanja i pratite lažno pozitivne rezultate

Poslednje pravilo jeste da validaciju pre slanja tretirate kao kapiju, a ne kao konačnu presudu. Nakon prihvatanja zahteva pregledajte odgovor API-ja i sačuvajte njegov status, identifikator zahteva, povezanost sa prevoznikom i svaki dokumentovani kod greške. Ako platforma prihvati zahtev, ali još ne može da vrati događaje kretanja, to može ukazivati na kašnjenje u obradi, a ne na nevažeći broj.

Definišite naknadni postupak za brojeve koji ostanu nerešeni. Vremenski period treba da odražava prevoznika, uslugu, poreklo pošiljke i vašu politiku korisničke službe; ne postoji univerzalni period koji dokazuje da je broj nevažeći. Prosledite na eskalaciju zapise sa nedostajućim prevoznikom, ponovljenim greškama provajdera, neusaglašenim rezultatima prevoznika ili statusom koji se ne podudara sa zapisom porudžbine.

Merite pogrešna odbacivanja i pogrešna prihvatanja. Strogi regularni izraz može smanjiti broj neispravnih slanja, ali istovremeno pogrešno blokirati legitimne pošiljke. Popustljiv validator može povećati broj prihvaćenih zahteva, ali proizvesti šum u narednim sistemima. Pregledajte neuspešne uzorke po prevozniku i usluzi, ažurirajte dokumentovana pravila kroz kontrolu verzija i testirajte izmene na reprezentativnom skupu testnih podataka bez ličnih informacija.

Praktičan redosled validacije

Implementacija koja se lako održava može koristiti sledeći redosled:

  1. Proverite da zahtev sadrži vrednost tipa string i važeći poslovni zapis.
  2. Sačuvajte originalni unos, a zatim kreirajte dokumentovani kanonski oblik.
  3. Odbacite prazne vrednosti, rezervisane vrednosti, nebezbedne znakove i vrednosti izvan dokumentovanog raspona dužine.
  4. Odredite prevoznika na osnovu pouzdanih podataka porudžbine ili koristite izričito podržan tok otkrivanja.
  5. Primenujte sintaksu specifičnu za prevoznika i pravila kontrolne sume samo kada ih podržava merodavna dokumentacija.
  6. Proverite zahteve krajnje tačke, stanje duplikata i podobnost za ponovni pokušaj.
  7. Pošaljite zahtev, klasifikujte odgovor, sačuvajte rezultat i zakažite naknadnu proveru nerešenih zapisa.

Ovaj redosled olakšava testiranje validatora jer svaka odluka ima drugačiji razlog. Takođe operativnim timovima pruža korisne kategorije grešaka umesto jedne nejasne greške.

Kontrolna lista za implementaciju

  • Čuvajte brojeve za praćenje kao stringove kako bi početne nule ostale sačuvane.
  • Čuvajte originalne i kanonske vrednosti odvojeno kada je važna mogućnost revizije.
  • Održavajte pravila prevoznika kao verzionisanu konfiguraciju, a ne kao rasute uslove ugrađene u kod.
  • Testirajte slova, cifre, crtice, praznine, Unicode znakove sličnog izgleda, rezervisane vrednosti i granične dužine.
  • Koristite pouzdan kontekst prevoznika kad god je dostupan.
  • Nemojte zaključivati da pošiljka postoji na osnovu uspešnog podudaranja sa regularnim izrazom.
  • Trajne greške validacije klasifikujte odvojeno od privremenih grešaka API-ja ili mreže.
  • Pre izmene pravila formata ili logike zahteva pregledajte dokumentaciju provajdera.

Česta pitanja

Može li regularni izraz da validira broj za praćenje?

Može da proveri ograničeni obrazac kada su format prevoznika i usluge poznati. Ne može da dokaže da broj postoji, da pripada određenoj pošiljci ili da je trenutno aktivan. Univerzalni izraz će verovatno stvoriti pogrešna odbacivanja ili pogrešna podudaranja.

Da li broj koji izgleda nevažeće treba poslati API-ju?

Očigledno prazne, nebezbedne ili strukturno nemoguće vrednosti obično treba zaustaviti pre slanja. Nepoznat, ali inače bezbedan format ne treba odbaciti samo zato što se ne podudara sa internim nagađanjem. Najpre proverite dokumentaciju prevoznika ili koristite podržani postupak otkrivanja.

Da li je kontrolna suma dovoljna za potvrdu pošiljke?

Ne. Kontrolna suma, kada je primenljiva, samo proverava da li vrednost zadovoljava matematičko pravilo. Ona ne potvrđuje da je prevoznik izdao broj ili da je paket ušao u mrežu.

Šta treba uraditi kada je prevoznik nepoznat?

Izvršite opšte bezbednosne provere i koristite tok API-ja koji izričito podržava otkrivanje prevoznika, ako je dostupan. U suprotnom sačuvajte zapis radi dopune podataka ili ručne provere umesto da tiho nagađate prevoznika.

Kako treba obrađivati greške API-ja?

Klasifikujte ih prema uzroku. Ispravite neispravan unos i nepodržane vrednosti prevoznika; privremene mrežne greške ili greške provajdera ponovite uz ograničenja i povećanje intervala; greške autentifikacije ili kvote prosledite vlasniku integracije. Sačuvajte detalje odgovora potrebne za dijagnostiku bez izlaganja tajni.

Izvori