USPS API dokumentacijos kontrolinis sąrašas, skirtas 17TRACK užsakymų vykdymo ir grąžinimų integracijai

Patikima USPS integracija su 17TRACK turėtų būti planuojama kaip du susiję, tačiau atskiri darbų srautai: USPS dokumentacija reglamentuoja su vežėju susijusius duomenis ir paslaugas, o 17TRACK gali teikti platesnį siuntų sekimo sluoksnį, užtikrinantį siuntų matomumą tarp skirtingų vežėjų. Vykdymo ir grąžinimo procesams įgyvendinimo komanda prieš rašydama gamybinį kodą turėtų patikrinti autentifikavimą, siuntų identifikatorius, įvykių susiejimą, tarifų ir etikečių atsakomybes, apklausos arba pranešimų veikimą, klaidų tvarkymą ir ribas tarp išsiunčiamų siuntų pristatymo bei atvirkštinės logistikos.

Šis kontrolinis sąrašas skirtas kūrėjams, elektroninės prekybos operacijų komandoms ir sprendimų savininkams, kurie USPS susijusius siuntų duomenis jungia su užsakymų valdymo sistema, sandėlio procesu, klientams skirta siuntų sekimo patirtimi arba grąžinimo procesu. Jame nelaikoma, kad kiekviena USPS API galimybė pasiekiama per 17TRACK arba kad sekimo API pati kuria etiketes, perka pašto paslaugas ar valdo fizinius grąžinimus.

1. Pirmiausia apibrėžkite integracijos ribas

Pradėkite dokumentuodami, ką turi atlikti kiekviena sistema. USPS dokumentacija aprašo USPS paslaugas ir sąsajas, prieinamas patvirtintam integratoriui. 17TRACK Tracking API dokumentacija yra aktuali, kai programai reikia nuo vežėjo nepriklausomo sekimo proceso arba vienos sąsajos siuntų įvykiams. 17RETURNS produkto puslapis yra aktualus, kai projektas taip pat apima elektroninės prekybos grąžinimų valdymą. Tai susiję naudojimo atvejai, tačiau jie nėra tarpusavyje pakeičiami.

• USPS: patvirtinkite, kokios su vežėju susijusios funkcijos reikalingos, pavyzdžiui, sekimas, adresų paslaugos, kainodara, informacija apie paslaugas ar kitos dokumentuotos API.
• 17TRACK Tracking API: patikrinkite, kaip USPS sekimo numeriai pateikiami, užklausiami, atnaujinami ir pateikiami programos normalizuotame įvykių modelyje.
• Vykdymo platforma: nustatykite sistemą, atsakingą už atsargų paskirstymą, užsakymo išleidimą, etiketės sukūrimą, pašto paslaugų įsigijimą, sandėlio patvirtinimą ir siuntos sukūrimą.
• Grąžinimo procesas: apibrėžkite, kas autorizuoja grąžinimą, generuoja grąžinimo instrukcijas arba etiketes, užregistruoja grąžintą siuntą ir nusprendžia dėl pinigų grąžinimo arba keitimo rezultato.

Taigi pirmasis architektūrinis sprendimas yra ne „kurį galinį tašką turėtume iškviesti?“, o „kuri sistema yra atsakinga už kiekvieną verslo veiksmą?“. Vežėjo sekimo API gali pagerinti matomumą, nebūdama pagrindine vykdymo ar grąžinimų apskaitos sistema.

2. Patikrinkite aktualią USPS kūrėjų dokumentaciją

Pradėkite nuo USPS Web Tools and APIs informacijos, tada vadovaukitės aktualia kūrėjų dokumentacija ir konkrečių produktų nuorodomis, kurias pateikia USPS. Nekopijuokite galinio taško, autentifikavimo metodo, lauko pavadinimo ar paslaugos nutraukimo pranešimo iš seno kodo pavyzdžio nepatikrinę jo dabartinės būsenos.

Prieš įgyvendinimą projekto įraše užfiksuokite šiuos dokumentacijos faktus:

• Tikslus reikalingas USPS API produktas arba produktai.
• Dabartinis bazinis URL ir testavimo bei gamybinės aplinkos informacija.
• Registracijos procesas, programos kredencialai ir leidžiamas šių kredencialų naudojimas.
• Autentifikavimo eiga, prieigos rakto galiojimo trukmė, sritys ir kredencialų keitimo reikalavimai, jei jie dokumentuoti pasirinktoje API.
• Reikalingos antraštės, turinio tipai, užklausų formatai, atsakymų formatai ir versijų identifikatoriai.
• Palaikomos operacijos ir bet kokie apribojimai, pagrįsti paskyra, paslauga, geografija ar duomenų tipu.
• Užklausų dažnio ribojimai, skirtasis laikas, techninės priežiūros pranešimai ir dokumentuoti klaidų atsakymai.
• Sąlygos, reglamentuojančios USPS atsakymų duomenų saugojimą, rodymą, pakartotinį naudojimą ir platinimą.

Jei reikalavimas oficialioje dokumentacijoje nenurodytas, pažymėkite jį tiesioginiam patvirtinimui su USPS arba atitinkamu paskyros atstovu. Nemanykite, kad senas USPS Web Tools pavyzdys atspindi dabartinę API, ir nemanykite, kad viename USPS produkte aprašyta funkcija prieinama kitame.

3. Sudarykite autentifikavimo ir saugumo kontrolinį sąrašą

Autentifikavimas turėtų būti testuojamas atskirai nuo verslo logikos. Komanda turi galėti atšaukti ir pakeisti kredencialus nekeisdama programos kodo ar nenutraukdama nesusijusių sekimo funkcijų.

1. Klientų paslaptis, API raktus, prieigos raktus ir sertifikatus saugokite valdomoje paslapčių saugykloje, o ne pradiniame kode ar kliento programoje.
2. Patvirtinkite, ar pasirinkta USPS API naudoja dabartinėje dokumentacijoje aprašytą autentifikavimo metodą. Įgyvendinkite dokumentuotą eigą tiksliai, įskaitant prieigos raktų užklausas, sritis, galiojimo pabaigą ir atnaujinimo arba pakartotinio autorizavimo veikimą.
3. Jei USPS tai leidžia, naudokite atskirus kredencialus arba aplinkas, kad testinis srautas nebūtų painiojamas su gamybiniu.
4. Apribokite prieigą prie klientų adresų duomenų, siuntų duomenų ir grąžinimo informacijos pagal vaidmenis, kuriems jos reikia.
5. Programos žurnaluose paslėpkite kredencialus ir nereikalingą asmeninę informaciją.
6. Autentifikavimo klaidas registruokite naudodami koreliacijos identifikatorių, tačiau nefiksuokite paslapčių ar visų neskelbtinų duomenų rinkinių.
7. Patikrinkite veikimą, kai baigiasi prieigos rakto galiojimas, kredencialas atšaukiamas, užklausa pakartojama arba autentifikavimo paslauga laikinai nepasiekiama.

Integruojant su 17TRACK, vežėjo kredencialus ir 17TRACK kredencialus laikykite konceptualiai atskirus, nebent atitinkama dokumentacija aiškiai apibrėžia kitokią tvarką. Per 17TRACK nukreipta sekimo užklausa neturėtų būti laikoma suteikiančia prieigą prie USPS pašto paslaugų, paskyros ar etikečių paslaugų.

4. Patvirtinkite identifikatorius ir duomenų nuosavybę

Siuntos tapatybė dažnai tampa pasikartojančių užsakymų ir nutrūkusių grąžinimo nuorodų priežastimi. Prieš jungdami sistemas sukurkite laukų žemėlapį. Bent jau atskirkite šias reikšmes:

Verslo reikšmė	Įgyvendinimo klausimas	Patvirtinimo taškas
Užsakymo ID	Kuris prekybos arba OMS įrašas yra užsakymo savininkas?	Viename užsakyme gali būti kelios siuntos.
Vykdymo ID	Kuris sandėlio arba 3PL veiksmas išleido siuntą?	Nepakeiskite jo sekimo numeriu.
Sekimo numeris	Kuris identifikatorius pateikiamas USPS arba 17TRACK?	Patvirtinkite formatą, vežėjo priskyrimą ir pasikartojančių įrašų tvarkymą.
Grąžinimo ID	Kuri autorizacija arba grąžinimo byla yra siuntos savininkė?	Grąžinama siunta neturėtų perrašyti išsiunčiamos siuntos.
Įvykio ID ir laiko žyma	Kaip tvarkomi pasikartojantys arba vėluojantys įvykiai?	Apibrėžkite eiliškumo, laiko juostos ir idempotentiškumo taisykles.

Kai įmanoma, išsaugokite pradinį vežėjo įvykį ir normalizuotą vidinę būseną. Normalizuota būsena, pavyzdžiui, „gabenama“, yra naudinga parduotuvėms, tačiau operacijų komandoms tyrimo metu vis tiek gali reikėti originalaus USPS įvykio teksto, vietos ir įvykio laiko.

5. Suprojektuokite sekimo duomenų gavimą ir būsenų susiejimą

Prieš prijungdami tiesioginį srautą išvardykite būsenas, kurių verslui iš tikrųjų reikia. Įprastos būsenos gali būti etiketė sukurta, priimta, gabenama, išvežta pristatyti, pristatyta, pristatymo išimtis ir grąžinama siuntėjui. Tikslus USPS įvykių žodynas ir per 17TRACK pateikiami įvykiai turi būti patikrinti atitinkamoje dokumentacijoje bei testiniuose atsakymuose; nekurkite susiejimų vien pagal būsenų pavadinimus.

Kiekvienam įvykiui apibrėžkite:

• Šaltinio sistemą ir pradinį įvykio kodą arba aprašą.
• Normalizuotą vidinę būseną.
• Ar įvykis matomas klientui, skirtas tik operacijoms, ar abiem.
• Ar jis gali perkelti užsakymą į priekį, sustabdyti SLA, sukelti pranešimą arba atidaryti išimties bylą.
• Ar vėlesnis įvykis gali jį pataisyti arba pakeisti.
• Kaip tvarkomi pasikartojantys ir ne eilės tvarka gaunami įvykiai.

Taip pat nuspręskite, kaip nauji sekimo numeriai patenka į sistemą. Siunta gali būti sukurta prieš pasirodant pirmajam vežėjo nuskaitymui. Programa turėtų atskirti „sekimo numeris užregistruotas“ nuo „vežėjas priėmė siuntą“, o nenuskaityta siunta neturėtų būti rodoma kaip jau judanti tinkle.

6. Nuspręskite tarp apklausos ir pranešimų

Įgyvendinime turi būti dokumentuota, kaip gaunama nauja sekimo informacija. Jei pasirinktas USPS arba 17TRACK produktas palaiko pranešimų mechanizmą, oficialioje dokumentacijoje patikrinkite jo prenumeratos modelį, pateikimo formatą, pakartotinių bandymų veikimą, pasirašymo arba tikrinimo metodą ir ribojimus. Jei būtina apklausa, apibrėžkite intervalą, sustabdymo sąlygas, atsitraukimo strategiją ir siuntų, kuriose nėra naujų įvykių, tvarkymą.

Neapklauskite agresyviai vien todėl, kad klientas atnaujina sekimo puslapį. Kai tikslinga, naudokite serverio įvykių saugyklą arba podėlį, taikykite eksponentinį atsitraukimą laikinoms klaidoms ir užtikrinkite, kad duomenų gavimas būtų idempotentiškas. Nepavykusi užklausa neturėtų sukurti antros siuntos, antro grąžinimo ar pasikartojančio pranešimo klientui.

Operaciniai įspėjimai turėtų apimti autentifikavimo klaidas, nuolatinius dažnio ribojimo atsakymus, netinkamai suformuotus vežėjo atsakymus, įvykių apdorojimo klaidas ir didėjantį neišspręstų siuntų skaičių. Stebėsena turėtų rodyti tiek API, tiek verslo būklę: sėkmingas HTTP atsakymas nebūtinai reiškia, kad siunta susieta su teisingu užsakymu.

7. Atskirkite vykdymą nuo grąžinimų

Išsiunčiamų siuntų vykdymas ir grąžinimai naudoja bendrus siuntų duomenis, tačiau jiems taikomos skirtingos verslo taisyklės. Išsiunčiamos siuntos vykdymas paprastai prasideda užsakymu ir baigiasi pristatymu arba išimtimi. Grąžinimas prasideda nuo kliento arba prekybininko sprendimo, gali reikėti autorizacijos ir baigiasi priėmimo patikra, pinigų grąžinimu, keitimu ar kitu sprendimu.

Prieš pridėdami vežėjo sekimą, grąžinimų integracijai dokumentuokite šiuos sprendimus:

• Kokios grąžinimo priežastys priimamos ir kas jas patvirtina?
• Ar grąžinimo etiketę generuoja prekybininko siuntimo platforma, su USPS susijęs procesas, trečiosios šalies grąžinimų sistema ar kitas teikėjas?
• Kaip grąžinimo sekimo numeris susiejamas su pradiniu užsakymu nepakeičiant išsiunčiamos siuntos sekimo numerio?
• Kuris įvykis laikomas „grąžinama siunta“, „grąžinimas pristatytas“ arba „gauta patikrai“?
• Ar grąžinimas gali būti pristatytas į sandėlį, bet likti nebaigtas, kol prekė nepatikrinta?
• Kas nutinka, kai klientas siunčia neautorizuotą siuntą arba naudoja kitą vežėją?

17RETURNS gali būti aktualus, kai projektui reikia specializuoto grąžinimų valdymo proceso, o 17TRACK API aktuali siuntų matomumui. Prieš priskirdami kuriam nors produktui tokią funkciją kaip etikečių generavimas, pinigų grąžinimo autorizavimas, prekių priėmimas sandėlyje ar vežėjo paskyros valdymas, patikrinkite aktualią produkto dokumentaciją.

8. Išbandykite integraciją realistiškais scenarijais

Vienos pristatytos siuntos sėkmingo scenarijaus testo nepakanka. Sukurkite testų matricą, apimančią:

1. Galiojantį USPS sekimo numerį, neturintį naujausio įvykio.
2. Siuntą, kurios keli įvykiai gauti ne eilės tvarka.
3. Pasikartojančius pristatymo arba išimties įvykius.
4. Negaliojantį, klaidingai įvestą arba nepalaikomą identifikatorių.
5. Siuntą, grąžinamą siuntėjui.
6. Išsiunčiamą ir grąžinamą siuntą, susietas su tuo pačiu užsakymu.
7. API skirtąjį laiką, dažnio ribojimo atsakymą, autentifikavimo klaidą ir netinkamai suformuotą atsakymą.
8. Siuntą, kurios vežėjas iš pradžių nežinomas arba kuriai reikia patvirtinimo.
9. Klientams skirtą puslapį, kuris gauna naują įvykį tuo metu, kai operacijų naudotojas redaguoja užsakymą.

Kiekvienam scenarijui užregistruokite tikėtiną duomenų bazės rezultatą, pranešimą klientui, operacijų veiksmą, pakartotinių bandymų elgseną ir audito seką. Testuokite naudodami sintetinius arba autorizuotus duomenis ir patvirtinkite, kad asmeniniai adresai bei kontaktiniai duomenys žurnaluose arba viešuose sekimo puslapiuose neatskleidžiami daugiau, nei leidžia patvirtinta verslo paskirtis.

9. Parengties gamybai peržiūra

Prieš paleidimą už veiksmą atsakingas asmuo turi galėti atsakyti į penkis praktinius klausimus: kuri sistema sukuria siuntą? Kuri sistema valdo sekimo numerį? Kuri sistema siunčia pranešimus klientams? Kuri sistema valdo grąžinimo bylą? Kuri komanda tiria trūkstamą arba prieštaringą įvykį?

Peržiūrą užbaikite tik patikrinę aktualią USPS dokumentaciją, pasirinktą 17TRACK API dokumentaciją ir konkretaus produkto sąlygas arba veiklos gaires. Saugokite versijuotą galinių taškų nuorodų, laukų susiejimų, testų įrodymų, kredencialų savininkų, eskalavimo kontaktų ir prielaidų, kurias reikia tiesiogiai patvirtinti, įrašą. Peržiūrėkite įrašą iš naujo, kai pasikeičia API versija, vežėjo procesas, sandėlio procesas arba grąžinimų politika.

DUK

Ar 17TRACK gali pakeisti USPS API atliekant visas vykdymo funkcijas?

Nereikėtų daryti jokios prielaidos. 17TRACK gali būti vertinama kaip sekimo sluoksnis, tačiau su USPS susijusios funkcijos, tokios kaip kainodara, adresų paslaugos, pašto paslaugos ar kitos vežėjo operacijos, turi būti patvirtintos pagal atitinkamą produkto dokumentaciją ir paskyros reikalavimus. Sekimo matomumas nėra tas pats, kas etiketės įsigijimas ar vykdymas.

Ar man reikia ir USPS, ir 17TRACK integracijų?

Ne visada. Jei programai reikia tik siaurai apibrėžtos USPS funkcijos, gali tikti tiesioginė USPS integracija. Jei reikia normalizuoto sekimo tarp kelių vežėjų arba nuo vežėjo nepriklausomo sekimo proceso, 17TRACK gali būti aktuali. Sprendimas turėtų būti grindžiamas reikalingomis galimybėmis, nuosavybės modeliu ir duomenų srautu, o ne vien sekimo numeriu.

Ar grąžinimo sekimo numeris turėtų pakeisti išsiunčiamos siuntos sekimo numerį?

Ne. Saugokite grąžinimą kaip atskirą siuntą arba grąžinimo judėjimą, susietą su pradiniu užsakymu ir vykdymo įrašu. Taip išsaugoma išsiunčiamos siuntos pristatymo istorija, o grąžinimas gali turėti atskirus įvykius, išimtis ir veiklos rezultatą.

Kaip turėtų būti tvarkomi trūkstami sekimo įvykiai?

Apibrėžkite dokumentuotą pakartotinių bandymų ir eskalavimo politiką. Trūkstamas įvykis gali reikšti įprastą vežėjo vėlavimą, negaliojantį identifikatorių, duomenų gavimo klaidą arba vėlavimą vežėjo pusėje. Venkite žymėti siuntą kaip prarastą vien todėl, kad per vieną apklausą negautas naujas įvykis.

Kur turėtų būti saugomi USPS kredencialai?

Naudokite valdomą serverio pusės paslapčių saugyklą ir apribokite prieigą pagal vaidmenis. Niekada nedėkite kredencialų į parduotuvės JavaScript, mobiliojo kliento kodą, viešas saugyklas ar žurnalus. Prieš diegdami gamybinę sistemą patvirtinkite dabartinius USPS autentifikavimo ir kredencialų valdymo reikalavimus.

Šaltiniai

• USPS Web Tools and APIs — oficialus USPS pradinis puslapis verslo API informacijai.
• 17TRACK Tracking API Documentation — oficiali 17TRACK API integracijos dokumentacija.
• 17RETURNS — oficiali produkto informacija apie grąžinimų valdymo naudojimo atvejus.
• 17TRACK API — oficiali produkto apžvalga apie sekimo API scenarijus.