Kako uporabljati API za sledenje UPS: vodnik za nastavitev po korakih

Za uporabo API-ja za sledenje UPS ustvarite račun UPS Developer, registrirajte aplikacijo, pridobite poverilnice OAuth 2.0, zahtevajte žeton za dostop in pošljite overjene zahteve za sledenje z veljavno številko za sledenje UPS. Natančne oznake v portalu, koraki odobritve in zahteve API-ja se lahko spremenijo, zato pred uvedbo produkcijske integracije preverite aktualna navodila v uradnem portalu UPS Developer Portal.

Ta vodnik je namenjen razvijalcem in ekipam za e-poslovanje, ki potrebujejo stanje pošiljk v spletni trgovini, sistemu za upravljanje naročil, skladiščnem poteku dela, orodju za podporo strankam ali internem nadzorni plošči. Osredotoča se na zaporedje integracije, odločitve, ki vplivajo na zanesljivost, in preverjanja, ki preprečujejo pogoste napake pri sledenju.

Kaj omogoča API za sledenje UPS

Integracija API omogoča programski opremi, da zahteva informacije o pošiljki od UPS, namesto da bi moral zaposleni ali stranka ročno odpreti stran prevoznika za sledenje. Vaša aplikacija lahko odgovor uporabi za prikaz zadnjega znanega stanja, prepoznavanje dogodkov dostave, podporo preiskavam službe za pomoč strankam ali sprožitev internega poteka dela.

API ni enak strani za sledenje. Stran za sledenje je zasnovana tako, da jo bere človek. Odgovor API je strukturiran podatek, ki ga mora programska oprema razčleniti, shraniti in prikazati. Vaš sistem je še naprej odgovoren za preverjanje pristnosti, obravnavo napak, periodično pridobivanje ali zbiranje dogodkov, hrambo podatkov, oblikovanje uporabniškega vmesnika in vsa poslovna pravila, povezana z dogodki dostave.

Pred začetkom

Preden odprete portal za razvijalce, pripravite naslednje:

• Račun UPS Developer ali vrsto računa, ki jo zahteva trenutni postopek vključitve UPS.
• Registrirano aplikacijo in poverilnice, izdane za to aplikacijo.
• Testno številko za sledenje ali drug odobren način testiranja. Če dokumentacija UPS določa ločeno testno okolje ali testni postopek, ne začnite z dejanskimi podatki strank.
• Jasno odločitev o tem, kateri sistem je lastnik zapisov o pošiljkah, dogodkov sledenja in sporočil o stanju, namenjenih strankam.
• Varno mesto za shranjevanje poverilnic odjemalca in žetonov za dostop. Skrivnosti nikoli ne vstavljajte v kodo brskalnika, javne repozitorije, posnetke zaslona ali mobilne aplikacije, ki jih lahko uporabniki pregledajo.

Odločiti se morate tudi, ali vaša aplikacija potrebuje samo sledenje ali širšo integracijo UPS. Sledenje, izračun cen, pošiljanje, preverjanje naslovov in storitve dokumentov imajo lahko različne izdelke, dovoljenja, oblike zahtev in operativne zahteve.

1. korak: Odprite portal UPS Developer Portal

Začnite v uradnem portalu UPS Developer Portal. Preglejte trenutni katalog API-jev, navodila za preverjanje pristnosti, zahteve za vključitev, pogoje in informacije o okoljih. Poiščite predvsem dokumentacijo API-ja za sledenje in ne predpostavljajte, da navodila za drugo storitev UPS veljajo tudi za sledenje.

Portal je ustrezen vir za trenutna polja zahtev, obsege pooblastil, definicije odgovorov, omejitve hitrosti, kode napak in podrobnosti o okoljih. Te podrobnosti se lahko spremenijo, primer kode tretje osebe pa lahko uporablja starejši vmesnik UPS ali zastarel način preverjanja pristnosti.

2. korak: Registrirajte aplikacijo

Ustvarite aplikacijo v portalu za razvijalce in izberite API-je UPS, ki jih aplikacija dejansko potrebuje. Pri projektu, namenjenem samo sledenju, zahtevajte samo zmogljivost sledenja, razen če vaš potek dela zahteva dodatne storitve. Omejevanje dovoljenj zmanjša zapletenost konfiguracije in olajša poznejše odpravljanje težav.

Identifikator in skrivnost aplikacije shranite v upravljalniku skrivnosti na strežniški strani ali v zaščitenem sistemu okoljskih spremenljivk. S skrivnostjo ravnajte kot z geslom. Če je razkrita, jo zamenjajte po postopku, ki ga zagotavlja UPS, in preglejte dnevnike glede nepooblaščene uporabe.

Če portal zahteva podatke o računu, obračunavanju, podjetju ali aplikaciji, navedite točne podatke. Ne izmišljajte produkcijskega primera uporabe in ne uporabljajte podatkov računa druge osebe samo zato, da bi zaključili test. Dostop do storitve je lahko odvisen od konfiguracije računa in trenutnega postopka odobritve UPS.

3. korak: Izvedite preverjanje pristnosti OAuth 2.0

Trenutna dokumentacija UPS za razvijalce za svoje API-je uporablja preverjanje pristnosti na osnovi OAuth. Vaš strežnik običajno izmenja poverilnice aplikacije prek dokumentiranega postopka za pridobitev žetona in prejme žeton za dostop. Nato ta žeton vključi v glavo za avtorizacijo zahteve API.

Preverjanje pristnosti ločite od logike sledenja. Praktična zasnova ima eno komponento, ki pridobi in predpomni veljaven žeton, ter drugo, ki kliče končno točko za sledenje. Komponenta za žetone mora:

• Poverilnice pošiljati samo na dokumentirano avtorizacijsko končno točko UPS.
• Uporabljati vrsto vsebine in parametre dodelitve, določene v trenutni dokumentaciji UPS.
• Žeton začasno shraniti in ga ponovno uporabiti do njegovega poteka, namesto da bi za vsako številko za sledenje zahtevala nov žeton.
• Žeton osvežiti ali znova pridobiti, ko nastopi dokumentirani pogoj poteka.
• Poverilnice in žetone izločiti iz dnevnikov aplikacije, poročil o napakah in zahtevkov za podporo.

Žetona iz seje brskalnika ne kopirajte v trajno integracijo. Zaledna storitev je na splošno varnejše mesto za upravljanje poverilnic, saj skrivnosti ohranja zunaj javne kode odjemalca.

4. korak: Izdelajte zahtevo za sledenje

Uporabite obliko zahteve, prikazano v uradnem sklicu API-ja za sledenje. Običajna zahteva vključuje številko za sledenje v poti ali parametrih zahteve, žeton za dostop v glavi za avtorizacijo in glave, ki jih zahteva API UPS. Ne predpostavljajte, da je številka za sledenje edina zahtevana vrednost: trenutni sklic lahko določa različico, transakcijo, vrsto vsebine ali glave za korelacijo.

Poenostavljen vzorec zahteve je videti tako:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

To je strukturni primer in ne končna točka za kopiranje. Uporabite končno točko, različico, glave in imena parametrov, objavljene v dokumentaciji UPS za vašo aplikacijo. Številko za sledenje normalizirajte v skladu s pravili lastnih podatkov o naročilih, vendar znakov ne odstranjujte, razen če dokumentacija prevoznika potrdi, da je to varno.

5. korak: Razčlenite dogodke v svoj podatkovni model

Odgovori prevoznikov pogosto vsebujejo več informacij kot eno samo oznako stanja. Pred programiranjem strani, namenjene strankam, odgovor preslikajte v notranji model, ki lahko vključuje identifikator pošiljke, prevoznika, najnovejše stanje, kodo dogodka, opis dogodka, časovni žig dogodka, lokacijo, podatke o predvideni dostavi in časovni žig dostave, kadar je na voljo.

Izvirni odgovor prevoznika ohranite, kadar to dopuščajo vaša pravila hrambe in zasebnosti. Neobdelani odgovor lahko pomaga diagnosticirati napako pri preslikavi ali pojasniti, zakaj se vaše normalizirano stanje razlikuje od izrazja prevoznika. Hkrati strankam ne prikazujte tehničnih kod dogodkov brez razumljive razlage.

Vsakega stanja ne obravnavajte kot končni rezultat dostave. Dogodek »v tranzitu«, izjema, poskus dostave in dogodek dostave na primer ne smejo biti združeni v isto sporočilo za stranko. Ustvarite izrecne preslikave in določite, kaj se zgodi, ko UPS doda vrednost dogodka, ki je vaša koda ne prepozna.

6. korak: Dodajte ponovne poskuse, preverjanje in spremljanje

Produkcijska integracija potrebuje več kot uspešno zahtevo v razvojni konzoli. Dodajte preverjanje in operativne zaščitne ukrepe:

• Preverjanje vnosa: prazne, napačno oblikovane ali očitno nepopolne številke za sledenje zavrnite, preden pošljete zahteve.
• Časovne omejitve: preprečite, da bi počasen odgovor prevoznika blokiral celoten potek plačila, podpore ali skladišča.
• Pravila ponovnih poskusov: začasne omrežne ali servisne napake previdno ponovite z uporabo povratnega zamika. Zahtev za preverjanje pristnosti ali neveljavnih številk za sledenje ne ponavljajte.
• Upoštevanje omejitev hitrosti: upoštevajte omejitve in pravila uporabe v dokumentaciji UPS. Kadar poslovni proces to dovoljuje, predpomnite nedavne rezultate.
• Neznana stanja: neprepoznan dogodek ohranite za pregled, namesto da bi ga napačno označili kot dostavljenega ali izgubljenega.
• Opazljivost: beležite čas zahtev, kategorijo odgovora in informacije za korelacijo, vendar brez beleženja skrivnosti ali nepotrebnih osebnih podatkov.

Sistem za sledenje mora določiti tudi, kako pogosto osvežuje pošiljko. Prepogosto pridobivanje lahko povzroči nepotrebno obremenitev in morda ne prinese novih informacij. Preredko pridobivanje lahko povzroči, da je stran, namenjena strankam, videti zastarela. Interval izberite glede na količino pošiljk, operativno nujnost, pravila prevoznika in svežino, ki jo uporabniki dejansko potrebujejo.

7. korak: Testirajte z realističnimi scenariji

Testirajte več kot samo uspešno dostavljeno pošiljko. Vključite neznano številko za sledenje, pošiljko v tranzitu, izjemo, pošiljko z več dogodki, potekel žeton, časovno omejitev, napako pri avtorizaciji in odgovor s polji, ki jih vaš razčlenjevalnik ne pričakuje. Če UPS zagotavlja ločeno testno okolje ali testne poverilnice, najprej upoštevajte ta postopek.

Preverite celotno pot od zahteve do uporabniškega vmesnika. Potrdite, da pravilno naročilo prejme pravilno pošiljko, da so časovni žigi prikazani v predvidenem časovnem pasu, da podvojeni dogodki ne ustvarjajo podvojenih sporočil za stranke in da izpad prevoznika ne prepiše prej veljavnega stanja z zavajajočim besedilom.

Kdaj je API za sledenje več prevoznikov primernejša izbira

Neposredna integracija UPS je lahko primerna, kadar vaša dejavnost večinoma pošilja z UPS in potrebuje tesen nadzor nad potekom dela prevoznika. Manj praktična postane, ko se naročila lahko pošiljajo prek več prevoznikov, tržnic, poštnih operaterjev ali regionalnih dostavnih podjetij. V takem primeru lahko ločene poverilnice, oblike odgovorov, besedišča stanj in pravila ponovnih poskusov povečajo vzdrževalno delo.

Storitev za več prevoznikov, kot je 17TRACK Tracking API, lahko zagotovi alternativni model integracije za aplikacije, ki potrebujejo sledenje pri več prevoznikih. Njeno dokumentacijo za razvijalce je treba neposredno pregledati glede podprtih prevoznikov, oblik zahtev, preverjanja pristnosti, pogojev uporabe in razpoložljivih zmogljivosti. Zaradi tega ni samodejno boljša od neposredne povezave UPS: prava izbira je odvisna od kombinacije prevoznikov, zahtev glede podatkov, nadzora nad integracijo ter komercialnih ali skladnostnih omejitev.

Za iskanje, namenjeno potrošnikom, in ne za integracijo za razvijalce, je lahko stran za sledenje 17TRACK primernejša od izdelave povezave API. Pri spletni trgovini, ki potrebuje blagovno znamko pri obvestilih po nakupu, ločeno preglejte ustrezno integracijo platforme, namesto da dodajate delo z API-jem, ki ga trgovina ne potrebuje.

Pogoste napake pri izvedbi

• Uporaba starih primerov: vzorec kode se lahko nanaša na umaknjeno različico, star način preverjanja pristnosti ali drugo storitev UPS.
• Vstavljanje skrivnosti v kodo uporabniškega vmesnika: vse, kar je poslano v brskalnik, je treba obravnavati kot pregledljivo.
• Predpostavka, da prazen rezultat pomeni odsotnost pošiljke: pred poslovnim sklepom preverite številko za sledenje, dovoljenja računa, okolje in sporočilo odgovora.
• Preslikava samo besedila: opisi stanj se lahko razlikujejo. Uporabite dokumentirane kode in neznane vrednosti ohranite za pregled.
• Neupoštevanje zahtev računa in uporabe: tehnična koda je lahko pravilna, vendar aplikacija ni konfigurirana za zahtevano storitev.
• Osveževanje brez poslovnega pravila: nepotrebno periodično pridobivanje lahko poveča stroške, obremenitev in operativni hrup, ne da bi izboljšalo izkušnjo strank.

Praktični kontrolni seznam pred uvedbo

1. Potrdite, da aplikacija uporablja trenutno dokumentacijo UPS in odobreno okolje.
2. Preverite, ali so poverilnice shranjene na strežniški strani in jih je mogoče zamenjati.
3. Testirajte neuspešno preverjanje pristnosti, napake prevoznika, napačno oblikovan vnos in časovne omejitve.
4. Normalizirana stanja primerjajte z izvirnim odgovorom za reprezentativne pošiljke.
5. Določite pravilnik osveževanja in spremljajte količino zahtev.
6. Določite odgovornost za neidentificirane dogodke, zakasnjene posodobitve in eskalacije strank.
7. Dokumentirajte integracijo, da bo lahko drug razvijalec varno posodobil poverilnice, različice končnih točk in preslikave stanj.

Pogosta vprašanja

Ali za uporabo API-ja za sledenje UPS potrebujem račun UPS?

Trenutne zahteve za vključitev in dostop UPS preverite v portalu Developer Portal. Dostop do API-ja je lahko odvisen od registracije aplikacije, poverilnic, konfiguracije računa in konkretne zahtevane storitve. Ne predpostavljajte, da je prijava na javno stran za sledenje zamenljiva z dostopom do API-ja za razvijalce.

Ali je API za sledenje UPS brezplačen?

Ne predpostavljajte, da dostop do API-ja nima komercialnih ali uporabniških pogojev. UPS objavlja aktualne informacije o storitvah in računih prek svojih uradnih kanalov, nekatere zahteve pa so lahko odvisne od izdelka, računa ali pogodbe. Pred načrtovanjem produkcijskega proračuna neposredno potrdite veljavne pogoje.

Ali lahko API UPS kličem neposredno iz JavaScripta v brskalniku?

Klic iz brskalnika lahko razkrije poverilnice aplikacije in povzroči težave, povezane z meddomenskim dostopom, varnostjo in nadzorom uporabe. Integracija na strežniški strani je na splošno varnejši vzorec za shranjevanje skrivnosti, pridobivanje žetonov, uporabo pravil ponovnih poskusov in omejevanje dostopa do podatkov o pošiljkah.

Kako pogosto naj moja aplikacija zahteva posodobitve sledenja?

Pravilnik osveževanja določite na podlagi dokumentiranih omejitev prevoznika, količine pošiljk, operativne nujnosti in svežine, ki jo potrebujejo uporabniki. Kjer je primerno, predpomnite nedavne rezultate, po začasnih napakah uporabite povratni zamik in ponavljajočega se pridobivanja ne obravnavajte kot nadomestilo za dokumentirano zmogljivost dogodkov ali obvestil.

Ali naj uporabim neposredno integracijo UPS ali API za več prevoznikov?

Neposredna integracija UPS je lahko primerna za potek dela, osredotočen na UPS, ki potrebuje specifičen nadzor prevoznika. API za več prevoznikov lahko zmanjša število integracij, kadar vaše pošiljke uporabljajo več prevoznikov. Pred izbiro primerjajte podprte prevoznike, preverjanje pristnosti, podatkovna polja, zahteve glede zanesljivosti, pogoje uporabe in izvedbeni napor.

Viri

• UPS Developer Portal — uradni katalog API-jev, dostop do aplikacij, preverjanje pristnosti in dokumentacija za razvijalce.
• UPS Technology Integration — uradne informacije o integraciji tehnologije UPS s poslovnimi sistemi.
• 17TRACK Tracking API — uradna vstopna točka za izdelek in razvijalce za sledenje pri več prevoznikih.
• 17TRACK API Documentation — uradna dokumentacija API-ja za preverjanje pristnosti, zahteve in obravnavo odgovorov.