Sådan bruger du API'er til forsendelsessporing til at sende proaktive leveringsnotifikationer
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.
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:
- Ordretilknytning: forbind et sporingsnummer og om nødvendigt en transportøridentifikator med en intern forsendelsespost.
- Registrering af sporing: indsend eller registrer forsendelsen i henhold til udbyderens integrationskrav.
- Indlæsning af opdateringer: modtag webhook-callbacks, hent opdateringer via API-anmodninger, eller kombiner begge metoder.
- Hændelsesbehandling: valider, normaliser, fjern dubletter fra og evaluer indgående hændelser.
- Notifikationsbeslutning: vælg, om der skal sendes en notifikation, hvem der skal kontaktes, og hvilken kanal og skabelon der skal bruges.
- 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 kategori | Notifikationsbeslutning | Grænse for meddelelsen |
|---|---|---|
| Forsendelsesoplysninger modtaget | Send kun en forberedelsesopdatering, hvis det er nyttigt. | Antyd ikke, at transportøren fysisk har modtaget pakken, alene fordi en label er oprettet. |
| Under transport | Overvej at sende en notifikation ved den første væsentlige bevægelse. | Undertryk rutinemæssige terminalscanninger, medmindre de ændrer kundens næste skridt. |
| Til levering | Send 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ævet | Send en handlingsanvisende notifikation. | Medtag kun frister eller afhentningsinstruktioner, når de er bekræftet. |
| Leveringsundtagelse | Vurder årsagen, og om kunden skal foretage sig noget. | Beskriv ikke enhver undtagelse som en bortkommet pakke. |
| Leveret | Send 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.
- 17TRACK Tracking API — officielt udgangspunkt for evaluering af API-integrationen.
- 17TRACK API-dokumentation — reference til udbyderspecifikke anmodningsformater, godkendelse, sporingsoperationer og integrationskrav.


