Kaip naudoti UPS Tracking API: nuoseklus sąrankos vadovas

Norėdami naudoti UPS Tracking API, sukurkite UPS kūrėjo paskyrą, užregistruokite programą, gaukite OAuth 2.0 prisijungimo duomenis, paprašykite prieigos rakto ir siųskite autentifikuotas siuntų sekimo užklausas su galiojančiu UPS sekimo numeriu. Tikslūs portalo pavadinimai, patvirtinimo veiksmai ir API reikalavimai gali keistis, todėl prieš paleisdami gamybinę integraciją patikrinkite dabartines instrukcijas oficialiame UPS Developer Portal.

Šis vadovas skirtas kūrėjams ir el. prekybos operacijų komandoms, kurioms reikia siuntos būsenos internetinėje parduotuvėje, užsakymų valdymo sistemoje, sandėlio darbo procese, klientų aptarnavimo įrankyje ar vidinėje informacijos suvestinėje. Jame daugiausia dėmesio skiriama integracijos sekai, sprendimams, kurie turi įtakos patikimumui, ir patikroms, padedančioms išvengti dažniausių siuntų sekimo klaidų.

Ką daro UPS Tracking API

API integracija leidžia programinei įrangai prašyti siuntos informacijos iš UPS, todėl darbuotojui ar klientui nereikia rankiniu būdu atidaryti vežėjo sekimo puslapio. Jūsų programa gali naudoti atsakymą naujausiai žinomai būsenai rodyti, pristatymo įvykiams nustatyti, klientų aptarnavimo tyrimams palaikyti arba vidiniam procesui paleisti.

API nėra tas pats, kas sekimo puslapis. Sekimo puslapis skirtas žmogui skaityti. API atsakymas yra struktūrizuoti duomenys, kuriuos programinė įranga turi išanalizuoti, išsaugoti ir pateikti. Jūsų sistema lieka atsakinga už autentifikavimą, klaidų tvarkymą, apklausą arba įvykių rinkimą, duomenų saugojimą, naudotojo sąsajos kūrimą ir visas verslo taisykles, pagrįstas pristatymo įvykiais.

Prieš pradedant

Prieš atidarydami kūrėjų portalą pasiruoškite šiuos dalykus:

• UPS kūrėjo paskyrą arba paskyros tipą, kurio reikalauja dabartinis UPS registracijos procesas.
• Užregistruotą programą ir jai išduotus prisijungimo duomenis.
• Bandomąjį sekimo numerį arba kitą patvirtintą bandymo metodą. Nepradėkite nuo tikrų klientų duomenų, jei UPS dokumentacijoje pateikiama atskira bandymo aplinka arba procedūra.
• Aiškų sprendimą, kuri sistema yra atsakinga už siuntų įrašus, sekimo įvykius ir klientams rodomus būsenos pranešimus.
• Saugią vietą kliento prisijungimo duomenims ir prieigos raktams saugoti. Niekada nedėkite paslapčių į naršyklės kodą, viešas saugyklas, ekrano kopijas ar mobiliąsias programas, kurias naudotojai gali patikrinti.

Taip pat turėtumėte nuspręsti, ar jūsų programai reikia tik sekimo, ar platesnės UPS integracijos. Sekimo, tarifų, siuntimo, adreso tikrinimo ir dokumentų paslaugoms gali būti taikomi skirtingi produktai, leidimai, užklausų formatai ir veiklos reikalavimai.

1 veiksmas: atidarykite UPS Developer Portal

Pradėkite nuo oficialaus UPS Developer Portal. Peržiūrėkite dabartinį API katalogą, autentifikavimo gaires, registracijos reikalavimus, sąlygas ir informaciją apie aplinkas. Ieškokite būtent Tracking API dokumentacijos, o ne manykite, kad kitos UPS paslaugos instrukcijos taip pat taikomos siuntų sekimui.

Portalas yra tinkamiausias šaltinis dabartiniams užklausų laukams, autorizacijos apimtims, atsakymų apibrėžimams, užklausų dažnio ribojimams, klaidų kodams ir informacijai apie aplinkas. Ši informacija gali keistis, o trečiosios šalies kodo pavyzdyje gali būti naudojama senesnė UPS sąsaja arba pasenęs autentifikavimo metodas.

2 veiksmas: užregistruokite programą

Sukurkite programą kūrėjų portale ir pasirinkite UPS API, kurių programai iš tikrųjų reikia. Jei projektas skirtas tik sekimui, prašykite tik sekimo funkcijos, nebent jūsų procesui reikia papildomų paslaugų. Apribojus leidimus sumažėja konfigūracijos sudėtingumas ir vėliau lengviau šalinti triktis.

Programos identifikatorių ir paslaptį saugokite serverio pusės paslapčių tvarkyklėje arba apsaugotų aplinkos kintamųjų sistemoje. Saugokite paslaptį kaip slaptažodį. Jei ji atskleidžiama, pakeiskite ją UPS nurodytu būdu ir patikrinkite žurnalus dėl neleistino naudojimo.

Jei portalas prašo paskyros, atsiskaitymo, verslo ar programos informacijos, pateikite tikslius duomenis. Nekurkite išgalvoto gamybinio naudojimo atvejo ir nenaudokite kito asmens paskyros informacijos vien tam, kad užbaigtumėte bandymą. Prieiga prie paslaugos gali priklausyti nuo paskyros konfigūracijos ir dabartinio UPS patvirtinimo proceso.

3 veiksmas: įdiekite OAuth 2.0 autentifikavimą

Dabartinėje UPS kūrėjų dokumentacijoje jos API naudojamas OAuth pagrįstas autentifikavimas. Jūsų serveris paprastai perduoda programos prisijungimo duomenis pagal dokumentuotą rakto gavimo srautą ir gauna prieigos raktą. Tada šis raktas įtraukiamas į API užklausos autorizacijos antraštę.

Atskirkite autentifikavimą nuo sekimo logikos. Praktiniame projekte vienas komponentas gauna ir išsaugo galiojantį raktą, o kitas iškviečia sekimo galinį tašką. Rakto komponentas turėtų:

• Siųsti prisijungimo duomenis tik į dokumentacijoje nurodytą UPS autorizacijos galinį tašką.
• Naudoti turinio tipą ir suteikimo parametrus, nurodytus dabartinėje UPS dokumentacijoje.
• Laikinai saugoti raktą ir pakartotinai jį naudoti, kol jis galioja, o ne prašyti naujo rakto kiekvienam sekimo numeriui.
• Atnaujinti arba iš naujo gauti raktą, kai įvyksta dokumentuota jo galiojimo pabaigos sąlyga.
• Pašalinti prisijungimo duomenis ir raktus iš programos žurnalų, klaidų ataskaitų ir pagalbos užklausų.

Nekopijuokite rakto iš naršyklės seanso į nuolatinę integraciją. Backend paslauga paprastai yra saugesnė vieta prisijungimo duomenims tvarkyti, nes ji apsaugo paslaptis nuo viešo kliento kodo.

4 veiksmas: sukurkite sekimo užklausą

Naudokite oficialioje Tracking API nuorodoje pateiktą užklausos formatą. Įprastoje užklausoje sekimo numeris nurodomas kelyje arba užklausos parametruose, prieigos raktas – autorizacijos antraštėje, taip pat pateikiamos UPS API reikalaujamos antraštės. Nemanykite, kad pakanka vien sekimo numerio: dabartinėje nuorodoje gali būti nurodytos versijos, operacijos, turinio tipo ar koreliacijos antraštės.

Supaprastintas užklausos šablonas atrodo taip:

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

Tai yra struktūrinis pavyzdys, o ne galinis taškas, kurį galima tiesiog nukopijuoti. Savo programai naudokite UPS dokumentacijoje paskelbtą galinį tašką, versiją, antraštes ir parametrų pavadinimus. Sekimo numerį normalizuokite pagal savo užsakymų duomenų taisykles, tačiau nepašalinkite simbolių, nebent vežėjo dokumentacijoje patvirtinta, kad tai saugu.

5 veiksmas: susiekite įvykius su savo duomenų modeliu

Vežėjų atsakymuose dažnai pateikiama daugiau informacijos nei vienas būsenos pavadinimas. Prieš kurdami klientams skirtą puslapį, susiekite atsakymą su vidiniu modeliu, kuriame, pavyzdžiui, būtų siuntos identifikatorius, vežėjas, naujausia būsena, įvykio kodas, įvykio aprašymas, įvykio laiko žyma, vieta, numatomo pristatymo informacija ir pristatymo laiko žyma, jei ji prieinama.

Jei tai leidžia jūsų saugojimo ir privatumo taisyklės, išsaugokite pradinį vežėjo atsakymą. Neapdorotas atsakymas gali padėti diagnozuoti susiejimo klaidą arba paaiškinti, kodėl jūsų normalizuota būsena skiriasi nuo vežėjo formuluotės. Tačiau nerodykite klientams techninių įvykių kodų be suprantamo paaiškinimo.

Nelaikykite kiekvienos būsenos galutiniu pristatymo rezultatu. Pavyzdžiui, vežama siunta, išimtis, nesėkmingas pristatymas ir pristatyta siunta neturėtų būti sutraukti į tą pačią klientui rodomą žinutę. Sukurkite aiškius susiejimus ir apibrėžkite, kas vyksta, kai UPS prideda įvykio reikšmę, kurios jūsų kodas neatpažįsta.

6 veiksmas: pridėkite pakartotinius bandymus, tikrinimą ir stebėseną

Gamybinėje integracijoje reikia daugiau nei sėkmingos užklausos kūrimo konsolėje. Pridėkite tikrinimą ir veiklos apsaugos priemones:

• Įvesties tikrinimas: prieš siųsdami užklausas atmeskite tuščius, netinkamo formato ar akivaizdžiai nebaigtus sekimo numerius.
• Skirtojo laiko intervalai: neleiskite, kad lėtas vežėjo atsakymas blokuotų visą atsiskaitymo, pagalbos ar sandėlio procesą.
• Pakartotinių bandymų taisyklės: laikinus tinklo ar paslaugos sutrikimus bandykite pakartoti atsargiai, taikydami laukimo intervalų didinimą. Nekartokite autentifikavimo klaidų ar netinkamų sekimo numerių užklausų nuolat.
• Užklausų dažnio kontrolė: laikykitės UPS dokumentacijoje nurodytų ribų ir naudojimo taisyklių. Jei jūsų verslo procesas leidžia, talpykloje saugokite naujausius rezultatus.
• Nežinomos būsenos: neatpažintą įvykį išsaugokite peržiūrai, o ne klaidingai pažymėkite kaip pristatytą ar prarastą.
• Stebimumas: registruokite užklausos trukmę, atsakymo kategoriją ir koreliacijos informaciją, tačiau neregistruokite paslapčių ar nereikalingų asmens duomenų.

Sekimo sistema taip pat turėtų apibrėžti, kaip dažnai ji atnaujina siuntos informaciją. Per dažna apklausa gali sukurti išvengiamą apkrovą ir ne visada pateikti naujos informacijos. Per reta apklausa gali sudaryti pasenusio klientams skirto puslapio įspūdį. Intervalą pasirinkite pagal siuntų skaičių, veiklos skubumą, vežėjo taisykles ir tai, kokio naujumo informacijos iš tikrųjų reikia naudotojams.

7 veiksmas: išbandykite realistiškus scenarijus

Išbandykite ne tik sėkmingai pristatytą siuntą. Įtraukite nežinomą sekimo numerį, vežamą siuntą, išimtį, siuntą su keliais įvykiais, pasibaigusio galiojimo raktą, skirtąjį laiką, autorizacijos klaidą ir atsakymą su laukais, kurių jūsų analizatorius nesitiki. Jei UPS pateikia atskirą bandymo aplinką ar bandymo prisijungimo duomenis, pirmiausia laikykitės tos procedūros.

Patikrinkite visą kelią nuo užklausos iki naudotojo sąsajos. Įsitikinkite, kad teisingas užsakymas gauna teisingą siuntą, laiko žymos rodomos numatytoje laiko juostoje, pasikartojantys įvykiai nesukuria pasikartojančių klientų pranešimų, o vežėjo sutrikimas nepakeičia anksčiau galiojusios būsenos klaidinančiu tekstu.

Kada labiau tinka kelių vežėjų sekimo API

Tiesioginė UPS integracija gali būti tinkama, kai jūsų veikla daugiausia siunčia per UPS ir jums reikia glaudžiai kontroliuoti vežėjo procesą. Ji tampa mažiau patogi, kai užsakymai gali būti perduodami keliems vežėjams, prekyvietėms, pašto operatoriams ar regioninėms pristatymo įmonėms. Tokiu atveju atskiri prisijungimo duomenys, atsakymų formatai, būsenų žodynai ir pakartotinių bandymų taisyklės gali padidinti priežiūros darbą.

Kelių vežėjų paslauga, tokia kaip 17TRACK Tracking API, gali būti alternatyvus integracijos modelis programoms, kurioms reikia kelių vežėjų sekimo. Kūrėjų dokumentaciją reikėtų tiesiogiai peržiūrėti dėl palaikomų vežėjų, užklausų formatų, autentifikavimo, naudojimo sąlygų ir galimų funkcijų. Tai nereiškia, kad ji automatiškai geresnė už tiesioginį UPS ryšį: tinkamas pasirinkimas priklauso nuo vežėjų derinio, duomenų reikalavimų, integracijos kontrolės ir komercinių bei atitikties apribojimų.

Jei reikia vartotojams skirto paieškos sprendimo, o ne kūrėjų integracijos, 17TRACK sekimo puslapis gali būti tinkamesnis nei API ryšio kūrimas. Internetinei parduotuvei, kuriai reikia firminių pranešimų po pirkimo, atskirai peržiūrėkite atitinkamą platformos integraciją, užuot papildę API darbu tai, ko parduotuvei nereikia.

Dažniausios diegimo klaidos

• Senų pavyzdžių naudojimas: kodo pavyzdyje gali būti nurodyta nebenaudojama versija, senas autentifikavimo metodas arba kita UPS paslauga.
• Paslapčių dėjimas į priekinės dalies kodą: viskas, kas siunčiama į naršyklę, turi būti laikoma patikrinama informacija.
• Manymas, kad tuščias rezultatas reiškia, jog siuntos nėra: prieš darydami verslo išvadą patikrinkite sekimo numerį, paskyros leidimus, aplinką ir atsakymo pranešimą.
• Vien tekstinis susiejimas: būsenų aprašymai gali skirtis. Naudokite dokumentuotus kodus ir išsaugokite nežinomas reikšmes peržiūrai.
• Paskyros ir naudojimo reikalavimų nepaisymas: techninis kodas gali būti teisingas, tačiau programa gali būti nesukonfigūruota prašomai paslaugai.
• Atnaujinimas be verslo taisyklės: nereikalinga apklausa gali padidinti išlaidas, apkrovą ir veiklos triukšmą, nepagerindama klientų patirties.

Praktinis paleidimo kontrolinis sąrašas

1. Patvirtinkite, kad programa naudoja dabartinę UPS dokumentaciją ir patvirtintą aplinką.
2. Įsitikinkite, kad prisijungimo duomenys saugomi serverio pusėje ir gali būti pakeisti.
3. Išbandykite autentifikavimo klaidą, vežėjo klaidas, netinkamą įvestį ir skirtąjį laiką.
4. Palyginkite normalizuotas būsenas su pradiniu atsakymu reprezentatyviose siuntose.
5. Nustatykite atnaujinimo politiką ir stebėkite užklausų skaičių.
6. Apibrėžkite atsakomybę už nenustatytus įvykius, vėluojančius atnaujinimus ir klientų eskalavimą.
7. Dokumentuokite integraciją, kad kitas kūrėjas galėtų saugiai atnaujinti prisijungimo duomenis, galinių taškų versijas ir būsenų susiejimus.

DUK

Ar norint naudoti Tracking API reikia UPS paskyros?

Dabartinius UPS registracijos ir prieigos reikalavimus turėtumėte peržiūrėti Developer Portal. API prieiga gali priklausyti nuo programos registracijos, prisijungimo duomenų, paskyros konfigūracijos ir konkrečios prašomos paslaugos. Nemanykite, kad viešo sekimo puslapio prisijungimas yra pakeičiamas kūrėjų API prieiga.

Ar UPS Tracking API yra nemokama?

Nemanykite, kad API prieigai netaikomos komercinės ar naudojimo sąlygos. UPS dabartinę paslaugų ir paskyrų informaciją skelbia oficialiais kanalais, o kai kurie reikalavimai gali priklausyti nuo produkto, paskyros ar sutarties. Prieš planuodami gamybinį biudžetą, tiesiogiai patvirtinkite taikomas sąlygas.

Ar galiu skambinti UPS API tiesiogiai iš JavaScript naršyklėje?

Naršyklės užklausa gali atskleisti programos prisijungimo duomenis ir sukelti dalijimosi tarp kilmių, saugumo bei naudojimo kontrolės problemų. Serverio pusės integracija paprastai yra saugesnis būdas saugoti paslaptis, gauti raktus, taikyti pakartotinių bandymų taisykles ir riboti prieigą prie siuntų duomenų.

Kaip dažnai mano programa turėtų prašyti sekimo atnaujinimų?

Atnaujinimo politiką nustatykite pagal dokumentuotas vežėjo ribas, siuntų skaičių, veiklos skubumą ir naudotojams reikalingą informacijos naujumą. Kai tinkama, talpykloje saugokite naujausius rezultatus, po laikinų klaidų naudokite laukimo intervalo didinimą ir nelaikykite pasikartojančios apklausos dokumentuoto įvykio ar pranešimo funkcijos pakaitalu.

Ar turėčiau naudoti tiesioginę UPS integraciją, ar kelių vežėjų API?

Tiesioginė UPS integracija gali tikti į UPS orientuotam procesui, kuriam reikia konkretaus vežėjo kontrolės. Kelių vežėjų API gali sumažinti integracijų skaičių, kai jūsų siuntos keliauja per kelis vežėjus. Prieš pasirinkdami palyginkite palaikomus vežėjus, autentifikavimą, duomenų laukus, patikimumo reikalavimus, naudojimo sąlygas ir diegimo pastangas.

Šaltiniai

• UPS Developer Portal — oficialus API katalogas, programų prieiga, autentifikavimas ir kūrėjų dokumentacija.
• UPS Technology Integration — oficiali informacija apie UPS technologijų integravimą su verslo sistemomis.
• 17TRACK Tracking API — oficialus kelių vežėjų sekimo produkto ir kūrėjų pradžios puslapis.
• 17TRACK API Documentation — oficiali API dokumentacija apie autentifikavimą, užklausas ir atsakymų tvarkymą.