Skip to main content
HemBloggGuiderSå validerar du spårningsnummer före insändning till API:t: 7 regler att följa

Så validerar du spårningsnummer före insändning till API:t: 7 regler att följa

17TRACK

Validera ett spårningsnummer i flera lager innan du skickar det till ett spårnings-API: normalisera indata, kontrollera dess grundläggande struktur, bekräfta transportörens sammanhang, använd en kontrollsumma endast när transportören dokumenterar en sådan och avvisa värden som uppenbart är osäkra eller ofullständiga. Förlita dig inte på ett enda universellt reguljärt uttryck. Format för spårningsnummer varierar beroende på transportör, tjänst, land och försändelsetyp, så en effektiv validator bör förhindra felaktiga förfrågningar utan att blockera legitima nummer som använder ett ovanligt format.

7 regler för validering av spårningsnummer före API-överföring

Den här guiden är skriven för utvecklare och driftteam som integrerar försändelsespårning i ett orderhanteringssystem, lagerflöde, kundportal eller e-handelsprogram. Målet är inte att bevisa att ett paket existerar före överföringen. Syntaktisk validering och validering av försändelsestatus är separata steg.

Vad validering kan – och inte kan – bekräfta

En validator före överföring kan identifiera vanliga indatafel, till exempel ett tomt värde, oavsiktliga mellanslag, otillåtna tecken, överdriven längd eller ett spårningsnummer som placerats i fel fält. Den kan också identifiera en sannolik transportör när transportören är känd och formatet är dokumenterat.

Den kan normalt inte bekräfta att ett nummer tillhör en verklig försändelse, att paketet har tagits emot av en transportör eller att numret för närvarande kan spåras. Dessa frågor kräver en sökning hos transportören eller spårningsplattformen. Ett nummer kan klara en formatkontroll och ändå vara oanvänt, subtilt felskrivet, utgånget eller kopplat till en annan tjänst.

De sju reglerna

1. Normalisera värdet utan att ändra dess innebörd

Användare och uppströms­system lägger ofta till inledande eller avslutande mellanslag, radbrytningar, icke-brytande mellanslag eller formateringstecken. Normalisera dessa på ett säkert sätt före valideringen. Ett vanligt första steg är att ta bort omgivande blanksteg och omvandla icke-utskrivande blanksteg till vanliga mellanslag. Om transportörens dokumenterade format tillåter interna mellanslag eller bindestreck bör du avgöra om de ska tas bort i API-förfrågan eller om originalvärdet ska bevaras för visning och granskning.

Bevara två värden när det är praktiskt möjligt: den ursprungliga indata och ett kanoniskt värde. Originalet hjälper supportteam att utreda problem med datakvaliteten; det kanoniska värdet används för validering och överföring. Undvik omvandlingar som kan ändra identifierare. Omvandla inte automatiskt bokstäver till siffror, ersätt inte tvetydiga tecken och ta inte bort all interpunktion om inte den relevanta transportörens eller API-dokumentationen uttryckligen stöder detta.

Unicode-hantering kräver uppmärksamhet. Ett visuellt liknande tecken från ett annat alfabet kanske inte accepteras av ett API, även om det ser ut som en ASCII-bokstav eller siffra. Genom att begränsa det kanoniska värdet till den teckenuppsättning som tillåts av den valda integrationen kan du förebygga förvirrande fel längre fram i flödet.

2. Avvisa värden som inte klarar grundläggande strukturkontroller

Innan transportörsspecifik logik tillämpas bör du kontrollera om värdet finns och är rimligt. Användbara kontroller omfattar minsta och största längd, tillåtna teckenklasser och om värdet endast innehåller blanksteg eller en platshållare som ”N/A”, ”TBD” eller ”test”. De exakta gränserna bör komma från API-kontraktet eller transportörens dokumentation. Hitta inte på en universell maxgräns enbart för att de flesta exempel är korta.

En strukturkontroll bör vara medvetet konservativ. En regel som endast tillåter siffror avvisar exempelvis giltiga alfanumeriska identifierare. En regel som kräver en fast längd kan avvisa tjänstevarianter eller internationella format. Använd generella kontroller för att fånga uppenbara fel och tillämpa sedan mer specifika kontroller endast när transportören och tjänsten är kända.

Validera även datatypen vid applikationsgränsen. Ett spårningsnummer bör vanligtvis behandlas som en sträng, inte som ett heltal. Numerisk konvertering kan ta bort inledande nollor och skapa precisionsproblem i system som använder numeriska typer med fast bredd. Bevara värdet exakt som en sträng efter godkänd normalisering.

3. Använd transportörens sammanhang i stället för att gissa utifrån numret ensamt

Ett spårningsnummer utan transportör är tvetydig indata. Olika transportörer kan använda överlappande längder, prefix eller teckenuppsättningar, och ett format som verkar rimligt för en transportör kan vara ogiltigt för en annan. Om ordern, etiketten, lagersystemet eller handlarens konto redan identifierar transportören bör du skicka med detta sammanhang tillsammans med spårningsnumret när API:et stöder det.

Transportörens sammanhang förbättrar både validering och dirigering. Det låter applikationen välja relevanta formatregler, minskar felaktiga träffar och gör felmeddelanden mer användbara. Det förhindrar också att ett resultat från automatisk identifiering behandlas som ett faktum när flera transportörer kan acceptera ett liknande värde.

Om transportören är okänd bör du använda ett tillvägagångssätt i två steg. Kör först generella säkerhetskontroller. Skicka därefter endast värdet genom ett API-flöde som uttryckligen stöder transportörsidentifiering, eller placera det i en granskningskö när affärsprocessen kräver en bekräftad transportör. Tilldela inte i tysthet en transportör enbart baserat på ett prefix om inte denna koppling underhålls och dokumenteras.

4. Använd kontrollsummor endast när regeln är dokumenterad

Vissa identifieringssystem använder kontrollsiffror, men spårningsnummer styrs inte av en enda universell standard för kontrollsummor. En kontrollsumma kan upptäcka vissa transkriptionsfel, men bevisar inte att en försändelse existerar. Ännu viktigare är att användning av fel kontrollsummealgoritm kan avvisa giltiga nummer.

Implementera en kontrollsumma endast när den relevanta transportören, tjänsten, etikettspecifikationen eller API-dokumentationen definierar algoritmen och den del av indata som omfattas. Dokumentera regelns version och testa den mot officiella exempel. Om ingen tillförlitlig regel finns bör du hoppa över kontrollsumman i stället för att gissa utifrån mönster som observerats i ett litet urval.

Betrakta resultatet från en kontrollsumma som en signal, inte som ett fullständigt valideringsbeslut. Ett underkänt resultat kan motivera att en överföring blockeras när regeln är auktoritativ. Ett godkänt resultat bör flytta värdet till nästa steg, inte markera det som en aktiv försändelse.

5. Separera formatvalidering från API-behörighet

Ett värde kan vara välformat men ändå olämpligt för den slutpunkt du anropar. Kontrollera före överföringen API-dokumentationen för obligatoriska fält, godkända transportörsidentifierare, autentiseringskrav, begränsningar för förfrågningar, hantering av dubbletter och eventuella begränsningar för tjänstetyper eller destinationer. Detta är integrationsregler, inte regler för spårningsnummer, men de avgör om en giltig identifierare kan behandlas framgångsrikt.

Dokumentationen för 17TRACK Tracking API är ett exempel på varför denna skillnad är viktig: utvecklare måste följa plattformens modell för förfrågningar och stödda integrationsbeteende i stället för att skapa en förfrågan utifrån hur ett spårningsnummer ser ut. Läs den aktuella dokumentationen om krav på slutpunkter och hantering av svar på 17TRACK API-dokumentation.

Håll valideringsfel åtskilda från transport- och autentiseringsfel. ”Ogiltigt format för spårningsnummer”, ”okänd transportör”, ”hastighetsgränsen nådd” och ”auktorisering misslyckades” kräver olika åtgärder. Ett enda generiskt meddelande som ”överföringen misslyckades” gör omförsök och operativ rapportering mindre tillförlitliga.

6. Skydda API:et med begränsad indata, deduplicering och säkra omförsök

Validering är också en operativ skyddsåtgärd. Tillämpa en begränsad indata­längd före parsning eller loggning. Avvisa kontrolltecken och oväntade nyttolaststrukturer. Tillämpa hastighetsbegränsningar vid din egen applikationsgräns så att en felaktig import inte kan skapa en okontrollerad mängd förfrågningar.

Ta bort dubbletter före överföring när affärsprocessen inte kräver upprepad registrering. En användbar nyckel för deduplicering kan innehålla det kanoniska spårningsnumret, transportören, kontot och försändelsens sammanhang. Den korrekta nyckeln beror på ditt arbetsflöde; samma identifierare kan ibland återanvändas för olika tjänster eller affärsposter, så anta inte att numret ensamt alltid är globalt unikt.

Använd begränsade omförsök med backoff vid tillfälliga fel och undvik att försöka igen vid permanenta valideringsfel. Spara en idempotens- eller överföringspost när API:et och din arkitektur stöder det. Logga tillräckligt med information för att felsöka förfrågan, men skydda autentiseringsuppgifter, kunddata och känsliga försändelseuppgifter. En validator bör minska upprepade fel, inte skapa ett andra säkerhetsproblem genom överdriven loggning.

7. Bekräfta resultatet efter överföringen och övervaka falska positiva resultat

Den sista regeln är att betrakta validering före överföring som en grind, inte som ett slutgiltigt besked. När förfrågan har godkänts ska du granska API-svaret och spara dess status, förfrågningsidentifierare, transportörskoppling och eventuella dokumenterade felkoder. Om plattformen accepterar förfrågan men ännu inte kan returnera händelser om försändelsens rörelser kan det tyda på en bearbetningsfördröjning snarare än ett ogiltigt nummer.

Definiera en uppföljningspolicy för nummer som förblir olösta. Tidsfönstret bör återspegla transportören, tjänsten, försändelsens ursprung och din kundservicepolicy; det finns ingen universell period som bevisar att ett nummer är ogiltigt. Eskalera poster med saknad transportör, upprepade leverantörsfel, motstridiga transportörsresultat eller en status som inte överensstämmer med orderposten.

Mät falska avvisningar och falska godkännanden. Ett strikt reguljärt uttryck kan minska felaktiga överföringar men samtidigt blockera legitima försändelser. En tillåtande validator kan öka antalet godkända förfrågningar men skapa brus längre fram i flödet. Granska misslyckade exempel per transportör och tjänst, uppdatera dokumenterade regler genom versionshantering och testa ändringar mot en representativ, integritetssäker uppsättning testdata.

En praktisk valideringssekvens

En underhållbar implementering kan använda följande sekvens:

  1. Kontrollera att förfrågan innehåller ett strängvärde och en giltig affärspost.
  2. Spara originalindatan och skapa sedan en dokumenterad kanonisk form.
  3. Avvisa tomma värden, platshållare, osäkra tecken och värden utanför det dokumenterade längdintervallet.
  4. Fastställ transportören från tillförlitliga orderdata eller använd ett uttryckligen stödd identifieringsflöde.
  5. Tillämpa transportörsspecifika syntax- och kontrollsumme­regler endast när auktoritativ dokumentation stöder dem.
  6. Kontrollera krav på slutpunkten, dubblettstatus och omförsöksbehörighet.
  7. Skicka förfrågan, klassificera svaret, spara resultatet och planera uppföljning för olösta poster.

Denna sekvens gör validatorn enklare att testa eftersom varje beslut har en egen orsak. Den ger också driftteam användbara felkategorier i stället för ett enda ogenomskinligt fel.

Checklista för implementering

  • Lagra spårningsnummer som strängar så att inledande nollor bevaras.
  • Bevara original- och kanoniska värden separat när spårbarhet är viktig.
  • Underhåll transportörsregler som versionshanterad konfiguration, inte som utspridda hårdkodade villkor.
  • Testa bokstäver, siffror, bindestreck, blanksteg, Unicode-tecken som ser likadana ut, platshållare och gränslängder.
  • Använd tillförlitligt transportörssammanhang när det finns tillgängligt.
  • Dra inte slutsatsen att en försändelse existerar baserat på en lyckad matchning med ett reguljärt uttryck.
  • Klassificera permanenta valideringsfel separat från tillfälliga API- eller nätverksfel.
  • Granska leverantörens dokumentation innan du ändrar formatregler eller logik för förfrågningar.

Vanliga frågor

Kan ett reguljärt uttryck validera ett spårningsnummer?

Det kan validera ett begränsat mönster när transportörens och tjänstens format är känt. Det kan inte bevisa att numret existerar, tillhör en viss försändelse eller för närvarande är aktivt. Ett universellt uttryck skapar sannolikt falska avvisningar eller falska träffar.

Bör ett nummer som ser ogiltigt ut skickas till API:et?

Uppenbart tomma, osäkra eller strukturellt omöjliga värden bör normalt stoppas före överföring. Ett ovanligt men i övrigt säkert format bör inte avvisas enbart för att det inte överensstämmer med en intern gissning. Kontrollera transportörens dokumentation eller använd först en stödd identifieringsprocess.

Räcker en kontrollsumma för att bekräfta en försändelse?

Nej. En kontrollsumma, när den är tillämplig, testar endast om värdet uppfyller en matematisk regel. Den bekräftar inte att en transportör utfärdade numret eller att paketet har kommit in i nätverket.

Vad bör hända när transportören är okänd?

Kör generella säkerhetskontroller och använd ett API-arbetsflöde som uttryckligen stöder transportörsidentifiering, om det finns tillgängligt. Behåll annars posten för komplettering eller manuell granskning i stället för att i tysthet gissa en transportör.

Hur bör API-fel hanteras?

Klassificera dem efter orsak. Korrigera felaktig indata och transportörsvärden som inte stöds; försök igen vid tillfälliga nätverks- eller leverantörsfel med begränsningar och backoff; och hänvisa autentiserings- eller kvotfel till integrationsansvarig. Spara de svarsdetaljer som krävs för diagnos utan att avslöja hemligheter.

Källor