UPS siuntų sekimo API: pradedančiųjų vadovas, kaip pradėti

UPS siuntų sekimo API leidžia įmonei gauti siuntos būseną ir rodyti pristatymo atnaujinimus savo svetainėje, programėlėje, užsakymų valdymo sistemoje ar klientų aptarnavimo įrankiuose. Pradėti paprastai reikia sukuriant UPS kūrėjo paskyrą, užregistruojant programą, gavus autentifikavimo duomenis, išsiuntus sekimo užklausą ir išvertus atsakymą į klientams naudingus įvykius. Šiame vadove procesas paaiškinamas darant prielaidą, kad neturite ankstesnės darbo su API patirties.

Pavyzdžiuose daugiausia dėmesio skiriama sekimui, o ne etikečių kūrimui, tarifų skaičiavimui ar adreso tikrinimui. UPS turi atskirus API produktus ir dokumentaciją, todėl prieš kurdami gamybos procesus įsitikinkite, kad jūsų užregistruota programa turi prieigą prie reikiamos sekimo funkcijos.

Ką daro UPS Tracking API

API yra struktūrizuotas būdas vienai programinei sistemai prašyti informacijos iš kitos. Sekimo procese jūsų sistema siunčia siuntos identifikatorių, pavyzdžiui, sekimo numerį, vežėjui arba sekimo platformai. Paslauga grąžina siuntos duomenis, kuriuose, atsižvelgiant į paslaugą, siuntą ir užklausos metu prieinamus atsakymo laukus, gali būti dabartinė būsena, būsenos aprašymas, vietos informacija, datos ir siuntos etapai.

Šie duomenys gali padėti įgyvendinti kelias praktines funkcijas:

• Elektroninės prekybos parduotuvėje įterptas sekimo puslapis.
• Siuntų matomumas užsakymų valdymo arba įmonės išteklių planavimo sistemoje.
• Klientų aptarnavimo ekranai, sumažinantys poreikį rankiniu būdu tikrinti vežėjo svetainę.
• Vidiniai įspėjimai apie pristatymo išimtis, vėlavimus ar užbaigtus pristatymus.
• Po pirkimo siunčiami pranešimai, pagrįsti siuntos įvykiais.

API nepakeičia jūsų programos logikos. Vis tiek turite nuspręsti, kaip dažnai prašyti atnaujinimų, kaip saugoti atsakymus, kaip tvarkyti neišsamius duomenis ir kaip paaiškinti vežėjo būsenas klientams.

UPS Tracking API ir UPS svetainė

UPS svetainė skirta žmogui, įvedančiam sekimo numerį ir skaitančiam rezultatą. API skirta programinei įrangai. Ji naudinga, kai sekimo informacija turi automatiškai atsirasti kitoje sistemoje arba suaktyvinti vidinį procesą.

Šis skirtumas svarbus, nes API integracija sukuria atsakomybes, kurių nėra atliekant rankinę paiešką. Jūsų komanda turi apsaugoti prisijungimo duomenis, patikrinti naudotojo įvestį, tinkamai registruoti užklausas ir atsakymus, tvarkyti laikinus sutrikimus ir stebėti, ar integracija toliau veikia po vežėjo platformos pakeitimų.

UPS kūrėjų platforma yra tinkama pradžia siekiant sužinoti dabartinius registracijos ir techninius reikalavimus. Jos dokumentacijai reikėtų teikti pirmenybę prieš senesnes mokomąsias instrukcijas, kodo pavyzdžius ar forumų įrašus, nes autentifikavimo metodai, API versijos, privalomos antraštės ir prieigos prie produktų taisyklės gali keistis.

Ko reikia prieš siunčiant užklausą

Prieš rašydami integraciją pasiruoškite šiuos elementus:

1. UPS kūrėjo paskyra. Naudodamiesi oficialiu UPS Developer Portal peržiūrėkite prieinamas API ir sukurkite programą.
2. Programos prisijungimo duomenys. Tikslūs prisijungimo duomenų pavadinimai ir autentifikavimo procesas turi būti paimti iš aktualios UPS dokumentacijos. Nedėkite kliento paslapčių į naršyklės kodą, mobiliąsias programas, viešas saugyklas ar klientams matomus puslapius.
3. Galiojantis sekimo numeris bandymams. Bandykite su siuntomis, kurias jūsų organizacija turi teisę pasiekti, ir venkite žurnaluose atskleisti asmens ar komercinės siuntos duomenis.
4. Serverio pusėje veikiantis integracijos taškas. Dažniausiai vidinė paslauga yra saugesnė nei tiesioginis kreipimasis į vežėją iš viešo tinklalapio, nes ji gali išlaikyti prisijungimo duomenis privačius ir kontroliuoti užklausų kiekį.
5. Atsakymų saugojimo planas. Nuspręskite, kurių laukų reikia, kiek laiko juos saugosite ir kaip susiesite vežėjo įvykį su vidiniu užsakymu.

Pradedantiesiems tinkamas integracijos procesas

1. Patvirtinkite verslo reikalavimą

Pirmiausia apibrėžkite, ką jūsų produkte reiškia „sekimas“. Klientams skirtam puslapiui gali pakakti dabartinės būsenos ir numatomos pristatymo informacijos. Sandėlio ar pagalbos tarnybos skydeliui taip pat gali reikėti skenavimo istorijos, laiko žymų, išimčių aprašymų ir pradinio sekimo numerio.

Neprašykite visų prieinamų laukų be priežasties. Mažesnį duomenų modelį lengviau prižiūrėti ir mažesnė tikimybė atskleisti informaciją, kurios naudotojams nereikia.

2. Užregistruokite programą

Sukurkite programą UPS kūrėjų aplinkoje ir pasirinkite atitinkamą sekimo produktą pagal dabartines portalo instrukcijas. Saugiai išsaugokite programos identifikatorių. Jei UPS gamybinei prieigai reikalauja patvirtinimo, paskyros susiejimo ar papildomos sąrankos, atlikite šiuos veiksmus prieš pažadėdami veikimo pradžios datą.

Jei platforma palaiko tokį modelį, testavimui ir gamybai naudokite atskirus prisijungimo duomenis ir konfigūraciją. Taip sumažinsite tikimybę, kad testavimo scenarijus paveiks veikiantį procesą.

3. Įdiekite autentifikavimą

Autentifikavimas įrodo, kad jūsų programai leidžiama skambinti paslaugai. Vadovaukitės autentifikavimo metodu, prieigos rakto galiniu tašku, apimties reikalavimais ir antraštės formatu, nurodytais aktualioje UPS dokumentacijoje. Prieigos raktus laikykite laikinais slaptais duomenimis ir nerašykite jų į programos žurnalus.

Tinkama realizacija prašo prieigos rakto tik tada, kai jo reikia, pakartotinai naudoja jį leidžiamą galiojimo laiką ir po galiojimo pabaigos gauna naują. Jūsų kodas taip pat turi atskirti autentifikavimo klaidą nuo sekimo numerio klaidos. Sprendimas skiriasi: pirmuoju atveju reikia peržiūrėti prisijungimo duomenis arba konfigūraciją, o antruoju gali reikėti patikrinti įvestį.

4. Išsiųskite sekimo užklausą

Po autentifikavimo išsiųskite užklausą naudodami UPS nurodytą sekimo operaciją ir identifikatoriaus formatą. Tikslus URL, HTTP metodas, antraštės ir atsakymo schema priklauso nuo pasirinktos API versijos oficialios dokumentacijos.

Konceptuali užklausa atrodo taip:

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

Tai mokomasis pavyzdys, o ne gamybinė užklausa, kurią galima tiesiog nukopijuoti ir įklijuoti. Operacijos pavadinimą, galinį tašką, antraštes ir turinį pakeiskite dabartinėje UPS API nuorodoje nurodytomis reikšmėmis. Kai kurios API naudoja kelio parametrą arba kitokią užklausos struktūrą.

5. Normalizuokite atsakymą

Vežėjų atsakymai ne visada pateikiami jūsų klientams suprantama kalba. Sukurkite vidinį įvykių modelį su stabiliais laukais, pavyzdžiui:

• Vidinis užsakymo arba siuntos ID.
• Vežėjo pavadinimas ir sekimo numeris.
• Naujausias vežėjo būsenos kodas ir neapdorotas aprašymas.
• Jūsų programos naudojama normalizuota būsena.
• Įvykio laiko žyma ir, jei pateikta, vieta.
• Paskutinio sėkmingo atnaujinimo laikas.

Jei įmanoma, išsaugokite pradinę vežėjo būseną. Normalizuota etiketė, pavyzdžiui, „Vežama“, naudinga klientų sąsajai, tačiau neapdorotas aprašymas gali padėti pagalbos tarnybos darbuotojams tirti neįprastą įvykį.

6. Nuspręskite, kaip gauti atnaujinimus

Kai kurios sistemos naudoja suplanuotą apklausą: vidinė paslauga pasirinktais intervalais tikrina tinkamas siuntas ir saugo pakeitimus. Kitos naudoja įvykių pranešimus, kai atitinkama platforma juos palaiko. Nemanykite, kad kiekvienas UPS sekimo produktas siūlo tą patį pranešimų mechanizmą. Prieš kurdami webhook pagrįstą procesą patikrinkite aktualią dokumentaciją ir komercines sąlygas.

Apklausa turėtų būti atrankinė. Neseniai išsiųstoms arba aktyviai gabenamoms siuntoms gali reikėti dažnesnių patikrinimų nei pristatytoms ar atšauktoms siuntoms. Laikinų klaidų atveju taikykite pakartotinius bandymus su didėjančiais intervalais, laikykitės dokumentuotų ribojimų ir nutraukite nereikalingas užklausas pasiekus galutinę būseną, nebent jūsų verslo procesui reikalingas vėlesnis patikrinimas.

Dažnos klaidos ir jų tvarkymas

Svarbiausia naudotojo patirties taisyklė – nepaversti trūkstamų duomenų užtikrinta išvada. „Naujo skenavimo nėra“ automatiškai nereiškia „pamesta“, o „etiketė sukurta“ nebūtinai reiškia „vežama“. Kruopščiai susiekite būsenas ir užtikrinkite, kad pagalbos tarnybos matytų išimčių tvarkymą.

Kada geriau rinktis kelių vežėjų API

Tiesioginė UPS integracija gali būti tinkamas pasirinkimas, kai jūsų siuntas daugiausia tvarko UPS ir jūsų komanda nori tiesiogiai valdyti ryšį su vežėju. Kompromisas tas, kad kiekvienam papildomam vežėjui gali reikėti kito autentifikavimo modelio, duomenų schemos, klaidų politikos ir priežiūros proceso.

Jei jūsų veikloje naudojami keli vežėjai, kelių vežėjų paslauga gali sumažinti atskirų integracijų skaičių. 17TRACK's Tracking API skirta programomis pagrįstam siuntų sekimui, o jos official developer documentation paaiškina prieinamą integracijos modelį. Verta ją įvertinti, kai tikrasis poreikis yra ne tik UPS sekimas, bet ir vienodas sekimo sluoksnis keliems vežėjams.

Tai nėra priežastis automatiškai pakeisti tiesioginį UPS ryšį. Palyginkite reikiamą vežėjų aprėptį, įvykių išsamumą, duomenų saugojimo reikalavimus, autentifikavimo modelį, veiklos ribojimus, pagalbos procesą ir bendras diegimo pastangas. Vieša teikėjo dokumentacija turėtų būti laikoma techninio koncepcijos patikrinimo pradžia, o ne jūsų siuntų modelių testavimo pakaitalu.

Pasirengimo gamybai kontrolinis sąrašas

• Prisijungimo duomenys saugomi paslapčių tvarkytuvėje ir niekada neatskleidžiami naršyklei.
• Testavimo ir gamybos aplinkos aiškiai atskirtos.
• Užklausoms nustatyti skirtojo laiko limitai, kontroliuojami pakartotiniai bandymai ir naudingas klaidų registravimas.
• Sekimo numeriai patikrinami prieš juos siunčiant.
• Sistema saugo paskutinį sėkmingą atnaujinimą ir nepakeičia jo tuščiu atsakymu.
• Neapdoroti vežėjo pranešimai ir klientams skirtos etiketės tvarkomi atskirai.
• Apklausų dažnis atitinka viešai paskelbtus teikėjo ribojimus ir jūsų veiklos poreikius.
• Stebėsena gali aptikti autentifikavimo klaidas, padidėjusį klaidų skaičių ir pasenusias siuntų būsenas.
• Pagalbos tarnybos darbuotojai mato pakankamai informacijos klientų klausimui ištirti.
• Integracija iš naujo išbandoma, kai UPS pakeičia dokumentaciją, prisijungimo duomenis, galinius taškus ar atsakymo laukus.

Pradėkite nuo vieno užbaigto kelio: autentifikuokitės, sekite vieną bandomąją siuntą, išsaugokite atsakymą, parodykite paprastą būseną ir tvarkykite klaidą. Plėskite tik tada, kai šis kelias veikia patikimai. Toks metodas paprastai yra saugesnis nei didelės klientams skirtos sekimo patirties kūrimas prieš suprantant pagrindinių duomenų ir klaidų elgseną.

DUK

Ar man reikia API, jei seku tik kelias siuntas?

Paprastai ne. Retkarčiais tikrinti siuntas vežėjo svetainėje gali būti praktiškiau. API tampa vertingesnė, kai sekimas yra pasikartojančio proceso dalis arba turi būti rodomas kitoje programoje.

Ar galiu iškviesti UPS Tracking API iš Shopify temos ar naršyklės?

Tiesioginis naršyklės kreipinys gali atskleisti prisijungimo duomenis ir apsunkinti užklausų kontrolę. Serverio pusėje veikianti paslauga arba sukurta sekimo integracija paprastai yra saugesnė. Dabartinėje UPS dokumentacijoje patikrinkite techninius reikalavimus ir leidžiamą architektūrą.

Ar sekimo API kuria siuntimo etiketes?

Nebūtinai. Sekimas, etikečių kūrimas, tarifų skaičiavimas, adreso tikrinimas ir kitos logistikos funkcijos gali būti atskiri API produktai. Pasirinkite produktą, atitinkantį jums reikalingą operaciją.

Kodėl galiojantis sekimo numeris gali grąžinti mažai informacijos?

Siunta galėjo dar negauti pirmojo skenavimo, duomenys gali būti dar neprieinami arba užklausa gali neatitikti API reikalaujamo formato ar prieigos leidimų. Tuščią arba ribotą atsakymą vertinkite kaip būseną, kurią reikia ištirti, o ne kaip įrodymą, kad siunta pamesta.

Ar turėčiau rinktis tiesioginį UPS ryšį, ar kelių vežėjų sekimo API?

Tiesioginį ryšį rinkitės, kai UPS yra pagrindinis vežėjas ir norite sutelktos integracijos. Kelių vežėjų paslaugą svarstykite, kai veiklos tikslas – vienas sekimo procesas keliems vežėjams. Prieš priimdami galutinį sprendimą išbandykite reikiamus vežėjus ir įvykių scenarijus.

Šaltiniai

• UPS Developer Portal
• UPS Tracking API documentation and product resources
• 17TRACK Tracking API
• 17TRACK API documentation