Skip to main content
HjemBlogVejledningerSådan validerer du trackingnumre før indsendelse til API'et: 7 regler, du skal følge

Sådan validerer du trackingnumre før indsendelse til API'et: 7 regler, du skal følge

17TRACK

Validér et trackingnummer i flere lag, før det sendes til en tracking-API: normalisér inputtet, kontrollér den grundlæggende struktur, bekræft transportørens kontekst, anvend kun et kontrolciffer, når transportøren dokumenterer et sådant, og afvis værdier, der tydeligvis er usikre eller ufuldstændige. Stol ikke på ét universelt regulært udtryk. Formater for trackingnumre varierer efter transportør, tjeneste, land og forsendelsestype, så en effektiv validator bør forhindre ugyldige forespørgsler uden at blokere legitime numre, der bruger et ukendt format.

Sådan validerer du trackingnumre før API-indsendelse – 7 regler

Denne vejledning er skrevet til udviklere og driftsteams, der integrerer forsendelsessporing i et ordre­styringssystem, et lagerworkflow, en kundeportal eller en e-handelsapplikation. Målet er ikke at bevise, at en pakke eksisterer, før den indsendes. Syntaktisk validering og validering af forsendelsesstatus er separate trin.

Hvad validering kan – og ikke kan – bekræfte

En validator før indsendelse kan identificere almindelige inputproblemer såsom en tom værdi, utilsigtede mellemrum, tegn, der ikke understøttes, overdreven længde eller et trackingnummer, der er placeret i det forkerte felt. Den kan også identificere en sandsynlig transportør, når transportøren er kendt, og formatet er dokumenteret.

Den kan normalt ikke bekræfte, at et nummer tilhører en reel forsendelse, at pakken er blevet accepteret af en transportør, eller at nummeret i øjeblikket kan spores. Disse spørgsmål kræver et opslag hos transportøren eller trackingplatformen. Et nummer kan bestå et formatcheck og stadig være ubrugt, indeholde en subtil tastefejl, være udløbet eller være knyttet til en anden tjeneste.

De syv regler

1. Normalisér værdien uden at ændre dens betydning

Brugere og upstream-systemer tilføjer ofte indledende eller afsluttende mellemrum, linjeskift, ikke-brydende mellemrum eller formateringstegn. Normalisér disse sikkert før validering. Et almindeligt første trin er at fjerne omgivende whitespace og konvertere ikke-udskrivende whitespace til almindelige mellemrum. Hvis transportørens dokumenterede format tillader interne mellemrum eller bindestreger, skal du beslutte, om de skal fjernes til API-forespørgslen eller bevare den oprindelige værdi til visning og revision.

Bevar to værdier, når det er praktisk: det oprindelige input og en kanonisk værdi. Den oprindelige værdi hjælper supportteams med at undersøge problemer med datakvalitet; den kanoniske værdi bruges til validering og indsendelse. Undgå transformationer, der kan ændre identifikatorer. Konvertér ikke automatisk bogstaver til tal, erstat ikke tvetydige tegn, og fjern ikke alle tegnsætningstegn, medmindre den relevante transportør eller API-dokumentation udtrykkeligt understøtter denne adfærd.

Unicode-håndtering kræver opmærksomhed. Et tegn fra et andet alfabet, der ser visuelt ens ud, accepteres måske ikke af en API, selv om det ligner et ASCII-bogstav eller -ciffer. Ved at begrænse den kanoniske værdi til det tegnsæt, der er tilladt af den valgte integration, kan du forebygge forvirrende fejl længere nede i systemet.

2. Afvis værdier, der ikke består grundlæggende strukturelle kontroller

Før du anvender transportørspecifik logik, skal du kontrollere, om værdien er til stede og plausibel. Nyttige kontroller omfatter minimums- og maksimumslængde, tilladte tegnklasser, og om værdien kun indeholder whitespace eller en pladsholder som “N/A”, “TBD” eller “test”. De præcise grænser bør komme fra API-kontrakten eller transportørens dokumentation. Opfind ikke et universelt maksimum blot fordi de fleste eksempler er korte.

En strukturel kontrol bør være bevidst konservativ. En regel, der kun tillader cifre, vil for eksempel afvise gyldige alfanumeriske identifikatorer. En regel, der kræver én fast længde, kan afvise servicevarianter eller internationale formater. Brug generiske kontroller til at fange åbenlyse fejl, og anvend derefter mere specifikke kontroller, når transportøren og tjenesten er kendt.

Valider også datatypen ved applikationsgrænsen. Et trackingnummer bør normalt behandles som en streng, ikke som et heltal. Numerisk konvertering kan fjerne indledende nuller og skabe præcisionsproblemer i systemer, der bruger numeriske typer med fast bredde. Bevar værdien nøjagtigt som en streng efter godkendt normalisering.

3. Brug transportørens kontekst i stedet for kun at gætte ud fra nummeret

Et trackingnummer uden en transportør er et tvetydigt input. Forskellige transportører kan bruge overlappende længder, præfikser eller tegnsæt, og et format, der ser plausibelt ud for én transportør, kan være ugyldigt for en anden. Hvis ordren, etiketten, lagersystemet eller forhandlerkontoen allerede identificerer transportøren, skal du sende denne kontekst sammen med trackingnummeret, når API'en understøtter det.

Transportørens kontekst forbedrer både validering og routing. Den gør det muligt for applikationen at vælge de relevante formatregler, reducerer falske match og gør fejlmeddelelser mere nyttige. Den forhindrer også, at et resultat fra automatisk registrering behandles som et faktum, når flere transportører kunne acceptere en lignende værdi.

Hvis transportøren er ukendt, skal du bruge en totrinsmetode. Kør først generiske sikkerhedskontroller. Indsend derefter kun værdien gennem et API-flow, der udtrykkeligt understøtter transportørregistrering, eller læg den i en gennemgangskø, når forretningsprocessen kræver en bekræftet transportør. Tildel ikke stiltiende en transportør udelukkende ud fra et præfiks, medmindre denne mapping vedligeholdes og er dokumenteret.

4. Anvend kun kontrolcifre, når reglen er dokumenteret

Nogle identifikatorsystemer bruger kontrolcifre, men trackingnumre er ikke underlagt én universel standard for kontrolsummer. En kontrolsum kan registrere bestemte transskriptionsfejl, men den beviser ikke, at en forsendelse eksisterer. Endnu vigtigere er det, at anvendelse af den forkerte kontrolsumalgoritme kan afvise gyldige numre.

Implementér kun en kontrolsum, når den relevante transportør, tjeneste, etiket­specifikation eller API-dokumentation definerer algoritmen og den del af inputtet, der er omfattet. Registrér reglens version, og test den mod officielle eksempler. Hvis der ikke findes en autoritativ regel, skal du springe kontrollen over i stedet for at gætte ud fra mønstre, der er observeret i en lille stikprøve.

Betragt et kontrolsumresultat som ét signal, ikke som en fuldstændig valideringsbeslutning. En fejlet kontrol kan begrunde blokering af en indsendelse, når reglen er autoritativ. En bestået kontrol bør flytte værdien til næste trin, ikke markere den som en aktiv forsendelse.

5. Adskil formatvalidering fra API-egnethed

En værdi kan være korrekt udformet, men stadig være uegnet til det endpoint, du kalder. Før indsendelse skal du kontrollere API-dokumentationen for påkrævede felter, accepterede transportøridentifikatorer, godkendelseskrav, anmodningsgrænser, håndtering af dubletter samt eventuelle begrænsninger for tjenestetyper eller destinationer. Dette er integrationsregler, ikke trackingnummerregler, men de afgør, om en gyldig identifikator kan behandles korrekt.

Dokumentationen til 17TRACK Tracking API er et eksempel på, hvorfor denne sondring er vigtig: Udviklere skal følge platformens anmodningsmodel og understøttede integrationsadfærd i stedet for at opfinde en forespørgsel ud fra trackingnummerets udseende. Se den aktuelle dokumentation for krav til endpoints og håndtering af svar på 17TRACK API-dokumentation.

Hold valideringsfejl adskilt fra transport- og godkendelsesfejl. “Ugyldigt trackingnummerformat”, “ukendt transportør”, “hastighedsbegrænsning nået” og “godkendelse mislykkedes” kræver forskellige handlinger. En enkelt generisk meddelelse om, at “indsendelsen mislykkedes”, gør gentagelser og driftsrapportering mindre pålidelige.

6. Beskyt API'en med begrænsede inputs, deduplikering og sikre gentagelser

Validering er også en driftsmæssig sikkerhedsforanstaltning. Håndhæv en begrænset inputlængde før parsing eller logning. Afvis kontroltegn og uventede payloadstrukturer. Anvend hastighedsbegrænsninger ved din egen applikationsgrænse, så en fejlbehæftet import ikke kan generere en ukontrolleret bølge af forespørgsler.

Fjern dubletter før indsendelse, når forretningsprocessen ikke kræver gentagen registrering. En nyttig deduplikeringsnøgle kan omfatte det kanoniske trackingnummer, transportør, konto og forsendelseskontekst. Den korrekte nøgle afhænger af dit workflow; den samme identifikator kan nogle gange genbruges på tværs af forskellige tjenester eller forretningsposter, så antag ikke, at nummeret alene altid er globalt unikt.

Brug begrænsede gentagelser med backoff ved midlertidige fejl, og gentag ikke permanente valideringsfejl. Gem en idempotens- eller indsendelsespost, når API'en og din arkitektur understøtter det. Log tilstrækkelige oplysninger til fejlfinding, men beskyt legitimationsoplysninger, kundedata og følsomme forsendelsesoplysninger. En validator bør reducere gentagne fejl, ikke skabe et nyt sikkerhedsproblem gennem overdreven logning.

7. Bekræft resultatet efter indsendelse, og overvåg falske positive

Den sidste regel er at betragte validering før indsendelse som en port, ikke som en dom. Når anmodningen er accepteret, skal du kontrollere API-svaret og gemme dets status, anmodningsidentifikator, transportørtilknytning og eventuelle dokumenterede fejlkoder. Hvis platformen accepterer anmodningen, men endnu ikke kan returnere hændelser om bevægelser, kan det være tegn på behandlingsforsinkelse snarere end et ugyldigt nummer.

Definér en opfølgningspolitik for numre, der forbliver uafklarede. Tidsvinduet bør afspejle transportøren, tjenesten, forsendelsens oprindelse og din kundeservicepolitik; der findes ingen universel periode, der beviser, at et nummer er ugyldigt. Eskalér poster med manglende transportør, gentagne leverandørfejl, modstridende transportørresultater eller en status, der ikke stemmer overens med ordreposten.

Mål falske afvisninger og falske acceptationer. Et strengt regulært udtryk kan reducere fejlbehæftede indsendelser, samtidig med at legitime forsendelser fejlagtigt blokeres. En lempelig validator kan øge antallet af accepterede forespørgsler, men skabe støj længere nede i systemet. Gennemgå mislykkede eksempler efter transportør og tjeneste, opdatér dokumenterede regler gennem versionsstyring, og test ændringer mod et repræsentativt, privatlivssikkert fixturesæt.

En praktisk valideringssekvens

En vedligeholdelsesvenlig implementering kan bruge følgende sekvens:

  1. Kontrollér, at anmodningen indeholder en strengværdi og en gyldig forretningspost.
  2. Gem det oprindelige input, og opret derefter en dokumenteret kanonisk form.
  3. Afvis tomme værdier, pladsholdere, usikre tegn og værdier uden for det dokumenterede længdeinterval.
  4. Find transportøren ud fra pålidelige ordredata, eller brug et udtrykkeligt understøttet registreringsflow.
  5. Anvend kun transportørspecifik syntaks og kontrolsumregler, når autoritativ dokumentation understøtter dem.
  6. Kontrollér endpointkrav, dubletstatus og egnethed til gentagelse.
  7. Indsend, klassificér svaret, gem resultatet, og planlæg opfølgning på uafklarede poster.

Denne sekvens gør validatoren lettere at teste, fordi hver beslutning har en forskellig begrundelse. Den giver også driftsteams handlingsrettede fejlkategorier i stedet for én uigennemsigtig fejl.

Implementeringstjekliste

  • Gem trackingnumre som strenge, så indledende nuller bevares.
  • Bevar oprindelige og kanoniske værdier separat, når revisionsmulighed er vigtig.
  • Vedligehold transportørregler som versionsstyret konfiguration, ikke som spredte hardcodede betingelser.
  • Test bogstaver, cifre, bindestreger, whitespace, Unicode-lignende tegn, pladsholdere og grænselængder.
  • Brug pålidelig transportørkontekst, når den er tilgængelig.
  • Udled ikke, at en forsendelse eksisterer, fordi den matcher et regulært udtryk.
  • Klassificér permanente valideringsfejl separat fra midlertidige API- eller netværksfejl.
  • Gennemgå leverandørens dokumentation, før du ændrer formatregler eller anmodningslogik.

Ofte stillede spørgsmål

Kan et regulært udtryk validere et trackingnummer?

Det kan validere et begrænset mønster, når transportørens og tjenestens format er kendt. Det kan ikke bevise, at nummeret eksisterer, tilhører en bestemt forsendelse eller er aktivt i øjeblikket. Et universelt udtryk vil sandsynligvis skabe falske afvisninger eller falske match.

Bør et nummer, der ser ugyldigt ud, indsendes til API'en?

Tydeligt tomme, usikre eller strukturelt umulige værdier bør normalt stoppes før indsendelse. Et ukendt, men ellers sikkert format bør ikke afvises alene, fordi det ikke matcher et internt gæt. Kontrollér først transportørens dokumentation, eller brug en understøttet registreringsproces.

Er en kontrolsum nok til at bekræfte en forsendelse?

Nej. En kontrolsum, når den er relevant, tester kun, om værdien opfylder en matematisk regel. Den bekræfter ikke, at en transportør har udstedt nummeret, eller at pakken er kommet ind i netværket.

Hvad skal der ske, når transportøren er ukendt?

Kør generiske sikkerhedskontroller, og brug et API-workflow, der udtrykkeligt understøtter transportørregistrering, hvis det er tilgængeligt. Ellers skal du bevare posten til berigelse eller manuel gennemgang i stedet for stiltiende at gætte transportøren.

Hvordan skal API-fejl håndteres?

Klassificér dem efter årsag. Ret fejlbehæftet input og transportørværdier, der ikke understøttes; gentag midlertidige netværks- eller leverandørfejl med begrænsninger og backoff; og send godkendelses- eller kvotefejl til den integrationsansvarlige. Gem de svardetaljer, der er nødvendige til diagnosticering, uden at afsløre hemmeligheder.

Kilder