Skip to main content
HjemBloggVeiledningerSlik validerer du sporingsnumre før innsending til API-et: 7 regler du bør følge

Slik validerer du sporingsnumre før innsending til API-et: 7 regler du bør følge

17TRACK

Valider et sporingsnummer i flere lag før du sender det til et sporings-API: normaliser inndataene, kontroller grunnleggende struktur, bekreft transportørkonteksten, bruk kontrollsiffer bare når transportøren dokumenterer dette, og avvis verdier som tydelig er usikre eller ufullstendige. Ikke stol på ett universelt regulært uttrykk. Formater for sporingsnumre varierer etter transportør, tjeneste, land og forsendelsestype, så en effektiv validator bør forhindre ugyldige forespørsler uten å blokkere legitime numre som bruker et ukjent format.

Slik validerer du sporingsnumre før API-innsending – 7 regler

Denne veiledningen er skrevet for utviklere og driftsteam som integrerer forsendelsessporing i et ordrebehandlingssystem, en lagerarbeidsflyt, en kundeportal eller en netthandelsapplikasjon. Målet er ikke å bevise at en pakke eksisterer før innsending. Syntaktisk validering og validering av forsendelsesstatus er separate trinn.

Hva validering kan – og ikke kan – bekrefte

En validator før innsending kan identifisere vanlige inndataproblemer, som en tom verdi, utilsiktede mellomrom, tegn som ikke støttes, overdreven lengde eller et sporingsnummer som er plassert i feil felt. Den kan også identifisere en sannsynlig transportør når transportøren er kjent og formatet er dokumentert.

Den kan normalt ikke bekrefte at et nummer tilhører en reell forsendelse, at pakken er mottatt av en transportør, eller at nummeret kan spores på nåværende tidspunkt. Disse spørsmålene krever et oppslag hos transportøren eller sporingsplattformen. Et nummer kan bestå en formatsjekk og likevel være ubrukt, feilstavet på en subtil måte, utløpt eller knyttet til en annen tjeneste.

De sju reglene

1. Normaliser verdien uten å endre betydningen

Brukere og oppstrømsystemer legger ofte til innledende eller avsluttende mellomrom, linjeskift, harde mellomrom eller formateringstegn. Normaliser dette på en trygg måte før validering. Et vanlig første trinn er å fjerne mellomrom rundt verdien og konvertere ikke-skrivbare mellomrom til vanlige mellomrom. Hvis transportørens dokumenterte format tillater interne mellomrom eller bindestreker, må du avgjøre om de skal fjernes for API-forespørselen eller om den opprinnelige verdien skal bevares for visning og revisjon.

Behold to verdier når det er praktisk: den opprinnelige inndataen og en kanonisk verdi. Den opprinnelige verdien hjelper supportteam med å undersøke problemer med datakvaliteten; den kanoniske verdien brukes til validering og innsending. Unngå transformasjoner som kan endre identifikatorer. Ikke konverter automatisk bokstaver til tall, erstatt tvetydige tegn eller fjern all tegnsetting med mindre den relevante transportøren eller API-dokumentasjonen uttrykkelig støtter dette.

Unicode-håndtering krever oppmerksomhet. Et tegn fra et annet alfabet som ser visuelt likt ut, godtas kanskje ikke av et API selv om det ser ut som en ASCII-bokstav eller et ASCII-siffer. Ved å begrense den kanoniske verdien til tegnsettet som tillates av den valgte integrasjonen, kan du forhindre forvirrende feil lenger ned i systemet.

2. Avvis verdier som ikke består grunnleggende struktursjekker

Før du bruker transportørspesifikk logikk, må du kontrollere om verdien finnes og virker plausibel. Nyttige kontroller omfatter minimums- og maksimumslengde, tillatte tegnklasser og om verdien bare inneholder mellomrom eller en plassholder som «N/A», «TBD» eller «test». De nøyaktige grensene bør komme fra API-kontrakten eller transportørens dokumentasjon. Unngå å finne opp en universell maksimumsgrense bare fordi de fleste eksemplene er korte.

En struktursjekk bør være bevisst konservativ. En regel som for eksempel bare tillater sifre, vil avvise gyldige alfanumeriske identifikatorer. En regel som krever én fast lengde, kan avvise tjenestevarianter eller internasjonale formater. Bruk generelle kontroller for å fange opp åpenbare feil, og bruk deretter mer spesifikke kontroller bare når transportør og tjeneste er kjent.

Valider også datatypen ved applikasjonsgrensen. Et sporingsnummer bør vanligvis behandles som en streng, ikke som et heltall. Numerisk konvertering kan fjerne innledende nuller og skape presisjonsproblemer i systemer som bruker numeriske typer med fast bredde. Bevar verdien nøyaktig som en streng etter godkjent normalisering.

3. Bruk transportørkontekst i stedet for å gjette ut fra nummeret alene

Et sporingsnummer uten transportør er en tvetydig inndata. Ulike transportører kan bruke overlappende lengder, prefikser eller tegnsett, og et format som virker plausibelt for én transportør, kan være ugyldig for en annen. Hvis ordren, etiketten, lagersystemet eller selgerkontoen allerede identifiserer transportøren, bør du sende denne konteksten sammen med sporingsnummeret når API-et støtter det.

Transportørkontekst forbedrer både validering og ruting. Den lar applikasjonen velge relevante formatregler, reduserer falske treff og gjør feilmeldingene mer nyttige. Den hindrer også at et resultat fra automatisk gjenkjenning behandles som et faktum når flere transportører kan godta en verdi som ser lik ut.

Hvis transportøren er ukjent, bør du bruke en tilnærming i to trinn. Kjør først generelle sikkerhetskontroller. Send deretter verdien bare gjennom en API-flyt som uttrykkelig støtter transportørgjenkjenning, eller legg den i en gjennomgangskø når forretningsprosessen krever en bekreftet transportør. Ikke tilordne en transportør i stillhet basert bare på et prefiks med mindre tilordningen vedlikeholdes og er dokumentert.

4. Bruk kontrollsiffer bare når regelen er dokumentert

Noen identifikatorsystemer bruker kontrollsifre, men sporingsnumre styres ikke av én universell standard for kontrollsifre. Et kontrollsiffer kan oppdage enkelte transkripsjonsfeil, men beviser ikke at en forsendelse eksisterer. Enda viktigere er det at bruk av feil algoritme kan avvise gyldige numre.

Implementer kontrollsiffer bare når den relevante transportøren, tjenesten, etikettspesifikasjonen eller API-dokumentasjonen definerer algoritmen og hvilken del av inndataen den gjelder for. Registrer versjonen av regelen og test den mot offisielle eksempler. Hvis ingen autoritativ regel finnes, bør du hoppe over kontrollsifferet i stedet for å gjette ut fra mønstre i et lite utvalg.

Betrakt resultatet fra kontrollsifferet som ett signal, ikke som en fullstendig valideringsavgjørelse. En mislykket kontroll kan begrunne blokkering av en innsending når regelen er autoritativ. En bestått kontroll bør flytte verdien til neste trinn, ikke merke den som en aktiv forsendelse.

5. Skill mellom formatvalidering og API-kvalifisering

En verdi kan være riktig utformet, men likevel uegnet for endepunktet du kaller. Før innsending må du kontrollere API-dokumentasjonen for obligatoriske felt, godkjente transportøridentifikatorer, autentiseringskrav, forespørselsgrenser, håndtering av duplikater og eventuelle begrensninger for tjenestetyper eller destinasjoner. Dette er integrasjonsregler, ikke regler for sporingsnumre, men de avgjør om en gyldig identifikator kan behandles.

Dokumentasjonen for 17TRACK Tracking API er et eksempel på hvorfor dette skillet er viktig: Utviklere må følge plattformens forespørselsmodell og støttede integrasjonsatferd i stedet for å lage en forespørsel basert på hvordan et sporingsnummer ser ut. Se den gjeldende dokumentasjonen for krav til endepunkter og håndtering av svar på 17TRACK API-dokumentasjon.

Hold valideringsfeil adskilt fra transport- og autentiseringsfeil. «Ugyldig format for sporingsnummer», «ukjent transportør», «hastighetsgrensen er nådd» og «autorisasjon mislyktes» krever ulike tiltak. Én generell melding om «innsending mislyktes» gjør nye forsøk og driftsrapportering mindre pålitelig.

6. Beskytt API-et med begrensede inndata, deduplisering og trygge nye forsøk

Validering er også et driftsmessig sikkerhetstiltak. Håndhev en begrenset inndatalengde før parsing eller logging. Avvis kontrolltegn og uventede nyttelaststrukturer. Bruk hastighetsbegrensninger ved din egen applikasjonsgrense, slik at en feilaktig import ikke kan generere en ukontrollert bølge av forespørsler.

Fjern duplikater før innsending når forretningsprosessen ikke krever gjentatt registrering. En nyttig dedupliseringsnøkkel kan omfatte det kanoniske sporingsnummeret, transportøren, kontoen og forsendelseskonteksten. Riktig nøkkel avhenger av arbeidsflyten din; den samme identifikatoren kan noen ganger brukes på tvers av ulike tjenester eller forretningsposter, så ikke anta at nummeret alene alltid er globalt unikt.

Bruk begrensede nye forsøk med tilbakestrategi ved midlertidige feil, og unngå nye forsøk ved permanente valideringsfeil. Lagre en idempotens- eller innsendingstilstand når API-et og arkitekturen din støtter det. Logg nok informasjon til å feilsøke forespørselen, men beskytt legitimasjon, kundedata og sensitive forsendelsesopplysninger. En validator bør redusere gjentatte feil, ikke skape et nytt sikkerhetsproblem gjennom overdreven logging.

7. Bekreft resultatet etter innsending og overvåk falske positiver

Den siste regelen er å behandle validering før innsending som en port, ikke en dom. Etter at forespørselen er godtatt, må du kontrollere API-svaret og lagre statusen, forespørselsidentifikatoren, transportørtilknytningen og eventuell dokumentert feilkode. Hvis plattformen godtar forespørselen, men ennå ikke kan returnere bevegelseshendelser, kan det tyde på en behandlingsforsinkelse i stedet for et ugyldig nummer.

Definer en oppfølgingspolicy for numre som forblir uavklarte. Tidsvinduet bør gjenspeile transportør, tjeneste, avsenderland og kundeservicepolicy; det finnes ingen universell periode som beviser at et nummer er ugyldig. Eskaler poster med manglende transportør, gjentatte leverandørfeil, motstridende transportørresultater eller en status som ikke samsvarer med ordreposten.

Mål falske avvisninger og falske godkjenninger. Et strengt regulært uttrykk kan redusere ugyldige innsendinger, men samtidig blokkere legitime forsendelser. En ettergivende validator kan øke antallet godkjente forespørsler, men skape støy lenger ned i systemet. Gå gjennom mislykkede eksempler etter transportør og tjeneste, oppdater dokumenterte regler gjennom versjonskontroll, og test endringer mot et representativt, personverntrygt sett med testdata.

En praktisk valideringssekvens

En vedlikeholdbar implementering kan bruke følgende sekvens:

  1. Kontroller at forespørselen inneholder en strengverdi og en gyldig forretningspost.
  2. Lagre den opprinnelige inndataen, og opprett deretter en dokumentert kanonisk form.
  3. Avvis tomme verdier, plassholdere, usikre tegn og verdier utenfor det dokumenterte lengdeintervallet.
  4. Finn transportøren fra pålitelige ordredata, eller bruk en uttrykkelig støttet gjenkjenningsflyt.
  5. Bruk transportørspesifikke syntaks- og kontrollsifferregler bare når autoritativ dokumentasjon støtter dem.
  6. Kontroller krav til endepunktet, duplikatstatus og om nye forsøk er tillatt.
  7. Send inn, klassifiser svaret, lagre resultatet og planlegg oppfølging for uavklarte poster.

Denne sekvensen gjør validatoren enklere å teste fordi hver avgjørelse har en egen begrunnelse. Den gir også driftsteam handlingsrettede feilkategorier i stedet for én utydelig feil.

Sjekkliste for implementering

  • Lagre sporingsnumre som strenger slik at innledende nuller bevares.
  • Behold opprinnelige og kanoniske verdier separat når sporbarhet er viktig.
  • Vedlikehold transportørregler som versjonsstyrt konfigurasjon, ikke som spredte hardkodede betingelser.
  • Test bokstaver, sifre, bindestreker, mellomrom, Unicode-tegn som ligner på andre tegn, plassholdere og grenselengder.
  • Bruk pålitelig transportørkontekst når den er tilgjengelig.
  • Ikke utled at en forsendelse eksisterer bare fordi et regulært uttrykk samsvarer.
  • Klassifiser permanente valideringsfeil separat fra midlertidige API- eller nettverksfeil.
  • Gå gjennom leverandørdokumentasjonen før du endrer formatregler eller forespørselslogikk.

Vanlige spørsmål

Kan et regulært uttrykk validere et sporingsnummer?

Det kan validere et begrenset mønster når formatet til transportøren og tjenesten er kjent. Det kan ikke bevise at nummeret eksisterer, tilhører en bestemt forsendelse eller er aktivt på nåværende tidspunkt. Et universelt uttrykk vil sannsynligvis skape falske avvisninger eller falske treff.

Bør et nummer som ser ugyldig ut, sendes til API-et?

Tydelig tomme, usikre eller strukturelt umulige verdier bør normalt stoppes før innsending. Et ukjent, men ellers trygt format bør ikke avvises bare fordi det ikke samsvarer med en intern gjetning. Kontroller transportørens dokumentasjon eller bruk først en støttet gjenkjenningsprosess.

Er et kontrollsiffer nok til å bekrefte en forsendelse?

Nei. Et kontrollsiffer, når det er aktuelt, tester bare om verdien oppfyller en matematisk regel. Det bekrefter ikke at en transportør har utstedt nummeret, eller at pakken har kommet inn i nettverket.

Hva bør skje når transportøren er ukjent?

Kjør generelle sikkerhetskontroller og bruk en API-arbeidsflyt som uttrykkelig støtter transportørgjenkjenning, hvis dette er tilgjengelig. Ellers bør posten beholdes for berikelse eller manuell gjennomgang i stedet for at en transportør gjettes i stillhet.

Hvordan bør API-feil håndteres?

Klassifiser dem etter årsak. Korriger feilaktige inndata og transportørverdier som ikke støttes; prøv på nytt ved midlertidige nettverks- eller leverandørfeil med begrensninger og tilbakestrategi; og send autentiserings- eller kvotefeil til integrasjonseieren. Lagre svardetaljene som trengs for diagnostisering uten å eksponere hemmeligheter.

Kilder

  • 17TRACK API-dokumentasjon — veiledning om forespørsler og integrasjon for utviklere av sporings-API-er.
  • 17TRACK Tracking API — offisiell produktinformasjon og bruksområder for API-et.
  • USPS-sporing — offisielt inngangspunkt for transportørsporing og kundeveiledning.
  • UPS-sporing — offisielt inngangspunkt for transportørsporing.