Skip to main content
HjemBloggVeiledningerSlik registrerer du et sporingsnummer via API: forespørselsfelter, transportørkoder og svar

Slik registrerer du et sporingsnummer via API: forespørselsfelter, transportørkoder og svar

17TRACK

For å registrere et sporingsnummer via API-et sender du en autentisert registreringsforespørsel som inneholder forsendelsens sporingsnummer og, når det kreves, en transportøridentifikator. Kontroller deretter svaret for hver innsendte forsendelse – ikke bare HTTP-statusen – og lagre om registreringen ble godkjent, mislyktes eller fortsatt er usikker. Registreringen starter sporingsarbeidsflyten; den bekrefter ikke at transportøren har skannet pakken, eller at sporingshendelser allerede er tilgjengelige.

Slik registrerer du et sporingsnummer via API-forespørselsfelter

Denne veiledningen er for utviklere som kobler et ordrebehandlingssystem, en lagerapplikasjon eller en e-handelsplattform til et sporings-API. Den bruker 17TRACK som et konkret integrasjonseksempel og forklarer hvilke detaljer som må kontrolleres mot dokumentasjonen for den valgte API-versjonen.

Hva registrering gjør – og ikke gjør

En registreringsforespørsel forteller en sporingstjeneste hvilken forsendelse du vil spore. Det er noe annet enn å kjøpe en fraktetikett, bestille henting eller be en transportør om å opprette en forsendelse. I en typisk integrasjon oppretter fraktarbeidsflyten først et sporingsnummer, og applikasjonen din registrerer deretter dette nummeret.

Hold disse tre hendelsene atskilt i applikasjonen:

  • Forsendelse opprettet: Fraktsystemet ditt har tildelt et sporingsnummer.
  • Registrering godkjent: Sporingstjenesten har godtatt forsendelsen for sporing.
  • Sporingsinformasjon mottatt: Transportørhendelser har blitt tilgjengelige gjennom sporingstjenesten.

Ikke oppdater en ordre til «under transport» bare fordi registreringen ble godkjent. En nylig opprettet etikett har kanskje ennå ikke fått en fysisk mottaksskanning. Forsendelsesstatusen som vises til kunden, bør baseres på sporingshendelser tolket gjennom reglene dine for statusmapping, ikke på registreringssvaret.

For 17TRACK-integrasjoner kan du begynne med oversikten over Tracking API og bruke den offisielle API-dokumentasjonen som kilde for endepunkter, feltdefinisjoner, autentisering og svarkoder. Eksemplene nedenfor fokuserer på registrering, ikke på de separate oppgavene med å hente resultater eller motta oppdateringer.

Forbered forespørselsfeltene før du skriver API-kallet

Den mest nyttige forberedelsen er en liten feltavtale mellom fraktsystemet og sporingsintegrasjonen. Bestem hvor hver verdi kommer fra, om den kan mangle, og hvordan den skal valideres.

Felt eller verdiFormålImplementeringsregel
SporingsnummerIdentifiserer forsendelsen som skal spores.Lagre og overfør det som en streng; behold innledende nuller.
TransportøridentifikatorIdentifiserer transportøren i sporingsleverandørens system.Bruk leverandørens dokumenterte identifikator, ikke en intern lagerkode.
Intern referanseKnytter registreringen til forsendelsesposten.Bruk et støttet referansefelt hvis det er tilgjengelig; behold uansett din egen databasemapping.
Ytterligere identifikasjonsdataKan bidra til å identifisere en forsendelse når transportøren krever mer enn sporingsnummeret.Send bare inn felter som er dokumentert for den aktuelle integrasjonen og transportøren.
API-legitimasjonAutentiserer kontoen som foretar kallet.Oppbevar den på serveren og utelat den fra applikasjonslogger.

Behandle sporingsnummeret som en identifikator

Konverter aldri et sporingsnummer til et heltall. Numerisk konvertering kan fjerne innledende nuller, og store verdier kan miste presisjon i enkelte programmeringsmiljøer. Fjern utilsiktede mellomrom rundt verdien, men ikke fjern tegnsetting eller endre store og små bokstaver med mindre den relevante dokumentasjonen eller transportørformatet støtter slik normalisering.

Valider åpenbare inndatafeil før du kaller API-et: tomme strenger, uventede linjeskift og et ordrenummer som er kopiert inn i sporingsnummerfeltet. Unngå å pålegge én universell lengde- eller tegnregel for alle transportører. En valideringsregel som passer én transportør, kan avvise gyldige numre fra en annen.

Hold ordre­referanser atskilt fra forsendelsesidentiteter

En ordre kan ha flere pakker, og en erstatningsforsendelse kan introdusere et nytt sporingsnummer. Modeller registreringen på forsendelses- eller pakkenivå i stedet for å anta ett sporingsnummer per ordre.

Hvis du bruker et leverandørstøttet merke- eller referansefelt, bør du bruke en ugjennomsiktig forsendelsesreferanse i stedet for kundens e-postadresse eller gateadresse. Din egen database bør fortsatt være den autoritative forbindelsen mellom ordrer, forsendelser, sporingsnumre og transportørmappinger.

Velg riktig transportørkode

En transportørkode er ikke nødvendigvis en universell bransjeidentifikator. Verdien som gjenkjennes av en sporingsplattform, kan avvike fra transportørnavnet som er lagret i fraktprogramvaren. Selv to systemer som bruker numeriske koder, kan tilordne ulike numre til samme transportør.

Vedlikehold en eksplisitt mapping fra frakttjenesten din til sporingsleverandørens transportøridentifikator. Skill ved behov mellom en transportørs regionale virksomhet eller tjeneste og den overordnede merkevaren. En mapping som bare er basert på et visningsnavn, kan bli tvetydig når fraktsystemer bruker aliaser.

  • Når transportøren er kjent: Bruk den dokumenterte transportøridentifikatoren når dette støttes, særlig der sporingsnummerformater overlapper.
  • Når transportøren er ukjent: Bruk automatisk gjenkjenning bare gjennom den dokumenterte mekanismen. Ikke anta at fravær, en tom streng, null og null betyr det samme.
  • Når resultatet ser feil ut: Kontroller den opprinnelige etiketten, frakttjenesten og mappingen før du registrerer samme nummer gjentatte ganger.

Automatisk gjenkjenning er nyttig, men er ikke et bevis på at en bestemt transportør fysisk har forsendelsen. På samme måte garanterer ikke en gyldig transportørkode at det oppgitte sporingsnummeret tilhører denne transportøren.

Hold transportørmappinger konfigurerbare i stedet for å spre dem rundt i applikasjonskoden. Registrer når en mapping sist ble kontrollert, og inkluder en kjent forsendelse i regresjonstestene hver gang du endrer den.

Eksempel: send en 17TRACK-registreringsforespørsel

Eksempelet nedenfor viser registreringsendepunktet for 17TRACK v2.2, autentiseringshodet 17token og en matrise som inneholder ett sporingsnummerobjekt. Bekreft at denne versjonen og kravene til forespørselen samsvarer med kontoen din og den offisielle dokumentasjonen før produksjonssetting. Sporingsnummeret er en plassholder og må erstattes med en ekte forsendelsesidentifikator.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

Dette minimale eksempelet viser ikke valg av transportør eller transportørspesifikke tilleggsfelter. Se registreringsdokumentasjonen for å finne ut hvordan transportørgjenkjenning fungerer når transportørfeltet utelates, og om forsendelsen din trenger ytterligere informasjon. Hvis du oppgir en transportør, bruker du det dokumenterte carrier-feltet og identifikatoren som forventes av denne API-versjonen.

Kjør denne forespørselen fra et miljø på serversiden. Ikke bygg inn tokenet i en offentlig nettbutikk, et nettleserskript eller en mobilapplikasjon som distribueres til kunder. En miljøvariabel er praktisk i et lokalt eksempel; produksjonsdistribusjoner bør bruke organisasjonens kontroller for håndtering av hemmeligheter.

Før du øker volumet, tester du én kjent forsendelse og kontrollerer hele svaret. Test deretter en ugyldig inndata og en batch som inneholder både gyldige og ugyldige elementer. Disse kontrollene viser om integrasjonen faktisk håndterer resultater på elementnivå, i stedet for bare å registrere et vellykket HTTP-svar.

Les svaret på tre nivåer

En pålitelig svarbehandler besvarer tre separate spørsmål: nådde forespørselen tjenesten, godtok tjenesten operasjonen, og hva skjedde med hver forsendelse?

1. HTTP- og transportresultat

En tilkoblingstidsavbrudd, TLS-feil eller avbrutt svar forteller ikke nødvendigvis om serveren behandlet forespørselen. Merk resultatet som usikkert til du kan avstemme det. En vellykket HTTP-status bekrefter en vellykket HTTP-utveksling, men du må fortsatt kontrollere applikasjonssvaret.

2. Resultat på forespørselsnivå

Kontroller API-ets dokumenterte overordnede resultat- og feilfelter. Autentiseringsfeil, ugyldig JSON og kontobegrensninger krever ulike tiltak. Lagre leverandørens opprinnelige feilkode og melding i stedet for å redusere alle feil til «sporing utilgjengelig».

Ikke anta at en numerisk applikasjonskode har samme betydning som en HTTP-statuskode. Betydningene kommer fra ulike lag og må tolkes separat.

3. Resultat på forsendelsesnivå

Ved batchregistrering må du ta hensyn til hvert innsendt element. Et svar kan skille mellom godkjente og avviste forsendelser; parseren må følge det nøyaktige skjemaet som er dokumentert for den valgte versjonen. Ikke merk en hel batch som registrert bare fordi ett element lyktes.

Normaliser leverandørsvar til dine egne stabile applikasjonstilstander. Databasen kan for eksempel bruke accepted, rejected og uncertain. Dette er foreslåtte interne tilstander, ikke bokstavelige 17TRACK-svarverdier. Behold det opprinnelige leverandørsvaret i henhold til en passende policy for lagringstid og tilgang, slik at utviklere kan undersøke avvik.

En nyttig registreringspost inneholder intern forsendelses-ID, innsendt nummer, transportørvalg, forsøks­tidspunkt, API-versjon, resultat og leverandørens feildetaljer. Hold registreringsstatus atskilt fra leveringsstatus.

Håndter nye forsøk uten å opprette en endeløs løkke

Strategien for nye forsøk bør avhenge av feilen, ikke bare av om det oppstod et unntak.

  • Ugyldig inndata: Korriger feltet før du prøver på nytt. Det er lite sannsynlig at det hjelper å sende den samme ugyldige forespørselen på nytt.
  • Autentiseringsfeil: Kontroller legitimasjon og kontokonfigurasjon. Unngå å sende den samme mislykkede batchen gjentatte ganger.
  • Frekvensbegrensning: Følg dokumenterte grenser og eventuelle relevante instruksjoner om nye forsøk. Bruk begrenset tilbakeventing i stedet for umiddelbare parallelle forsøk.
  • Midlertidig tjenestefeil: Prøv på nytt innenfor en definert grense for antall forsøk og tidsbruk.
  • Tidsavbrudd etter innsending: Avstem forsendelsens registreringsstatus ved hjelp av dokumentert API-atferd før du antar at det første forsøket mislyktes.
  • Svar relatert til duplikat: Kontroller om forsendelsen allerede er registrert og riktig knyttet til applikasjonsposten.

Ikke anta at registrering er idempotent med mindre dokumentasjonen definerer denne atferden. Dedup­lisering på applikasjonssiden reduserer utilsiktede gjentatte innsendinger, men fastslår ikke leverandørens policy for håndtering av duplikater.

Bruk en intern unikhetsregel som passer for forsendelsesmodellen din. Sporingsnummer alene er kanskje ikke en tilstrekkelig permanent nøkkel på tvers av transportører og lange lagringsperioder. Behold transportørkontekst og din egen forsendelsesidentifikator, og dokumenter hvordan erstatninger og korrigerte numre håndteres.

Overvåk registrering separat fra sporingsoppdateringer

API-overvåkingen bør skille en integrasjonsfeil fra en forsendelse som ganske enkelt ikke har noen ny transportørhendelse. Disse tilstandene krever ulike ansvarlige og ulike løsninger.

For registrering bør du overvåke antall godkjennelser og avvisninger, feilkategorier, usikre resultater, køen for nye forsøk og svartid. For den videre sporingen bør du overvåke mottaks- eller hentefeil for oppdateringer separat. Unngå å fastsette numeriske alarmgrenser før du forstår normal trafikk og leverandørens dokumenterte driftsgrenser.

En praktisk kontroll i produksjon bør besvare følgende:

  1. Har hver forsendelse som venter på sporing en registreringspost?
  2. Kan hver godkjente registrering spores tilbake til riktig pakke?
  3. Blir avviste elementer sendt til noen som kan korrigere de underliggende dataene?
  4. Blir usikre forespørsler avstemt i stedet for forlatt eller forsøkt på nytt uten ende?
  5. Bas­eres statusene som vises til kundene på forsendelseshendelser i stedet for registreringsgodkjenning?
  6. Er legitimasjon og unødvendige personopplysninger utelatt fra logger?

For e-handelsdrift er den operative overleveringen like viktig som API-kallet. Utviklere bør eie transport- og parserfeil; frakt- eller oppfyllelsesteam bør kunne undersøke feil etiketter, transportørmappinger og manglende forsendelsesinformasjon.

Vanlige spørsmål

Kan jeg registrere et sporingsnummer før den første transportørskanningen?

Registrering og transportørskanninger er separate hendelser. En tjeneste kan godta et nummer før sporingshendelser er tilgjengelige, avhengig av valideringsreglene. Ikke tolk godkjenning som et bevis på at transportøren har mottatt pakken.

Må jeg alltid oppgi en transportørkode?

Det avhenger av API-ets dokumenterte gjenkjenningsatferd og den aktuelle forsendelsen. Hvis transportøren er kjent, kan en eksplisitt og riktig mappet identifikator redusere tvetydighet. Hvis den er ukjent, bruker du den dokumenterte metoden for automatisk gjenkjenning i stedet for å finne på en transportørverdi.

Hvorfor returnerte API-et HTTP-suksess mens en forsendelse mislyktes?

HTTP-forespørselen kan lykkes samtidig som applikasjonen avviser et individuelt element. Les det overordnede applikasjonsresultatet og resultatene på forsendelsesnivå. Dette skillet er særlig viktig for batchforespørsler.

Hva bør jeg gjøre når en registreringsforespørsel får tidsavbrudd?

Behandle resultatet som usikkert. Serveren kan ha behandlet forespørselen før forbindelsen brøt. Kontroller leverandørens dokumenterte duplikatatferd og tilgjengelige metoder for oppslag av registrering eller sporing, og avstem eller prøv på nytt innenfor en begrenset policy.

Konfigurerer registrering automatisk sporingsvarsler?

Ikke anta at den gjør det. Registrering, henting av sporing og konfigurasjon av webhooks er separate integrasjonsområder. Kontroller den relevante dokumentasjonen og test hele oppdateringsflyten før du stoler på den for kundevarsler.

Kilder

  • 17TRACK API-dokumentasjon – referanse for registreringsendepunkter, autentisering, forespørselsfelter, transportøridentifikatorer, responsskjemaer og feilhåndtering. Tilpass implementeringsdetaljene til API-versjonen du setter i drift.
  • Oversikt over 17TRACK Tracking API – offisielt utgangspunkt for sporings-API-produktet og ressurser for utviklerintegrasjon.