Skip to main content
ПочетакБлогVodičiKako koristiti API-je za praćenje pošiljaka za slanje proaktivnih obaveštenja o isporuci

Kako koristiti API-je za praćenje pošiljaka za slanje proaktivnih obaveštenja o isporuci

17TRACK

Da biste slali proaktivna obaveštenja o isporuci pomoću API-ja za praćenje pošiljki, povežite svaki paket sa njegovom porudžbinom, preuzimajte ažuriranja praćenja, prevedite ta ažuriranja u događaje relevantne za korisnike i pokrenite slanje poruka putem svoje usluge za e-poštu, SMS ili obaveštenja u aplikaciji. Postavite trajni red čekanja i provere duplikata između dolaznih podataka o praćenju i odlaznih poruka kako ponovljena ili odložena ažuriranja ne bi stvarala zbunjujuća obaveštenja.

Kako koristiti API-je za praćenje pošiljki za slanje proaktivnih obaveštenja o isporuci

Ovaj vodič je namenjen programerima i timovima za upravljanje e-trgovinom koji grade takav tok rada. Cilj nije prosleđivanje svakog skeniranja prevoznika. Cilj je obavestiti korisnike kada se dogodi nešto značajno, objasniti šta ta promena znači i da li treba da preduzmu nešto.

Dizajnirajte tok obaveštavanja pre povezivanja API-ja

API za praćenje pošiljki obezbeđuje informacije o praćenju; vaša aplikacija odlučuje kako da ih koristi. Posmatrajte vidljivost pošiljke i komunikaciju sa korisnicima kao odvojene odgovornosti, čak i ako izabrana usluga nudi obe.

Praktična arhitektura ima šest faza:

  1. Povezivanje sa porudžbinom: povežite broj za praćenje i identifikator prevoznika, kada je potrebno, sa internim zapisom pošiljke.
  2. Registracija praćenja: pošaljite ili registrujte pošiljku u skladu sa zahtevima provajdera za integraciju.
  3. Preuzimanje ažuriranja: primajte povratne pozive webhook-a, preuzimajte ažuriranja putem API zahteva ili kombinujte oba pristupa.
  4. Obrada događaja: proverite, normalizujte, uklonite duplikate i procenite dolazne događaje.
  5. Odluka o obaveštavanju: izaberite da li treba obavestiti korisnika, koga kontaktirati i koji kanal i šablon koristiti.
  6. Isporuka poruke: pošaljite obaveštenje i zabeležite odgovor usluge za razmenu poruka.

Čuvajte kontakt podatke korisnika u sopstvenom sistemu za porudžbine ili razmenu poruka, osim ako integracija zaista zahteva njihovo deljenje. Usluga za praćenje uglavnom ne mora da zna adresu e-pošte korisnika samo da bi vaša aplikacija povezala događaj praćenja sa porudžbinom.

1. Potvrdite ugovor o integraciji

Pre nego što napišete prijemnik, proverite dokumentaciju provajdera u vezi sa autentifikacijom, registracijom pošiljke, identifikacijom prevoznika, podržanim metodama ažuriranja, formatima odgovora, ograničenjima zahteva i postupanjem sa greškama. Kod webhook integracija proverite i kako se autentifikuju povratni pozivi, koji odgovor potvrđuje prijem i kako se obrađuju neuspešne isporuke.

Za implementaciju 17TRACK-a počnite od stranice 17TRACK Tracking API i njegove zvanične API dokumentacije. Za integraciju koristite dokumentovani ugovor, umesto da ilustrativne nazive polja iz ovog vodiča tretirate kao polja zahteva ili odgovora 17TRACK-a. Pre implementacije potvrdite podešavanje povratnih poziva, bezbednosne zahteve i ograničenja specifična za nalog.

Izaberite metod ažuriranja u skladu sa ugovorom o integraciji:

  • Webhook-ovi: koristite povratne pozive kada su podržani i odgovaraju vašoj infrastrukturi. Oni omogućavaju aplikaciji da obrađuje ažuriranja kada ih provajder pošalje, bez ponovljenog zahtevanja iste pošiljke.
  • Polling: preuzimajte informacije o praćenju prema rasporedu kada povratni pozivi nisu dostupni ili odgovarajući. Raspored mora ostati u okviru dokumentovanih ograničenja zahteva.
  • Kombinovani pristup: koristite povratne pozive za uobičajenu obradu i selektivno preuzimanje putem API-ja za usklađivanje pošiljki čija ažuriranja deluju zastarelo, ako provajder podržava takav tok rada.

Nemojte korisnicima obećavati trenutna obaveštenja samo zato što koristite webhook-ove. Vaša aplikacija ne može prijaviti događaj prevoznika pre nego što ga izvorni podaci o praćenju učine dostupnim.

2. Izgradite zapis pošiljke koji može da izdrži stvarne porudžbine

Koristite interni ID pošiljke kao primarnu referencu, a ne samo broj za praćenje. Porudžbina može sadržati više paketa, a ne treba pretpostaviti da su brojevi za praćenje zauvek globalno jedinstveni.

Korisni interni zapis obuhvata:

  • Interni ID porudžbine i ID pošiljke.
  • Broj za praćenje i identifikator prevoznika, kada su poznati.
  • Referencu pošiljke provajdera, ako je navedena.
  • Trenutni normalizovani status i najnoviji značajan događaj.
  • Vreme događaja kod prevoznika, uključujući vremensku zonu ili pomeraj, kada je dostupan.
  • Vreme kada je vaš sistem primio ažuriranje.
  • Referencu na komunikacione postavke korisnika.
  • Istoriju obaveštenja i svaki aktivni tok rada za izuzetke.

Čuvajte vreme događaja odvojeno od vremena prijema. Skeniranje koje se dogodilo ranije može stići nakon novijeg skeniranja. Ako aplikacija sortira samo prema redosledu prijema, može greškom promeniti status isporučene pošiljke nazad u „u transportu“.

Kod podeljenih porudžbina povežite obaveštenja sa pogođenim paketom. „Jedan paket iz vaše porudžbine je stigao“ preciznije je od poruke „Vaša porudžbina je stigla“ kada se drugi paket još uvek prevozi.

3. Povežite događaje praćenja sa odlukama korisnika

Opisi prevoznika su operativni podaci, a ne gotove poruke za korisnike. Izgradite sloj za normalizaciju koji čuva originalni događaj i istovremeno mu dodeljuje internu kategoriju koju pravila obaveštavanja mogu da razumeju.

Sledeće kategorije su predloženi koncepti aplikacije, a ne univerzalni rečnik statusa API-ja:

Interna kategorijaOdluka o obaveštavanjuGranica komunikacije
Informacije o pošiljci primljenePošaljite pripremno ažuriranje samo ako je korisno.Nemojte implicirati da prevoznik fizički poseduje paket samo na osnovu kreiranja etikete.
U transportuRazmotrite obaveštavanje pri prvom značajnom pomeranju.Potisnite rutinska skeniranja u objektima osim ako menjaju sledeći korak korisnika.
Na dostaviObavestite korisnika kada podržani događaj ukazuje na ovaj status.Nemojte status pretvoriti u garantovano vreme dolaska.
Pokušaj dostave ili potrebno preuzimanjePošaljite obaveštenje koje zahteva postupanje.Uključite rokove ili uputstva za preuzimanje samo kada su provereni.
Izuzetak pri dostaviProcenite uzrok i da li korisnik treba da reaguje.Nemojte svaki izuzetak opisivati kao izgubljeni paket.
IsporučenoPošaljite potvrdu na nivou paketa.Nemojte izmišljati primaoca, mesto isporuke ili dokaz o isporuci.

Sačuvajte neizvesnost. Neprepoznati događaj treba da uđe u tok za proveru ili rezervni tok, umesto da bude nasilno svrstan u najbližu poznatu kategoriju. Sirovi opis treba da ostane dostupan osoblju za podršku radi rešavanja problema.

4. Primajte ažuriranja bez gubitka ili dupliranja posla

Vaša webhook krajnja tačka treba da proveri zahtev, trajno sačuva prihvaćeno ažuriranje i vrati potvrdu koju zahteva provajder. Generisanje poruka obavljajte asinhrono, umesto da tokom zahteva za povratni poziv čekate uslugu za e-poštu ili SMS.

Implementirajte dokumentovani metod provajdera za verifikaciju povratnih poziva. Nemojte izmišljati zaglavlje potpisa niti pretpostavljati da svaki provajder koristi istu šemu autentifikacije. Takođe primenite HTTPS, ograničenja veličine zahteva, proveru sadržaja i odgovarajuće kontrole pristupa.

Pojednostavljeni tok obrade izgleda ovako. Ovo su operacije na nivou aplikacije, a ne funkcionalni primer SDK-a:

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 koraci su važni. Ako aplikacija sačuva promenu statusa, ali se sruši pre kreiranja zadatka za obaveštavanje, korisnik možda nikada neće primiti obaveštenje. Transakcioni outbox je jedna od mogućnosti dizajna: sačuvajte promenu stanja i zadatak na čekanju u istoj transakciji baze podataka, a zatim prepustite radniku slanje zadatka.

Jasno obrađujte nepoznate reference pošiljki. Stavite ih u karantin radi istrage ili usklađivanja, umesto da nagađate koji korisnik treba da primi obaveštenje.

5. Dodajte zaštitu od duplikata i hronološke provere

Dizajnirajte prijemnik tako da podnosi ponovljene povratne pozive i ponovne pokušaje radnika. Prednost dajte stabilnom identifikatoru događaja provajdera kada je dokumentovan. U suprotnom kreirajte deterministički otisak događaja iz odgovarajućih polja, kao što su interni ID pošiljke, šifra događaja, vreme događaja i lokacija. Testirajte taj otisak na stvarnim sadržajima pre nego što se oslonite na njega.

Uklanjanje duplikata događaja i potiskivanje obaveštenja rešavaju različite probleme. Uklanjanje duplikata sprečava dvostruku obradu istog događaja. Potiskivanje sprečava da više različitih skeniranja generiše praktično istu poruku korisniku.

Definišite identitet obaveštenja oko poslovnog događaja. Potvrda isporuke može koristiti ID pošiljke i prekretnicu „isporučeno“. Pokušaj dostave može zahtevati identitet specifičan za pokušaj, jer kasniji pokušaj može biti zaista novi događaj.

Kod ažuriranja van redosleda uporedite vremenske oznake događaja i procenite dozvoljene prelaze stanja. Nemojte pretpostaviti da povratni poziv sadrži samo novo skeniranje; proverite da li njegova dokumentovana struktura predstavlja pojedinačni događaj, snimak stanja ili istoriju. Protivrečna ažuriranja usmerite na usklađivanje umesto da tiho odbacite sve ispravke.

6. Pišite poruke koje objašnjavaju šta se dešava sledeće

Svako obaveštenje treba da navede relevantni paket, potvrđenu promenu i sledeći korak korisnika. Uključite bezbednu vezu za praćenje i prepoznatljivu referencu porudžbine. Izbegavajte otkrivanje punih adresa ili nepotrebnih ličnih podataka u SMS porukama i pregledima na zaključanom ekranu.

Na primer:

  • Na dostavi: „Vaš paket iz porudžbine {order_reference} je na dostavi. Pratite njegovo kretanje ovde: {tracking_link}.“
  • Pokušaj dostave: „Prevoznik je prijavio pokušaj dostave vašeg paketa. Proverite stranicu za praćenje da biste videli sledeće dostupne korake: {tracking_link}.“
  • Isporučeno: „Prevoznik je označio paket iz porudžbine {order_reference} kao isporučen. Pogledajte dostupne detalje isporuke: {tracking_link}.“

Prikazujte rezervisana mesta samo iz proverenih podataka. Ako je procena isporuke dostupna i pogodna za prikaz, označite je kao procenu. Ako nedostaje, izostavite je umesto da izmišljate datum.

Kod izuzetaka razlikujte problem sa pošiljkom od zadatka za korisnika. Prekid može zahtevati samo objašnjenje; provereni problem sa adresom može zahtevati reakciju. Nemojte korisnike usmeravati na stranicu za plaćanje ili otpremanje dokumenata samo na osnovu nepouzdanog slobodnog teksta iz praćenja.

Birajte kanale na osnovu korisničkih postavki, dozvola kanala, hitnosti i primenljivih pravila. Proverite zahteve u vezi sa pristankom, odjavom i periodima bez obaveštavanja za jurisdikcije i kanale koje koristite. Obaveštenja o usluzi isporuke držite odvojeno od promotivnih kampanja, umesto da pretpostavite da iste dozvole pokrivaju obe vrste poruka.

7. Definišite šta se dešava kada praćenje utihne

Proaktivna komunikacija treba da obuhvati nedostatak napretka, kao i nove događaje, ali sama tišina ne dokazuje da je pošiljka zakašnjela ili izgubljena.

Kreirajte pravilo za zastarelo praćenje koristeći nivo usluge, rutu, poslednji značajan događaj i svaku podržanu procenu isporuke. Pragove postavite na osnovu operativnih podataka i procesa podrške, umesto da primenjujete jedan univerzalni period čekanja na svaku pošiljku.

Kada se pravilo aktivira, proverite da li je obrada propuštena, uskladite podatke sa izvorom praćenja kada je podržano i odlučite da li treba otvoriti interni zadatak podrške. Ako obavestite korisnika, koristite formulaciju koja odražava ono što znate: „Nismo primili novo ažuriranje praćenja“ razlikuje se od poruke „Vaš paket je izgubljen.“

Dodelite vlasnika nerešenim izuzecima. Sistem obaveštavanja koji stalno objavljuje problem, a ne stvara put ka njegovom rešavanju, može povećati nezadovoljstvo korisnika.

8. Testirajte ceo tok pre uključivanja automatskog slanja

Najpre pokrenite tok u režimu posmatranja: preuzimajte stvarne ili odobrene testne događaje, generišite predložena obaveštenja i pregledajte rezultate bez kontaktiranja korisnika.

  • Ponovite identičan povratni poziv i potvrdite da ne kreira novu poruku.
  • Obradite stariji događaj „u transportu“ nakon događaja „isporučeno“ i proverite rezultatno stanje.
  • Testirajte nedostajuće vremenske oznake, nepoznate statuse i neispravan sadržaj.
  • Simulirajte kvar baze podataka pre potvrde i kvar radnika nakon trajnog čuvanja.
  • Testirajte prekide komunikacije sa uslugom za razmenu poruka, uključujući neizvestan odgovor kada je usluga možda već prihvatila poruku.
  • Potvrdite da podeljene pošiljke proizvode formulacije specifične za paket.
  • Proverite primaoce koji su odustali, nevažeće kontakt podatke i obradu perioda bez obaveštavanja.
  • Proverite da veze za praćenje ne otkrivaju podatke o porudžbini drugog korisnika.

Pratite prihvaćene povratne pozive, neuspehe obrade, starost reda čekanja, zadatke obaveštavanja, potiskivanje duplikata i ishode razmene poruka. Merite kašnjenje obrade od vremena prijema u vašem sistemu odvojeno od starosti događaja prevoznika. Ta razlika pomaže da se utvrdi da li je sporo obaveštenje posledica dostupnosti podataka uzvodno ili vašeg sopstvenog toka.

Počnite sa malim skupom dobro razumljivih prekretnica. Proširujte pravila tek nakon što se timovi za podršku i operacije slože da su poruke tačne, korisne i vredne primanja.

Česta pitanja

Da li API za praćenje pošiljki automatski šalje e-poštu ili SMS poruke?

Ne nužno. Pristup podacima o praćenju i komunikacija sa korisnicima odvojene su mogućnosti. Proverite dokumentovani obim usluge. U prilagođenoj integraciji vaša aplikacija može obrađivati ažuriranja praćenja i slati obaveštenja putem zasebne usluge za razmenu poruka.

Da li treba da obavestim korisnike o svakom skeniranju praćenja?

Uglavnom ne. Dajte prednost značajnim prekretnicama i događajima koji zahtevaju postupanje. Više skeniranja u objektima može predstavljati uobičajen transport bez promene onoga što korisnik treba da zna. Detaljnu istoriju zadržite na stranici za praćenje.

Mogu li da garantujem obaveštenja o isporuci u realnom vremenu?

Možete postaviti i pratiti cilj obrade nakon što vaš sistem primi ažuriranje. Ne možete garantovati kada će prevoznik zabeležiti ili objaviti skeniranje. Uslugu opišite tako da odražava tu zavisnost.

Kako mogu da sprečim duple poruke o isporuci?

Koristite trajno uklanjanje duplikata događaja, zaseban identitet obaveštenja za svaku poslovnu prekretnicu i transakciono kreiranje zadataka. Ako vaša usluga za razmenu poruka podržava idempotentnost, koristite je kao dodatnu zaštitu. Provera duplikata samo u memoriji neće preživeti ponovna pokretanja ili više radnika.

Šta treba da se desi ako prevoznik ispravi status „isporučeno“?

Sačuvajte oba događaja i uskladite stanje pošiljke. Ako ispravka značajno utiče na korisnika, pošaljite jasno obaveštenje o ispravci ili je, u skladu sa pravilima, usmerite podršci. Nemojte status „isporučeno“ učiniti trajno nepromenljivim samo da biste pojednostavili kod.

Izvori

Sledeći zvanični resursi predstavljaju reference za implementaciju 17TRACK integracije o kojoj je ovde reč. Interna šema, pravila obaveštavanja i tok obrade u ovom vodiču arhitektonske su preporuke, a ne citirani ugovori API-ja.

  • 17TRACK Tracking API — zvanična početna tačka za procenu integracije API-ja.
  • 17TRACK API documentation — referenca za formate zahteva specifične za provajdera, autentifikaciju, operacije praćenja i zahteve integracije.