Kako uporabljati API-je za sledenje pošiljkam za pošiljanje proaktivnih obvestil o dostavi
Za pošiljanje proaktivnih obvestil o dostavi z API-jem za sledenje pošiljkam povežite vsak paket z njegovim naročilom, zajemajte posodobitve sledenja, te posodobitve prevedite v dogodke, pomembne za stranke, in sprožite sporočila prek svoje e-poštne, SMS- ali aplikacijske storitve za obvestila. Med vhodne podatke o sledenju in izhodna sporočila vključite trajno čakalno vrsto ter preverjanje dvojnikov, da ponavljajoče se ali zakasnele posodobitve ne bodo povzročale zmedenih opozoril.
Ta vodnik je namenjen razvijalcem in ekipam za e-trgovino, ki gradijo takšen potek dela. Cilj ni posredovati vsakega skena prevoznika, temveč strankam sporočiti, kdaj se je zgodila pomembna sprememba, kaj ta sprememba pomeni in ali morajo ukrepati.
Načrtujte potek obvestil, preden povežete API
API za sledenje pošiljkam zagotavlja informacije o sledenju, vaša aplikacija pa odloča, kako jih bo uporabila. Preglednost pošiljke in komunikacijo s strankami obravnavajte kot ločeni odgovornosti, tudi če izbrana storitev ponuja oboje.
Praktična arhitektura ima šest stopenj:
- Povezava z naročilom: po potrebi povežite številko za sledenje in identifikator prevoznika z internim zapisom pošiljke.
- Registracija sledenja: pošiljko predložite ali registrirajte v skladu z zahtevami ponudnika za integracijo.
- Zajem posodobitev: prejemajte povratne klice webhook, pridobivajte posodobitve prek zahtev API-ja ali združite oba pristopa.
- Obdelava dogodkov: preverite, normalizirajte, deduplicirajte in ocenite vhodne dogodke.
- Odločitev o obvestilu: izberite, ali boste poslali obvestilo, koga boste obvestili ter kateri kanal in predlogo boste uporabili.
- Dostava sporočila: pošljite obvestilo in zabeležite odgovor storitve za sporočanje.
Podatke za stik s strankami hranite v lastnem sistemu za naročila ali sporočanje, razen če integracija resnično zahteva njihovo deljenje. Storitev za sledenje na splošno ne potrebuje strankinega e-poštnega naslova samo zato, da bi vaša aplikacija povezala dogodek sledenja z naročilom.
1. Potrdite integracijsko pogodbo
Preden napišete sprejemnik, v dokumentaciji ponudnika preverite preverjanje pristnosti, registracijo pošiljk, identifikacijo prevoznika, podprte načine posodabljanja, oblike odgovorov, omejitve zahtev in obravnavo napak. Pri integracijah webhook preverite tudi, kako se preverjajo pristnost povratnih klicev, kateri odgovor potrjuje prejem in kako se obravnavajo neuspešne dostave.
Pri implementaciji 17TRACK začnite na strani 17TRACK Tracking API in v njegovi uradni dokumentaciji API-ja. Za integracijo uporabite dokumentirano pogodbo in imen polj iz tega vodnika ne obravnavajte kot zahtevna ali odzivna polja 17TRACK. Pred implementacijo potrdite nastavitev povratnih klicev, varnostne zahteve in omejitve, povezane z računom.
Način posodabljanja izberite glede na integracijsko pogodbo:
- Webhooki: uporabite povratne klice, kadar so podprti in primerni za vašo infrastrukturo. Aplikaciji omogočajo obdelavo posodobitev, ko jih ponudnik pošlje, brez ponavljajočega se zahtevanja iste pošiljke.
- Periodično preverjanje: informacije o sledenju pridobivajte po urniku, kadar povratni klici niso na voljo ali niso primerni. Urnik naj bo znotraj dokumentiranih omejitev zahtev.
- Kombinirani pristop: povratne klice uporabite za običajno obdelavo, selektivno pridobivanje prek API-ja pa za usklajevanje pošiljk, katerih posodobitve so videti zastarele, če ponudnik podpira tak potek dela.
Strankam ne obljubljajte takojšnjih obvestil samo zato, ker uporabljate webhooke. Vaša aplikacija ne more poročati o dogodku prevoznika, preden ga izvorni podatki o sledenju ne omogočijo.
2. Ustvarite zapis pošiljke, ki bo kos dejanskim naročilom
Kot primarno referenco uporabite interni ID pošiljke, ne samo številke za sledenje. Naročilo lahko vsebuje več paketov, zato ne smete predpostaviti, da so številke za sledenje za vedno globalno edinstvene.
Uporaben interni zapis vključuje:
- Interni ID naročila in ID pošiljke.
- Številko za sledenje in identifikator prevoznika, če sta znana.
- Referenco pošiljke pri ponudniku, če je na voljo.
- Trenutno normalizirano stanje in najnovejši pomemben dogodek.
- Čas dogodka pri prevozniku, vključno s časovnim pasom ali odmikom, kadar je na voljo.
- Čas, ko je vaš sistem prejel posodobitev.
- Referenco na strankine nastavitve komunikacije.
- Zgodovino obvestil in morebitni aktivni potek obravnave izjem.
Čas dogodka shranjujte ločeno od časa prejema. Sken, ki se je zgodil prej, lahko prispe po novejšem skenu. Če aplikacija razvršča samo po vrstnem redu prihoda, lahko napačno spremeni status dostavljene pošiljke nazaj v »v tranzitu«.
Pri deljenih naročilih obvestila povežite s prizadetim paketom. »En paket iz vašega naročila je prispel« je natančnejše od »Vaše naročilo je prispelo«, kadar je drug paket še na poti.
3. Dogodke sledenja povežite z odločitvami strank
Opisi prevoznikov so operativni podatki, ne že pripravljena sporočila za stranke. Ustvarite plast normalizacije, ki ohrani izvirni dogodek, hkrati pa mu dodeli interno kategorijo, ki jo lahko razumejo pravila za obvestila.
Naslednje kategorije so predlagani koncepti aplikacije in ne univerzalni besednjak statusov API-ja:
| Interna kategorija | Odločitev o obvestilu | Omejitev sporočanja |
|---|---|---|
| Informacije o pošiljki prejete | Posodobitev o pripravi pošljite le, če je koristna. | Samo na podlagi ustvaritve etikete ne namigujte, da je prevoznik fizično prevzel pošiljko. |
| V tranzitu | Razmislite o obvestilu ob prvem pomembnem premiku. | Običajne skene v objektih opustite, razen če spremenijo naslednji korak za stranko. |
| Na dostavi | Obvestite, ko podprt dogodek kaže to stanje. | Statusa ne spreminjajte v zagotovljen čas prihoda. |
| Poskus dostave ali potreben prevzem | Pošljite obvestilo, na podlagi katerega lahko stranka ukrepa. | Roke ali navodila za prevzem vključite samo, ko so preverjeni. |
| Izjema pri dostavi | Ocenite vzrok in ali mora stranka ukrepati. | Vsake izjeme ne opišite kot izgubljen paket. |
| Dostavljeno | Pošljite potrditev na ravni paketa. | Ne izmišljajte si prejemnika, lokacije dostave ali dokazila o dostavi. |
Ohranite negotovost. Neprepoznan dogodek naj vstopi v pregled ali rezervni potek, namesto da ga na silo uvrstite v najbližjo znano kategorijo. Izvirni opis naj bo podporni ekipi na voljo za odpravljanje težav.
4. Prejemajte posodobitve brez izgube ali podvajanja dela
Končna točka webhook mora preveriti zahtevo, trajno shraniti sprejeto posodobitev in vrniti potrdilo, ki ga zahteva ponudnik. Ustvarjanje sporočil izvajajte asinhrono, namesto da med zahtevo povratnega klica čakate na storitev za e-pošto ali SMS.
Izvedite dokumentirani način preverjanja povratnih klicev ponudnika. Ne izmišljajte glave podpisa in ne predpostavljajte, da vsak ponudnik uporablja enako shemo preverjanja pristnosti. Zagotovite tudi HTTPS, omejitve velikosti zahtev, preverjanje vsebine in ustrezen nadzor dostopa.
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
Atomski koraki so pomembni. Če aplikacija shrani spremembo statusa, nato pa se sesuje, preden ustvari opravilo za obvestilo, stranka morda nikoli ne bo prejela opozorila. Transakcijski izhodni predal je ena od možnosti: spremembo stanja in čakajoče opravilo shranite v isti transakciji zbirke podatkov, nato pa naj delavec odpošlje opravilo.
Neznane reference pošiljk obravnavajte izrecno. Dajte jih v karanteno zaradi preiskave ali usklajevanja, namesto da ugibate, katera stranka naj prejme obvestilo.
5. Dodajte zaščito pred dvojniki in kronološka preverjanja
Sprejemnik zasnujte tako, da prenese ponavljajoče se povratne klice in ponovne poskuse delavcev. Če je dokumentiran stabilen identifikator dogodka ponudnika, ga prednostno uporabite. V nasprotnem primeru ustvarite deterministični prstni odtis dogodka iz ustreznih polj, kot so interni ID pošiljke, koda dogodka, čas dogodka in lokacija. Preden se nanj zanesete, ga preizkusite z dejanskimi vsebinami zahtev.
Dedupliciranje dogodkov in preprečevanje obvestil rešujeta različni težavi. Dedupliciranje prepreči dvakratno obdelavo istega dogodka. Preprečevanje obvestil prepreči, da bi več različnih skenov ustvarilo v bistvu isto sporočilo za stranko.
Identiteto obvestila določite okoli poslovnega dogodka. Potrditev dostave lahko uporablja ID pošiljke in mejnik »dostavljeno«. Poskus dostave lahko potrebuje identiteto, specifično za poskus, saj je poznejši poskus lahko resnično nov dogodek.
Pri posodobitvah izven vrstnega reda primerjajte časovne žige dogodkov in ocenite dovoljene prehode stanj. Ne predpostavljajte, da povratni klic vsebuje samo nov sken; preverite, ali njegova dokumentirana struktura predstavlja posamezen dogodek, posnetek ali zgodovino. Protislovne posodobitve usmerite v usklajevanje, namesto da bi vse popravke tiho zavrgli.
6. Pišite sporočila, ki pojasnijo naslednji korak
Vsako obvestilo naj navede zadevni paket, potrjeno spremembo in naslednji korak za stranko. Vključite varno povezavo za sledenje in prepoznavno referenco naročila. V sporočilih SMS in predogledih na zaklenjenem zaslonu ne razkrivajte celotnih naslovov ali nepotrebnih osebnih podatkov.
Na primer:
- Na dostavi: »Vaš paket za naročilo {order_reference} je na dostavi. Njegovemu napredku sledite tukaj: {tracking_link}.«
- Poskus dostave: »Prevoznik je poročal o poskusu dostave vašega paketa. Razpoložljive naslednje korake preverite na strani za sledenje: {tracking_link}.«
- Dostavljeno: »Prevoznik je vaš paket za naročilo {order_reference} označil kot dostavljen. Oglejte si razpoložljive podrobnosti dostave: {tracking_link}.«
Ograde izrisujte samo iz preverjenih podatkov. Če je ocena dostave na voljo in primerna za prikaz, jo označite kot oceno. Če manjka, jo izpustite, namesto da bi si izmislili datum.
Pri izjemah ločite težavo s pošiljko od naloge za stranko. Motnja lahko zahteva samo pojasnilo, preverjena težava z naslovom pa lahko zahteva ukrepanje. Strank ne usmerjajte na stran za plačilo ali nalaganje dokumentov samo na podlagi nezaupanja vredne vsebine sledenja v prostem besedilu.
Kanale izbirajte glede na nastavitve stranke, dovoljenja kanala, nujnost in veljavna pravila. Preverite zahteve glede soglasja, odjave in mirnih ur za jurisdikcije in kanale sporočanja, ki jih uporabljate. Obvestila o dostavi ločite od promocijskih kampanj in ne predpostavljajte, da ista dovoljenja veljajo za oboje.
7. Določite, kaj se zgodi, ko sledenje utihne
Proaktivna komunikacija naj zajema manjkajoči napredek in nove dogodke, vendar samo tišina še ne dokazuje, da je pošiljka zamujena ali izgubljena.
Ustvarite pravilo za zastarelo sledenje z uporabo ravni storitve, poti, zadnjega pomembnega dogodka in morebitne podprte ocene dostave. Pragove določite na podlagi operativnih podatkov in podpornega procesa, namesto da bi za vsako pošiljko uporabili eno univerzalno čakalno obdobje.
Ko se pravilo sproži, preverite, ali je prišlo do izpuščene obdelave, po potrebi uskladite podatke z virom sledenja in odločite, ali boste odprli interno podporno opravilo. Če obvestite stranko, uporabite besedilo, ki odraža vaše znanje: »Nismo prejeli nove posodobitve sledenja« ni isto kot »Vaš paket je izgubljen.«
Za nerešene izjeme določite odgovorno osebo. Sistem obvestil, ki večkrat napove težavo, ne da bi ustvaril pot do rešitve, lahko poveča nezadovoljstvo strank.
8. Pred vklopom samodejnega pošiljanja preizkusite celotno pot
Potek dela najprej izvajajte v načinu brez neposrednega vpliva: zajemajte resnične ali odobrene testne dogodke, ustvarjajte predlagana obvestila in preglejte rezultate, ne da bi stopili v stik s strankami.
- Ponovite enak povratni klic in potrdite, da ne ustvari novega sporočila.
- Po dogodku »dostavljeno« obdelajte starejši dogodek »v tranzitu« in preglejte nastalo stanje.
- Preizkusite manjkajoče časovne žige, neznane statuse in nepravilne vsebine zahtev.
- Simulirajte odpoved zbirke podatkov pred potrditvijo in odpoved delavca po trajnem shranjevanju.
- Preizkusite časovne prekoračitve pri sporočanju, vključno z negotovim odgovorom, ko je storitev morda že sprejela sporočilo.
- Potrdite, da deljene pošiljke ustvarijo besedilo, specifično za paket.
- Preverite prejemnike, ki so se odjavili, neveljavne kontaktne podatke in obravnavo mirnih ur.
- Preverite, da povezave za sledenje ne razkrivajo podatkov o naročilu druge stranke.
Spremljajte sprejete povratne klice, napake pri obdelavi, starost čakalne vrste, opravila obvestil, preprečevanje dvojnikov in rezultate sporočanja. Zakasnitev obdelave od časa prejema v vašem sistemu merite ločeno od starosti dogodka pri prevozniku. Ta razlika pomaga ugotoviti, ali je počasno obvestilo posledica razpoložljivosti izvornih podatkov ali vašega lastnega cevovoda.
Začnite z majhnim naborom dobro razumljenih mejnikov. Pravila razširite šele, ko se ekipe za podporo in operacije strinjajo, da so sporočila natančna, uporabna in vredna prejema.
Pogosta vprašanja
Ali API za sledenje pošiljkam samodejno pošilja e-pošto ali SMS-sporočila?
Ni nujno. Dostop do podatkov o sledenju in sporočanje strankam sta ločeni zmogljivosti. Preverite dokumentirani obseg storitve. Pri prilagojeni integraciji lahko vaša aplikacija obdela posodobitve sledenja in pošlje obvestila prek ločene storitve za sporočanje.
Ali naj stranke obvestim o vsakem skenu sledenja?
Običajno ne. Prednost dajte pomembnim mejnikom in dogodkom, ki zahtevajo ukrepanje. Več skenov v objektih lahko pomeni običajen tranzit, ne da bi se spremenilo to, kar mora stranka vedeti. Podrobno zgodovino ohranite na strani za sledenje.
Ali lahko zagotovim obvestila o dostavi v realnem času?
Po prejemu posodobitve lahko določite in spremljate cilj obdelave svojega sistema. Ne morete zagotoviti, kdaj bo prevoznik zabeležil ali objavil sken. Storitev opišite z izrazi, ki odražajo to odvisnost.
Kako preprečim podvojena sporočila o dostavi?
Uporabite trajno dedupliciranje dogodkov, ločeno identiteto obvestila za vsak poslovni mejnik in transakcijsko ustvarjanje opravil. Če vaša storitev za sporočanje podpira idempotentnost, jo uporabite kot dodatno zaščito. Preverjanje dvojnikov samo v pomnilniku ne bo preživelo ponovnih zagonov ali več delavcev.
Kaj se mora zgoditi, če prevoznik popravi status »dostavljeno«?
Ohranite oba dogodka in uskladite stanje pošiljke. Če popravek bistveno vpliva na stranko, pošljite jasno popravljeno obvestilo ali ga v skladu s svojimi pravili usmerite podpori. Statusa »dostavljeno« ne naredite trajno nespremenljivega samo zato, da bi poenostavili kodo.
Viri
Naslednji uradni viri so izvedbene reference za zgoraj obravnavano integracijo 17TRACK. Interna shema, pravila obvestil in potek obdelave v tem vodniku so arhitekturna priporočila, ne navedene pogodbe API-ja.
- 17TRACK Tracking API — uradna začetna točka za ocenjevanje integracije API-ja.
- Dokumentacija API-ja 17TRACK — referenca za oblike zahtev, specifične za ponudnika, preverjanje pristnosti, operacije sledenja in zahteve za integracijo.


