Kontrolni seznam dokumentacije USPS API za integracijo izpolnjevanja naročil in vračil 17TRACK

Zanesljivo integracijo USPS s 17TRACK je treba načrtovati kot dva povezana, vendar ločena delovna toka: dokumentacija USPS ureja podatke in storitve, povezane s prevoznikom, medtem ko lahko 17TRACK zagotovi širši sloj sledenja za pregled nad pošiljkami pri različnih prevoznikih. Pri izpolnjevanju naročil in vračilih mora izvedbena ekipa pred pisanjem produkcijske kode preveriti avtentikacijo, identifikatorje pošiljk, preslikavo dogodkov, odgovornosti za cene in nalepke, vedenje pri periodičnem preverjanju ali obvestilih, obravnavo napak ter meje med izhodno dostavo in povratno logistiko.

Ta kontrolni seznam je namenjen razvijalcem, ekipam za e-trgovino in lastnikom rešitev, ki podatke o pošiljkah, povezanih z USPS, povezujejo s sistemom za upravljanje naročil, skladiščnim delovnim tokom, uporabniško izkušnjo sledenja ali postopkom vračil. Ne predpostavlja, da je vsaka zmogljivost USPS API na voljo prek 17TRACK ali da API za sledenje sam ustvarja nalepke, kupuje poštnino ali upravlja fizična vračila.

1. Najprej določite mejo integracije

Začnite z dokumentiranjem pričakovanih nalog vsakega sistema. Dokumentacija USPS opisuje storitve USPS in vmesnike, ki so na voljo odobrenemu integratorju. Dokumentacija Tracking API 17TRACK je pomembna, kadar aplikacija potrebuje sledenje, neodvisno od prevoznika, ali enoten vmesnik za dogodke pošiljk. Stran izdelka 17RETURNS je pomembna, kadar projekt vključuje tudi upravljanje vračil v e-trgovini. To so sorodni primeri uporabe, vendar niso medsebojno zamenljivi.

• USPS: potrdite, katere funkcije, povezane s prevoznikom, so potrebne, na primer sledenje, storitve za naslove, določanje cen, informacije o storitvah ali drugi dokumentirani API-ji.
• Tracking API 17TRACK: preverite, kako se številke za sledenje USPS pošljejo, poizvedujejo, posodabljajo in predstavljajo v normaliziranem modelu dogodkov aplikacije.
• Platforma za izpolnjevanje naročil: določite sistem, odgovoren za razporejanje zaloge, sprostitev naročila, ustvarjanje nalepk, nakup poštnine, potrditev skladišča in ustvarjanje pošiljke.
• Potek vračil: določite, kdo odobri vračilo, ustvari navodila ali nalepke za vračilo, zabeleži vrnjeni paket ter odloči o vračilu denarja ali zamenjavi.

Prva arhitekturna odločitev zato ni »kateri končni naslov naj pokličemo?«, temveč »kateri sistem je lastnik posameznega poslovnega dejanja?« API za sledenje prevoznikov lahko izboljša preglednost, ne da bi bil sistem evidenc za izpolnjevanje naročil ali vračila.

2. Preverite aktualno dokumentacijo za razvijalce USPS

Za izhodišče uporabite informacije USPS Web Tools and APIs, nato pa sledite aktualni dokumentaciji za razvijalce in referencam za posamezne izdelke, ki jih povezuje USPS. Ne kopirajte končne točke, metode avtentikacije, imena polja ali obvestila o umiku iz starega vzorca kode, ne da bi preverili njegovo trenutno stanje.

Pred izvedbo zabeležite naslednja dejstva iz dokumentacije v projektni zapis:

• Točen izdelek ali izdelke USPS API, ki jih potrebujete.
• Trenutni osnovni URL in podrobnosti okolij za testiranje in produkcijo.
• Postopek registracije, poverilnice aplikacije in dovoljeno uporabo teh poverilnic.
• Potek avtentikacije, življenjsko dobo žetona, obsege ter zahteve za menjavo poverilnic, če so dokumentirane za izbrani API.
• Zahtevane glave, vrste vsebine, formate zahtev in odgovorov ter identifikatorje različic.
• Podprte operacije in morebitne omejitve glede na račun, storitev, geografijo ali vrsto podatkov.
• Omejitve hitrosti, priporočila glede časovne omejitve, obvestila o vzdrževanju in dokumentirane odgovore o napakah.
• Pogoje glede shranjevanja, prikaza, ponovne uporabe in distribucije podatkov iz odgovorov USPS.

Če zahteva ni navedena v uradni dokumentaciji, jo označite za neposredno potrditev pri USPS ali ustreznem predstavniku računa. Ne sklepajte, da primer starega USPS Web Tools predstavlja trenutni API, in ne sklepajte, da je funkcija, opisana v enem izdelku USPS, na voljo tudi v drugem.

3. Sestavite kontrolni seznam za avtentikacijo in varnost

Avtentikacijo je treba testirati ločeno od poslovne logike. Ekipa mora imeti možnost preklicati in zamenjati poverilnice brez spreminjanja kode aplikacije ali prekinitve nepovezanih funkcij sledenja.

1. Skrivnosti odjemalca, ključe API, žetone in potrdila hranite v upravljanem trezorju skrivnosti, ne v izvorni kodi ali odjemalski aplikaciji.
2. Potrdite, ali izbrani API USPS uporablja metodo avtentikacije, opisano v aktualni dokumentaciji. Dokumentirani potek izvedite natančno, vključno z zahtevami za žetone, obsegi, potekom veljavnosti ter osveževanjem ali ponovno avtorizacijo.
3. Kjer USPS to dovoljuje, uporabite ločene poverilnice ali okolja, da testni promet ne bo zamenjan s produkcijskim.
4. Omejite dostop do podatkov o naslovih strank, podatkov o pošiljkah in informacij o vračilih glede na vloge, ki jih potrebujejo.
5. Iz dnevnikov aplikacije odstranite poverilnice in nepotrebne osebne podatke.
6. Napake pri avtentikaciji zabeležite z identifikatorjem korelacije, vendar ne beležite skrivnosti ali celotnih občutljivih vsebin.
7. Preizkusite vedenje ob poteku žetona, preklicu poverilnice, ponovitvi zahteve ali začasni nedosegljivosti storitve za avtentikacijo.

Pri integraciji s 17TRACK naj bodo poverilnice prevoznika in poverilnice 17TRACK konceptualno ločene, razen če ustrezna dokumentacija izrecno določa drugačno ureditev. Zahteva za sledenje, usmerjena prek 17TRACK, ne pomeni samodejno dostopa do storitev USPS za poštnino, račune ali nalepke.

4. Potrdite identifikatorje in lastništvo podatkov

Identiteta pošiljke je pogost vir podvojenih naročil in prekinjenih povezav do vračil. Pred povezovanjem sistemov ustvarite preslikavo polj. Najmanj ločite naslednje vrednosti:

Kadar je mogoče, ohranite izvirni dogodek prevoznika in normalizirano notranje stanje. Normalizirano stanje, kot je »v tranzitu«, je uporabno za trgovine, vendar operativne ekipe morda še vedno potrebujejo izvirno besedilo dogodka USPS, lokacijo in čas dogodka za preiskavo.

5. Načrtujte sprejemanje sledenja in preslikavo stanj

Pred povezovanjem produkcijskega prometa naštejte stanja življenjskega cikla, ki jih podjetje dejansko potrebuje. Običajna stanja lahko vključujejo ustvarjeno nalepko, sprejeto, v tranzitu, pred dostavo, dostavljeno, izjemo pri dostavi in vrnjeno pošiljatelju. Točen besednjak dogodkov USPS in dogodke, ki so na voljo prek 17TRACK, je treba preveriti v ustrezni dokumentaciji in testnih odgovorih; preslikav ne ustvarjajte samo na podlagi imen stanj.

Za vsak dogodek določite:

• Izvorni sistem ter izvirno kodo ali opis dogodka.
• Normalizirano notranje stanje.
• Ali je dogodek viden stranki, namenjen samo operacijam ali obojemu.
• Ali lahko premakne naročilo naprej, zaustavi SLA, sproži obvestilo ali odpre primer izjeme.
• Ali ga lahko poznejši dogodek popravi ali nadomesti.
• Kako se obravnavajo podvojeni dogodki in dogodki v napačnem vrstnem redu.

Odločite tudi, kako nove številke za sledenje vstopajo v sistem. Pošiljka je lahko ustvarjena, preden se pojavi prvi pregled prevoznika. Aplikacija mora ločiti »številka za sledenje je registrirana« od »prevoznik je paket sprejel«, namesto da bi neskenerano pošiljko prikazala kot že premikajočo se po omrežju.

6. Odločite se med periodičnim preverjanjem in obvestili

Izvedba mora dokumentirati, kako se pridobivajo nove informacije o sledenju. Če izbrani izdelek USPS ali 17TRACK podpira mehanizem obvestil, v uradni dokumentaciji preverite njegov model naročanja, obliko dostave, vedenje pri ponovnih poskusih, način podpisovanja ali preverjanja ter omejitve. Če je potrebno periodično preverjanje, določite interval, pogoje za ustavitev, strategijo umika in obravnavo pošiljk brez novih dogodkov.

Ne izvajajte agresivnega preverjanja samo zato, ker stranka osveži stran za sledenje. Kjer je primerno, uporabite strežniško shrambo dogodkov ali predpomnilnik, pri začasnih napakah uporabite eksponentni umik in zagotovite idempotentno sprejemanje. Neuspešna zahteva ne sme ustvariti druge pošiljke, drugega vračila ali podvojenega obvestila stranki.

Operativna opozorila morajo zajemati napake pri avtentikaciji, trajne odgovore o omejitvi hitrosti, nepravilne odgovore prevoznika, napake pri obdelavi dogodkov in povečanje števila nerazrešenih pošiljk. Spremljanje mora prikazovati zdravje API-ja in poslovno zdravje: uspešen odgovor HTTP ne pomeni nujno, da je bila pošiljka povezana s pravilnim naročilom.

7. Ločite izpolnjevanje naročil od vračil

Izhodno izpolnjevanje naročil in vračila si delita podatke o pošiljkah, vendar imata različna poslovna pravila. Izhodno izpolnjevanje se običajno začne z naročilom in konča z dostavo ali izjemo. Vračilo se začne z odločitvijo stranke ali trgovca, lahko zahteva odobritev in se konča s pregledom prejete pošiljke, vračilom denarja, zamenjavo ali drugo odločitvijo.

Pri integraciji vračil pred dodajanjem sledenja dokumentirajte naslednje odločitve:

• Kateri razlogi za vračilo so sprejemljivi in kdo jih odobri?
• Ali vračilno nalepko ustvari trgovčeva platforma za pošiljanje, delovni tok, povezan z USPS, sistem tretje osebe za vračila ali drug ponudnik?
• Kako je številka za sledenje vračila povezana z izvirnim naročilom, ne da bi nadomestila številko za sledenje izhodne pošiljke?
• Kateri dogodek šteje kot »vračilo v tranzitu«, »vračilo dostavljeno« ali »prejeto v pregled«?
• Ali je lahko vračilo dostavljeno v skladišče, vendar ostane v čakanju, dokler izdelek ni pregledan?
• Kaj se zgodi, ko stranka pošlje nepooblaščen paket ali uporabi drugega prevoznika?

17RETURNS je lahko pomemben, kadar projekt potrebuje namenski delovni tok za upravljanje vračil, medtem ko je API 17TRACK pomemben za preglednost pošiljk. Preden kateremu koli izdelku dodelite funkcijo, kot so ustvarjanje nalepk, odobritev vračila denarja, prevzem v skladišču ali upravljanje računa prevoznika, preverite aktualno dokumentacijo izdelka.

8. Integracijo preizkusite z realističnimi scenariji

Test uspešne poti za en dostavljen paket ni dovolj. Ustvarite testno matriko, ki vključuje:

1. Veljavno številko za sledenje USPS brez nedavnega dogodka.
2. Pošiljko z več dogodki, prejetimi v napačnem vrstnem redu.
3. Ponavljajoče se dogodke dostave ali izjem.
4. Neveljaven, napačno vpisan ali nepodprt identifikator.
5. Paket, ki je vrnjen pošiljatelju.
6. Izhodno pošiljko in vračilno pošiljko, povezani z istim naročilom.
7. Časovno omejitev API-ja, odgovor o omejitvi hitrosti, napako pri avtentikaciji in nepravilen odgovor.
8. Pošiljko, pri kateri je dodelitev prevoznika sprva neznana ali zahteva potrditev.
9. Stran, namenjeno strankam, ki prejme nov dogodek, medtem ko uporabnik iz operacij ureja naročilo.

Za vsak scenarij zabeležite pričakovani rezultat v podatkovni zbirki, sporočilo stranki, dejanje operacij, vedenje pri ponovnem poskusu in revizijsko sled. Testirajte s sintetičnimi ali odobrenimi podatki ter potrdite, da osebni naslovi in kontaktni podatki niso izpostavljeni v dnevnikih ali na javnih straneh za sledenje bolj, kot je potrebno za odobren poslovni namen.

9. Pregled pripravljenosti na produkcijo

Pred uvedbo mora biti odgovorna oseba za dejanje sposobna odgovoriti na pet praktičnih vprašanj: Kateri sistem ustvari pošiljko? Kateri sistem je lastnik številke za sledenje? Kateri sistem pošilja obvestila strankam? Kateri sistem upravlja primer vračila? Katera ekipa preiskuje manjkajoč ali protisloven dogodek?

Pregled zaključite šele po preverjanju aktualne dokumentacije USPS, izbrane dokumentacije API 17TRACK ter pogojev za posamezne izdelke ali operativnih navodil. Hranite različicno urejen zapis referenc končnih točk, preslikav polj, dokazov testiranja, lastnikov poverilnic, kontaktov za eskalacijo in predpostavk, ki zahtevajo neposredno potrditev. Zapis ponovno preglejte, ko se spremenijo različica API-ja, delovni tok prevoznika, skladiščni postopek ali politika vračil.

Pogosta vprašanja

Ali lahko 17TRACK nadomesti API USPS za vse funkcije izpolnjevanja naročil?

Takšne predpostavke ne smete sprejeti. 17TRACK je mogoče oceniti kot sloj za sledenje, vendar je treba funkcije, povezane z USPS, kot so določanje cen, storitve za naslove, poštnina ali druge operacije prevoznika, potrditi glede na ustrezno dokumentacijo izdelka in zahteve računa. Preglednost sledenja ni enaka nakupu nalepke ali izvedbi izpolnjevanja naročila.

Ali potrebujem integraciji USPS in 17TRACK?

Ne vedno. Če aplikacija potrebuje samo ozko opredeljeno funkcijo USPS, je lahko primerna neposredna integracija USPS. Če potrebuje normalizirano sledenje pri več prevoznikih ali delovni tok sledenja, neodvisen od prevoznika, je lahko pomemben 17TRACK. Odločitev mora temeljiti na zahtevanih zmogljivostih, modelu lastništva in toku podatkov, ne zgolj na številki za sledenje.

Ali naj številka za sledenje vračila nadomesti številko za sledenje izhodne pošiljke?

Ne. Vračilo shranite kot ločeno pošiljko ali premik vračila, povezan z izvirnim naročilom in zapisom o izpolnitvi naročila. Tako ohranite zgodovino izhodne dostave, vračilo pa ima lahko lastne dogodke, izjeme in operativni rezultat.

Kako je treba obravnavati manjkajoče dogodke sledenja?

Določite dokumentirano politiko ponovnih poskusov in eskalacije. Manjkajoči dogodek lahko odraža običajen čas prevoznika, neveljaven identifikator, napako pri sprejemanju ali zamudo na strani prevoznika. Pošiljke ne označite kot izgubljene samo zato, ker en poskus preverjanja ni vrnil novega dogodka.

Kje je treba hraniti poverilnice USPS?

Uporabite upravljan strežniški trezor skrivnosti in omejite dostop glede na vlogo. Poverilnic nikoli ne vstavljajte v JavaScript trgovine, kodo mobilnega odjemalca, javne repozitorije ali dnevnike. Pred uvedbo v produkcijo preverite aktualne zahteve USPS glede avtentikacije in upravljanja poverilnic.

Viri

• USPS Web Tools and APIs — uradna vstopna točka USPS za informacije o poslovnih API-jih.
• Dokumentacija Tracking API 17TRACK — uradna dokumentacija za integracijo API-ja 17TRACK.
• 17RETURNS — uradne informacije o izdelku za primere uporabe upravljanja vračil.
• 17TRACK API — uradni pregled izdelka za scenarije API-ja za sledenje.