Skip to main content
HjemBloggVeiledningerSlik bruker du API-er for forsendelsessporing til å sende proaktive leveringsvarsler

Slik bruker du API-er for forsendelsessporing til å sende proaktive leveringsvarsler

17TRACK

For å sende proaktive leveringsvarsler med et API for forsendelsessporing må du koble hver pakke til bestillingen, hente inn sporingsoppdateringer, oversette disse oppdateringene til kundeorienterte hendelser og utløse meldinger gjennom e-post-, SMS- eller appvarslingstjenesten din. Plasser en robust kø og kontroller for duplikater mellom innkommende sporingsdata og utgående meldinger, slik at gjentatte eller forsinkede oppdateringer ikke fører til forvirrende varsler.

Slik bruker du API-er for forsendelsessporing til å sende proaktive leveringsvarsler

Denne veiledningen er for utviklere og e-handelsteam som bygger denne arbeidsflyten. Målet er ikke å videresende hver skanning fra transportøren. Målet er å fortelle kundene når noe viktig endres, hva endringen betyr, og om de må gjøre noe.

Utform varslingsarbeidsflyten før du kobler til API-et

Et API for forsendelsessporing leverer sporingsinformasjon; applikasjonen din bestemmer hvordan den skal brukes. Behandle forsendelsessynlighet og kundekommunikasjon som separate ansvarsområder, selv om den valgte tjenesten tilbyr begge deler.

En praktisk arkitektur har seks trinn:

  1. Bestillingstilknytning: Koble et sporingsnummer og, der det kreves, en transportør-ID til en intern forsendelsespost.
  2. Registrering av sporing: Send inn eller registrer forsendelsen i henhold til leverandørens integrasjonskrav.
  3. Innhenting av oppdateringer: Motta webhook-tilbakeringinger, hent oppdateringer gjennom API-forespørsler, eller kombiner begge metodene.
  4. Hendelsesbehandling: Valider, normaliser, fjern duplikater og evaluer innkommende hendelser.
  5. Varslingsbeslutning: Velg om du skal varsle, hvem som skal kontaktes, og hvilken kanal og mal som skal brukes.
  6. Meldingslevering: Send varslingen og registrer svaret fra meldingstjenesten.

Oppbevar kundens kontaktinformasjon i ditt eget bestillings- eller meldingssystem, med mindre integrasjonen faktisk krever at den deles. En sporingstjeneste trenger vanligvis ikke kundens e-postadresse bare for at applikasjonen din skal kunne knytte en sporingshendelse til en bestilling.

1. Bekreft integrasjonsavtalen

Før du skriver mottakeren, bør du kontrollere leverandørens dokumentasjon for autentisering, registrering av forsendelser, identifisering av transportører, støttede oppdateringsmetoder, svarformater, forespørselsgrenser og feilhåndtering. For webhook-integrasjoner bør du også kontrollere hvordan tilbakeringinger autentiseres, hvilket svar som bekrefter mottak, og hvordan mislykkede leveranser håndteres.

For en 17TRACK-implementering kan du begynne med 17TRACK Tracking API-siden og den offisielle API-dokumentasjonen. Bruk den dokumenterte avtalen for integrasjonen, i stedet for å behandle de illustrerende feltnavnene i denne veiledningen som 17TRACK-forespørsels- eller svarfelt. Bekreft oppsett av tilbakeringinger, sikkerhetskrav og kontospesifikke grenser før implementering.

Velg oppdateringsmetode i henhold til integrasjonsavtalen:

  • Webhooks: Bruk tilbakeringinger når dette støttes og passer infrastrukturen din. Da kan applikasjonen behandle oppdateringer når leverandøren sender dem, uten å be om den samme forsendelsen gjentatte ganger.
  • Polling: Hent sporingsinformasjon etter en tidsplan når tilbakeringinger ikke er tilgjengelige eller ikke passer. Hold tidsplanen innenfor de dokumenterte forespørselsgrensene.
  • Kombinert metode: Bruk tilbakeringinger til normal behandling og selektiv API-henting for å avstemme forsendelser der oppdateringene ser ut til å være utdaterte, dersom leverandøren støtter denne arbeidsflyten.

Ikke lov kundene varsler i sanntid bare fordi du bruker webhooks. Applikasjonen kan ikke rapportere en hendelse fra transportøren før de underliggende sporingsdataene gjør den tilgjengelig.

2. Bygg en forsendelsespost som tåler virkelige bestillinger

Bruk en intern forsendelses-ID som primærreferanse, ikke bare sporingsnummeret. En bestilling kan inneholde flere pakker, og sporingsnumre bør ikke antas å være globalt unike for alltid.

En nyttig intern post inneholder:

  • Intern bestillings-ID og forsendelses-ID.
  • Sporingsnummer og transportør-ID når disse er kjent.
  • Leverandørens forsendelsesreferanse, hvis den oppgis.
  • Gjeldende normaliserte status og siste betydningsfulle hendelse.
  • Tidspunktet for transportørens hendelse, inkludert tidssone eller forskyvning når dette er tilgjengelig.
  • Tidspunktet systemet ditt mottok oppdateringen.
  • En referanse til kundens kommunikasjonsinnstillinger.
  • Varslingshistorikk og eventuell aktiv arbeidsflyt for avvik.

Lagre hendelsestidspunkt separat fra mottakstidspunktet. En skanning som fant sted tidligere, kan komme inn etter en nyere skanning. Hvis applikasjonen bare sorterer etter ankomstrekkefølge, kan den feilaktig endre en levert forsendelse tilbake til under transport.

For delte bestillinger bør du knytte varslingene til den berørte pakken. «Én pakke fra bestillingen din er levert» er mer presist enn «Bestillingen din er levert» når en annen pakke fortsatt er underveis.

3. Knytt sporingshendelser til kundebeslutninger

Beskrivelser fra transportøren er driftsdata, ikke ferdige kundemeldinger. Bygg et normaliseringslag som bevarer den opprinnelige hendelsen, samtidig som den får en intern kategori som varslingsreglene kan forstå.

Følgende kategorier er foreslåtte applikasjonsbegreper, ikke et universelt API-statusvokabular:

Intern kategoriVarslingsbeslutningGrense for meldingen
Forsendelsesinformasjon mottattSend bare en forberedelsesoppdatering hvis det er nyttig.Ikke antyd at transportøren fysisk har mottatt pakken kun fordi etiketten er opprettet.
Under transportVurder varsling ved den første betydningsfulle bevegelsen.Undertrykk rutinemessige skanninger på anlegg med mindre de endrer kundens neste steg.
Ute for leveringVarsle når en støttet hendelse angir denne statusen.Ikke gjør statusen om til et garantert leveringstidspunkt.
Leveringsforsøk eller henting krevesSend en handlingsrettet varsling.Ta bare med frister eller henteinstruksjoner når de er bekreftet.
LeveringsavvikVurder årsaken og om kunden må gjøre noe.Ikke beskriv hvert avvik som en tapt pakke.
LevertSend en bekreftelse på pakkenivå.Ikke finn opp mottaker, leveringssted eller leveringsbevis.

Bevar usikkerhet. En ukjent hendelse bør sendes til gjennomgang eller en reserveflyt i stedet for å tvinges inn i nærmeste kjente kategori. Gjør den rå beskrivelsen tilgjengelig for supportpersonell ved feilsøking.

4. Motta oppdateringer uten å miste eller duplisere arbeid

Webhook-endepunktet bør validere forespørselen, lagre den godkjente oppdateringen varig og returnere bekreftelsen leverandøren krever. Generer meldinger asynkront i stedet for å vente på en e-post- eller SMS-tjeneste mens tilbakeringingen behandles.

Implementer leverandørens dokumenterte metode for verifisering av tilbakeringinger. Ikke finn opp et signaturhode eller anta at alle leverandører bruker samme autentiseringsmetode. Håndhev også HTTPS, grenser for forespørselsstørrelse, validering av nyttelast og egnede tilgangskontroller.

receive callback
  verify request using documented provider mechanism
  validate payload
  persist accepted payload and enqueue processing atomically
  return documented acknowledgment

process queued update
  find internal shipment
  normalize relevant events
  ignore already-processed events
  evaluate chronology and state transition
  create notification job if policy permits
  commit state and job together

send notification job
  check recipient preferences and suppression rules
  submit message to messaging service
  record result and retry only when appropriate

De atomiske trinnene er viktige. Hvis applikasjonen lagrer en statusendring, men krasjer før varslingsjobben opprettes, kan kunden aldri motta varslet. En transaksjonell outbox er ett mulig design: Lagre statusendringen og den ventende jobben i samme databasetransaksjon, og la deretter en arbeider sende jobben.

Håndter ukjente forsendelsesreferanser eksplisitt. Plasser dem i karantene for undersøkelse eller avstemming i stedet for å gjette hvilken kunde som skal motta en varsling.

5. Legg til beskyttelse mot duplikater og kronologiske kontroller

Utform mottakeren slik at den tåler gjentatte tilbakeringinger og nye forsøk fra arbeidere. Foretrekk en stabil leverandørhendelses-ID når en slik er dokumentert. Ellers kan du opprette et deterministisk hendelsesfingeravtrykk fra egnede felt, for eksempel intern forsendelses-ID, hendelseskode, hendelsestidspunkt og sted. Test fingeravtrykket mot faktiske nyttelaster før du stoler på det.

Fjerning av duplikater og undertrykking av varsler løser ulike problemer. Fjerning av duplikater hindrer at samme hendelse behandles to ganger. Undertrykking hindrer at flere ulike skanninger genererer i hovedsak samme kundemelding.

Definer en varslingsidentitet rundt forretningshendelsen. En leveringsbekreftelse kan bruke forsendelses-ID og leveringsmilepæl. Et leveringsforsøk kan trenge en forsøksspesifikk identitet fordi et senere forsøk kan være en helt ny hendelse.

For oppdateringer som kommer i feil rekkefølge, sammenlign hendelsestidspunkter og vurder tillatte statusoverganger. Ikke anta at en tilbakeringing bare inneholder en ny skanning; kontroller om den dokumenterte strukturen representerer en individuell hendelse, et øyeblikksbilde eller en historikk. Send motstridende oppdateringer til avstemming i stedet for å forkaste alle korrigeringer i stillhet.

6. Skriv meldinger som forklarer hva som skjer videre

Hver varsling bør angi den relevante pakken, den bekreftede endringen og kundens neste steg. Ta med en sikker sporingslenke og en gjenkjennelig bestillingsreferanse. Unngå å vise fullstendige adresser eller unødvendig personopplysninger i SMS-meldinger og forhåndsvisninger på låseskjermen.

For eksempel:

  • Ute for levering: «Pakken din for bestilling {order_reference} er ute for levering. Følg fremdriften her: {tracking_link}.»
  • Levering forsøkt: «Transportøren har rapportert et leveringsforsøk for pakken din. Se sporingssiden for tilgjengelige neste steg: {tracking_link}.»
  • Levert: «Transportøren har markert pakken din for bestilling {order_reference} som levert. Se tilgjengelige leveringsdetaljer: {tracking_link}.»

Gjengi plassholdere bare fra validerte data. Hvis et leveringsestimat er tilgjengelig og egnet for visning, må det merkes som et estimat. Hvis det mangler, skal det utelates i stedet for at en dato diktes opp.

For avvik bør du skille mellom et problem med forsendelsen og en oppgave for kunden. En forstyrrelse kan bare kreve en forklaring; et bekreftet adresseproblem kan kreve handling. Ikke send kunder til en betalings- eller dokumentopplastingsside utelukkende basert på upålitelig sporingstekst i fritekst.

Velg kanaler basert på kundens preferanser, kanaltillatelser, hast og gjeldende regler. Gå gjennom krav til samtykke, avmelding og stille perioder for jurisdiksjonene og meldingskanalene du bruker. Hold leveringsvarsler atskilt fra reklamekampanjer i stedet for å anta at de samme tillatelsene dekker begge deler.

7. Definer hva som skjer når sporingen blir stille

Proaktiv kommunikasjon bør dekke manglende fremdrift så vel som nye hendelser, men stillhet alene beviser ikke at en forsendelse er forsinket eller tapt.

Opprett en regel for utdatert sporing basert på tjenestenivå, rute, siste betydningsfulle hendelse og eventuelt støttet leveringsestimat. Fastsett terskler ut fra driftsdataene og supportprosessen din, i stedet for å bruke én universell ventetid for alle forsendelser.

Når regelen utløses, bør du kontrollere om behandlingen har uteblitt, avstemme med sporingskilden der dette støttes, og avgjøre om en intern supportoppgave skal opprettes. Hvis du varsler kunden, bør ordlyden gjenspeile det du vet: «Vi har ikke mottatt en ny sporingsoppdatering» er noe annet enn «Pakken din er tapt.»

Utpek en ansvarlig for uløste avvik. Et varslingssystem som gjentatte ganger kunngjør et problem uten å opprette en vei til løsning, kan øke kundens frustrasjon.

8. Test hele flyten før automatiske utsendelser aktiveres

Kjør først arbeidsflyten i skyggemodus: Hent inn ekte eller godkjente testhendelser, generer foreslåtte varsler og kontroller resultatene uten å kontakte kunder.

  • Spill av en identisk tilbakeringing på nytt og bekreft at den ikke oppretter en ny melding.
  • Behandle en eldre hendelse under transport etter en levert-hendelse, og kontroller den resulterende statusen.
  • Test manglende tidsstempler, ukjente statuser og feilformaterte nyttelaster.
  • Simuler en databasefeil før bekreftelsen og en arbeiderfeil etter lagringen.
  • Test tidsavbrudd i meldingstjenesten, inkludert et usikkert svar der tjenesten allerede kan ha godtatt meldingen.
  • Bekreft at delte forsendelser gir pakkeorientert ordlyd.
  • Kontroller mottakere som har reservert seg, ugyldige kontaktopplysninger og håndtering av stille perioder.
  • Kontroller at sporingslenker ikke viser en annen kundes bestillingsinformasjon.

Overvåk godtatte tilbakeringinger, behandlingsfeil, køalder, varslingsjobber, undertrykking av duplikater og meldingsresultater. Mål behandlingsforsinkelsen fra systemets mottakstidspunkt separat fra alderen på transportørens hendelse. Dette skillet gjør det lettere å finne ut om en langsom varsling skyldtes tilgjengeligheten av data oppstrøms eller din egen pipeline.

Begynn med et lite sett velkjente milepæler. Utvid reglene først etter at support- og driftsteamene er enige om at meldingene er presise, handlingsrettede og verdt å motta.

Vanlige spørsmål

Sender et API for forsendelsessporing e-post- eller SMS-meldinger automatisk?

Ikke nødvendigvis. Tilgang til sporingsdata og kundemeldinger er separate funksjoner. Kontroller tjenestens dokumenterte omfang. I en tilpasset integrasjon kan applikasjonen behandle sporingsoppdateringer og sende varsler gjennom en separat meldingstjeneste.

Bør jeg varsle kundene om hver sporingsskanning?

Vanligvis ikke. Prioriter betydningsfulle milepæler og hendelser som krever handling. Flere skanninger på anlegg kan representere normal transport uten å endre det kunden trenger å vite. Oppbevar den detaljerte historikken på sporingssiden.

Kan jeg garantere leveringsvarsler i sanntid?

Du kan fastsette og overvåke et behandlingsmål etter at systemet mottar en oppdatering. Du kan ikke garantere når en transportør registrerer eller publiserer en skanning. Beskriv tjenesten på en måte som gjenspeiler denne avhengigheten.

Hvordan kan jeg forhindre dupliserte leveringsmeldinger?

Bruk varig fjerning av hendelsesduplikater, en separat varslingsidentitet for hver forretningsmilepæl og transaksjonell opprettelse av jobber. Når meldingstjenesten støtter idempotens, bør du bruke dette som et ekstra sikkerhetstiltak. En duplikatkontroll i minnet alene overlever ikke omstarter eller flere arbeidere.

Hva bør skje hvis transportøren korrigerer en levert-status?

Bevar begge hendelsene og avstem forsendelsens status. Hvis korrigeringen påvirker kunden vesentlig, bør du sende en tydelig korrigering eller videresende saken til support i henhold til retningslinjene dine. Ikke gjør levert-statusen permanent irreversibel bare for å forenkle koden.

Kilder

Følgende offisielle ressurser er implementasjonsreferansene for 17TRACK-integrasjonen som omtales ovenfor. Det interne skjemaet, varslingsreglene og behandlingsflyten i denne veiledningen er arkitekturanbefalinger, ikke gjengitte API-avtaler.

  • 17TRACK Tracking API — offisielt utgangspunkt for vurdering av API-integrasjonen.
  • 17TRACK API-dokumentasjon — referanse for leverandørspesifikke forespørselsformater, autentisering, sporingsoperasjoner og integrasjonskrav.