Kako integrirati API za sledenje pošiljkam v svojo e-trgovino
Če želite v svojo e-trgovino vključiti API za sledenje pošiljkam, povežite svoj sistem naročil s ponudnikom sledenja, pošljite podatke o pošiljki in prevozniku prek varne zahteve na strani strežnika, shranite normalizirane dogodke sledenja ter prikazujte rezultatni status v vmesnikih za stranke in podporo. Zanesljiva izvedba je več kot dodajanje polja za sledilno številko: obravnavati mora izbiro prevoznika, posodobitve statusa, izjeme pri dostavi, ponovne poskuse, zasebnost in način, kako stranke dejansko uporabljajo informacije po nakupu.
Ta vodnik pojasnjuje praktičen pristop k integraciji za lastnike trgovin, razvijalce in operativne ekipe. Kot referenčno točko uporablja uradno dokumentacijo 17TRACK's Tracking API, vendar enaka načela načrtovanja veljajo tudi pri ocenjevanju drugega ponudnika za več prevoznikov.
Odločite se, kaj mora integracija doseči
Začnite s poslovnim rezultatom, ne s končno točko API-ja. Večina trgovin želi zmanjšati število vprašanj »Kje je moje naročilo?«, kupcem ponuditi jasen pregled dostave in operativnim ekipam pomagati prepoznati zamujajoče pošiljke, še preden se stranka pritoži. Ti cilji zahtevajo različne podatke in delovne tokove.
- Preglednost za stranke: prikaz trenutnega statusa pošiljke, predvidenih informacij o dostavi, kadar so na voljo, podatkov o prevozniku in najnovejšega pomembnega dogodka.
- Operativna preglednost: osebju omogočite iskanje zamujenih, zastalih, vrnjenih ali problematičnih pošiljk pri različnih prevoznikih.
- Avtomatizirana komunikacija: sprožite odobrena e-poštna sporočila, SMS-e ali druga obvestila, ko pošiljka doseže določeno stanje.
- Skladnost podatkov: različne oznake dogodkov prevoznikov pretvorite v manjše število statusov, ki jih lahko vaša trgovina zanesljivo uporablja.
Te rezultate opredelite, preden izberete način izvedbe. API za sledenje lahko zagotovi podatke o pošiljki, vendar samodejno ne odloči, kateri dogodki si zaslužijo obvestilo stranki ali kako naj vaša trgovina obravnava težavo z naslovom.
Izberite ustrezno arhitekturo integracije
Tipična arhitektura ima štiri plasti: trgovsko platformo, integracijsko storitev, ponudnika sledenja in izkušnjo, namenjeno strankam. Integracijska storitev je lahko zaledna aplikacija, sistem za upravljanje naročil ali brezstrežniški delovni tok. Hranjenje te logike na strežniku je običajno varnejše kot vstavljanje poverilnic API-ja v kodo brskalnika.
Osnovni tok je videti takole:
- Plačano naročilo je odpremljeno ter prejme sledilno številko in prevoznika.
- Vaše zaledje pošlje podrobnosti pošiljke ponudniku sledenja.
- Ponudnik vrne identifikator sledenja ali podatke o sledenju v skladu z zasnovo svojega API-ja.
- Vaš sistem shrani referenco ponudnika in dogodke pošiljke preslika v notranje statuse.
- Načrtovan proces posodabljanja ali podprto obvestilo o dogodku osveži pošiljko.
- Vaša trgovina, stran naročila, podporna orodja in storitev za obvestila berejo iz vaših lastnih normaliziranih podatkov.
Ne omogočite, da bi vsak ogled strani klical prevoznika ali API za sledenje. Takšna zasnova lahko povzroči počasnejšo uporabniško izkušnjo, podvojene zahteve, težave z omejitvami hitrosti in neskladne rezultate. Najnovejše sprejeto stanje sledenja shranite v svojo podatkovno zbirko ter ga osvežujte z nadzorovanimi opravili v ozadju ali s podprtim mehanizmom posodabljanja ponudnika.
Pred kodiranjem preverite dokumentacijo ponudnika
Pred izvedbo preglejte uradno dokumentacijo API-ja ponudnika glede preverjanja pristnosti, formatov zahtev, polj odgovorov, podprtih prevoznikov, ravnanja z napakami, mehanizmov posodabljanja in zahtev računa. 17TRACK ponuja namensko stran izdelka Tracking API in dokumentacijo za razvijalce. Te strani obravnavajte kot avtoriteto za trenutno vedenje API-ja, namesto da bi se zanašali na primere, kopirane s forumov ali iz starih vodnikov za integracijo.
Na podlagi dokumentacije pripravite kratek seznam zahtev:
- Kako se poverilnice API-ja izdajo, shranijo, zamenjajo in prekličejo?
- Ali zahteva potrebuje kodo prevoznika ali lahko storitev prevoznika prepozna iz sledilne številke?
- Katera polja odgovora identificirajo pošiljko, status, lokacijo, časovne žige in sporočilo o izjemi?
- Kako se dostavijo asinhrone posodobitve, če jih račun podpira?
- Kakšne so dokumentirane omejitve zahtev, pravila obračunavanja, pričakovanja glede časovne omejitve in kode napak?
- Kako je treba obravnavati podvojene sledilne številke, neveljavne številke, neznane prevoznike in dostavljene pošiljke?
Funkcije ne sklepajte iz imena izdelka. Na primer, izraz »v realnem času« lahko opisuje pozicioniranje izdelka in ne zagotavlja, da se vsak dogodek prevoznika prikaže takoj. Vaša izvedba mora pojasniti, da se skeniranja prevoznika lahko zamaknejo in da API ne more ustvariti skeniranja, o katerem prevoznik ni poročal.
Pripravite podatke o naročilu in pošiljki
Najprimernejši trenutek za ustvarjanje sledenja je običajno izpolnitev pošiljke, ne ustvarjanje naročila. Naročilo je lahko plačano, vendar še ni zapakirano, sledilna številka pa je lahko ustvarjena, preden prevoznik sprejme paket. Določite, kateri dogodek v vašem delovnem toku izpolnitve naj ustvari zapis sledenja.
Notranji zapis pošiljke mora najmanj razlikovati med naslednjimi vrednostmi:
- Notranji ID naročila in ID izpolnitve
- Sledilna številka
- Ime prevoznika ali koda prevoznika
- Ciljna država ali regija, kjer je to operativno potrebno
- Identifikator sledenja ponudnika ali referenca naročnine, če je vrnjena
- Trenutni normalizirani status
- Časovni žig zadnjega dogodka in časovni žig zadnje sinhronizacije
- Surov odgovor ponudnika ali nadzorovana revizijska referenca
Podatke o naročilu in pošiljki hranite ločeno. Eno naročilo lahko vsebuje več paketov, razdeljene pošiljke ali različne prevoznike. Predpostavka, da je enemu naročilu pripisana ena sledilna številka, pogosto odpove, ko skladišče izdelke pošilja ločeno.
Uporabite idempotenten proces. Če sistem za izpolnitev ponovi isto zahtevo, mora integracija posodobiti obstoječo pošiljko, namesto da ustvari podvojene naročnine ali podvojena sporočila strankam. Praktični idempotentni ključ lahko združuje vaš notranji ID izpolnitve, identifikator prevoznika in sledilno številko, ob upoštevanju lastnih zahtev ponudnika.
Normalizirajte statuse prevoznikov za stranke
Prevozniki uporabljajo različne oznake in zaporedja dogodkov. Vaša trgovina mora vzdrževati majhen notranji model statusov, kot so Informacije prejete, V tranzitu, Na dostavi, Dostavljeno, Izjema in Vrnjeno. Izvirni dogodek prevoznika ohranite za podporno osebje, za logiko trgovine pa uporabite normalizirani status.
Pravila normalizacije morajo biti izrecna. Dogodek »etiketa ustvarjena« ne sme biti prikazan kot dokaz, da se paket premika. Status »Dostavljeno« obravnavajte kot dogodek, o katerem je poročal prevoznik, ne kot zagotovilo, da je stranka paket fizično našla. Izjeme ne pretvorite tiho v »v tranzitu« samo zato, ker se bo pošiljka morda pozneje nadaljevala.
Opredelite tudi prednost statusov in obravnavo regresij. Zakasnjen vir podatkov prevoznika lahko prispe v napačnem vrstnem redu. Kjer je mogoče, primerjajte časovne žige dogodkov, zabeležite surovi dogodek in se izogibajte zamenjavi novejšega stanja »dostavljeno« s starejšim stanjem »v tranzitu«. Če časovni žigi manjkajo ali so dvoumni, zapis označite za previdno posodobitev, namesto da bi si izmislili zaporedje.
Vzpostavite tok zahtev na strani strežnika
Vaše zaledje mora preveriti vhodne podatke o izpolnitvi, preden pokliče ponudnika sledenja. Preverite, ali je sledilna številka prisotna, odstranite nenamerno presledke, kjer je primerno preverite pričakovani format in potrdite, da je vrednost prevoznika sprejemljiva. Nenavadnih, vendar veljavnih sledilnih številk ne zavrnite samo zato, ker se ne ujemajo z ozkim lokalnim vzorcem.
Tok zahtev, neodvisen od ponudnika, je lahko predstavljen tako:
sprejmi dogodek izpolnitve
preveri polja naročila in pošiljke
preveri obstoječi idempotentni ključ
pošlji dokumentirano zahtevo za sledenje s strežnika
shrani odgovor ponudnika in notranji zapis pošiljke
uvrsti osvežitev v čakalno vrsto ali obdelaj podprti dogodek posodobitve
objavi samo odobrena polja v trgoviniZa začasne napake uporabite kratke časovne omejitve, omejeno število ponovnih poskusov in eksponentno zaostajanje. Ne ponavljajte vsake napake. Napaka pri preverjanju pristnosti, neveljavna zahteva ali nepodprt prevoznik običajno zahtevajo popravek in ne ponavljajočih se klicev. Zabeležite korelacijski ID, izid zahteve in kategorijo napake ponudnika, vendar v dnevnike aplikacije ne zapisujte ključev API-ja, celotnih naslovov strank ali nepotrebnih osebnih podatkov.
Odgovor ponudnika hranite ločeno od modela, namenjenega strankam. Tako je lažje zamenjati ponudnika, popraviti pravilo preslikave in omejiti informacije, izpostavljene na javni strani naročila.
Oblikujte uporabniško izkušnjo sledenja
Stran za sledenje mora hitro odgovoriti na tri vprašanja: kakšno je trenutno stanje, kaj se je zgodilo nazadnje in kaj naj stranka stori naslednje? Prikažite referenco naročila, številko pošiljke v obliki, ki upošteva zasebnost, ime prevoznika, čas zadnjega dogodka in jasno razlago izjem.
Prazne časovnice ne prikazujte, kot da gre za tehnično napako. Pred prvim skeniranjem prevoznika pojasnite, da so bile informacije o pošiljanju prejete in da premikanje morda še ni vidno. Pri izjemi zagotovite razumljivo razlago samo, kadar jo izvorni podatki podpirajo. Če prevoznik poroča o težavi z naslovom, dodajte povezavo do postopka podpore ali dejanja službe za stranke, ki ga vaše podjetje lahko dejansko zagotovi.
Pri trgovinah, zgrajenih na platformi Shopify ali drugi trgovski platformi, preverite, kako platforma izpostavlja dogodke izpolnitve, račune strank, strani s statusom naročila in predloge obvestil. Uradna dokumentacija za razvijalce Shopify vključuje vire za spletne kavlje in podatke o izpolnitvi. API-ji platforme in različice dokumentacije se lahko spreminjajo, zato pred delom v produkciji potrdite različico, ki jo uporablja vaša aplikacija.
Obvestila uporabljajte previdno
Dogodki pošiljke so uporabni sprožilci, vendar lahko pošiljanje sporočila za vsako skeniranje prevoznika povzroči utrujenost zaradi obvestil. Določite poslovna pravila, kot so obvestilo ob ustvarjanju pošiljke, pomembnem napredku v tranzitu, statusu »na dostavi«, dostavi in izbranih izjemah. Podvojena obvestila potlačite in za ponavljajoča se sporočila o zamudi dodajte najkrajši časovni interval.
Operativna opozorila ločite od obvestil strankam. Podporna ekipa bo morda morala vedeti, da se pošiljka več dni ni spremenila, stranka pa bo morda potrebovala sporočilo šele, ko prevoznik poroča o konkretni izjemi. Časovni prag naj odraža raven storitve, cilj, prevoznika in način pošiljanja, ne pa univerzalnega števila brez operativne podlage.
Preizkusite resnične scenarije dostave
Uspešen odgovor za eno sledilno številko ne zadostuje za zagon v produkciji. Ustvarite testno matriko, ki vključuje več prevoznikov, držav, vrst pošiljk in stanj dogodkov. Preizkusite vsaj:
- Na novo ustvarjeno pošiljko brez skeniranja prevoznika
- Običajno pošiljko v tranzitu
- Pošiljko na dostavi
- Dostavljeno pošiljko
- Izjemo ali dogodek, povezan z naslovom
- Vrnjeno pošiljko
- Neveljavno sledilno številko
- Podvojeni dogodek izpolnitve
- Zakasnjen odgovor ponudnika ali časovno omejitev
- Dogodek v napačnem vrstnem redu
Merite več kot samo razpoložljivost API-ja. Preverite, ali je posodobljeno pravilno naročilo, ali stranka vidi razumljiv jezik, ali so podvojena obvestila potlačena in ali lahko podporno osebje prepozna izvirni dogodek prevoznika. Najprej izvedite omejeno uvedbo, ohranite operativno nadomestno možnost in po izdaji spremljajte kategorije napak.
Varnost, zasebnost in vzdrževanje
Poverilnice hranite v upravljalniku skrivnosti ali zaščiteni okoljski spremenljivki, ne v kodi teme, mobilni kodi, nadzoru izvorne kode ali zahtevah brskalnika. Dostop do podatkov o pošiljkah omejite glede na vlogo, uporabljajte HTTPS in preverite, kako dolgo se hranijo surovi odgovori ter polja, povezana s strankami.
Redno pregledujte dokumentacijo ponudnika in različico API-ja svoje trgovske platforme. Podpora prevoznikov, imena dogodkov, zahteve za preverjanje pristnosti in vedenje spletnih kavljev platforme se lahko spremenijo. Pravila preslikave statusov naj bodo nastavljiva, dokumentirajte predpostavke, na katerih temeljijo, ter omogočite ponovno predvajanje ali uskladitev pošiljke brez ponovnega pošiljanja sporočila stranki.
API 17TRACK je ustrezna možnost za oceno, ko vaša trgovina potrebuje namensko integracijo sledenja med različnimi prevozniki. Ustrezna izbira je še vedno odvisna od prevoznikov, ki jih uporabljate, držav, v katerih poslujete, vedenja posodobitev, dokumentiranega za vaš račun, pričakovanega obsega zahtev in operativnih nadzorov, ki jih potrebuje vaša ekipa. Te točke potrdite v uradni dokumentaciji in nadzorovanem dokazilu koncepta, preden se zavežete produkcijski zasnovi.
Pogosta vprašanja
Ali je treba sledenje ustvariti ob oddaji naročila?
Običajno ne. Zapis pošiljke ustvarite ali aktivirajte, ko ima vaš delovni tok izpolnitve prevoznika in sledilno številko. Ustvarjanje ob zaključku nakupa lahko ustvari zapise za naročila, ki so pozneje preklicana, niso izpolnjena ali so razdeljena.
Ali lahko API za sledenje zagotovi informacije o dostavi v realnem času?
Ne. Noben API ne more zagotoviti, da bo vsako skeniranje prevoznika takoj vidno. Ponudnik je odvisen od podatkov prevoznika, sistemi prevoznikov pa lahko dogodke sporočijo z zamudo ali z vrzelmi. Časovne žige in jezik statusov prikazujte natančno ter ne obljubljajte točnega časa osveževanja, razen če to podpirata ustrezna dokumentacija in pogodba o storitvi.
Ali naj brskalnik neposredno kliče API za sledenje?
V večini izvedb ne. Uporabite integracijo na strani strežnika, da poverilnice ostanejo zaščitene, da je mogoče odgovore normalizirati, nadzorovati ponovne poskuse in filtrirati podatke, namenjene strankam. Trgovina bi morala običajno brati odobren prikaz pošiljke iz vaše aplikacije.
Kako naj trgovina obravnava več paketov v enem naročilu?
Vsako izpolnitev ali paket modelirajte kot ločeno pošiljko, pri tem pa ohranite ID nadrejenega naročila. Stran naročila lahko prikazuje skupni povzetek in ločene časovnice za vsak paket. Tako preprečite, da bi bila zamujena pošiljka skrita za statusom »dostavljeno« drugega paketa.
Katero produkcijsko metriko je treba spremljati najprej?
Spremljajte celoten tok od ustvarjanja izpolnitve do pravilne posodobitve, vidne stranki. Uspeh API-ja sam po sebi ni dovolj. Spremljajte podvojene zapise, zastarele pošiljke, nepreslikane dogodke, neuspešna obvestila in delež pošiljk, ki zahtevajo ročni popravek.
