Dokumentacija API-ja za sledenje UPS: 7 ključnih funkcij, ki bi jih razvijalci morali poznati

Dokumentacija API-ja za sledenje UPS je najbolj uporabna, ko razvijalcu pomaga preiti od številke za sledenje do zanesljive izkušnje spremljanja statusa pošiljke. Sedem področij, ki jih je treba preučiti, so preverjanje pristnosti, zahteve za sledenje, sheme odgovorov, zgodovina dogodkov, obravnava napak, operativne omejitve in testiranje. UPS za neposredne integracije UPS zagotavlja lastno platformo za razvijalce, medtem ko je storitev za več prevoznikov, kot je 17TRACK Tracking API, lahko primernejša, kadar mora ena integracija podpirati UPS in druge prevoznike.

Pravilna izvedba je odvisna od sistema, ki ga gradite. Trgovec morda potrebuje posodobitve dostave na strani naročila, skladiščna ekipa lahko potrebuje opozorila o izjemah, podjetniška platforma pa morda potrebuje normalizirane podatke o sledenju za več prevoznikov. Branje dokumentacije skozi prizmo teh primerov uporabe pomaga preprečiti pogosto napako: enačenje uspešnega odgovora API-ja s celovito rešitvijo za preglednost pošiljk.

Na katera vprašanja bi vam morala pomagati odgovoriti dokumentacija API-ja za sledenje UPS

Pred pisanjem kode razjasnite štiri vprašanja:

• Ali integrirate samo UPS ali bo sistem sledil več prevoznikom?
• Ali potrebujete trenutni status paketa, celotno zgodovino pregledov ali oboje?
• Ali bo vaša aplikacija zahtevala posodobitve na zahtevo, prejemala obvestila ali uporabljala kombinacijo obojega?
• Kaj naj stranke in notranje ekipe vidijo, ko je pošiljka zamujena, dostavljena, vrnjena ali še ni najdena?

Dokumentacija UPS je primarni vir za aktualne poverilnice, podprte operacije, zahteve za zahteve, polja odgovorov in pogoje komercialnega dostopa. Te podrobnosti se lahko razlikujejo glede na izdelek API, ureditev računa ali različico platforme za razvijalce, zato mora produkcijska koda slediti trenutnemu portalu za razvijalce UPS in ne staremu vzorcu kode.

7 ključnih funkcij, ki jih morajo razvijalci razumeti

1. Preverjanje pristnosti in dostop aplikacije

Preverjanje pristnosti je prva praktična funkcija, saj določa, kako aplikacija dokaže svojo identiteto in pridobi dovoljenje za klic API-ja. Dokumentacija za razvijalce UPS zagotavlja aktualni postopek registracije aplikacije, ustvarjanja poverilnic, zahtevanja dostopa in upravljanja žetonov. Dokumentacija opisuje dostop, temelječ na OAuth, vendar morajo razvijalci pred izvedbo na delujočem portalu preveriti trenutni tok dodelitve, obsege, življenjsko dobo žetona in zahteve okolja.

Poverilnice hranite na strežniški strani. Ne smejo biti vključene v JavaScript brskalnika, mobilne različice, javne repozitorije ali kodo strani za sledenje, vidno odjemalcu. Varnejša arhitektura postavi zaledno storitev med aplikacijo, namenjeno strankam, in UPS. Ta storitev se lahko varno preveri, uveljavlja omejitve zahtev, beleži tehnične rezultate brez razkrivanja skrivnosti in vrača samo podatke o pošiljki, ki jih potrebuje sprednji del.

Razvojne poverilnice ločite od produkcijskih, kjer platforma UPS podpira ločena okolja. Kontrolni seznam za uvedbo mora vključevati shranjevanje skrivnosti, rotacijo, lastništvo dostopa, obravnavo poteklih žetonov in opozorilo, ko začne število napak pri preverjanju pristnosti naraščati.

2. Zahteve s številko za sledenje in kontekst prevoznika

Integracija sledenja potrebuje predvidljiv način za pošiljanje identifikatorja za sledenje in zahtevanje informacij o pošiljki. Pomembna vprašanja niso samo naslov končne točke. Vključujejo sprejeto obliko številke za sledenje, ali zahteva podpira eno ali več številk, kako je prevoznik identificiran in kako API odgovori, ko je številka nepopolna ali še ni prepoznana.

Ne predpostavljajte, da vsak niz, ki je podoben številki za sledenje, pripada UPS. Če vaša aplikacija prejema oznake iz več sistemov za pošiljanje, shranite prevoznika kot ločeno polje, kadar je znan. Usmerjanje, ki upošteva prevoznika, zmanjša število napačnih ujemanj in olajša odpravljanje težav. Ustvari tudi čisto pot za prihodnjo širitev, če vaše podjetje doda drugega prevoznika.

Pred pošiljanjem zahteve preverite vnos, vendar se izogibajte pretirano strogemu preverjanju, ki zavrne veljaven identifikator, ker se je njegova oblika spremenila ali ker je bila oznaka ustvarjena pred kratkim. Odgovor API-ja ostaja merodajno preverjanje. Shranite izvirno vrednost, normalizirano vrednost, uporabljeno za iskanje, prevoznika, referenco naročila in čas zadnje uspešne poizvedbe.

3. Strukturirana shema odgovora

Uporabna dokumentacija API-ja za sledenje UPS pojasnjuje, kako so podatki o pošiljki organizirani in katera polja so neobvezna. Razvijalci morajo pregledati model odgovora za identiteto pošiljke, trenutni status, opis statusa, časovne žige pregledov, lokacije, ocene dostave, informacije o storitvi in podrobnosti na ravni paketa. Manjkajoče polje ni nujno enako polju s prazno vrednostjo in nobenega od njiju ne bi smeli samodejno obravnavati kot neuspešno pošiljko.

Ustvarite normaliziran notranji model, namesto da bi celotno aplikacijo neposredno vezali na imena polj, značilna za ponudnika. Vaša zbirka podatkov bi lahko na primer vsebovala identifikator pošiljke, prevoznika, trenutni status, čas zadnjega dogodka, predvideni čas dostave, čas dostave, kodo izjeme in neobdelan uporabniški tovor ponudnika. Normalizirana polja podpirajo poročanje in uporabniške vmesnike, neobdelani uporabniški tovor pa podpira revizije in prihodnje spremembe preslikav.

Časovne žige ohranite z njihovim odmikom ali informacijami o časovnem pasu, kadar so posredovane. Prikaz pregleda z ene lokacije, kot da se je zgodil v lokalnem času gledalca, lahko ustvari zmedene pripovedi o dostavi. Prav tako statusa prevoznika z več podrobnostmi ne pretvorite v preprostejšo oznako, dokler poslovno pravilo ni dokumentirano.

4. Zgodovina pregledov in razlaga statusa

Vrednost UPS tracking je pogosto v zaporedju dogodkov in ne v eni sami trenutni oznaki. Paket lahko preide skozi ustvarjanje oznake, prevzem, tranzit, pregled ob prihodu, izjemo, dogodek odhoda na dostavo in dostavo. Uporabna integracija shranjuje dogodke po vrstnem redu in, kjer je mogoče, ohranja njihove izvirne opise.

Preslikava statusov zahteva uredniško in operativno presojo. »V tranzitu« lahko zajema več različnih faz, medtem ko lahko »izjema« zahteva razlago, ki je bolj specifična od imena statusa. Vaša aplikacija mora razlikovati vsaj med običajnim premikom, dejavnostjo dostave, dostavljeno pošiljko, izjemo, vrnjeno pošiljko in statusom, ki ga še ni mogoče določiti. Natančna preslikava mora slediti poljem in kodam, dokumentiranim pri UPS, in ne le predpostavkam na podlagi angleških opisov.

Na straneh, namenjenih strankam, prikažite najnovejši pomemben dogodek, njegov čas in kratko razlago. Za notranje poslovanje ohranite celotno zgodovino dogodkov in izvirno besedilo prevoznika. Tako lahko podporno osebje razišče pritožbo, ne da bi od stranke zahtevalo ponovitev informacij, ki jih je sistem že prejel.

5. Ocene dostave in obravnava izjem

Razvijalci se pogosto osredotočijo na običajni potek, vendar ocene dostave in izjeme določajo, ali so podatki za sledenje v praksi uporabni. Pošiljka morda nima ocene, ocena se lahko spremeni ali pa izjema začasno prekine običajno gibanje. Dokumentacijo je treba preveriti glede polj in pogojev, ki predstavljajo te primere.

Ocene nikoli ne predstavljajte kot zagotovila, razen če ustrezni pogoji storitve UPS izrecno podpirajo takšno razlago. V uporabniškem vmesniku oceno označite kot oceno in datum ali časovno okno prikažite natančno tako, kot to podpirajo podatki. Če API ne vrne ocene, prikažite nevtralno sporočilo, kot je »Ocena dostave trenutno ni na voljo«, namesto da bi jo ustvarili na podlagi splošnega pravila o času tranzita.

Poteki obravnave izjem morajo biti izrecni. Odločite se, ali nova izjema sproži e-pošto, nalogo službe za pomoč, dejanje upravljanja naročila ali samo spremembo statusa. Dodajte odstranjevanje dvojnikov, da ponavljajoče se poizvedovanje ne pošlje istega opozorila večkrat. Praktično pravilo je primerjava identifikatorja dogodka ali stabilne kombinacije časa dogodka, statusa in opisa, preden ustvarite novo obvestilo.

6. Napake, ponovni poskusi in operativne omejitve

Dokumentacijo API-ja je treba brati kot operativno pogodbo in ne le kot seznam uspešnih primerov. Razvijalci morajo razumeti napake pri preverjanju pristnosti, neveljavne zahteve, neznane številke za sledenje, začasne izpade storitve, časovne prekoračitve in odgovore o omejitvah hitrosti. Vsaka kategorija si zasluži drugačen odziv.

• Napake pri preverjanju pristnosti morajo ustvariti opozorilo za inženiring in se jih ne sme poskušati znova v nedogled.
• Napake preverjanja je treba zabeležiti z dovolj konteksta za popravek zahteve.
• Začasne napake se lahko ponovijo z eksponentnim umikom in največjim številom poskusov.
• Neznane ali na novo ustvarjene številke za sledenje je mogoče preveriti pozneje, vendar jih ne smemo označiti kot izgubljene.
• Odgovori o omejitvi hitrosti morajo upočasniti urnik poizvedovanja in upoštevati omejitve, navedene v aktualni dokumentaciji UPS.

Uporabite časovne omejitve, odklopnike, identifikatorje zahtev in strukturirane dnevnike. Shranite status odgovora ponudnika, notranji ID pošiljke in časovni žig, pri tem pa izključite žetone za dostop in nepotrebne osebne podatke. Če dokumentacija določa glave odgovorov ali navodila za ponovne poskuse, ta navodila vključite namesto uporabe splošnega pravilnika.

7. Testiranje, spremljanje in pripravljenost za produkcijo

Integracijo API-ja za sledenje je treba testirati z več kot eno uspešno številko za sledenje. Ustvarite testne primere za novo ustvarjeno oznako, pošiljko z več pregledi, izjemo, dostavljen paket, neznano številko, poteklo poverilnico, nepravilno oblikovano zahtevo, časovno prekoračitev in podvojeni dogodek. Natančne testne podatke in vedenje peskovnika je treba potrditi v okolju za razvijalce UPS, saj se podatki o živih pošiljkah in testna okolja ne obnašajo vedno enako.

Spremljajte tehnične in poslovne rezultate. Tehnični kazalniki vključujejo obseg zahtev, zakasnitev, stopnjo časovnih prekoračitev, napake pri preverjanju pristnosti, stopnjo napak ponudnika in število ponovnih poskusov. Poslovni kazalniki vključujejo odstotek pošiljk z nedavnim dogodkom, starost najstarejše neosvežene pošiljke in število naročil, na katere vpliva izjema. Storitev ima lahko nizko stopnjo napak HTTP, vendar še vedno zagotavlja zastarele podatke o sledenju, če se je poizvedovanje ali obdelava dogodkov ustavila.

Pred zagonom dokumentirajte, kako začasno ustaviti poizvedovanje, zamenjati poverilnice, ponovno predvajati neuspešne odgovore, popraviti napačno preslikavo statusa in stopiti v stik s podporo UPS. Uporabniški tovor ponudnika hranite za nadzorovano obdobje hrambe, če je potreben za preiskavo, ter z ustreznim skrbnikom preglejte zahteve glede zasebnosti in hrambe podatkov.

Neposredna integracija UPS ali API za več prevoznikov?

Neposredna integracija UPS je smiselna izbira, kadar je UPS edini predvideni prevoznik, želi ekipa upravljati model, značilen za prevoznika, in je zahtevan dostop do API-ja UPS na voljo. Zagotovi lahko tesno ujemanje z izrazoslovjem in operativnimi postopki UPS.

API za več prevoznikov je lahko boljša arhitekturna izbira, kadar mora ista aplikacija slediti paketom UPS, poštnih operaterjev in drugih logističnih ponudnikov. Pred tehnično odločitvijo je treba pregledati dokumentacijo API-ja 17TRACK glede trenutnega modela preverjanja pristnosti, podprtih operacij, strukture odgovorov, vedenja spletnih kavljev, pogojev uporabe in pokritosti prevoznikov. Njegova vrednost v tem scenariju ni v tem, da bi odpravil potrebo po dokumentaciji, temveč v tem, da lahko razvojna ekipa eno integracijsko plast primerja s stroški vzdrževanja več povezav, značilnih za posamezne prevoznike.

Primerjavo izvedite s konceptnim dokazom. Za vsako možnost uporabite isti življenjski cikel pošiljke ter izmerite trud izvedbe, popolnost polj, svežino dogodkov, vedenje pri ponovnih poskusih, zahteve spletnih kavljev ali poizvedovanja, opazljivost in delo, potrebno ob spremembi odgovora prevoznika. Ponudnika ne izberite samo zato, ker je vzorec zahteve kratek. Boljša izbira je tista, ki podpira operativni rezultat, ki ga mora zagotoviti vaša aplikacija.

Praktično zaporedje izvedbe

1. Določite uporabniške in operativne rezultate, kot sta stran za sledenje strankam ali čakalna vrsta izjem.
2. Potrdite, ali je obseg omejen na UPS ali vključuje več prevoznikov.
3. Preberite aktualno uradno dokumentacijo za preverjanje pristnosti, zahteve za sledenje, polja odgovorov, napake, omejitve in testiranje.
4. Ustvarite od ponudnika neodvisen model pošiljke in dogodka.
5. Izvedite varno preverjanje pristnosti na strežniški strani in preverjanje vnosov.
6. Neobdelane odgovore in normalizirana polja shranjujte ločeno.
7. Dodajte poizvedovanje ali sprejemanje dogodkov z odstranjevanjem dvojnikov in umikom.
8. Testirajte običajne, zamujene, izjemne, neznane in neuspešne zahteve.
9. Zaženite sistem s spremljanjem svežine, napak in zastarelih pošiljk.

To zaporedje preprečuje, da bi klic API-ja postal celotna zasnova. Sledenje je neprekinjen podatkovni proces: aplikacija mora pridobiti dogodke, jih skrbno razlagati, jasno predstaviti in se obnoviti, ko ponudnik ali omrežje nista na voljo.

Pogosta vprašanja

Kaj naj najprej preberem v dokumentaciji API-ja za sledenje UPS?

Začnite s preverjanjem pristnosti in operacijo sledenja. Nato preglejte zahteve zahtev, polja odgovorov, vedenje pri napakah, omejitve uporabe in navodila za testiranje. Ti razdelki pokažejo, ali API ustreza vašemu varnostnemu modelu in podatkovnim zahtevam, preden vložite sredstva v celotno integracijo.

Ali lahko API za sledenje UPS uporabim za stran za sledenje, namenjeno strankam?

Da, API lahko zagotavlja podatke za stran, namenjeno strankam, vendar mora biti stran strežena prek vašega zaledja, namesto da bi bile poverilnice API-ja izpostavljene v brskalniku. Stran zasnujte tako, da razlikuje med trenutnim statusom, zgodovino pregledov, ocenami in izjemami, ter se izogibajte predstavljanju ocen kot zagotovil.

Ali je treba številke za sledenje neprekinjeno poizvedovati?

Ni nujno. Pogostost poizvedovanja mora odražati fazo pošiljke, poslovno nujnost, dokumentirane omejitve uporabe in to, ali je na voljo možnost, temelječa na dogodkih. Za nespremenjene pošiljke uporabite umik, po dostavi ali končnem statusu vrnitve pa poizvedovanje ustavite ali zmanjšajte.

Kakšna je razlika med neznano številko za sledenje in izgubljenim paketom?

Neznana številka za sledenje pomeni, da trenutna zahteva ni vrnila prepoznanega rezultata pošiljke. Morda je bila številka pravkar ustvarjena, napačno vnesena, usmerjena k napačnemu prevozniku ali začasno nedostopna. Brez ločenega poslovnega postopka in podpornih dokazov je ne smemo označiti kot izgubljeno.

Kdaj je vredno razmisliti o API-ju za sledenje več prevoznikov?

O njem je vredno razmisliti, ko mora vaša aplikacija podpirati več prevoznikov ali ko bi vzdrževanje ločenih preverjanj pristnosti, shem, preslikav statusov in pravilnikov napak povzročilo veliko operativnega dela. Ponudnike primerjajte z uporabo resničnih scenarijev pošiljk in aktualne informacije o prevoznikih ter funkcijah preverite v njihovi uradni dokumentaciji.

Viri

• UPS Developer Portal — uradna vstopna točka za izdelke API UPS, nastavitev aplikacij, preverjanje pristnosti in vire za razvijalce.
• UPS Tracking — uradna storitev sledenja UPS in referenca izrazoslovja.
• 17TRACK Tracking API — uradna stran izdelka za ocenjevanje integracije sledenja več prevoznikov.
• 17TRACK API Documentation — uradna dokumentacija za razvijalce z aktualnimi podrobnostmi API-ja in zahtevami za integracijo.