Arbejdsgang for API'et til pakkesporing: fra registrering af en forsendelse til hentning af sporingsoplysninger
Et workflow for en API til forsendelsessporing begynder med indsendelse af et trackingnummer og eventuelle påkrævede oplysninger om transportøren, kontrol af om registreringen lykkedes, afventning af at sporingsdata bliver tilgængelige samt hentning af forsendelsens status og hændelseshistorik. Ved en produktionsintegration skal udviklere også knytte hver trackingpost til en ordre, håndtere delvise fejl, behandle opdateringer sikkert og skelne mellem en accepteret registrering og en faktisk scanning hos transportøren.
Denne vejledning forklarer dette workflow for udviklere, der forbinder en ecommerce-platform, et ordre管理system, en lagerapplikation eller et kundeserviceværktøj. Den adskiller anbefalinger til applikationsdesign fra udbyderspecifikke API-krav. Ved en 17TRACK-integration skal du bruge den officielle API-dokumentation til at bekræfte forespørgslens skema, godkendelse, understøttede handlinger og svarfelter, før du implementerer eksemplerne nedenfor.
Forstå, hvad registrering gør – og ikke gør
Registrering af en forsendelse hos en sporingstjeneste betyder, at du indsender en identifikator, så tjenesten kan spore eller administrere forsendelsen i henhold til sin API-kontrakt. Det er ikke det samme som at købe porto, generere en forsendelsesetiket, bestille afhentning eller aflevere en pakke til en transportør.
Hold tre resultater adskilt i din applikation:
- Forespørgsel modtaget: API'et returnerede et svar på din HTTP-forespørgsel.
- Registrering accepteret: Tjenesten accepterede den enkelte trackingpost til behandling.
- Sporingsoplysninger tilgængelige: Tjenesten har forsendelsesoplysninger, som din applikation kan hente eller modtage.
Disse resultater bør ikke samles i ét enkelt "succes"-flag. Et accepteret trackingnummer har muligvis endnu ingen hændelser fra transportøren. På samme måde betyder et vellykket HTTP-svar på en batchforespørgsel ikke, at alle elementer i batchen blev accepteret; undersøg den resultatstruktur på applikationsniveau, som udbyderen har defineret.
1. Forbered din forsendelsesidentitet og API-konfiguration
Før du sender en registreringsforespørgsel, skal du beslutte, hvordan en forsendelse identificeres i dit eget system. En ordreidentifikator alene er normalt utilstrækkelig, fordi én ordre kan blive opdelt i flere pakker. Giv hver forsendelse eller pakke sin egen interne post, og knyt posten til den relevante ordre.
En nyttig intern post indeholder følgende oplysninger. Dette er foreslåede applikationsfelter, ikke et 17TRACK-forespørgselsskema.
- Internt forsendelses-ID: Din stabile identifikator for pakken.
- Ordreference: Den ordre eller leveringspost, som den tilhører.
- Trackingnummer: Den identifikator, som transportøren har udstedt, gemt som tekst for at bevare indledende nuller.
- Oplysninger om transportøren: Transportørens identitet fra dit leveringssystem, hvis den er kendt.
- Udbyderreference: En identifikator, som sporingstjenesten returnerer, og som er nødvendig ved senere handlinger.
- Registreringstilstand: Din registrering af, om indsendelsen afventer, er accepteret, afvist eller venter på afstemning.
- Sporingstilstand: Den seneste forsendelsesstatus, vedligeholdt separat fra registreringstilstanden.
Valider input før indsendelse. Fjern utilsigtede mellemrum omkring værdien, men omskriv ikke trackingnummeret ud fra antagelser om transportørens format. Bevar den oprindelige værdi til fejlfinding. Hvis en transportør er kendt, skal du knytte den til udbyderens dokumenterede transportøridentifikator i stedet for at sende et uformelt visningsnavn.
Konfigurer godkendelse på serversiden. Opbevar legitimationsoplysninger uden for kildekontrol, hold udviklings- og produktionskonfiguration adskilt, og fjern hemmeligheder fra logfiler. Bekræft den dokumenterede API-version, forespørgselsgrænser, batchgrænser og kontokrav i stedet for at genbruge værdier fra en uvedkommende integration.
2. Registrer forsendelsen, og gem resultatet på elementniveau
Indsend trackingposten ved hjælp af den registreringshandling, der er beskrevet i udbyderens dokumentation. Medtag kun de påkrævede felter og valgfrie oplysninger, der har et klart formål. Undgå at sende kundenavne, adresser eller andre personoplysninger blot fordi de findes i din ordredatabase.
Følgende pseudokode illustrerer applikationssekvensen. Funktionsnavnene er illustrative; de er ikke API-endpoints eller SDK-metoder.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Gem tilstrækkelige oplysninger til at forklare, hvad der skete: internt forsendelses-ID, indsendelsestidspunkt, forsøgsnummer, resultat på elementniveau og eventuel reference til udbyderens forespørgsel. Stol ikke udelukkende på en midlertidig worker-log. Kundeservice- og driftsteams har brug for et varigt svar på, om en forsendelse blev registreret korrekt.
Håndter batchindsendelser individuelt
Hvis API'et understøtter batchregistrering, skal hvert returneret element knyttes til den oprindelige forsendelse. Markér ikke hele batchen som accepteret, fordi HTTP-forespørgslen blev gennemført. Gem accepterede elementer, isolér afviste elementer, og undersøg uklare resultater separat.
Det forhindrer, at ét ugyldigt trackingnummer medfører unødvendige genforsøg for poster, der allerede er lykkedes. Det giver også driftspersonalet en handlingsorienteret liste over poster, der kræver rettelse.
Betragt timeouts som et ukendt resultat
Et timeout beviser ikke, at registreringen mislykkedes. Udbyderen kan have accepteret forespørgslen, før din forbindelse blev afbrudt. Brug dokumenteret idempotensadfærd, håndtering af dubletter eller opslagshandlinger til at afstemme resultatet, før du indsender igen uden kontrol.
Hvis udbyderens adfærd ved dubletter er uklar, skal du teste den med kontrollerede poster og bekræfte kontrakten, før du aktiverer automatiske genforsøg. Intern deduplikering af registreringsjob er stadig nyttig, men den erstatter ikke forståelsen af, hvordan den eksterne tjeneste håndterer gentagne forespørgsler.
3. Giv tid til, at de første sporingsoplysninger ankommer
Efter at registreringen er accepteret, er sporingsoplysningerne muligvis ikke tilgængelige med det samme. En etiket kan eksistere, før transportøren har registreret en fysisk håndteringshændelse. Manglende oplysninger kan også kræve kontrol af trackingnummeret, transportørvalget eller kravene til opslag af den specifikke forsendelse.
Gengiv denne tilstand eksplicit. "Registreret; afventer sporingsoplysninger" er mere præcist end enten "Under transport" eller "Registrering mislykkedes". Opfind ikke et leveringstidspunkt eller en bevægelseshændelse for at udfylde en tom brugerflade.
Når en post fortsat er tom, skal du undersøge følgende i praktisk rækkefølge:
- Bekræft, at den individuelle registrering blev accepteret.
- Sammenlign det indsendte trackingnummer med leveringsposten.
- Kontrollér transportørtilknytningen og eventuelle dokumenterede ekstra krav til opslag.
- Kontrollér transportørens egen sporingsside for den samme forsendelse.
- Hvis transportøren har hændelser, men din integration ikke har dem, skal du undersøge svarene på hentningen og kontakte API-udbyderen med redigerede diagnostiske oplysninger.
Undgå at indføre en universel ventetid uden dokumentation. Eskaleringsregler bør afspejle transporttjenesten, den forventede overdragelsesproces og dine egne driftsforpligtelser.
4. Hent sporingsoplysninger, og fortolk dem korrekt
Når posten er tilgængelig, skal du kalde den dokumenterede handling til hentning af sporingsoplysninger ved hjælp af de identifikatorer, den kræver. Antag ikke, at registrering og hentning accepterer identiske felter. Nogle API-kontrakter skelner mellem trackingnumre, transportøridentifikatorer og postreferencer genereret af udbyderen.
Din applikation bør skelne mellem tre informationslag:
- Forsendelsesoversigt: Den overordnede tilstand, der bruges i dashboards, ordresider og driftsfiltre.
- Hændelseshistorik: De enkelte observationer, herunder hændelsesbeskrivelser, tidsstempler og lokationer, når de leveres.
- Metadata for hentning: Hvornår din applikation modtog eller hentede oplysningerne, og om forespørgslen blev gennemført korrekt.
Et vellykket opslag betyder, at hentningen lykkedes. Det betyder ikke, at pakken har bevæget sig siden det forrige opslag. Sammenlign de returnerede sporingsoplysninger med den gemte post, før du opretter en notifikation eller et efterfølgende workflow.
Hold hændelsestidspunkt adskilt fra hentningstidspunkt
Gem tidspunktet for en hændelse hos transportøren separat fra det tidspunkt, hvor dit system modtog den. En hændelse, der hentes i eftermiddag, kan beskrive en tidligere scanning. Hvis hændelsestidspunktet erstattes af hentningstidspunktet, vil en gammel opdatering se ud som en ny fysisk bevægelse.
Bevar det oprindelige tidsstempel og eventuelle angivne forskydninger. Normalisér kun tidsstempler til sammenligning, når tidszonen er kendt. Hvis en hændelse ikke indeholder oplysninger om tidszone, skal du bevare denne usikkerhed i stedet for stiltiende at tildele serverens tidszone.
Bevar den rå betydning sammen med den normaliserede status
En normaliseret status er nyttig til at gruppere forsendelser på tværs af transportører, men den oprindelige hændelsesbeskrivelse kan forklare et driftsproblem mere præcist. Bevar begge, når de er tilgængelige. En bred undtagelseskategori alene fortæller måske ikke en supportmedarbejder, om næste handling er at kontrollere en adresse, kontakte modtageren eller vente på en ny opdatering.
Udled ikke en leveringsgaranti, et bekræftet tab eller et bestemt toldresultat ud fra en vag status. Eskalér i henhold til de underliggende oplysninger og din driftsprocedure.
5. Hold poster opdateret via polling eller webhooks
Det er nok at hente oplysninger én gang for at teste forbindelsen, men ikke nok til at opretholde synlighed over forsendelser. Dit produktionsdesign har brug for en opdateringsmekanisme. Bekræft de mekanismer, som din valgte udbyder understøtter, samt de betingelser, der gælder for dem.
Ved polling anmoder din applikation om sporingsoplysninger efter en tidsplan. Planlæg forespørgsler inden for de dokumenterede grænser, undgå gentagne opslag af uændrede poster uden en grund, og brug backoff ved fejl, der kan genforsøges. En kunde, der åbner en ordreside, bør ikke automatisk udløse en ubegrænset upstream-forespørgsel; en gemt sporingsvisning kan vise siden, mens en kontrolleret baggrundsproces opdaterer den.
Hvis du bruger webhooks, skal du validere indgående forespørgsler ved hjælp af udbyderens dokumenterede verifikationsmekanisme. Gem eller læg accepterede meddelelser i en holdbar kø, før du kvitterer for dem i henhold til webhook-kontrakten, og behandl derefter hændelserne asynkront.
Byg modtageren, så den kan håndtere dubletter og en uventet ankomstrækkefølge, medmindre den dokumenterede leveringskontrakt garanterer andet. Brug en hændelsesidentifikator fra udbyderen til deduplikering, når den er tilgængelig. Ellers skal du definere og teste et fingeraftryk baseret på egnede hændelsesfelter, idet du erkender, at et sådant fingeraftryk kan kræve tilpasninger til dine data.
En webhook-baseret integration kan også bruge kontrolleret hentning til afstemning. Et gendannelsesjob kan for eksempel kontrollere poster, der blev påvirket af en driftsafbrydelse hos modtageren. Dette er et robusthedsmønster, ikke en tilladelse til at ignorere hastighedsgrænser eller udbyderspecifik vejledning.
6. Omsæt sporingsoplysninger til sikre forretningshandlinger
Opdatér din interne forsendelsespost, før du udløser kundeorienterede handlinger. Gem en varig registrering af notifikationer og workflow-overgange, så en gentagen hændelse ikke genererer gentagne meddelelser.
Knyt forretningshandlinger til meningsfulde ændringer i stedet for hvert API-svar. En ny observeret leveringshændelse kan retfærdiggøre en leveringsnotifikation. Et gentaget svar med den samme hændelse bør ikke gøre det. En undtagelse kan begrunde en intern gennemgang, men kundemeddelelsen bør afspejle, hvad hændelsen faktisk siger.
Definér, hvordan du håndterer hændelser, der modtages, efter at en forsendelse er blevet betragtet som afsluttet. Slet ikke hændelseshistorikken, og blokér ikke permanent alle senere opdateringer, blot fordi en oversigt nåede en afsluttende tilstand. Dine regler for opbevaring, afstemning og notifikationer bør tage højde for legitime rettelser uden gentagne gange at genåbne afsluttede workflows.
Anvendelse af workflowet på en 17TRACK-integration
Ved en tilpasset sporingsintegration er de relevante udgangspunkter 17TRACK Tracking API-siden og den tilhørende udviklerdokumentation. Brug produktsiden til at vurdere tilbuddet og dokumentationen til at fastlægge den faktiske integrationskontrakt. Sporingssider til forbrugere kan ikke erstatte API-specifikationer.
Før du skriver din adapter, skal du bekræfte godkendelsesformatet, registrerings- og hentningshandlingerne, reglerne for transportøridentifikation, håndteringen af svar på elementniveau og de gældende forespørgselsgrænser. Ved webhook-baseret behandling skal du også bekræfte payload-skemaet, verifikationsprocessen, kravene til kvittering og adfærden ved genforsøg.
Hold disse udbyderspecifikke detaljer inde i en adapter i stedet for at sprede antagelser om svarfelter gennem hele dit ordresystem. Resten af applikationen kan derefter arbejde med interne begreber som registreringsresultat, forsendelsesstatus, hændelseshistorik og seneste vellykkede synkronisering.
Kontroller før lancering, der afslører dyre fejl
- Accepteret, men tom post: Brugerfladen viser, at sporingsoplysninger afventes, ikke at pakken er i bevægelse.
- Blandet batchresultat: Hver forsendelse får sit eget gemte resultat.
- Timeout efter indsendelse: Workeren afstemmer det usikre resultat i stedet for at antage fejl.
- Gentagen hændelse: Forsendelsens tidslinje og kundenotifikation forbliver deduplikerede.
- Ældre hændelse modtaget senere: Hændelsen bevares uden blindt at erstatte en nyere oversigt.
- Utilgængelig upstream-tjeneste: Kundesiden kan vise det senest gemte resultat med en passende angivelse af aktualitet.
- Forkert transportørtilknytning: Posten kan rettes via en dokumenteret gendannelsessti.
- Opdelt ordre: Hver pakke bevarer sin egen sporingstilstand og hændelseshistorik.
- Eksponering af legitimationsoplysninger eller payload: Logfiler indeholder diagnostiske referencer uden at lække hemmeligheder eller unødvendige personoplysninger.
Det praktiske færdiggørelseskriterium er ikke blot at modtage et vellykket registreringssvar. Det er at kunne følge en pakke fra indsendelse gennem opdateringer, forklare et tomt eller mislykket resultat og komme sig efter afbrudt behandling uden at miste hændelser eller udføre kundehandlinger flere gange.
Ofte stillede spørgsmål
Opretter registrering af et trackingnummer en forsendelse?
Ikke i det workflow, der er beskrevet her. Sporingsregistrering indsender en eksisterende identifikator til en sporingstjeneste. Oprettelse af etiketter, køb af porto og bestilling hos transportøren er separate handlinger, medmindre et bestemt API udtrykkeligt kombinerer dem.
Hvorfor er sporingsoplysningerne tomme, efter at registreringen lykkes?
Accept af registrering og tilgængelighed af sporingsdata er forskellige betingelser. Transportøren har muligvis endnu ikke registreret en hændelse, eller trackingnummeret, transportørtilknytningen eller ekstra opslagoplysninger skal muligvis kontrolleres. Undersøg resultatet på elementniveau, før du betragter posten som vellykket registreret.
Bør jeg registrere forsendelsen, hver gang jeg henter dens status?
Brug ikke gentagen registrering som din standardmekanisme til opdatering. Gem den accepterede registreringstilstand, og brug den dokumenterede hentnings- eller opdateringsmekanisme. Følg udbyderens udtrykkelige regler for rettelser, genaktivering eller dubletindsendelser.
Bør jeg bruge polling eller webhooks?
Brug den mekanisme, der passer til den dokumenterede API-kontrakt og dine driftskrav. Polling kræver en kontrolleret tidsplan for forespørgsler. Webhooks kræver en sikker, holdbar modtager og behandling, der tåler dubletter. Hvor det understøttes, kan webhook-opdateringer med målrettet afstemning give en praktisk gendannelsessti.
Kan jeg bruge et trackingnummer som det eneste forsendelses-ID i min database?
Brug i stedet en intern forsendelsesidentifikator. Gem trackingnummeret og den relevante transportørkontekst som attributter for posten. Det gør opdelte ordrer, rettede trackingnumre og udbyderspecifikke referencer lettere at håndtere uden at ændre identiteten på din interne forsendelse.
Kilder
- 17TRACK Tracking API — officielt produktudgangspunkt til vurdering af en 17TRACK API-integration.
- 17TRACK API-dokumentation — officiel reference til implementeringsspecifikke forespørgselsformater, handlinger, svar og integrationskrav. Pseudokoden og forslagene til interne felter i denne vejledning er eksempler på applikationsdesign, ikke citater fra denne API-kontrakt.


