UPS sekimo API dokumentacija: 7 pagrindinės funkcijos, kurias kūrėjai turėtų žinoti

UPS siuntų sekimo API dokumentacija yra naudingiausia tada, kai padeda kūrėjui nuo sekimo numerio pereiti prie patikimos siuntos būsenos pateikimo patirties. Septynios sritys, kurias reikia išnagrinėti, yra autentifikavimas, sekimo užklausos, atsakymų schemos, įvykių istorija, klaidų tvarkymas, veikimo ribojimai ir testavimas. UPS teikia savo kūrėjų platformą tiesioginėms UPS integracijoms, o kelių vežėjų paslauga, tokia kaip 17TRACK Tracking API, gali būti tinkamesnė, kai viena integracija turi palaikyti UPS ir kitus vežėjus.

Tinkamas įgyvendinimas priklauso nuo kuriamos sistemos. Mažmenininkui gali reikėti pristatymo atnaujinimų užsakymo puslapyje, sandėlio komandai – įspėjimų apie išimtis, o įmonės platformai – normalizuotų kelių vežėjų sekimo duomenų. Dokumentacijos skaitymas atsižvelgiant į šiuos naudojimo scenarijus padeda išvengti dažnos klaidos: nelaikyti sėkmingo API atsakymo tuo pačiu, kas yra visavertis siuntos matomumo sprendimas.

Į ką turėtų padėti atsakyti UPS siuntų sekimo API dokumentacija

Prieš rašydami kodą, išsiaiškinkite keturis klausimus:

• Ar integruojate tik UPS, ar sistema seks kelių vežėjų siuntas?
• Ar jums reikia dabartinės siuntos būsenos, visos skenavimų istorijos, ar abiejų dalykų?
• Ar jūsų programa prašys atnaujinimų pagal poreikį, gaus pranešimus, ar naudos abu būdus?
• Ką klientai ir vidinės komandos turėtų matyti, kai siunta vėluoja, pristatyta, grąžinta arba dar nerasta?

UPS dokumentacija yra pagrindinis šaltinis, kuriame pateikiami dabartiniai kredencialai, palaikomos operacijos, užklausų reikalavimai, atsakymų laukai ir komercinės prieigos sąlygos. Ši informacija gali keistis priklausomai nuo API produkto, paskyros susitarimo ar kūrėjų platformos versijos, todėl gamybinis kodas turėtų remtis dabartiniu UPS kūrėjų portalu, o ne senu kodo pavyzdžiu.

7 pagrindinės funkcijos, kurias kūrėjai turėtų suprasti

1. Autentifikavimas ir prieiga prie programos

Autentifikavimas yra pirmoji praktinė funkcija, nes nuo jos priklauso, kaip programa įrodo savo tapatybę ir gauna leidimą iškviesti API. UPS kūrėjų dokumentacijoje pateikiamas dabartinis programos registravimo, kredencialų kūrimo, prieigos užklausos ir žetonų valdymo procesas. Dokumentacijoje aprašoma OAuth pagrįsta prieiga prie UPS API, tačiau prieš įgyvendindami kūrėjai turėtų tiesioginiame portale patikrinti dabartinį suteikimo srautą, apimtis, žetono galiojimo laiką ir aplinkos reikalavimus.

Kredencialus laikykite serverio pusėje. Jie neturėtų būti įterpti į naršyklės JavaScript, mobiliųjų programų versijas, viešas saugyklas ar klientui matomą siuntos sekimo puslapio kodą. Saugesnėje architektūroje tarp klientui skirtos programos ir UPS įterpiama vidinės sistemos paslauga. Ši paslauga gali saugiai autentifikuotis, užtikrinti užklausų ribojimus, registruoti techninius rezultatus neatskleisdama paslapčių ir grąžinti tik tuos siuntos duomenis, kurių reikia priekinei sąsajai.

Taip pat atskirkite kūrimo ir gamybos kredencialus, jei UPS platforma palaiko atskiras aplinkas. Diegimo kontroliniame sąraše turėtų būti paslapčių saugojimas, keitimas, prieigos nuosavybė, pasibaigusio žetono tvarkymas ir įspėjimas, kai autentifikavimo klaidų pradeda daugėti.

2. Užklausos pagal sekimo numerį ir vežėjo kontekstas

Sekimo integracijai reikia nuspėjamo būdo pateikti sekimo identifikatorių ir paprašyti siuntos informacijos. Svarbūs klausimai susiję ne tik su galinio taško adresu. Reikia žinoti, kokį sekimo numerio formatą priima sistema, ar užklausa palaiko vieną, ar kelis numerius, kaip identifikuojamas vežėjas ir kaip API atsako, kai numeris neišsamus arba dar neatpažintas.

Nelaikykite savaime suprantamu dalyku, kad kiekviena į sekimo numerį panaši eilutė priklauso UPS. Jei jūsų programa gauna etiketes iš kelių siuntimo sistemų, kai tik žinomas vežėjas, saugokite jį atskirame lauke. Vežėjui pritaikytas maršrutizavimas mažina klaidingų atitikmenų skaičių ir palengvina trikčių šalinimą. Be to, tai sukuria aiškų pagrindą būsimai plėtrai, jei jūsų verslas pridės kitą vežėją.

Prieš siųsdami užklausą patikrinkite įvestį, tačiau venkite pernelyg griežto tikrinimo, dėl kurio teisėtas identifikatorius atmetamas, nes pasikeitė jo formatas arba etiketė buvo sukurta neseniai. API atsakymas išlieka autoritetingu patikrinimu. Saugokite pradinę reikšmę, paieškai naudojamą normalizuotą reikšmę, vežėją, užsakymo nuorodą ir paskutinės sėkmingos užklausos laiką.

3. Struktūrizuota atsakymo schema

Naudingoje UPS siuntų sekimo API dokumentacijoje paaiškinama, kaip organizuojami siuntos duomenys ir kurie laukai yra pasirenkami. Kūrėjai turėtų išnagrinėti siuntos tapatybės, dabartinės būsenos, būsenos aprašo, skenavimų laiko žymų, vietų, pristatymo įverčių, paslaugos informacijos ir paketo lygmens informacijos atsakymo modelį. Neužpildyto lauko nebuvimas nebūtinai reiškia tą patį, ką tuščią reikšmę turintis laukas, ir nė vienas iš jų neturėtų būti automatiškai laikomas nepavykusia siunta.

Kurkite normalizuotą vidinį modelį, o ne susiekite visą programą tiesiogiai su konkretaus teikėjo laukų pavadinimais. Pavyzdžiui, jūsų duomenų bazėje gali būti saugomas siuntos identifikatorius, vežėjas, dabartinė būsena, paskutinio įvykio laikas, numatomas pristatymo laikas, pristatymo laikas, išimties kodas ir neapdorotas teikėjo mokinys. Normalizuoti laukai palaiko ataskaitas ir naudotojo sąsajas, o neapdorotas mokinys padeda atlikti auditus ir ateityje keisti susiejimą.

Išsaugokite laiko žymas su jų poslinkio arba laiko juostos informacija, kai ji pateikiama. Vienoje vietoje atliktą skenavimą rodant taip, lyg jis būtų įvykęs žiūrovo vietos laiku, galima sukurti klaidinantį pristatymo pasakojimą. Taip pat nekeiskite išsamios vežėjo būsenos į paprastesnę etiketę, kol verslo taisyklė nėra dokumentuota.

4. Skenavimų istorija ir būsenos interpretavimas

UPS tracking vertė dažnai slypi įvykių sekoje, o ne vienoje dabartinėje etiketėje. Paketas gali pereiti etiketės sukūrimo, paėmimo, gabenimo, atvykimo skenavimo, išimties, pristatymo ir pristatymo užbaigimo etapus. Naudinga integracija saugo įvykius eilės tvarka ir, jei įmanoma, išlaiko jų pradinius aprašus.

Būsenų susiejimui reikia redakcinio ir operacinio vertinimo. „Gabenama“ gali apimti kelis skirtingus etapus, o „išimtis“ gali reikalauti konkretesnio paaiškinimo nei vien būsenos pavadinimas. Jūsų programa turėtų bent atskirti įprastą judėjimą, pristatymo veiklą, pristatytą siuntą, išimtį, grąžintą siuntą ir būseną, kurios dar negalima nustatyti. Tikslus susiejimas turi atitikti UPS dokumentuotus laukus ir kodus, o ne būti grindžiamas vien anglų kalbos aprašais.

Klientams skirtuose puslapiuose rodykite naujausią reikšmingą įvykį, jo laiką ir trumpą paaiškinimą. Vidinėms operacijoms išsaugokite visą įvykių istoriją ir pradinę vežėjo formuluotę. Tai leidžia pagalbos darbuotojams ištirti skundą neprašant kliento pakartoti informacijos, kurią sistema jau gavo.

5. Pristatymo įverčiai ir išimčių tvarkymas

Kūrėjai dažnai daugiausia dėmesio skiria sėkmingam scenarijui, tačiau pristatymo įverčiai ir išimtys lemia, ar sekimo duomenys praktiškai naudingi. Siunta gali neturėti įverčio, įvertis gali pasikeisti arba išimtis gali laikinai sutrikdyti įprastą judėjimą. Reikia patikrinti, kokie laukai ir sąlygos dokumentacijoje naudojami šiems atvejams nurodyti.

Niekada nepateikite įverčio kaip garantijos, nebent atitinkamos UPS paslaugos sąlygos aiškiai leidžia taip jį interpretuoti. Naudotojo sąsajoje įvertį pažymėkite kaip įvertį ir datą arba laiko intervalą rodykite tiksliai taip, kaip leidžia duomenys. Jei API nepateikia įverčio, rodykite neutralų pranešimą, pavyzdžiui, „Šiuo metu pristatymo įvertis nepasiekiamas“, o ne sukurkite jį pagal bendrą gabenimo laiko taisyklę.

Išimčių procesai turėtų būti aiškiai apibrėžti. Nuspręskite, ar nauja išimtis suaktyvina el. laišką, pagalbos tarnybos užduotį, užsakymų valdymo veiksmą ar tik būsenos pakeitimą. Įdiekite pasikartojančių įvykių pašalinimą, kad pakartotinis tikrinimas nesiųstų to paties įspėjimo kelis kartus. Praktinė taisyklė – prieš kuriant naują pranešimą palyginti įvykio identifikatorių arba stabilų įvykio laiko, būsenos ir aprašo derinį.

6. Klaidos, pakartotiniai bandymai ir veikimo ribojimai

API dokumentaciją reikia skaityti kaip veikimo sutartį, o ne tik kaip sėkmingų pavyzdžių sąrašą. Kūrėjai turi suprasti autentifikavimo klaidas, netinkamas užklausas, nežinomus sekimo numerius, laikinuosius paslaugos sutrikimus, skirtuosius laikus ir dažnio ribojimo atsakymus. Į kiekvieną kategoriją reikia reaguoti skirtingai.

• Autentifikavimo klaidos turėtų sukurti įspėjimą inžinerijos komandai ir neturėtų būti kartojamos neribotai.
• Patikros klaidos turėtų būti registruojamos pateikiant pakankamai konteksto, kad užklausa būtų ištaisyta.
• Laikinuosius sutrikimus galima bandyti įveikti naudojant eksponentinį laukimą ir nustatant didžiausią bandymų skaičių.
• Nežinomus arba naujai sukurtus sekimo numerius galima patikrinti vėliau, tačiau jų nereikėtų laikyti prarastais.
• Gavus dažnio ribojimo atsakymus, reikia retinti tikrinimo grafiką ir laikytis dabartinėje UPS dokumentacijoje nurodytų ribų.

Naudokite skirtuosius laikus, grandinės pertraukiklius, užklausų identifikatorius ir struktūrizuotus žurnalus. Saugokite teikėjo atsakymo būseną, vidinį siuntos ID ir laiko žymą, tačiau neįtraukite prieigos žetonų ir nebūtinos asmeninės informacijos. Jei dokumentacijoje nurodomos atsakymo antraštės arba pakartotinių bandymų gairės, įtraukite šias instrukcijas, o ne taikykite bendrą politiką.

7. Testavimas, stebėsena ir parengtis gamybai

Sekimo API integraciją reikia testuoti naudojant daugiau nei vieną sėkmingą sekimo numerį. Sukurkite testavimo atvejus naujai sugeneruotai etiketei, siuntai su keliais skenavimais, išimčiai, pristatytam paketui, nežinomam numeriui, pasibaigusiam kredencialui, netinkamai užklausai, skirtajam laikui ir pasikartojančiam įvykiui. Tikslūs testavimo duomenys ir smėlio dėžės elgsena turi būti patvirtinti UPS kūrėjų aplinkoje, nes tikri siuntų duomenys ir testavimo aplinkos ne visada veikia vienodai.

Stebėkite tiek techninius, tiek verslo rezultatus. Techniniai rodikliai apima užklausų apimtį, delsą, skirtųjų laikų dažnį, autentifikavimo klaidas, teikėjo klaidų dažnį ir pakartotinių bandymų skaičių. Verslo rodikliai apima siuntų, turinčių naujausią įvykį, procentą, seniausios neatnaujintos siuntos amžių ir užsakymų, kuriems turėjo įtakos išimtis, skaičių. Paslauga gali turėti mažą HTTP klaidų dažnį, tačiau vis tiek teikti pasenusią sekimo informaciją, jei tikrinimas arba įvykių apdorojimas sustojo.

Prieš paleidimą dokumentuokite, kaip sustabdyti tikrinimą, pakeisti kredencialus, pakartoti nepavykusius atsakymus, pataisyti neteisingą būsenos susiejimą ir susisiekti su UPS pagalba. Jei tai reikalinga tyrimui, kontroliuojamą laikotarpį saugokite teikėjo mokinį ir kartu su atsakingu asmeniu peržiūrėkite privatumo bei duomenų saugojimo reikalavimus.

Tiesioginė UPS integracija ar kelių vežėjų API?

Tiesioginė UPS integracija yra pagrįstas pasirinkimas, kai UPS yra vienintelis numatytas vežėjas, komanda nori valdyti konkrečiam vežėjui pritaikytą modelį ir yra prieinama reikiama UPS API prieiga. Ji gali gerai atitikti UPS terminologiją ir veiklos procesus.

Kelių vežėjų API gali būti tinkamesnis architektūrinis pasirinkimas, kai ta pati programa turi sekti UPS, pašto operatorių ir kitų logistikos teikėjų siuntas. Prieš priimant techninį sprendimą reikėtų peržiūrėti 17TRACK API documentation, kad būtų įvertintas dabartinis autentifikavimo modelis, palaikomos operacijos, atsakymo struktūra, žiniatinklio kabliukų elgsena, naudojimo sąlygos ir vežėjų aprėptis. Šio scenarijaus vertė nėra ta, kad dokumentacijos nebereikia; ji ta, kad kūrėjų komanda gali įvertinti vieną integracijos sluoksnį, palygindama jį su kelių konkrečiam vežėjui skirtų jungčių priežiūros kaina.

Palyginkite pasirinkimus naudodami koncepcijos patikrinimą. Kiekvienam variantui naudokite tą patį siuntos gyvavimo ciklą ir įvertinkite įgyvendinimo pastangas, laukų išsamumą, įvykių naujumą, pakartotinių bandymų elgseną, žiniatinklio kabliukų arba tikrinimo reikalavimus, stebimumą ir darbą, kurio reikia vežėjui pakeitus atsakymą. Nesirinkite teikėjo vien todėl, kad pavyzdinė užklausa yra trumpa. Tinkamesnis yra tas variantas, kuris padeda pasiekti veiklos rezultatą, kurį turi pateikti jūsų programa.

Praktinė įgyvendinimo seka

1. Apibrėžkite naudotojų ir veiklos rezultatus, pavyzdžiui, klientų sekimo puslapį arba išimčių eilę.
2. Patvirtinkite, ar aprėptis yra tik UPS, ar keli vežėjai.
3. Perskaitykite dabartinę oficialią autentifikavimo, sekimo užklausų, atsakymo laukų, klaidų, ribų ir testavimo dokumentaciją.
4. Sukurkite nuo teikėjo nepriklausomą siuntos ir įvykio modelį.
5. Įgyvendinkite saugų serverio pusės autentifikavimą ir įvesties tikrinimą.
6. Neapdorotus atsakymus ir normalizuotus laukus saugokite atskirai.
7. Pridėkite tikrinimą arba įvykių priėmimą su pasikartojančių įvykių pašalinimu ir laukimo mechanizmu.
8. Ištestuokite įprastas, vėluojančias, išskirtines, nežinomas ir nepavykusias užklausas.
9. Paleiskite sistemą stebėdami duomenų naujumą, klaidas ir pasenusias siuntas.

Ši seka neleidžia API iškvietimui tapti visu sprendimo pagrindu. Sekimas yra nuolatinis duomenų procesas: programa turi gauti įvykius, atidžiai juos interpretuoti, aiškiai pateikti ir atsigauti, kai teikėjas arba tinklas nepasiekiamas.

DUK

Ką pirmiausia turėčiau perskaityti UPS siuntų sekimo API dokumentacijoje?

Pradėkite nuo autentifikavimo ir sekimo operacijos. Tada peržiūrėkite užklausų reikalavimus, atsakymo laukus, klaidų elgseną, naudojimo ribas ir testavimo instrukcijas. Šie skyriai parodo, ar API atitinka jūsų saugumo modelį ir duomenų reikalavimus, dar prieš investuojant į visavertę integraciją.

Ar galiu naudoti UPS siuntų sekimo API klientams skirtame sekimo puslapyje?

Taip, API gali teikti duomenis klientams skirtam puslapiui, tačiau puslapis turėtų būti pateikiamas per jūsų vidinės sistemos paslaugą, o ne atskleidžiant API kredencialus naršyklėje. Suprojektuokite puslapį taip, kad būtų atskirta dabartinė būsena, skenavimų istorija, įverčiai ir išimtys, ir venkite pateikti įverčius kaip garantijas.

Ar sekimo numeriai turėtų būti tikrinami nuolat?

Nebūtinai. Tikrinimo dažnis turėtų atspindėti siuntos etapą, verslo skubumą, dokumentuotas naudojimo ribas ir tai, ar prieinama įvykiais pagrįsta parinktis. Nepasikeitusioms siuntoms naudokite laukimo mechanizmą, o po pristatymo arba galutinės grąžinimo būsenos tikrinimą sustabdykite arba suretinkite.

Kuo skiriasi nežinomas sekimo numeris ir prarastas paketas?

Nežinomas sekimo numeris reiškia, kad dabartinė užklausa negrąžino atpažintos siuntos rezultato. Numeris gali būti sukurtas neseniai, įvestas neteisingai, nukreiptas netinkamam vežėjui arba laikinai nepasiekiamas. Jo nereikėtų žymėti kaip prarasto be atskiro verslo proceso ir patvirtinančių įrodymų.

Kada verta svarstyti kelių vežėjų siuntų sekimo API?

Ją verta įvertinti, kai jūsų programa turi palaikyti kelis vežėjus arba kai atskiro autentifikavimo, schemų, būsenų susiejimų ir klaidų politikos priežiūra sukeltų daug veiklos darbų. Palyginkite teikėjus naudodami tikrus siuntų scenarijus ir patikrinkite dabartinę vežėjų bei funkcijų informaciją jų oficialioje dokumentacijoje.

Šaltiniai

• UPS Developer Portal — oficialus UPS API produktų, programos nustatymo, autentifikavimo ir kūrėjų išteklių prieigos taškas.
• UPS Tracking — oficiali UPS sekimo paslauga ir terminologijos šaltinis.
• 17TRACK Tracking API — oficialus produkto puslapis, skirtas kelių vežėjų sekimo integracijai įvertinti.
• 17TRACK API Documentation — oficiali kūrėjų dokumentacija apie dabartines API detales ir integracijos reikalavimus.