Skip to main content
HjemBlogVejledningerSådan bruger du API'er til forsendelsessporing til at sende proaktive leveringsnotifikationer

Sådan bruger du API'er til forsendelsessporing til at sende proaktive leveringsnotifikationer

17TRACK

For at sende proaktive leveringsnotifikationer med en API til forsendelsessporing skal du forbinde hver pakke med dens ordre, indlæse sporingsopdateringer, oversætte disse opdateringer til kundeorienterede hændelser og udløse meddelelser via din e-mail-, SMS- eller app-notifikationstjeneste. Anbring en holdbar kø og kontroller for dubletter mellem indgående sporingsdata og udgående meddelelser, så gentagne eller forsinkede opdateringer ikke skaber forvirrende advarsler.

Sådan bruger du API'er til forsendelsessporing til at sende proaktive leveringsnotifikationer

Denne vejledning er til udviklere og teams, der arbejder med e-handelsdrift, og som bygger denne arbejdsgang. Målet er ikke at videresende hver eneste transportørscanning. Det er at fortælle kunderne, når noget væsentligt ændrer sig, hvad ændringen betyder, og om de skal foretage sig noget.

Design notifikationsarbejdsgangen, før du forbinder API'en

En API til forsendelsessporing leverer sporingsoplysninger; din applikation beslutter, hvordan de skal bruges. Behandl synlighed af forsendelser og kundekommunikation som separate ansvarsområder, selv hvis den valgte tjeneste tilbyder begge dele.

En praktisk arkitektur har seks trin:

  1. Ordretilknytning: forbind et sporingsnummer og om nødvendigt en transportøridentifikator med en intern forsendelsespost.
  2. Registrering af sporing: indsend eller registrer forsendelsen i henhold til udbyderens integrationskrav.
  3. Indlæsning af opdateringer: modtag webhook-callbacks, hent opdateringer via API-anmodninger, eller kombiner begge metoder.
  4. Hændelsesbehandling: valider, normaliser, fjern dubletter fra og evaluer indgående hændelser.
  5. Notifikationsbeslutning: vælg, om der skal sendes en notifikation, hvem der skal kontaktes, og hvilken kanal og skabelon der skal bruges.
  6. Levering af meddelelse: send notifikationen, og registrer meddelelsestjenestens svar.

Opbevar kundernes kontaktoplysninger i dit eget ordre- eller meddelelsessystem, medmindre integrationen reelt kræver, at de deles. En sporingstjeneste har normalt ikke brug for kundens e-mailadresse, blot for at din applikation kan knytte en sporingshændelse til en ordre.

1. Bekræft integrationsaftalen

Før du skriver modtageren, skal du gennemgå udbyderens dokumentation for godkendelse, forsendelsesregistrering, transportøridentifikation, understøttede opdateringsmetoder, svarformater, anmodningsgrænser og fejlhåndtering. Ved webhook-integrationer skal du også kontrollere, hvordan callbacks godkendes, hvilket svar der bekræfter modtagelsen, og hvordan mislykkede leveringer håndteres.

Ved en 17TRACK-implementering skal du begynde på siden 17TRACK Tracking API og i den officielle API-dokumentation. Brug den dokumenterede aftale til din integration i stedet for at behandle de illustrative feltnavne i denne vejledning som 17TRACK-anmodnings- eller svarfelter. Bekræft callback-opsætning, sikkerhedskrav og kontospecifikke grænser før implementeringen.

Vælg opdateringsmetode i henhold til integrationsaftalen:

  • Webhooks: brug callbacks, når de understøttes og passer til din infrastruktur. De lader din applikation behandle opdateringer, når udbyderen sender dem, uden gentagne gange at anmode om den samme forsendelse.
  • Polling: hent sporingsoplysninger efter en tidsplan, når callbacks ikke er tilgængelige eller ikke passer. Hold tidsplanen inden for de dokumenterede anmodningsgrænser.
  • Kombineret tilgang: brug callbacks til normal behandling og selektiv API-hentning til at afstemme forsendelser, hvis opdateringer ser ud til at være forældede, når udbyderen understøtter denne arbejdsgang.

Lov ikke kunderne øjeblikkelige notifikationer, blot fordi du bruger webhooks. Din applikation kan ikke rapportere en transportørhændelse, før de overordnede sporingsdata gør den tilgængelig.

2. Opbyg en forsendelsespost, der kan håndtere virkelige ordrer

Brug et internt forsendelses-ID som primær reference, ikke kun sporingsnummeret. En ordre kan indeholde flere pakker, og sporingsnumre bør ikke antages at være globalt unikke for altid.

En nyttig intern post indeholder:

  • Internt ordre-ID og forsendelses-ID.
  • Sporingsnummer og transportøridentifikator, når de er kendt.
  • Udbyderens forsendelsesreference, hvis den leveres.
  • Aktuel normaliseret status og seneste væsentlige hændelse.
  • Transportørens hændelsestidspunkt, inklusive tidszone eller forskydning, når det er tilgængeligt.
  • Det tidspunkt, hvor dit system modtog opdateringen.
  • En reference til kundens kommunikationspræferencer.
  • Notifikationshistorik og eventuelle aktive workflows for undtagelser.

Gem hændelsestidspunkt separat fra modtagelsestidspunktet. En scanning, der fandt sted tidligere, kan ankomme efter en nyere scanning. Hvis din applikation kun sorterer efter ankomstrækkefølge, kan den fejlagtigt ændre en leveret forsendelse tilbage til under transport.

Ved delte ordrer skal notifikationer knyttes til den berørte pakke. “En pakke fra din ordre er ankommet” er mere præcist end “Din ordre er ankommet”, når en anden pakke stadig er undervejs.

3. Knyt sporingshændelser til kundens beslutninger

Transportørernes beskrivelser er driftsdata, ikke færdige kundemeddelelser. Opbyg et normaliseringslag, der bevarer den oprindelige hændelse, samtidig med at den tildeles en intern kategori, som dine notifikationsregler kan forstå.

Følgende kategorier er foreslåede applikationsbegreber, ikke et universelt API-statusordforråd:

Intern kategoriNotifikationsbeslutningGrænse for meddelelsen
Forsendelsesoplysninger modtagetSend kun en forberedelsesopdatering, hvis det er nyttigt.Antyd ikke, at transportøren fysisk har modtaget pakken, alene fordi en label er oprettet.
Under transportOvervej at sende en notifikation ved den første væsentlige bevægelse.Undertryk rutinemæssige terminalscanninger, medmindre de ændrer kundens næste skridt.
Til leveringSend en notifikation, når en understøttet hændelse angiver denne status.Gør ikke status til et garanteret leveringstidspunkt.
Leveringsforsøg eller afhentning påkrævetSend en handlingsanvisende notifikation.Medtag kun frister eller afhentningsinstruktioner, når de er bekræftet.
LeveringsundtagelseVurder årsagen, og om kunden skal foretage sig noget.Beskriv ikke enhver undtagelse som en bortkommet pakke.
LeveretSend en bekræftelse på pakkeniveau.Opfind ikke en modtager, leveringsplacering eller leveringsdokumentation.

Bevar usikkerhed. En ukendt hændelse bør sendes til en gennemgangs- eller fallback-proces i stedet for at blive tvunget ind i den nærmeste kendte kategori. Gør den rå beskrivelse tilgængelig for supportmedarbejdere til fejlfinding.

4. Modtag opdateringer uden at miste eller duplikere arbejde

Dit webhook-endpoint skal validere anmodningen, gemme den accepterede opdatering holdbart og returnere den kvittering, som udbyderen kræver. Generer meddelelser asynkront i stedet for at vente på en e-mail- eller SMS-tjeneste under callback-anmodningen.

Implementer udbyderens dokumenterede metode til callback-verifikation. Opfind ikke et signaturheader, og antag ikke, at alle udbydere bruger samme godkendelsesordning. Håndhæv også HTTPS, grænser for anmodningsstørrelse, validering af payloads og passende adgangskontroller.

Et forenklet behandlingsforløb ser således ud. Dette er operationer på applikationsniveau, ikke et fungerende SDK-eksempel:

modtag callback
  verificer anmodning ved hjælp af udbyderens dokumenterede mekanisme
  valider payload
  gem accepteret payload, og sæt behandling atomisk i kø
  returner dokumenteret kvittering

behandl opdatering fra køen
  find intern forsendelse
  normaliser relevante hændelser
  ignorer allerede behandlede hændelser
  evaluer kronologi og tilstandsovergang
  opret notifikationsjob, hvis politikken tillader det
  commit tilstand og job sammen

send notifikationsjob
  kontroller modtagerpræferencer og undertrykkelsesregler
  indsend meddelelse til meddelelsestjenesten
  registrer resultat, og prøv kun igen, når det er passende

De atomiske trin er vigtige. Hvis din applikation gemmer en statusændring, men går ned, før notifikationsjobbet oprettes, modtager kunden muligvis aldrig advarslen. En transaktionel outbox er en mulig løsning: Gem statusændringen og det ventende job i den samme databasetransaktion, og lad derefter en worker sende jobbet.

Håndter ukendte forsendelsesreferencer eksplicit. Isolér dem til undersøgelse eller afstemning i stedet for at gætte, hvilken kunde der skal modtage en notifikation.

5. Tilføj beskyttelse mod dubletter og kronologiske kontroller

Design modtageren, så den kan håndtere gentagne callbacks og worker-gentagelser. Foretræk en stabil udbyderhændelsesidentifikator, når en sådan er dokumenteret. Ellers skal du oprette et deterministisk hændelsesfingeraftryk ud fra egnede felter, f.eks. internt forsendelses-ID, hændelseskode, hændelsestidspunkt og placering. Test fingeraftrykket mod faktiske payloads, før du stoler på det.

Deduplicering af hændelser og undertrykkelse af notifikationer løser forskellige problemer. Deduplicering forhindrer, at den samme hændelse behandles to gange. Undertrykkelse forhindrer, at flere forskellige scanninger genererer stort set den samme kundemeddelelse.

Definer en notifikationsidentitet omkring forretningshændelsen. En leveringsbekræftelse kan bruge forsendelses-ID'et og milepælen “leveret”. Et leveringsforsøg kan have brug for en forsøgsspecifik identitet, fordi et senere forsøg kan være en reelt ny hændelse.

Ved opdateringer i forkert rækkefølge skal du sammenligne hændelsestidspunkter og evaluere tilladte tilstandsovergange. Antag ikke, at en callback kun indeholder en ny scanning; kontrollér, om dens dokumenterede struktur repræsenterer en individuel hændelse, et øjebliksbillede eller en historik. Send modstridende opdateringer til afstemning i stedet for lydløst at kassere alle rettelser.

6. Skriv meddelelser, der forklarer, hvad der sker bagefter

Hver notifikation bør angive den relevante pakke, den bekræftede ændring og kundens næste skridt. Medtag et sikkert sporingslink og en genkendelig ordrereference. Undgå at vise komplette adresser eller unødvendige personoplysninger i SMS-meddelelser og forhåndsvisninger på låseskærmen.

For eksempel:

  • Til levering: “Din pakke til ordre {order_reference} er til levering. Følg dens status her: {tracking_link}.”
  • Leveringsforsøg: “Transportøren har rapporteret et leveringsforsøg for din pakke. Se sporingssiden for tilgængelige næste skridt: {tracking_link}.”
  • Leveret: “Transportøren har markeret din pakke til ordre {order_reference} som leveret. Se de tilgængelige leveringsoplysninger: {tracking_link}.”

Gengiv kun pladsholdere fra validerede data. Hvis et leveringestimat er tilgængeligt og egnet til visning, skal det mærkes som et estimat. Hvis det mangler, skal du udelade det i stedet for at opfinde en dato.

Ved undtagelser skal du skelne mellem et problem med forsendelsen og en opgave for kunden. En forstyrrelse kræver måske kun en forklaring; et bekræftet adresseproblem kan kræve handling. Send ikke kunder til en betalings- eller dokumentuploadside udelukkende på grundlag af upålideligt frit tekstindhold fra sporingen.

Vælg kanaler ud fra kundens præferencer, kanalstilladelser, hast og gældende regler. Gennemgå krav til samtykke, fravalg og stilleperioder for de jurisdiktioner og meddelelseskanaler, du bruger. Hold notifikationer om leveringstjenester adskilt fra reklamekampagner i stedet for at antage, at de samme tilladelser dækker begge dele.

7. Definer, hvad der sker, når sporingen bliver stille

Proaktiv kommunikation bør dække manglende fremdrift såvel som nye hændelser, men stilhed alene beviser ikke, at en forsendelse er forsinket eller bortkommet.

Opret en regel for forældet sporing ved hjælp af serviceniveau, rute, seneste væsentlige hændelse og eventuelt understøttet leveringestimat. Fastlæg tærskler ud fra dine driftsdata og din supportproces i stedet for at anvende én universel ventetid på alle forsendelser.

Når reglen udløses, skal du kontrollere, om behandlingen er misset, afstemme med sporingskilden, hvor det understøttes, og beslutte, om der skal oprettes en intern supportopgave. Hvis du underretter kunden, skal du bruge en formulering, der afspejler det, du ved: “Vi har ikke modtaget en ny sporingsopdatering” er ikke det samme som “Din pakke er bortkommet.”

Tildel en ansvarlig til uafklarede undtagelser. Et notifikationssystem, der gentagne gange annoncerer et problem uden at skabe en vej til løsning, kan øge kundernes frustration.

8. Test hele forløbet, før du aktiverer automatiske udsendelser

Kør først arbejdsgangen i skyggetilstand: indlæs virkelige eller godkendte testhændelser, generer foreslåede notifikationer, og gennemgå resultaterne uden at kontakte kunderne.

  • Afspil en identisk callback, og bekræft, at den ikke opretter en ny meddelelse.
  • Behandl en ældre hændelse under transport efter en leveret hændelse, og kontrollér den resulterende tilstand.
  • Test manglende tidsstempler, ukendte statuser og fejlbehæftede payloads.
  • Simulér en databasefejl før kvitteringen og en worker-fejl efter persistens.
  • Test timeouts for meddelelsestjenesten, herunder et usikkert svar, hvor tjenesten muligvis allerede har accepteret meddelelsen.
  • Bekræft, at delte forsendelser giver pakkespecifik formulering.
  • Kontrollér fravalgte modtagere, ugyldige kontaktoplysninger og håndtering af stilleperioder.
  • Kontrollér, at sporingslinks ikke afslører en anden kundes ordreoplysninger.

Overvåg accepterede callbacks, behandlingsfejl, køens alder, notifikationsjob, undertrykkelse af dubletter og resultater fra meddelelsestjenesten. Mål behandlingsforsinkelsen fra dit systems modtagelsestidspunkt separat fra transportørhændelsens alder. Denne skelnen hjælper med at identificere, om en langsom notifikation skyldtes tilgængeligheden af overordnede data eller din egen pipeline.

Begynd med et lille udvalg af velkendte milepæle. Udvid først reglerne, når support- og driftsteams er enige om, at meddelelserne er nøjagtige, handlingsanvisende og værd at modtage.

Ofte stillede spørgsmål

Sender en API til forsendelsessporing automatisk e-mails eller SMS-meddelelser?

Ikke nødvendigvis. Adgang til sporingsdata og kundekommunikation er separate funktioner. Kontrollér tjenestens dokumenterede omfang. I en tilpasset integration kan din applikation behandle sporingsopdateringer og sende notifikationer via en separat meddelelsestjeneste.

Bør jeg underrette kunderne om hver sporingsscanning?

Som regel ikke. Prioritér væsentlige milepæle og hændelser, der kræver handling. Flere scanninger på terminaler kan være normal transport uden at ændre det, kunden har brug for at vide. Gem den detaljerede historik på sporingssiden.

Kan jeg garantere leveringsnotifikationer i realtid?

Du kan fastsætte og overvåge et behandlingsmål, efter at dit system har modtaget en opdatering. Du kan ikke garantere, hvornår en transportør registrerer eller offentliggør en scanning. Beskriv tjenesten på en måde, der afspejler denne afhængighed.

Hvordan kan jeg forhindre duplikerede leveringsmeddelelser?

Brug vedvarende deduplicering af hændelser, en separat notifikationsidentitet for hver forretningsmæssig milepæl og transaktionel oprettelse af job. Når din meddelelsestjeneste understøtter idempotens, skal du bruge det som endnu en sikkerhedsforanstaltning. En kontrol af dubletter, der kun ligger i hukommelsen, overlever ikke genstarter eller flere workers.

Hvad skal der ske, hvis transportøren retter en status fra leveret?

Bevar begge hændelser, og afstem forsendelsens tilstand. Hvis rettelsen påvirker kunden væsentligt, skal du sende en tydelig rettelse eller sende sagen til support i henhold til din politik. Gør ikke status “leveret” permanent irreversibel blot for at forenkle koden.

Kilder

Følgende officielle ressourcer er implementeringsreferencerne for den 17TRACK-integration, der omtales ovenfor. Det interne skema, notifikationsreglerne og behandlingsforløbet i denne vejledning er arkitekturanbefalinger, ikke citerede API-aftaler.