Skip to main content
HjemBloggVeiledningerArbeidsflyt for API-et for forsendelsessporing: fra registrering av en forsendelse til henting av sporingsdetaljer

Arbeidsflyt for API-et for forsendelsessporing: fra registrering av en forsendelse til henting av sporingsdetaljer

17TRACK

A arbeidsflyt for et API for forsendelsessporing starter med å sende inn et sporingsnummer og eventuell nødvendig transportørinformasjon, kontrollere om registreringen var vellykket, vente på at sporingsdata blir tilgjengelige og hente forsendelsens status og hendelseshistorikk. For en produksjonsintegrasjon må utviklere også knytte hver sporingspost til en ordre, håndtere delvise feil, behandle oppdateringer på en trygg måte og skille mellom en akseptert registrering og en faktisk skanning hos transportøren.

Arbeidsflyt for Shipment Tracking API fra registrering av en forsendelse til henting

Denne veiledningen forklarer arbeidsflyten for utviklere som kobler til en e-handelsplattform, et ordrebehandlingssystem, en lagerapplikasjon eller et kundeserviceverktøy. Den skiller anbefalinger for applikasjonsdesign fra leverandørspesifikke API-krav. For en 17TRACK-integrasjon kan du bruke den offisielle API-dokumentasjonen til å bekrefte forespørselsskjemaet, autentiseringen, støttede operasjoner og svarfeltene før du implementerer eksemplene nedenfor.

Forstå hva registrering gjør – og ikke gjør

Å registrere en forsendelse hos en sporingstjeneste betyr å sende inn en identifikator slik at tjenesten kan spore eller administrere forsendelsen i henhold til API-kontrakten. Det er ikke det samme som å kjøpe porto, opprette en fraktetikett, bestille henting eller overlevere en pakke til en transportør.

Hold tre resultater atskilt i applikasjonen:

  • Forespørsel mottatt: API-et returnerte et svar på HTTP-forespørselen.
  • Registrering akseptert: Tjenesten aksepterte den individuelle sporingsposten for behandling.
  • Sporingsinformasjon tilgjengelig: Tjenesten har forsendelsesinformasjon som applikasjonen kan hente eller motta.

Disse resultatene bør ikke slås sammen til ett enkelt «vellykket»-flagg. Et akseptert sporingsnummer kan ennå mangle hendelser fra transportøren. På samme måte bekrefter ikke et vellykket HTTP-svar på en gruppeforespørsel at hvert element i gruppen ble akseptert. Kontroller resultatstrukturen på applikasjonsnivå slik leverandøren har definert den.

1. Klargjør forsendelsesidentitet og API-konfigurasjon

Før du sender en registreringsforespørsel, må du bestemme hvordan en forsendelse skal identifiseres i ditt eget system. En ordreidentifikator alene er vanligvis ikke tilstrekkelig, fordi én ordre kan deles opp i flere pakker. Gi hver forsendelse eller pakke sin egen interne post, og knytt posten til den relevante ordren.

En nyttig intern post inneholder følgende informasjon. Dette er foreslåtte applikasjonsfelter, ikke et 17TRACK-forespørselsskjema.

  • Intern forsendelses-ID: Din stabile identifikator for pakken.
  • Ordrereferanse: Ordren eller oppfyllelsesposten den tilhører.
  • Sporingsnummer: Identifikatoren fra transportøren, lagret som tekst for å bevare innledende nuller.
  • Transportørinformasjon: Transportøridentiteten fra oppfyllelsessystemet, hvis den er kjent.
  • Leverandørreferanse: En identifikator fra sporingstjenesten som trengs for senere operasjoner.
  • Registreringstilstand: Din registrering av om innsendingen er ventende, akseptert, avvist eller venter på avstemming.
  • Sporingstilstand: Den siste forsendelsesstatusen, vedlikeholdt separat fra registreringstilstanden.

Valider inndata før innsending. Fjern utilsiktede mellomrom rundt verdien, men ikke skriv om sporingsnummeret basert på antakelser om transportørens format. Bevar den opprinnelige verdien for feilsøking. Hvis transportøren er kjent, må du koble den til leverandørens dokumenterte transportøridentifikator i stedet for å sende et uformelt visningsnavn.

Konfigurer autentisering på serversiden. Hold legitimasjon utenfor kildekontroll, skill mellom utviklings- og produksjonskonfigurasjon, og fjern hemmeligheter fra logger. Bekreft den dokumenterte API-versjonen, forespørselsgrensene, gruppegrensene og kontokravene i stedet for å låne verdier fra en urelatert integrasjon.

2. Registrer forsendelsen og lagre resultatet på elementnivå

Send inn sporingsposten ved hjelp av registreringsoperasjonen som er beskrevet i leverandørens dokumentasjon. Ta bare med obligatoriske felter og valgfri informasjon som har et definert formål. Unngå å sende kundenavn, adresser eller andre personopplysninger bare fordi de finnes i ordredatabasen.

Følgende pseudokode viser rekkefølgen i applikasjonen. Funksjonsnavnene er illustrative; de er ikke API-endepunkter 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)

Lagre nok informasjon til å forklare hva som skjedde: intern forsendelses-ID, innsendingstidspunkt, forsøksnummer, resultat på elementnivå og eventuell forespørselsreferanse fra leverandøren. Ikke stol bare på en midlertidig arbeidslogg. Kundeservice- og driftsteamene trenger et varig svar på om en forsendelse ble registrert.

Håndter gruppeinnsendinger individuelt

Hvis API-et støtter grupperegistrering, må hvert returnerte element kobles til den opprinnelige forsendelsen. Ikke merk hele gruppen som akseptert fordi HTTP-forespørselen ble fullført. Lagre aksepterte elementer, isoler avviste elementer og undersøk uklare resultater separat.

Dette hindrer at ett ugyldig sporingsnummer fører til unødvendige nye forsøk på poster som allerede har lykkes. Det gir også driftspersonalet en handlingsrettet liste over poster som må korrigeres.

Behandle tidsavbrudd som et ukjent resultat

Et tidsavbrudd beviser ikke at registreringen mislyktes. Leverandøren kan ha akseptert forespørselen før forbindelsen ble avbrutt. Bruk dokumentert idempotens, håndtering av duplikater eller oppslagsoperasjoner for å avstemme resultatet før du sender inn forespørselen på nytt uten kontroll.

Når leverandørens håndtering av duplikater er uklar, bør du teste den med kontrollerte poster og bekrefte kontrakten før automatiske nye forsøk aktiveres. Intern deduplisering av registreringsjobber er fortsatt nyttig, men erstatter ikke forståelsen av hvordan fjerntjenesten håndterer gjentatte forespørsler.

3. Vent på at den første sporingsinformasjonen kommer

Selv etter at registreringen er akseptert, er det ikke sikkert at sporingsdetaljer er tilgjengelige umiddelbart. En etikett kan eksistere før transportøren har registrert en fysisk håndteringshendelse. Manglende informasjon kan også gjøre det nødvendig å kontrollere sporingsnummeret, transportørvalget eller kravene til oppslag for den aktuelle forsendelsen.

Representer denne tilstanden eksplisitt. «Registrert; venter på sporingsinformasjon» er mer presist enn enten «Under transport» eller «Registrering mislyktes». Ikke finn opp et leveringstidspunkt eller en bevegelseshendelse for å fylle et tomt grensesnitt.

Når en post fortsatt er tom, bør du undersøke i denne rekkefølgen:

  1. Bekreft at den individuelle registreringen ble akseptert.
  2. Sammenlign det innsendte sporingsnummeret med oppfyllelsesposten.
  3. Kontroller transportørtilordningen og eventuelle dokumenterte tilleggskrav til oppslag.
  4. Kontroller transportørens egen sporingsside for samme forsendelse.
  5. Hvis transportøren har hendelser, men integrasjonen din ikke har det, må du undersøke svarene fra uthentingen og kontakte API-leverandøren med redigert diagnostisk informasjon.

Unngå å innføre en universell ventetid uten dokumentasjon. Eskaleringsreglene bør gjenspeile frakttjenesten, den forventede overleveringsprosessen og dine egne driftsforpliktelser.

4. Hent sporingsdetaljer og tolk dem riktig

Når posten er tilgjengelig, kaller du den dokumenterte operasjonen for sporingdetaljer ved hjelp av identifikatorene den krever. Ikke anta at registrering og uthenting godtar identiske felter. Noen API-kontrakter skiller mellom sporingsnumre, transportøridentifikatorer og leverandørgenererte postreferanser.

Applikasjonen bør skille mellom tre informasjonslag:

  • Forsendelsesoversikt: Den overordnede tilstanden som brukes i dashbord, ordresider og driftsfiltre.
  • Hendelseshistorikk: De individuelle observasjonene, inkludert hendelsesbeskrivelser, tidsstempler og steder når de oppgis.
  • Metadata for uthenting: Når applikasjonen mottok eller hentet informasjonen, og om forespørselen ble fullført.

Et vellykket oppslag betyr at uthentingsoperasjonen lyktes. Det betyr ikke at pakken har beveget seg siden forrige oppslag. Sammenlign den returnerte sporingsinformasjonen med den lagrede posten før du oppretter et varsel eller en etterfølgende arbeidsflyt.

Hold hendelsestidspunkt atskilt fra uthentingstidspunkt

Lagre tidspunktet som er knyttet til en transportørhendelse separat fra tidspunktet systemet ditt mottok den. En hendelse som hentes i ettermiddag, kan beskrive en tidligere skanning. Hvis du erstatter hendelsestidspunktet med uthentingstidspunktet, vil en gammel oppdatering se ut som ny fysisk bevegelse.

Bevar det opprinnelige tidsstempelet og eventuell oppgitt forskyvning. Normaliser tidsstempler for sammenligning bare når tidssonen er kjent. Hvis en hendelse ikke har informasjon om tidssone, må du beholde denne usikkerheten i stedet for å tilordne serverens tidssone i stillhet.

Bevar den opprinnelige betydningen sammen med normalisert status

En normalisert status er nyttig for å gruppere forsendelser på tvers av transportører, men den opprinnelige hendelsesbeskrivelsen kan forklare et driftsproblem mer presist. Bevar begge der det er mulig. En bred unntakskategori alene forteller kanskje ikke en kundestøttemedarbeider om neste handling er å kontrollere en adresse, kontakte mottakeren eller vente på en ny oppdatering.

Ikke utled en leveringsgaranti, et bekreftet tap eller et bestemt tollresultat fra en vag status. Eskaler i henhold til den underliggende informasjonen og driftsreglene dine.

5. Hold poster oppdatert gjennom polling eller webhooks

Det er nok å hente detaljer én gang for å teste tilkoblingen, men ikke for å opprettholde oversikt over forsendelsen. Produksjonsdesignet trenger en mekanisme for oppdateringer. Bekreft hvilke mekanismer den valgte leverandøren støtter, og hvilke betingelser som gjelder.

Ved polling ber applikasjonen om sporingsdetaljer etter en tidsplan. Planlegg forespørsler innenfor de dokumenterte grensene, unngå å spørre gjentatte ganger etter uendrede poster uten grunn, og bruk tilbakeventing ved feil som kan forsøkes på nytt. Når en kunde åpner en ordreside, bør det ikke automatisk utløse en ubegrenset forespørsel oppstrøms. En lagret sporingsvisning kan vise siden mens en kontrollert bakgrunnsprosess oppdaterer den.

Hvis du bruker webhooks, må du validere innkommende forespørsler ved hjelp av leverandørens dokumenterte verifiseringsmekanisme. Lagre eller legg aksepterte meldinger i en varig kø før du bekrefter mottaket i henhold til webhook-kontrakten, og behandle deretter hendelsene asynkront.

Bygg mottakeren slik at den tåler duplikater og uventet ankomstrekkefølge, med mindre den dokumenterte leveringskontrakten garanterer noe annet. Bruk en hendelsesidentifikator fra leverandøren til deduplisering når den er tilgjengelig. Ellers må du definere og teste et fingeravtrykk basert på egnede hendelsesfelter, og være klar over at et slikt fingeravtrykk kan kreve tilpasninger for dataene dine.

En webhook-basert integrasjon kan også bruke kontrollert uthenting for avstemming. En gjenopprettingsjobb kan for eksempel kontrollere poster som ble påvirket av et avbrudd hos mottakeren. Dette er et robusthetsmønster, ikke en tillatelse til å ignorere hastighetsgrenser eller leverandørspesifikke retningslinjer.

6. Gjør sporingsinformasjon om til trygge forretningshandlinger

Oppdater den interne forsendelsesposten før du utløser kundevendte handlinger. Bevar en varig oversikt over varsler og overganger i arbeidsflyten, slik at en gjentatt hendelse ikke genererer gjentatte meldinger.

Knytt forretningshandlinger til meningsfulle endringer, ikke til hvert API-svar. En nylig registrert leveringshendelse kan begrunne et levert-varsel. Et gjentatt svar med samme hendelse bør ikke gjøre det. Et unntak kan begrunne en intern gjennomgang, men kundemeldingen bør gjenspeile det hendelsen faktisk sier.

Definer hvordan du håndterer hendelser som mottas etter at en forsendelse er ansett som ferdig. Ikke slett hendelseshistorikken eller blokker alle senere oppdateringer permanent bare fordi en oversikt har nådd en sluttstatus. Regler for oppbevaring, avstemming og varsling bør ta høyde for legitime korrigeringer uten å gjenåpne ferdige arbeidsflyter gjentatte ganger.

Bruk av arbeidsflyten med en 17TRACK-integrasjon

For en tilpasset sporingsintegrasjon er relevante utgangspunkter 17TRACK Tracking API-siden og utviklerdokumentasjonen. Bruk produktsiden til å vurdere tilbudet og dokumentasjonen til å fastsette den faktiske integrasjonskontrakten. Sporingssider for sluttbrukere kan ikke erstatte API-spesifikasjoner.

Før du skriver adapteren, må du bekrefte autentiseringsformatet, registrerings- og uthentingsoperasjonene, reglene for transportøridentifikasjon, håndteringen av svar på elementnivå og gjeldende forespørselsgrenser. For webhook-basert behandling må du også bekrefte nyttelastskjemaet, verifiseringsprosessen, kravene til bekreftelse og håndteringen av nye forsøk.

Hold disse leverandørspesifikke detaljene inne i en adapter i stedet for å spre antakelser om svarfelter gjennom ordresystemet. Resten av applikasjonen kan da arbeide med interne begreper som registreringsresultat, forsendelsesstatus, hendelseshistorikk og siste vellykkede synkronisering.

Kontroller før lansering som avdekker kostbare feil

  • Akseptert, men tom post: Grensesnittet viser at sporingsinformasjon venter, ikke at pakken er i bevegelse.
  • Blandet gruppresultat: Hver forsendelse får sitt eget lagrede resultat.
  • Tidsavbrudd etter innsending: Arbeideren avstemmer det usikre resultatet i stedet for å anta feil.
  • Gjentatt hendelse: Forsendelsens tidslinje og kundemelding forblir deduplisert.
  • Eldre hendelse mottatt senere: Hendelsen bevares uten blindt å erstatte en nyere oversikt.
  • Utilgjengelig tjeneste oppstrøms: Kundesiden kan vise det sist lagrede resultatet med en passende indikasjon på aktualitet.
  • Feil transportørtilordning: Posten kan korrigeres gjennom en dokumentert gjenopprettingsbane.
  • Delt ordre: Hver pakke beholder sin egen sporingstilstand og hendelseshistorikk.
  • Eksponert legitimasjon eller nyttelast: Logger inneholder diagnostiske referanser uten å lekke hemmeligheter eller unødvendig personinformasjon.

Det praktiske ferdigkriteriet er ikke bare å motta et vellykket registreringssvar. Det er å kunne spore en pakke fra innsending gjennom oppdateringer, forklare et tomt eller mislykket resultat og gjenopprette avbrutt behandling uten å miste hendelser eller duplisere kundevendte handlinger.

Vanlige spørsmål

Oppretter registrering av et sporingsnummer en forsendelse?

Ikke i arbeidsflyten som beskrives her. Sporingsregistrering sender en eksisterende identifikator til en sporingstjeneste. Opprettelse av etikett, kjøp av porto og bestilling hos transportøren er separate operasjoner, med mindre et bestemt API uttrykkelig kombinerer dem.

Hvorfor er sporingsdetaljene tomme etter at registreringen er vellykket?

Aksept av registrering og tilgjengelighet av sporingsdata er forskjellige tilstander. Transportøren har kanskje ikke registrert en hendelse ennå, eller sporingsnummeret, transportørtilordningen eller ytterligere oppslagsinformasjon må kontrolleres. Undersøk resultatet på elementnivå før du behandler posten som vellykket registrert.

Bør jeg registrere forsendelsen hver gang jeg henter statusen?

Ikke bruk gjentatt registrering som standardmekanisme for oppdatering. Lagre den aksepterte registreringstilstanden og bruk den dokumenterte uthentings- eller oppdateringsmekanismen. Følg leverandørens uttrykkelige regler for korrigeringer, reaktivering eller dupliserte innsendinger.

Bør jeg bruke polling eller webhooks?

Bruk mekanismen som passer den dokumenterte API-kontrakten og driftskravene dine. Polling krever en kontrollert forespørselsplan. Webhooks krever en sikker og varig mottaker samt behandling som tåler duplikater. Når det støttes, kan webhook-oppdateringer med målrettet avstemming gi en praktisk gjenopprettingsbane.

Kan jeg bruke et sporingsnummer som den eneste forsendelsesidentifikatoren i databasen?

Bruk i stedet en intern forsendelsesidentifikator. Lagre sporingsnummeret og relevant transportørkontekst som egenskaper ved denne posten. Dette gjør delte ordrer, korrigerte sporingsnumre og leverandørspesifikke referanser enklere å håndtere uten å endre identiteten til den interne forsendelsen.

Kilder

  • 17TRACK Tracking API – offisielt produktutgangspunkt for vurdering av en 17TRACK API-integrasjon.
  • 17TRACK API-dokumentasjon – offisiell referanse for implementasjonsspesifikke forespørselsformater, operasjoner, svar og integrasjonskrav. Pseudokoden og forslagene til interne felter i denne veiledningen er eksempler på applikasjonsdesign, ikke sitater fra denne API-kontrakten.