Sådan registrerer du et sporingsnummer via API: anmodningsfelter, transportørkoder og svar
For at registrere et trackingnummer via API skal du sende en godkendt registreringsanmodning, der indeholder forsendelsens trackingnummer og, når det kræves, en transportøridentifikator. Kontrollér derefter svaret for hver indsendt forsendelse – ikke kun HTTP-statussen – og gem, om registreringen lykkedes, mislykkedes eller fortsat er usikker. Registreringen starter trackingarbejdsgangen; den beviser ikke, at transportøren har scannet pakken, eller at trackinghændelser allerede er tilgængelige.
Denne vejledning er til udviklere, der forbinder et ordrestyringssystem, en lagerapplikation eller en ecommerce-platform med et tracking-API. Den bruger 17TRACK som et konkret integrationseksempel og forklarer, hvilke oplysninger der skal kontrolleres i dokumentationen for den valgte API-version.
Hvad registrering gør – og hvad den ikke gør
En registreringsanmodning fortæller en trackingtjeneste, hvilken forsendelse du ønsker at tracke. Det er noget andet end at købe en forsendelseslabel, bestille en afhentning eller bede en transportør om at oprette en forsendelse. I en typisk integration opretter forsendelsesarbejdsgangen først et trackingnummer, hvorefter din applikation registrerer nummeret.
Hold disse tre hændelser adskilt i din applikation:
- Forsendelse oprettet: Dit forsendelsessystem har tildelt et trackingnummer.
- Registrering accepteret: Trackingtjenesten har accepteret forsendelsen til tracking.
- Trackingoplysninger modtaget: Transportørens hændelser er blevet tilgængelige via trackingtjenesten.
Opdatér ikke en ordre til “under transport”, blot fordi registreringen lykkedes. En nyoprettet label har muligvis endnu ikke fået en fysisk modtagelsesscanning. Den kundevendte forsendelsesstatus bør komme fra trackinghændelser, der fortolkes gennem dine regler for statusmapping, ikke fra registreringssvaret.
For 17TRACK-integrationer skal du begynde med oversigten over Tracking API'et og bruge den officielle API-dokumentation som kilde til endpoints, feltdefinitioner, godkendelse og svarkoder. Eksemplerne nedenfor fokuserer på registrering og ikke på de separate opgaver med at hente resultater eller modtage opdateringer.
Forbered anmodningsfelterne, før du skriver API-kaldet
Den mest nyttige forberedelse er en lille feltkontrakt mellem dit forsendelsessystem og din trackingintegration. Beslut, hvor hver værdi kommer fra, om den kan mangle, og hvordan den skal valideres.
| Felt eller værdi | Formål | Implementeringsregel |
|---|---|---|
| Trackingnummer | Identificerer den forsendelse, der skal trackes. | Gem og send det som en streng; bevar indledende nuller. |
| Transportøridentifikator | Identificerer transportøren i trackingudbyderens system. | Brug udbyderens dokumenterede identifikator, ikke en intern lagerkode. |
| Intern reference | Knytter registreringen til din forsendelsespost. | Brug et understøttet referencefelt, hvis det er tilgængeligt; bevar under alle omstændigheder din egen databasemapping. |
| Yderligere identifikationsdata | Kan hjælpe med at identificere en forsendelse, hvor en transportør kræver mere end trackingnummeret. | Indsend kun felter, der er dokumenteret for den pågældende integration og transportør. |
| API-legitimationsoplysninger | Godkender den konto, der foretager kaldet. | Opbevar dem på serveren, og udelad dem fra applikationslogs. |
Behandl trackingnummeret som en identifikator
Konvertér aldrig et trackingnummer til et heltal. Numerisk konvertering kan fjerne indledende nuller, og store værdier kan miste præcision i visse programmeringsmiljøer. Fjern utilsigtede mellemrum omkring værdien, men fjern ikke tegnsætning og ændr ikke store og små bogstaver, medmindre den relevante dokumentation eller transportørens format understøtter denne normalisering.
Validér åbenlyse inputfejl, før du kalder API'et: tomme strenge, uventede linjeskift og et ordrenummer, der er kopieret ind i trackingnummerfeltet. Undgå at håndhæve én universel længde- eller tegnregel på tværs af alle transportører. En valideringsregel, der passer til én transportør, kan afvise gyldige numre fra en anden.
Hold ordrereferencer adskilt fra forsendelsesidentiteter
En ordre kan have flere pakker, og en erstatningsforsendelse kan introducere et nyt trackingnummer. Modellér registrering på forsendelses- eller pakkeniveau i stedet for at antage ét trackingnummer pr. ordre.
Hvis du bruger et tag- eller referencefelt, der understøttes af udbyderen, bør du foretrække en ugennemsigtig forsendelsesreference frem for kundens e-mailadresse eller gadeadresse. Din egen database bør fortsat være den autoritative forbindelse mellem ordrer, forsendelser, trackingnumre og transportørmappings.
Vælg den rigtige transportørkode
En transportørkode er ikke nødvendigvis en universel brancheidentifikator. Den værdi, som en trackingplatform genkender, kan være forskellig fra transportørnavnet, der er gemt i din forsendelsessoftware. Selv to systemer, der bruger numeriske koder, kan tildele forskellige numre til den samme transportør.
Oprethold en eksplicit mapping fra din forsendelsestjeneste til trackingudbyderens transportøridentifikator. Skeln om nødvendigt mellem en transportørs regionale drift eller tjeneste og dens bredere brand. En mapping, der kun er baseret på et visningsnavn, kan blive tvetydig, når forsendelsessystemer bruger aliaser.
- Når transportøren er kendt: Brug den dokumenterede transportøridentifikator, når den understøttes, især hvor trackingnummerformater overlapper.
- Når transportøren er ukendt: Brug kun automatisk registrering via den dokumenterede mekanisme. Antag ikke, at udeladelse, en tom streng, nul og null betyder det samme.
- Når resultatet ser forkert ud: Kontrollér den oprindelige label, forsendelsestjenesten og mappingen, før du gentagne gange registrerer det samme nummer.
Automatisk registrering er nyttig, men den er ikke bevis på, at en bestemt transportør fysisk har forsendelsen. På samme måde garanterer en gyldig transportørkode ikke, at det angivne trackingnummer tilhører denne transportør.
Gør transportørmappings konfigurerbare i stedet for at sprede dem i applikationskoden. Registrér, hvornår en mapping sidst blev kontrolleret, og inkludér en kendt forsendelse i regressionstests, hver gang du ændrer den.
Eksempel: indsend en 17TRACK-registreringsanmodning
Det følgende eksempel viser 17TRACK v2.2-registreringsendpointet, 17token-godkendelsesheaderen og et array, der indeholder ét trackingnummerobjekt. Kontrollér, at denne version og dens anmodningskrav stemmer overens med din konto og den officielle dokumentation, før du går i produktion. Trackingnummeret er en pladsholder og skal erstattes med en reel 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 eksempel viser ikke valg af transportør eller transportørspecifikke supplerende felter. Kontrollér registreringsdokumentationen for at fastslå, hvordan transportørregistrering fungerer, når transportørfeltet udelades, og om din forsendelse kræver yderligere oplysninger. Hvis du angiver en transportør, skal du bruge det dokumenterede carrier-felt og den identifikator, som den pågældende API-version forventer.
Kør denne anmodning fra et servermiljø. Indlejr ikke tokenet i en offentlig webshop, et browserscript eller en mobilapplikation, der distribueres til kunder. En miljøvariabel er praktisk i et lokalt eksempel; produktionsinstallationer bør bruge organisationens kontroller til håndtering af hemmeligheder.
Test én kendt forsendelse, og kontrollér hele svaret, før du øger mængden. Test derefter et ugyldigt input og en batch, der indeholder både gyldige og ugyldige elementer. Disse kontroller viser, om din integration faktisk håndterer resultater på elementniveau i stedet for blot at registrere et HTTP-succesvar.
Læs svaret på tre niveauer
En pålidelig svarhåndtering besvarer tre separate spørgsmål: nåede anmodningen frem til tjenesten, accepterede tjenesten handlingen, og hvad skete der med hver forsendelse?
1. HTTP- og transportresultat
En forbindelsestimeout, TLS-fejl eller afbrudt svar fortæller ikke nødvendigvis, om serveren behandlede anmodningen. Markér resultatet som usikkert, indtil du kan afstemme det. En HTTP-successtatus bekræfter en vellykket HTTP-udveksling, men du skal stadig kontrollere applikationssvaret.
2. Resultat på anmodningsniveau
Kontrollér API'ets dokumenterede overordnede resultat- og fejlfelter. Godkendelsesfejl, ugyldig JSON og kontobegrænsninger kræver forskellige handlinger. Gem udbyderens oprindelige fejlkode og meddelelse i stedet for at reducere enhver fejl til “tracking utilgængelig”.
Antag ikke, at en numerisk applikationskode har samme betydning som en HTTP-statuskode. Deres betydninger kommer fra forskellige lag og skal fortolkes separat.
3. Resultat på forsendelsesniveau
Ved batchregistrering skal du medregne hvert indsendt element. Et svar kan skelne mellem accepterede og afviste forsendelser; din parser bør følge det nøjagtige skema, der er dokumenteret for den valgte version. Markér ikke en hel batch som registreret, blot fordi ét element lykkedes.
Normalisér udbyderens svar til dine egne stabile applikationstilstande. Din database kan for eksempel bruge accepted, rejected og uncertain. Dette er foreslåede interne tilstande, ikke bogstavelige 17TRACK-svarværdier. Bevar det oprindelige udbydersvar i henhold til en passende politik for opbevaring og adgang, så udviklere kan undersøge uoverensstemmelser.
En nyttig registreringspost indeholder det interne forsendelses-ID, det indsendte nummer, transportørvalget, forsøgstidspunktet, API-versionen, resultatet og udbyderens fejloplysninger. Hold registreringsstatus adskilt fra leveringsstatus.
Håndtér gentagelser uden at skabe en endeløs løkke
Gentagelsespolitikken bør afhænge af fejlen og ikke blot af, om der opstod en undtagelse.
- Ugyldigt input: Ret feltet, før du prøver igen. Det hjælper sandsynligvis ikke at gentage en uændret fejlbehæftet anmodning.
- Godkendelsesfejl: Kontrollér legitimationsoplysninger og kontokonfiguration. Undgå gentagne gange at indsende den samme fejlende batch.
- Hastighedsbegrænsning: Følg de dokumenterede grænser og eventuelle relevante instruktioner om gentagelse. Brug begrænset backoff i stedet for øjeblikkelige parallelle forsøg.
- Midlertidig tjenestefejl: Prøv igen inden for et defineret antal forsøg og en defineret tidsramme.
- Timeout efter indsendelse: Afstem forsendelsens registreringstilstand ved hjælp af den dokumenterede API-adfærd, før du antager, at det første forsøg mislykkedes.
- Svar relateret til en dublet: Kontrollér, om forsendelsen allerede er registreret og korrekt knyttet til din applikationspost.
Antag ikke, at registrering er idempotent, medmindre dokumentationen definerer denne adfærd. Deduplicering på applikationssiden reducerer utilsigtede gentagne indsendelser, men fastlægger ikke udbyderens politik for håndtering af dubletter.
Brug en intern entydighedsregel, der passer til din forsendelsesmodel. Trackingnummeret alene er muligvis ikke en tilstrækkelig permanent nøgle på tværs af transportører og lange opbevaringsperioder. Bevar transportørkonteksten og din egen forsendelsesidentifikator, og dokumentér, hvordan erstatninger og korrigerede numre håndteres.
Overvåg registrering separat fra trackingopdateringer
API-overvågning bør skelne mellem en integrationsfejl og en forsendelse, der blot ikke har nogen ny transportørhændelse. Disse forhold kræver forskellige ejere og forskellige løsninger.
Ved registrering skal du overvåge antal accepterede og afviste, fejlkategorier, usikre resultater, køen af gentagelser og svartid. Ved efterfølgende tracking skal du overvåge modtagelse af opdateringer eller fejl ved hentning separat. Undgå at fastsætte numeriske alarmtærskler, før du forstår den normale trafik og udbyderens dokumenterede driftsgrænser.
En praktisk produktionskontrol bør besvare følgende:
- Har hver forsendelse, der afventer tracking, en registreringspost?
- Kan enhver accepteret registrering spores tilbage til den korrekte pakke?
- Sendes afviste elementer til en person, der kan korrigere de underliggende data?
- Bliver usikre anmodninger afstemt i stedet for opgivet eller gentaget på ubestemt tid?
- Er kundevendte statuser afledt af forsendelseshændelser i stedet for registreringsaccept?
- Er legitimationsoplysninger og unødvendige personoplysninger udeladt fra logs?
For ecommerce-drift er den operationelle overdragelse lige så vigtig som API-kaldet. Udviklere bør eje transport- og parserfejl; forsendelses- eller fulfillmentteams bør kunne undersøge forkerte labels, transportørmappings og manglende forsendelsesoplysninger.
FAQ
Kan jeg registrere et trackingnummer før den første scanning hos transportøren?
Registrering og scanninger hos transportøren er separate hændelser. En tjeneste kan acceptere et nummer, før trackinghændelser er tilgængelige, afhængigt af dens valideringsregler. Fortolk ikke accept som bevis på, at transportøren har modtaget pakken.
Skal jeg altid angive en transportørkode?
Det afhænger af API'ets dokumenterede registreringsadfærd og den involverede forsendelse. Hvis transportøren er kendt, kan en eksplicit, korrekt mappet identifikator mindske tvetydighed. Hvis den er ukendt, skal du bruge den dokumenterede metode til automatisk registrering i stedet for at opfinde en transportørværdi.
Hvorfor returnerede API'et HTTP-succes, mens en forsendelse mislykkedes?
HTTP-anmodningen kan lykkes, mens applikationen afviser et individuelt element. Læs det overordnede applikationsresultat og resultaterne på forsendelsesniveau. Denne forskel er særligt vigtig ved batchanmodninger.
Hvad skal jeg gøre, når en registreringsanmodning får timeout?
Behandl resultatet som usikkert. Serveren kan have behandlet anmodningen, før forbindelsen mislykkedes. Kontrollér udbyderens dokumenterede adfærd ved dubletter og tilgængelige metoder til opslag af registrering eller tracking, og afstem eller gentag derefter under en begrænset politik.
Konfigurerer registrering automatisk trackingnotifikationer?
Antag ikke, at den gør det. Registrering, hentning af tracking og webhook-konfiguration er separate integrationsområder. Kontrollér den relevante dokumentation, og test hele opdateringsforløbet, før du baserer kundemeddelelser på det.
Kilder
- 17TRACK API-dokumentation – reference for registreringsendpoints, godkendelse, anmodningsfelter, transportøridentifikatorer, svarskemaer og fejlhåndtering. Tilpas implementeringsdetaljerne til den API-version, du installerer.
- Oversigt over 17TRACK Tracking API – officielt udgangspunkt for tracking-API-produktet og ressourcer til udviklerintegration.


