8 geriausios UPS Tracking API integracijos praktikos (ir klaidos, kurių reikėtų vengti)

Patikima UPS siuntų sekimo API integracija nėra vien tik sekimo numerio rodymas – svarbiau sukurti patikimą siuntos būsenos valdymo procesą. Geriausios realizacijos tikrina įvestis, saugiai autentifikuoja, normalizuoja vežėjų atsakymus, apdoroja asinchroninius atnaujinimus ir aiškiai paaiškina klientams būsenos pokyčius. Ši praktika taip pat taikoma, kai įmonė derina UPS duomenis su kitų vežėjų duomenimis naudodama kelių vežėjų sekimo paslaugą, pvz., 17TRACK Tracking API.

Šis vadovas skirtas kūrėjams, el. prekybos operacijų komandoms ir produktų vadovams, atsakingiems už užsakymų matomumą. Jame daugiausia dėmesio skiriama praktiniams sprendimams, kurie turi įtakos duomenų kokybei, klientų patirčiai, veiklos sąnaudoms ir incidentų pašalinimui.

Ką turi atlikti UPS sekimo API integracija

Produkcijoje veikianti integracija paprastai turi keturias atsakomybes: priimti siuntos identifikatorių, užklausti arba gauti sekimo informaciją, išversti atsakymą į vidinį siuntos modelį ir pateikti darbuotojui arba gavėjui naujausią reikšmingą įvykį. UPS kūrėjų portalas yra autoritetingas šaltinis, kuriame reikia patikrinti šiuo metu prieinamas API, autentifikavimo reikalavimus, užklausų formatus, atsakymų laukus ir paskyros sąlygas.

Nekurkite sistemos remdamiesi vienu atsakymo pavyzdžiu. Siunta gali dar neturėti jokių įvykių, tą pačią dieną gali būti užregistruoti keli įvykiai, gali įvykti išimtis, pasikeisti numatomas pristatymo laikas arba galutinis pristatymo įvykis gali būti gautas po ankstesnio pranešimo. Jūsų duomenų modelis ir naudotojo sąsaja turi būti pritaikyti visoms šioms būsenoms.

1. Prieš programuodami patvirtinkite API produktą ir prieigos reikalavimus

UPS siūlo kelis kūrėjams skirtus išteklius, o tikslus įvedimo į sistemą procesas priklauso nuo API ir paskyros nustatymų. Prieš pradėdami diegimą, oficialioje UPS kūrėjų dokumentacijoje patvirtinkite pasirinktą sekimo produktą, sukurkite reikiamus programos prisijungimo duomenis ir nustatykite, kokie produkcinės aplinkos patvirtinimo arba paskyros veiksmai taikomi jūsų naudojimo atvejui.

Parenkite trumpą integracijos aprašą, kuriame būtų nurodytas API pavadinimas, aplinka, autentifikavimo metodas, būtini leidimai, jei dokumentuoti – užklausų limitai, palaikomi identifikatoriai ir laukai, kurių iš tikrųjų reikia jūsų programai. Taip išvengsite dažnos klaidos: kūrimo pagal pavyzdį ar senesnį integracijos modelį ir vėlyvo išsiaiškinimo, kad produkcinė prieiga arba būtinas laukas gaunamas kitu būdu.

Klaida, kurios reikia vengti: Sėkmingą užklausą smėlio dėžėje laikyti įrodymu, kad produkcinė aplinka paruošta. Testavimo ir produkcinius prisijungimo duomenis, galinių taškų konfigūraciją bei operacinį patvirtinimą atskirkite tiek dokumentacijoje, tiek diegimo nustatymuose.

2. Apsaugokite prisijungimo duomenis ir izoliuokite aplinkas

UPS prisijungimo duomenis laikykite serverio pusėje veikiančioje programoje arba apsaugotoje integracijos tarnyboje. Nedėkite paslapčių į naršyklės kodą, mobiliąsias programas, viešąsias saugyklas, ekrano kopijas ar kliento pusėje naudojamus sekimo URL. Jei įmanoma, saugokite paslaptis valdomoje paslapčių saugykloje, apribokite prieigą pagal vaidmenis ir keiskite jas pagal savo organizacijos saugumo politiką.

Naudokite atskirą kūrimo, testavimo ir produkcinės aplinkos konfigūraciją. Saugus diegimas turi apsunkinti testavimo srauto siuntimą į veikiančią darbo eigą arba produkcinio prisijungimo duomens naudojimą kūrėjo kompiuteryje. Registruokite programos tapatybę ir užklausos rezultatą, tačiau iš žurnalų pašalinkite prieigos žetonus, kliento paslaptis ir bet kokią neskelbtiną siuntos informaciją.

Autentifikavimo klaidos turi būti atskiriamos nuo vežėjo duomenų klaidų. 401 arba 403 atsakymas paprastai reikalauja peržiūrėti prisijungimo duomenis, leidimus arba konfigūraciją; jo nereikėtų neribotai kartoti taip, lyg tai būtų laikina tinklo problema.

3. Patikrinkite ir normalizuokite sekimo numerius

Tikrinkite įvestį savo sistemos ribose, tačiau nesukurkite pernelyg siauros taisyklės, kuri atmestų galiojantį identifikatorių. Sekimo numeris turi būti laikomas eilute, o ne sveikuoju skaičiumi: pradiniai nuliai, ilgos reikšmės ir formatavimo simboliai gali būti reikšmingi naudotojui, net jei prieš siunčiant API užklausą jie pašalinami.

Praktinis tikrinimo sluoksnis gali pašalinti atsitiktinius tarpus, išsaugoti pradinę reikšmę rodymui, sukurti normalizuotą paieškos reikšmę atitikimui ir atmesti akivaizdžiai tuščią arba netinkamai suformuotą įvestį. Tikslūs priimtini formatai turi būti nustatyti pagal UPS dokumentaciją ir jūsų verslo reikalavimus, o ne pagal prielaidą, kad kiekviena siunta naudoja tą patį šabloną.

Kartu su identifikatoriumi saugokite vežėjo kontekstą. Vien iš sekimo numerį primenančios reikšmės nepakanka nustatyti, kuriam vežėjui arba galiniam taškui ją reikia perduoti. Jei jūsų programa palaiko kelis vežėjus, vežėjo lauką, šaltinio lauką ir vidinį siuntos ID laikykite atskirai nuo klientui rodomo sekimo numerio.

4. Kurkite vidinį būsenos modelį, o ne kopijuokite vežėjo tekstą

Vežėjų atsakymuose dažnai pateikiami kodai, aprašymai, laiko žymos, vietos, įverčiai ir įvykių lygmens informacija. Jūsų programa turėtų išsaugoti neapdorotą atsakymą trikčių šalinimui, o naudingą verslo reikšmę susieti su stabiliu vidiniu modeliu.

Paprastą modelį gali sudaryti label_created, in_transit, out_for_delivery, delivered, exception ir unknown. Tikslus sąrašas yra produkto sprendimas, o ne UPS garantija. Kartu su normalizuota būsena išsaugokite pradinį vežėjo kodą ir aprašymą, kad pagalbos darbuotojai galėtų ištirti neaiškius atvejus.

Neišvadaukite apie pristatymą pagal neaiškią žinutę arba praėjusį laiką. Pažymėdami siuntą kaip pristatytą, naudokite vežėjo dokumentuotą įvykį arba pristatymo indikaciją. Taip pat išimtis neturėtų būti automatiškai laikoma prarastu paketu. Gali reikėti tyrimo, kliento veiksmo arba tiesiog dar vieno nuskaitymo.

5. Sekimą vertinkite kaip įvykiais pagrįstą duomenų problemą

Viena užklausa iškart po etiketės sukūrimo gali grąžinti ribotą informaciją. Sekimo duomenys gali keistis vežėjui užregistravus naujus nuskaitymus, todėl naudingai integracijai reikalinga atnaujinimo strategija. Atsižvelgiant į pasirinktos API ir jūsų paskyros dokumentuotas galimybes, tai gali būti suplanuotos apklausos, įvykių pranešimai arba jų derinys.

Atnaujinimai turi būti idempotentiniai. Jei tas pats įvykis gaunamas du kartus, sistema turi atnaujinti vieną įrašo įvykį, o ne kurti pasikartojančius pranešimus. Naudingas įvykio raktas gali būti sudarytas iš vežėjo, siuntos identifikatoriaus, įvykio kodo, įvykio laiko žymos ir kito stabilaus lauko, jei jis prieinamas. Jei nėra patikimo unikalaus rakto, išsaugokite neapdorotą atsakymą ir naudokite kruopščiai patikrintą dublikatų šalinimo taisyklę.

Skirtingoms siuntų būsenoms taikykite skirtingą atnaujinimo elgseną. Siuntai, kuri dar negavo pirmojo nuskaitymo, gali reikėti kitokio grafiko nei paketui, kuris jau išgabentas pristatyti. Po pristatymo arba galutinės išimties sumažinkite arba sustabdykite įprastas apklausas, nebent jūsų pagalbos procesui reikalingi tolesni patikrinimai.

6. Kurkite sistemą atsižvelgdami į pakartotinius bandymus, dažnio ribojimus ir dalinius sutrikimus

Išorinės API užklausos gali nepavykti dėl priežasčių, nesusijusių su siunta: dėl skirtųjų laikų, DNS klaidų, laikinų paslaugos sutrikimų, netinkamų prisijungimo duomenų ir dažnio ribojimo. Prieš nuspręsdama, ką daryti toliau, jūsų integracija turi suklasifikuoti klaidas.

• Laikinas tinklo ir serverio klaidas kartokite taikydami eksponentinį laukimą ir nustatę maksimalų bandymų skaičių.
• Pakartotinai nekartokite netinkamų užklausų, autentifikavimo klaidų ar nepalaikomų identifikatorių.
• Naudokite eilę arba užduočių vykdytoją, kai sekimo atnaujinimai neturi blokuoti atsiskaitymo ar kliento puslapio.
• Registruokite kito bandymo laiką, klaidos kategoriją ir paskutinį sėkmingą atnaujinimą.
• Rodykite aiškią atsarginę žinutę, o ne pateikite pasenusius duomenis kaip aktualius.

Laikykitės konkrečiai naudojamai UPS API paskelbtų limitų ir veiklos rekomendacijų. Jei jūsų programa seka didelį katalogą, neatnaujinkite kiekvienos siuntos tuo pačiu intervalu. Eilė, podėlis ir būseną atsižvelgiantis grafikas gali sumažinti nereikalingų užklausų skaičių, neslepiant svarbių pokyčių.

7. Atskirkite duomenų aktualumą nuo klientų pranešimų

Naujausias vežėjo atsakymas ir pirkėjui rodoma žinutė yra susiję, bet ne tapatūs dalykai. Neapdorotas įvykis gali būti naudingas operacijų komandai, tačiau klaidinantis klientui. Sukurkite pateikimo sluoksnį, kuris normalizuotus įvykius paverčia paprasta kalba, kartu išsaugodamas prieigą prie pradinės vežėjo informacijos.

Kiekviena klientui rodoma būsena, kai praktiška, turėtų turėti laiko žymą arba aktualumo indikatorių. Jei nuo paskutinio sėkmingo atnaujinimo praėjo daug laiko, nurodykite, kad naujausia informacija dar neprieinama, o ne sudarykite įspūdį, kad siunta nepajudėjo. Laiko juostos turi būti tvarkomos nuosekliai, o sąsaja turi atskirti įvykio vietą nuo gavėjo vietos.

Pranešimų taisyklėms taip pat reikia dublikatų šalinimo ir tylos laikotarpio logikos. Klientas neturėtų gauti pasikartojančių el. laiškų vien todėl, kad tas pats nuskaitymas buvo grąžintas per du atnaujinimus. Siųskite reikšmingus atnaujinimus apie tokius įvykius kaip išimtis, siuntos išgabenimas pristatyti arba patvirtintas pristatymas, atsižvelgdami į jūsų verslui taikomus komunikacijos pageidavimus ir teisinius reikalavimus.

8. Testuokite veiklos kraštutinius atvejus, ne tik sėkmingą scenarijų

Prieš paleisdami sistemą išbandykite ne tik sėkmingą atsakymą apie vežamą siuntą. Parenkite testinius duomenis arba kontroliuojamus atvejus nežinomam sekimo numeriui, siuntai be įvykių, pasikartojantiems įvykiams, ne eilės tvarka pateiktoms laiko žymoms, išimčiai, pasikeitusiam pristatymo įverčiui, pristatytai siuntai, API skirtajam laikui, dažnio ribojimo atsakymui ir pasibaigusiems prisijungimo duomenims.

Išbandykite visą kelią nuo API atsakymo iki duomenų bazės, kliento puslapio, pagalbos skydelio ir pranešimų tarnybos. Įsitikinkite, kad netinkamai suformuotas atsakymas negali perrašyti geros būsenos, kad vėluojantis įvykis negrąžina siuntos į ankstesnę būseną be aiškios taisyklės ir kad vežėjo sutrikimas sukuria matomą veiklos įspėjimą.

Po paleidimo stebėkite užklausų sėkmės rodiklį, delsą, autentifikavimo klaidas, analizavimo klaidas, pasenusias siuntas, pasikartojančius pranešimus ir įrašų, kurių normalizuota būsena nežinoma, procentą. Šie rodikliai padeda atskirti vežėjo pusės incidentą nuo jūsų integracijos regresijos.

Dažnos UPS sekimo API klaidos trumpai

Klaida	Veiklos pasekmė	Geresnė praktika
Prisijungimo duomenų įrašymas į kodą	Prisijungimo duomenų nutekėjimas ir sudėtingas jų keitimas	Naudokite apsaugotą serverio pusės konfigūraciją ir paslapčių valdymą
Sekimo laikymas viena užklausa	Pasenęs arba neišsamus siuntos matomumas	Naudokite būseną atsižvelgiantį atnaujinimą ir įvykių išsaugojimą
Tik rodomo teksto analizavimas	Trapi logika pasikeitus formuluotei	Susiekite dokumentuotus kodus ir išsaugokite neapdorotus atsakymus
Kiekvienos klaidos kartojimas	Švaistomos užklausos ir lėtesnis atkūrimas	Klasifikuokite klaidas ir taikykite ribotą laukimo laiką
Tik sėkmės atvejų testavimas	Produkcijos klaidos tampa klientams matomais incidentais	Testuokite tuščias, vėluojančias, pasikartojančias, netinkamas ir išimčių būsenas

Kada kelių vežėjų sekimo API gali būti tinkamesnė

Tiesioginė UPS integracija tinka, kai UPS yra pagrindinis vežėjas, o jūsų komanda nori tiesiogiai valdyti darbo eigą. Kelių vežėjų sluoksnis gali būti praktiškesnis, kai įmonė siunčia užsakymus per kelis vežėjus, veikia keliose šalyse arba nori vienos normalizuotos sekimo sąsajos užsakymų valdymo ar klientų patirties sistemai.

Oficialioje 17TRACK medžiagoje nurodoma, kad jos Tracking API yra kūrėjams skirta integracija siuntoms sekti per skirtingus vežėjus. Jei ją vertinate, palyginkite dokumentuotą vežėjų palaikymą, atsakymo schemą, autentifikavimą, žiniatinklio kablių arba apklausų galimybes, naudojimo sąlygas ir pagalbos procesą su konkrečiais savo reikalavimais. Nemanykite, kad kelių vežėjų paslauga pašalina poreikį tikrinti duomenis, kartoti užklausas, stebėti sistemą ar turėti aiškų vidinį būsenos modelį.

Praktinis paleidimo kontrolinis sąrašas

1. Oficialioje dokumentacijoje patvirtinkite dabartinį UPS API produktą, prieigos procesą, aplinkas ir autentifikavimo metodą.
2. Prieš rašydami atsakymo analizatorių apibrėžkite vidinį siuntos ir įvykio modelį.
3. Apsaugokite prisijungimo duomenis ir atskirkite produkcinę konfigūraciją nuo testavimo.
4. Tikrinkite identifikatorius, išsaugodami pradinę kliento įvestą reikšmę.
5. Įgyvendinkite ribotus pakartotinius bandymus, podėliavimą, dublikatų šalinimą ir būseną atsižvelgiantį atnaujinimą.
6. Klientams skirtas žinutes rašykite atskirai nuo neapdorotų vežėjo įvykių duomenų.
7. Testuokite išimtis, tuščius rezultatus, vėluojančius nuskaitymus, pasikartojančius įvykius ir paslaugos sutrikimus.
8. Po diegimo stebėkite aktualumą ir analizavimo kokybę, o pasikeitus vežėjo dokumentacijai peržiūrėkite integraciją.

DUK

Ar galiu kviesti UPS sekimo API tiesiogiai iš naršyklės?

Naršyklės užklausa gali atskleisti prisijungimo duomenis ir sukelti kryžminės kilmės arba prieigos kontrolės problemų. Serverio pusės integracija arba apsaugota vidinės sistemos paslauga paprastai yra saugesnė. Prieš diegdami patvirtinkite leidžiamą architektūrą ir autentifikavimo eigą dabartinėje UPS kūrėjų dokumentacijoje.

Kodėl sekimo numeris kartais negrąžina naudingo įvykio?

Siunta dar gali neturėti užregistruoto nuskaitymo, identifikatorius gali būti neteisingas, užklausoje gali būti naudojamas netinkamas vežėjo kontekstas arba atsakymas gali rodyti laikiną paslaugos problemą. Išsaugokite rezultatą ir jo laiko žymą, atskirkite tuščią rezultatą nuo klaidos ir kartokite užklausą pagal kontroliuojamą grafiką.

Ar kiekvienas sekimo atnaujinimas turėtų sukelti el. laišką?

Ne. Pasikartojantys nuskaitymai gali sukelti pranešimų nuovargį. Naudokite dublikatų šalinimą ir apibrėžkite, kurie normalizuoti įvykiai svarbūs gavėjui, pavyzdžiui, reikšminga išimtis, siuntos išgabenimas pristatyti arba patvirtintas pristatymas.

Kaip programa turėtų apdoroti nežinomą UPS būseną?

Išsaugokite pradinį kodą ir aprašymą, susiekite juos su aiškia nežinoma arba peržiūros būsena ir nebandykite spėti, kad tai reiškia pristatymą arba praradimą. Įdiekite stebėseną, kad naujas arba nesusietas būsenas būtų galima saugiai peržiūrėti ir įtraukti.

Ar tiesioginė UPS integracija geresnė už kelių vežėjų API?

Nė viena nėra visuotinai geresnė. Tiesioginė integracija gali tikti į UPS orientuotai darbo eigai, kuriai reikia glaudžios kontrolės. Kelių vežėjų API gali sumažinti konkretiems vežėjams skirtų integracijų skaičių, kai siuntų matomumas apima kelis teikėjus. Palyginkite dokumentuotą aprėptį, duomenų laukus, veiklos kontrolę, kainą ir pagalbos reikalavimus pagal realų savo siuntų derinį.

Šaltiniai

• UPS Developer Portal — oficialūs kūrėjams skirti ištekliai ir API dokumentacija.
• UPS Tracking — oficiali UPS sekimo paslauga.
• 17TRACK API — oficiali informacija apie kelių vežėjų sekimo API integracijos produktą.
• 17TRACK API Documentation — oficiali API dokumentacija ir integracijos žinynas.