UPS Tracking API Webhooks: Kaj so, kako delujejo in primeri uporabe
Spletni kavlji API-ja za sledenje UPS omogočajo aplikaciji prejemanje posodobitev pošiljk, ko je na voljo dogodek sledenja, namesto da bi večkrat poizvedovala pri storitvi za sledenje glede najnovejšega stanja. Uporabni so za spletne trgovine, logistične ekipe, tržnice in razvijalce, ki ustvarjajo delovne tokove za upravljanje naročil. Praktična vrednost ni le hitrejša sinhronizacija stanja: dobro zasnovan tok spletnih kavljev lahko posodobi strani, namenjene strankam, sproži obravnavo izjem in zmanjša nepotrebne zahteve za sledenje.
Natančen način preverjanja pristnosti, model dogodkov, omejitve zahtev, polja koristnega tovora in zahteve glede računa so odvisni od razvijalskega izdelka UPS in okolja integracije. Razvijalci naj pred izdelavo povezave za produkcijsko okolje te podrobnosti preverijo v aktualni dokumentaciji UPS.
Kaj je spletni kavelj API-ja za sledenje UPS?
API za sledenje omogoča programsko pridobivanje informacij o pošiljki. Spletni kavelj doda vzorec izhodnega obveščanja: ko se aplikacija naroči na ustrezne posodobitve, storitev ob nastanku ustreznega dogodka pošlje zahtevo HTTP na končno točko, ki jo upravlja aplikacija.
Sistem naročil lahko na primer shrani sledilno številko UPS in registrira končno točko spletnega kavlja. Ko se stanje pošiljke spremeni, lahko prejemni sistem prejme obvestilo, ki vsebuje kombinacijo sledilne številke, stanja, časovnega žiga, lokacije, predvidene dostave ali informacij o izjemi. Prejemni sistem nato preveri sporočilo, posodobi lastni zapis in določi naslednje dejanje.
Spletni kavelj ni enak strani za sledenje. Stran za sledenje je namenjena ogledu človeka, spletni kavelj pa uporabi programska oprema. Prav tako ni zagotovilo, da bo vsak pregled prevoznika dostavljen natanko enkrat ali v popolnem vrstnem redu. Produkcijski sistemi morajo upoštevati podvojena sporočila, zakasnjeno dostavo, ponovne poskuse in občasno usklajevanje.
Kako običajno poteka delovni tok
- Razvijalec ustvari ali konfigurira dostop prek ustreznega razvijalskega računa UPS in pridobi poverilnice, ki jih zahteva API.
- Aplikacija pošlje ali shrani identifikator pošiljke, običajno sledilno številko, skupaj z notranjimi sklici na naročilo in stranko.
- Razvijalec konfigurira javno dosegljivo končno točko HTTPS in po potrebi upošteva postopek ponudnika za naročanje ali registracijo.
- Storitev za sledenje pošlje obvestilo HTTP, ko je na voljo naročena posodobitev.
- Končna točka preveri pristnost zahteve, razčleni koristni tovor in preveri, ali je pošiljka znana.
- Aplikacija hitro potrdi prejem zahteve, nato pa poslovno dejanje obdela prek čakalne vrste ali opravila v ozadju.
- Sistem zabeleži dogodek, uporabi pravila idempotentnosti in posodobi delovni tok naročila, skladišča, podpore ali obvestil strankam.
Ločitev med potrditvijo in obdelavo je pomembna. Pošiljatelj spletnega kavlja lahko poskus ponovi, če je končna točka počasna ali vrne napako. Prejemnik, ki pred odgovorom izvede obsežna opravila v zbirki podatkov, pošiljanje e-pošte ali skladiščno obdelavo, lahko povzroči časovne prekoračitve in podvojene dostave.
Obvestila spletnih kavljev v primerjavi z anketiranjem
| Pristop | Kako deluje | Glavni kompromis |
|---|---|---|
| Anketiranje | Vaša aplikacija po urniku zahteva najnovejše stanje. | O njem je preprosto razmišljati, vendar lahko ponavljajoče se zahteve povzročijo zamude in nepotreben promet. |
| Dostava prek spletnega kavlja | Storitev za sledenje pošlje obvestilo, ko je na voljo posodobitev. | Zmanjša lahko načrtovano preverjanje, vendar zahteva varen in zanesljiv prejemnik ter postopek obnovitve. |
| Hibridni model | Spletni kavlji sprožijo običajno obdelavo, medtem ko anketiranje ali usklajevanje preverja vrzeli. | Zahteva več načrtovanja, vendar je pogosto odpornejši od zanašanja na eno samo pot dostave. |
Spletni kavelj samodejno ne odpravi potrebe po zahtevah API-ja. Nekatere integracije obvestilo uporabijo kot signal in nato pokličejo API za sledenje, da pridobijo najnovejši verodostojni zapis. To je lahko koristno, kadar je koristni tovor spletnega kavlja zgoščen dogodek, kadar aplikacija potrebuje podrobnosti o pošiljki, ki niso vključene v obvestilo, ali kadar želi podjetje eno samo pot normalizacije za vse posodobitve.
Kaj mora vsebovati koristni tovor spletnega kavlja za sledenje?
Koristni tovori se razlikujejo glede na ponudnika in izdelek. Zbirke podatkov ne zasnujte na predpostavljenih imenih polj, dokler ne preverite aktualne dokumentacije in testnih odgovorov. Na splošno mora dogodek sledenja določiti:
- Pošiljko ali sledilno številko
- Dogodek ali stanje pošiljke
- Čas dogodka in, če je naveden, lokalni časovni pas
- Opis pregleda ali operativno sporočilo
- Podatke o lokaciji, če so na voljo
- Predvideno dostavo ali potrditev dostave, če je navedena
- Kazalnik izjeme ali opis izjeme
- Identifikator dogodka ponudnika ali drugo vrednost, uporabno za odstranjevanje dvojnikov
Besedilo stanja obravnavajte kot podatke ponudnika, ne kot univerzalno poslovno pravilo. Oznako, kot so »v tranzitu«, »izjema« ali »dostavljeno«, bo morda treba preslikati v notranji model stanj. Sistem mora ohraniti izvirno stanje prevoznika in normalizirano stanje, da lahko podporno osebje preuči razlike, ne da bi izgubilo izvorno sporočilo.
Praktični primeri uporabe
Posodobitve dostave za stranke
Platforma za e-trgovino lahko dogodke sledenja uporabi za osvežitev strani s stanjem naročila ali pošiljanje obvestila stranki. Najboljši sprožilec je odvisen od poslovnega pravila. Pregled ob prevzemu pošiljke lahko potrdi napredek pri izpolnitvi naročila, medtem ko lahko dogodek izjeme zahteva sporočilo podpore namesto splošnega e-poštnega sporočila o stanju. Izogibajte se pošiljanju obvestila za vsak pregled, razen če stranke izrecno želijo takšno raven podrobnosti.
Upravljanje izjem
Spletni kavelj lahko morebitne težave pri dostavi usmeri v čakalno vrsto za pregled. Primeri vključujejo izjemo pri dostavi, težavo, povezano z naslovom, ali pošiljko, ki ni napredovala po pričakovanjih. Integracija mora razlikovati med informativnim pregledom in operativno izjemo. Določiti mora tudi odgovornost: podpora strankam lahko obravnava komunikacijo, ekipa za izpolnjevanje naročil pa lahko preuči pošiljko ali naslov.
Sinhronizacija skladišča in upravljanja naročil
Skladiščni sistem ali sistem za upravljanje naročil lahko dogodke sledenja uporabi za posodobitev zapisa o izpolnitvi naročila, ne da bi moralo osebje ročno preverjati stran prevoznika. To je posebej koristno, kadar eno naročilo vsebuje več paketov. Podatkovni model mora hraniti zapise sledenja na ravni paketa, namesto da bi eno stanje pripisal celotnemu naročilu, saj se lahko paketi istega naročila premikajo ali prispejo ob različnih časih.
Vračila in povratna logistika
Delovni tokovi vračil lahko dogodke sledenja uporabijo za ugotavljanje, kdaj se paket vrača trgovcu ali kdaj prispe v obrat za vračila. Dogodek sam po sebi ne sme odobriti vračila kupnine, razen če politika trgovca izrecno uporablja ta pogoj. Po poročilu prevoznika o dostavi bo morda potrebno preverjanje, usklajevanje zalog ali pregled zaradi goljufij.
Operativno poročanje
Normalizirani dogodki sledenja lahko podpirajo poročila o napredku pošiljk, številu izjem in izidih dostave. Poročila morajo svoje opredelitve jasno navesti. »Dostavljeno« lahko na primer pomeni dogodek dostave, o katerem poroča prevoznik, medtem ko »pravočasno« zahteva opredeljen obljubljeni datum, rok, časovni pas ter obravnavo sprememb naslova ali zamud na zahtevo stranke.
Integracija samo z UPS ali API za več prevoznikov?
Integracija, značilna za UPS, je lahko primerna, kadar podjetje pošilja predvsem z UPS in želi neposredno uporabljati njegovo uradno razvijalsko okolje. Prav tako je lahko najpreprostejša izbira, kadar ima obstoječi sistem naročil že priključek UPS in so zahtevani delovni tokovi omejeni.
API za sledenje več prevoznikov je drugačna arhitekturna izbira. Zagotovi lahko enoten model integracije med prevozniki, vendar mora aplikacija še vedno obravnavati posebne pomene stanj prevoznikov, razlike v pokritosti, zahteve za preverjanje pristnosti in kakovost podatkov. Storitve za več prevoznikov ne izberite samo zato, ker oglašuje spletni kavelj. Preverite podprte prevoznike, normalizacijo dogodkov, dokumentacijo, testno okolje, pravila hrambe in operativno podporo.
API za sledenje 17TRACK je pomemben za ekipe, ki ocenjujejo pristop sledenja več prevoznikov, njegova uradna dokumentacija API-ja pa naj se uporablja za preverjanje trenutnih zmogljivosti, formatov zahtev in zahtev za integracijo. Ni nadomestilo za preverjanje, ali so prevozniki in dogodki, potrebni za določen delovni tok UPS, podprti za predvideni primer uporabe.
Kontrolni seznam za izvedbo
- Potrdite obseg izdelka. Preverite, ali izbrana storitev UPS podpira operacije sledenja in model obveščanja, ki jih potrebuje vaša aplikacija.
- Uporabite HTTPS. Prejemnik mora biti med prenosom zaščiten, poverilnic pa ne sme izpostavljati v URL-jih ali dnevnikih.
- Preverite pristnost. Upoštevajte dokumentirano metodo ponudnika za podpis, žeton ali preverjanje. Če metoda ni na voljo, uporabite omrežne nadzore in preverjanje zahtev, primerno storitvi.
- Obdelavo naredite idempotentno. Kadar je na voljo, shranite identifikator dogodka ali ustvarite previden ključ za odstranjevanje dvojnikov iz stabilnih polj dogodka.
- Sprejmite dogodke izven vrstnega reda. Uporabite časovne žige dogodkov in dokumentirano politiko prehodov stanj, namesto da bi predpostavljali, da vrstni red prihoda ustreza vrstnemu redu pregledov.
- Vrnete hiter odgovor. Daljša opravila postavite v čakalno vrsto ter spremljajte neuspešne dostave, ponovne poskuse in sporočila v čakalni vrsti za nedostavo.
- Uskladite vrzeli. Načrtujte nadzorovan postopek preverjanja pošiljk brez nedavne posodobitve, z neuspešno dostavo ali z neskladnim stanjem.
- Zaščitite osebne podatke. Omejite shranjene podatke o naslovu in prejemniku, omejite dostop ter določite pravila hrambe, ki ustrezajo poslovnim potrebam.
- Preizkusite resnične poslovne primere. Vključite dostavljene pošiljke, izjeme, preklicana naročila, podvojene dogodke, neznane sledilne številke in zakasnjena obvestila.
Pogoste napake, ki se jim je treba izogniti
Najpogostejša napaka pri zasnovi je obravnavanje spletnega kavlja kot popolnega vira resnice brez načrtovanja ponovnih poskusov ali manjkajočih dogodkov. Druga napaka je neposredno posodabljanje stanja naročila iz prostega besedila brez preslikovalnega sloja. To lahko povzroči nepravilna sporočila strankam, ko se terminologija prevoznika spremeni ali ko dogodek velja samo za en paket.
Ekipe se morajo izogibati tudi izpostavljanju končne točke spletnega kavlja brez nadzora zlorab, beleženju celotnih koristnih tovorov z nepotrebnimi osebnimi podatki in pošiljanju obvestil strankam, preden dogodek prestane osnovno preverjanje. Nazadnje ne obljubljajte datumov dostave samo zato, ker odgovor sledenja vsebuje oceno. Ocene se lahko spremenijo, zato mora besedilo za stranke odražati to negotovost.
Kako izbrati pristop k integraciji
Neposredno integracijo UPS izberite, kadar je obseg prevoznikov omejen, ekipa zna vzdrževati logiko, značilno za prevoznika, in so zahtevane uradne funkcije na voljo. O API-ju za sledenje več prevoznikov razmislite, kadar podjetje potrebuje en notranji vmesnik za več prevoznikov in ima dovolj obsega ali zapletenosti, da upraviči abstrakcijski sloj. V obeh primerih primerjajte dejansko dokumentacijo in vedenje pri testiranju, ne le imen funkcij.
Pred uvedbo v produkcijo izvedite dokaz koncepta z reprezentativnimi sledilnimi številkami in scenariji napak. Potrdite, kako se ustvarijo naročnine, kako se zamenjajo poverilnice, kako se preverijo obvestila, kako se prikažejo podvojeni dogodki, kako se obravnavajo zgodovinske posodobitve in kaj se zgodi, če prejemnik ni na voljo. Ti odgovori določajo, ali bo integracija po začetnem predstavitvenem okolju ostala zanesljiva.
Pogosta vprašanja
Ali je spletni kavelj API-ja za sledenje UPS boljši od anketiranja?
Noben pristop ni samodejno boljši. Spletni kavlji lahko zmanjšajo načrtovano preverjanje in omogočijo hitrejše odzive, medtem ko je anketiranje lažje nadzorovati in lahko pomaga uskladiti zamujene dogodke. Številni produkcijski sistemi uporabljajo obvestila spletnih kavljev skupaj z omejenimi zahtevami za usklajevanje.
Ali potrebujem spletni kavelj, če sledim le majhnemu številu pošiljk?
Ni nujno. Pri majhnem delovnem toku z nizko pogostostjo lahko zadostujeta dokumentiran postopek anketiranja ali obstoječa integracija platforme. Spletni kavelj postane privlačnejši, ko morajo posodobitve sprožiti avtomatizirana dejanja ali ko redno ročno preverjanje povzroča operativno delo.
Ali lahko spletni kavelj zagotovi, da vsak pregled UPS doseže moj sistem?
Tega ne smete predpostavljati. Vedenje dostave, ponovni poskusi, vrstni red dogodkov in hramba so odvisni od konkretne storitve. V integracijo vključite spremljanje, idempotentnost in usklajevanje ter veljavna zagotovila preverite v aktualni dokumentaciji UPS.
Ali mora vsak dogodek sledenja sprožiti e-pošto stranki?
Običajno ne. Dogodke prevoznika preslikajte v pravila komunikacije s strankami in sporočila omejite na mejnike ali izjeme, ki so koristne za prejemnika. Izvirni dogodek ohranite v notranji zgodovini, tudi če ne ustvari obvestila.
Kdaj naj podjetje uporabi API za sledenje več prevoznikov?
O njem je vredno razmisliti, ko podjetje pošilja prek več prevoznikov in želi skupni delovni tok sledenja. Odločitev mora upoštevati podporo prevoznikov, normalizirane podatke, vedenje spletnih kavljev, dokumentacijo, varnost, testiranje in trud, potreben za vzdrževanje integracije.
