Hogyan ellenőrizze a nyomkövetési számokat API-n keresztüli beküldés előtt: 7 betartandó szabály
Egy nyomkövetési számot rétegekben ellenőrizzen, mielőtt elküldi egy nyomkövetési API-nak: normalizálja a bemenetet, ellenőrizze az alapvető szerkezetét, erősítse meg a fuvarozói környezetet, ellenőrző összeget csak akkor alkalmazzon, ha azt a fuvarozó dokumentációja meghatározza, és utasítsa el az egyértelműen nem biztonságos vagy hiányos értékeket. Ne hagyatkozzon egyetlen univerzális reguláris kifejezésre. A nyomkövetési számok formátuma fuvarozónként, szolgáltatásonként, országonként és szállítmánytípusonként eltér, ezért egy hatékony validátornak meg kell akadályoznia a hibás kéréseket anélkül, hogy blokkolná az ismeretlen formátumot használó, legitim számokat.
Ez az útmutató olyan fejlesztőknek és üzemeltetési csapatoknak készült, akik szállítmánykövetést integrálnak rendeléskezelő rendszerbe, raktári munkafolyamatba, ügyfélportálba vagy e-kereskedelmi alkalmazásba. A cél nem annak bizonyítása, hogy egy csomag létezik-e a beküldés előtt. A szintaktikai validálás és a szállítmány állapotának ellenőrzése két külön lépés.
Mit erősíthet meg — és mit nem — a validálás?
A beküldés előtti validátor azonosíthatja a gyakori bemeneti problémákat, például az üres értéket, a véletlen szóközöket, a nem támogatott karaktereket, a túlzott hosszt vagy azt, ha a nyomkövetési szám rossz mezőbe került. A valószínűsíthető fuvarozót is azonosíthatja, ha a fuvarozó ismert, és a formátuma dokumentált.
Általában nem tudja megerősíteni, hogy egy szám valódi szállítmányhoz tartozik-e, hogy a fuvarozó átvette-e a csomagot, illetve hogy a szám jelenleg követhető-e. Ezekhez a kérdésekhez fuvarozói vagy nyomkövetési platformon végzett lekérdezés szükséges. Egy szám átmehet a formátum-ellenőrzésen, miközben még használaton kívüli, finom módon elírt, lejárt vagy más szolgáltatáshoz társított.
A hét szabály
1. Normalizálja az értéket a jelentés megváltoztatása nélkül
A felhasználók és a feljebb lévő rendszerek gyakran kezdő vagy záró szóközöket, sortöréseket, nem törő szóközöket vagy formázási karaktereket adnak hozzá. Validálás előtt biztonságosan normalizálja ezeket. Gyakori első lépés a körülvevő whitespace eltávolítása és a nem nyomtatható whitespace normál szóközzé alakítása. Ha a fuvarozó dokumentált formátuma engedélyezi a belső szóközöket vagy kötőjeleket, döntse el, hogy eltávolítja-e ezeket az API-kérésből, vagy megőrzi az eredeti értéket megjelenítés és auditálás céljából.
Amikor célszerű, tartson meg két értéket: az eredeti bemenetet és a kanonikus értéket. Az eredeti segít az ügyfélszolgálati csapatoknak az adatminőségi problémák kivizsgálásában; a kanonikus értéket használja validáláshoz és beküldéshez. Kerülje az olyan átalakításokat, amelyek módosíthatják az azonosítókat. Ne alakítsa automatikusan a betűket számokká, ne cserélje le a félreérthető karaktereket, és ne távolítson el minden írásjelet, kivéve, ha az adott fuvarozó vagy API dokumentációja ezt kifejezetten támogatja.
Az Unicode-kezelés külön figyelmet érdemel. Egy másik ábécéből származó, vizuálisan hasonló karaktert az API elutasíthat, még akkor is, ha ASCII-betűnek vagy számjegynek tűnik. A kanonikus értéknek a kiválasztott integráció által engedélyezett karakterkészletre korlátozása megelőzheti a zavaró későbbi hibákat.
2. Utasítsa el az alapvető szerkezeti ellenőrzéseken megbukó értékeket
A fuvarozóspecifikus logika alkalmazása előtt ellenőrizze, hogy az érték jelen van-e és életszerű-e. Hasznos ellenőrzések lehetnek a minimális és maximális hossz, az engedélyezett karakterosztályok, valamint annak vizsgálata, hogy az érték csak whitespace-et vagy olyan helyőrzőt tartalmaz-e, mint például az „N/A”, a „TBD” vagy a „test”. A pontos korlátokat az API-szerződésből vagy a fuvarozó dokumentációjából kell származtatni. Ne találjon ki univerzális maximumot pusztán azért, mert a legtöbb példa rövid.
A szerkezeti ellenőrzésnek szándékosan konzervatívnak kell lennie. Például egy csak számjegyeket engedélyező szabály elutasítja az érvényes alfanumerikus azonosítókat. Egy fix hosszúságot megkövetelő szabály elutasíthatja a szolgáltatásváltozatokat vagy a nemzetközi formátumokat. Általános ellenőrzésekkel fogja meg a nyilvánvaló hibákat, majd csak akkor alkalmazzon specifikusabb ellenőrzéseket, ha a fuvarozó és a szolgáltatás ismert.
Az alkalmazás határán az adattípust is validálja. A nyomkövetési számot általában stringként, nem pedig egész számként kell kezelni. A numerikus átalakítás eltávolíthatja a kezdő nullákat, és pontossági problémákat okozhat a rögzített szélességű numerikus típusokat használó rendszerekben. A jóváhagyott normalizálás után az értéket pontosan stringként őrizze meg.
3. A szám önmagában történő találgatása helyett használja a fuvarozói környezetet
A fuvarozó nélküli nyomkövetési szám nem egyértelmű bemenet. A különböző fuvarozók átfedő hosszúságokat, előtagokat vagy karakterkészleteket használhatnak, és egy adott fuvarozóhoz valószínűnek tűnő formátum egy másiknál érvénytelen lehet. Ha a rendelés, a címke, a raktári rendszer vagy a kereskedői fiók már azonosítja a fuvarozót, minden olyan esetben adja át ezt a környezetet a nyomkövetési számmal együtt, amikor az API támogatja.
A fuvarozói környezet javítja mind a validálást, mind az útválasztást. Lehetővé teszi, hogy az alkalmazás a releváns formátumszabályokat válassza ki, csökkenti a téves egyezéseket, és hasznosabbá teszi a hibaüzeneteket. Azt is megakadályozza, hogy az automatikus felismerés eredményét tényként kezelje, amikor több fuvarozó is elfogadhat egy hasonló kinézetű értéket.
Ha a fuvarozó ismeretlen, használjon kétlépcsős megközelítést. Először futtassa le az általános biztonsági ellenőrzéseket. Ezután csak olyan API-folyamaton keresztül küldje be az értéket, amely kifejezetten támogatja a fuvarozó felismerését, vagy helyezze ellenőrzési sorba, ha az üzleti folyamat megerősített fuvarozót igényel. Ne rendeljen csendben fuvarozót kizárólag egy előtag alapján, kivéve, ha a leképezést karbantartják és dokumentálják.
4. Ellenőrző összeget csak dokumentált szabály esetén alkalmazzon
Egyes azonosítórendszerek ellenőrző számjegyeket használnak, de a nyomkövetési számokra nem vonatkozik egyetlen univerzális ellenőrzőösszeg-szabvány sem. Az ellenőrző összeg bizonyos átírási hibákat felismerhet, de nem bizonyítja, hogy egy szállítmány létezik. Ennél is fontosabb, hogy a nem megfelelő ellenőrzőösszeg-algoritmus alkalmazása érvényes számokat utasíthat el.
Ellenőrző összeget csak akkor valósítson meg, ha az adott fuvarozó, szolgáltatás, címkespecifikáció vagy API-dokumentáció meghatározza az algoritmust és az általa lefedett bemeneti részt. Rögzítse a szabály verzióját, és tesztelje hivatalos példákon. Ha nem áll rendelkezésre hiteles szabály, hagyja ki az ellenőrző összeget ahelyett, hogy egy kis mintában megfigyelt minták alapján találgatna.
Az ellenőrzőösszeg-eredményt egyetlen jelzésként kezelje, ne teljes validálási döntésként. A sikertelen ellenőrzés indokolhatja a beküldés blokkolását, ha a szabály hiteles. A sikeres ellenőrzésnek a következő szakaszba kell juttatnia az értéket, nem pedig élő szállítmánnyá nyilvánítania.
5. Válassza külön a formátumvalidálást és az API-kompatibilitást
Egy érték lehet jól formázott, mégis alkalmatlan az Ön által hívott végponthoz. Beküldés előtt ellenőrizze az API dokumentációjában a kötelező mezőket, az elfogadott fuvarozóazonosítókat, a hitelesítési követelményeket, a kéréskorlátokat, a duplikátumok kezelését, valamint a szolgáltatástípusokra vagy célállomásokra vonatkozó korlátozásokat. Ezek integrációs szabályok, nem nyomkövetési számra vonatkozó szabályok, de meghatározzák, hogy egy érvényes azonosító sikeresen feldolgozható-e.
A 17TRACK Tracking API dokumentációja jól mutatja, miért fontos ez a megkülönböztetés: a fejlesztőknek a platform kérési modelljét és a támogatott integrációs működést kell követniük, nem pedig a nyomkövetési szám megjelenése alapján kitalálniuk egy kérést. A végpontok követelményeiről és a válaszok kezeléséről az aktuális dokumentációban tájékozódjon itt: 17TRACK API-dokumentáció.
A validálási hibákat különítse el a szállítási és hitelesítési hibáktól. Az „Érvénytelen nyomkövetési számformátum”, az „Ismeretlen fuvarozó”, a „Sebességkorlát elérve” és a „Hitelesítés sikertelen” eltérő műveleteket igényel. Egyetlen általános „A beküldés sikertelen” üzenet megbízhatatlanabbá teszi az újrapróbálkozásokat és az üzemeltetési jelentéseket.
6. Védje az API-t korlátozott bemenetekkel, duplikációszűréssel és biztonságos újrapróbálkozásokkal
A validálás egyben üzemeltetési védelmet is jelent. Elemzés vagy naplózás előtt érvényesítsen korlátozott bemeneti hosszt. Utasítsa el a vezérlőkaraktereket és a váratlan payload-struktúrákat. Saját alkalmazási határán alkalmazzon sebességkorlátokat, hogy egy hibás import ne generálhasson ellenőrizetlen kérésrohamot.
Beküldés előtt szűrje ki a duplikátumokat, ha az üzleti folyamat nem igényel ismételt regisztrációt. Hasznos duplikációszűrési kulcs lehet a kanonikus nyomkövetési szám, a fuvarozó, a fiók és a szállítmány környezete. A megfelelő kulcs a munkafolyamattól függ; ugyanaz az azonosító néha különböző szolgáltatásokban vagy üzleti rekordokban is újra felhasználható, ezért ne feltételezze, hogy önmagában a szám mindig globálisan egyedi.
Ideiglenes hibák esetén korlátozott számú, visszalépéssel végrehajtott újrapróbálkozást használjon, és kerülje a végleges validálási hibák újrapróbálását. Rögzítsen idempotencia- vagy beküldési rekordot, ha az API és az architektúra támogatja. A kérés hibakereséséhez elegendő információt naplózzon, de védje a hitelesítő adatokat, az ügyféladatokat és az érzékeny szállítmányadatokat. A validátornak csökkentenie kell az ismételt hibákat, nem pedig túlzott naplózással újabb biztonsági problémát létrehoznia.
7. Beküldés után erősítse meg az eredményt, és figyelje a téves pozitív eredményeket
Az utolsó szabály szerint a beküldés előtti validálást kapunak, nem pedig ítéletnek kell tekinteni. A kérés elfogadása után vizsgálja meg az API-választ, és mentse el annak állapotát, kérésazonosítóját, fuvarozói hozzárendelését és minden dokumentált hibakódját. Ha a platform elfogadja a kérést, de még nem tud mozgási eseményeket visszaadni, ez feldolgozási késedelmet jelezhet, nem pedig érvénytelen számot.
Határozzon meg nyomonkövetési szabályzatot azokra a számokra, amelyek továbbra is feloldatlanok maradnak. Az időablaknak tükröznie kell a fuvarozót, a szolgáltatást, a szállítmány kiindulási helyét és az ügyfélszolgálati szabályzatot; nincs olyan univerzális időszak, amely bizonyítaná, hogy egy szám érvénytelen. Emelje ki azokat a rekordokat, amelyeknél hiányzik a fuvarozó, ismétlődő szolgáltatói hibák jelentkeznek, ellentmondó fuvarozói eredmények érkeznek, vagy az állapot nem egyezik a rendelési rekorddal.
Mérje a téves elutasításokat és a téves elfogadásokat. A szigorú reguláris kifejezés csökkentheti a hibás beküldéseket, miközben tévesen blokkolhat legitim szállítmányokat. Az engedékeny validátor növelheti az elfogadott kérések számát, de későbbi zajt okozhat. Vizsgálja meg a sikertelen mintákat fuvarozó és szolgáltatás szerint, frissítse a dokumentált szabályokat verziókezeléssel, és tesztelje a módosításokat reprezentatív, személyes adatoktól mentes tesztadatkészleten.
Gyakorlati validálási sorrend
Egy karbantartható megvalósítás a következő sorrendet használhatja:
- Ellenőrizze, hogy a kérés string típusú értéket és érvényes üzleti rekordot tartalmaz-e.
- Mentse az eredeti bemenetet, majd hozzon létre dokumentált kanonikus formát.
- Utasítsa el az üres értékeket, a helyőrzőket, a nem biztonságos karaktereket és a dokumentált hossztartományon kívüli értékeket.
- Megbízható rendelési adatokból oldja fel a fuvarozót, vagy használjon kifejezetten támogatott felismerési folyamatot.
- Fuvarozóspecifikus szintaktikai és ellenőrzőösszeg-szabályokat csak akkor alkalmazzon, ha azokat hiteles dokumentáció támogatja.
- Ellenőrizze a végpont követelményeit, a duplikációs állapotot és az újrapróbálkozásra való jogosultságot.
- Küldje be a kérést, osztályozza a választ, mentse az eredményt, és ütemezzen nyomon követést a feloldatlan rekordokhoz.
Ez a sorrend megkönnyíti a validátor tesztelését, mivel minden döntésnek más oka van. Emellett a műveleti csapatok számára egyetlen átláthatatlan hiba helyett használható hibakategóriákat biztosít.
Megvalósítási ellenőrzőlista
- A nyomkövetési számokat stringként tárolja, hogy a kezdő nullák megmaradjanak.
- Ha fontos az auditálhatóság, külön őrizze meg az eredeti és a kanonikus értékeket.
- A fuvarozói szabályokat verziózott konfigurációként tartsa fenn, ne szétszórt, kódba égetett feltételekként.
- Tesztelje a betűket, számjegyeket, kötőjeleket, whitespace-et, Unicode-hoz hasonló karaktereket, helyőrzőket és a határértékű hosszokat.
- Amikor elérhető, használjon megbízható fuvarozói környezetet.
- Sikeres reguláriskifejezés-egyezésből ne következtessen a szállítmány létezésére.
- A végleges validálási hibákat különítse el az ideiglenes API- vagy hálózati hibáktól.
- Formátumszabályok vagy kéréslogika módosítása előtt tekintse át a szolgáltató dokumentációját.
GYIK
Validálható egy nyomkövetési szám reguláris kifejezéssel?
Egy korlátozott mintát validálhat, ha a fuvarozó és a szolgáltatás formátuma ismert. Nem bizonyíthatja azonban, hogy a szám létezik, egy adott szállítmányhoz tartozik vagy jelenleg aktív. Egy univerzális kifejezés valószínűleg téves elutasításokat vagy téves egyezéseket eredményez.
Be kell küldeni az API-nak egy érvénytelennek tűnő számot?
Az egyértelműen üres, nem biztonságos vagy szerkezetileg lehetetlen értékeket általában még beküldés előtt meg kell állítani. Egy ismeretlen, de egyébként biztonságos formátumot nem szabad pusztán azért elutasítani, mert nem egyezik egy belső feltételezéssel. Először ellenőrizze a fuvarozó dokumentációját, vagy használjon támogatott felismerési folyamatot.
Elegendő az ellenőrző összeg a szállítmány megerősítéséhez?
Nem. Az ellenőrző összeg, amikor alkalmazható, csak azt vizsgálja, hogy az érték megfelel-e egy matematikai szabálynak. Nem erősíti meg, hogy a fuvarozó kiadta a számot, vagy hogy a csomag belépett a hálózatba.
Mi történjen, ha a fuvarozó ismeretlen?
Futtassa le az általános biztonsági ellenőrzéseket, és ha elérhető, használjon olyan API-munkafolyamatot, amely kifejezetten támogatja a fuvarozó felismerését. Ellenkező esetben tartsa meg a rekordot kiegészítés vagy manuális ellenőrzés céljából ahelyett, hogy csendben találgatna egy fuvarozót.
Hogyan kell kezelni az API-hibákat?
Osztályozza őket okuk szerint. Javítsa ki a hibás bemenetet és a nem támogatott fuvarozói értékeket; az ideiglenes hálózati vagy szolgáltatói hibákat korlátozott számú, visszalépéssel végrehajtott újrapróbálkozással kezelje; a hitelesítési vagy kvótahibákat pedig irányítsa az integráció felelőséhez. A diagnosztikához szükséges válaszadatokat mentse el a titkok felfedése nélkül.
Források
- 17TRACK API-dokumentáció — kérési és integrációs útmutató a nyomkövetési API fejlesztői számára.
- 17TRACK Tracking API — hivatalos termékinformációk és API-használati esetek.
- USPS Tracking — hivatalos fuvarozói nyomkövetési belépési pont és ügyféltájékoztatás.
- UPS Tracking — hivatalos fuvarozói nyomkövetési belépési pont.


