Dokumentacioni i API-së së gjurmimit të UPS: 7 veçori kryesore që zhvilluesit duhet të dinë

Dokumentacioni i API-së së gjurmimit të UPS është më i dobishëm kur ndihmon një zhvillues të kalojë nga një numër gjurmimi te një përvojë e besueshme e statusit të dërgesës. Shtatë fushat që duhen shqyrtuar janë autentikimi, kërkesat e gjurmimit, skemat e përgjigjeve, historiku i ngjarjeve, trajtimi i gabimeve, kufizimet operacionale dhe testimi. UPS ofron platformën e vet për zhvilluesit për integrime të drejtpërdrejta me UPS, ndërsa një shërbim me shumë transportues, si 17TRACK Tracking API, mund të jetë më i përshtatshëm kur një integrim duhet të mbështesë UPS dhe transportues të tjerë.

Implementimi i duhur varet nga sistemi që po ndërtoni. Një shitës me pakicë mund të ketë nevojë për përditësime të dorëzimit në faqen e porosisë, një ekip magazine mund të ketë nevojë për sinjalizime për përjashtime, ndërsa një platformë ndërmarrjeje mund të ketë nevojë për të dhëna të standardizuara gjurmimi për disa transportues. Leximi i dokumentacionit përmes këtyre rasteve të përdorimit ndihmon në parandalimin e një gabimi të zakonshëm: trajtimin e një përgjigjeje të suksesshme të API-së si të ishte e njëjtë me një zgjidhje të plotë për dukshmërinë e dërgesës.

Çfarë duhet t'ju ndihmojë të përgjigjeni dokumentacioni i API-së së gjurmimit të UPS

Para se të shkruani kod, sqaroni katër pyetje:

• A po integroni vetëm UPS, apo sistemi do të gjurmojë disa transportues?
• Keni nevojë për statusin aktual të pakos, historikun e plotë të skanimeve, apo të dyja?
• A do të kërkojë aplikacioni juaj përditësime sipas kërkesës, do të marrë njoftime, apo do të përdorë një kombinim të të dyjave?
• Çfarë duhet të shohin klientët dhe ekipet e brendshme kur një dërgesë vonohet, dorëzohet, kthehet ose ende nuk është gjetur?

Dokumentacioni i UPS është burimi kryesor për kredencialet aktuale, operacionet e mbështetura, kërkesat e kërkesave, fushat e përgjigjeve dhe kushtet e aksesit komercial. Këto detaje mund të ndryshojnë sipas produktit API, marrëveshjes së llogarisë ose versionit të platformës së zhvilluesve, ndaj kodi i prodhimit duhet të ndjekë portalin aktual të zhvilluesve të UPS dhe jo të mbështetet në një shembull të vjetër kodi.

7 veçori kryesore që zhvilluesit duhet të kuptojnë

1. Autentikimi dhe aksesi i aplikacionit

Autentikimi është veçoria e parë praktike, sepse përcakton se si një aplikacion provon identitetin e tij dhe merr leje për të thirrur API-në. Dokumentacioni i zhvilluesve të UPS përshkruan procesin aktual për regjistrimin e një aplikacioni, krijimin e kredencialeve, kërkimin e aksesit dhe menaxhimin e tokenëve. Dokumentacioni përshkruan akses të bazuar në OAuth për API-të e UPS, por zhvilluesit duhet të konfirmojnë rrjedhën aktuale të autorizimit, fushëveprimin, jetëgjatësinë e tokenit dhe kërkesat e mjedisit në portalin aktiv para implementimit.

Mbajini kredencialet në anën e serverit. Ato nuk duhet të vendosen në JavaScript të shfletuesit, ndërtime celulare, depo publike ose kod të faqes së gjurmimit të dukshëm për klientin. Një arkitekturë më e sigurt vendos një shërbim backend midis aplikacionit të dukshëm për klientin dhe UPS. Ky shërbim mund të autentikohet në mënyrë të sigurt, të zbatojë kufijtë e kërkesave, të regjistrojë rezultatet teknike pa ekspozuar sekretet dhe të kthejë vetëm të dhënat e dërgesës që i nevojiten pjesës së përparme.

Gjithashtu, ndani kredencialet e zhvillimit nga kredencialet e prodhimit kur platforma UPS mbështet mjedise të ndara. Një listë kontrolli e vendosjes duhet të përfshijë ruajtjen e sekreteve, rotacionin, pronësinë e aksesit, trajtimin e tokenëve të skaduar dhe një sinjalizim kur dështimet e autentikimit fillojnë të rriten.

2. Kërkesat me numër gjurmimi dhe konteksti i transportuesit

Një integrim gjurmimi ka nevojë për një mënyrë të parashikueshme për të dërguar një identifikues gjurmimi dhe për të kërkuar informacion mbi dërgesën. Pyetjet e rëndësishme nuk lidhen vetëm me adresën e endpoint-it. Ato përfshijnë formatin e pranuar të numrit të gjurmimit, nëse kërkesa mbështet një numër apo disa numra, si identifikohet transportuesi dhe si përgjigjet API-ja kur numri është i paplotë ose ende nuk njihet.

Mos supozoni se çdo varg që ngjan me një numër gjurmimi i përket UPS. Nëse aplikacioni juaj merr etiketa nga disa sisteme transporti, ruajeni transportuesin si fushë të veçantë sa herë që dihet. Drejtimi sipas transportuesit redukton përputhjet e gabuara dhe e bën më të lehtë zgjidhjen e problemeve. Gjithashtu krijon një rrugë të pastër për zgjerimin e ardhshëm nëse biznesi juaj shton një transportues tjetër.

Vërtetoni hyrjen para se të bëni një kërkesë, por shmangni vërtetimin tepër të rreptë që refuzon një identifikues të vlefshëm sepse formati i tij ka ndryshuar ose sepse etiketa është krijuar së fundmi. Përgjigjja e API-së mbetet kontrolli autoritativ. Ruani vlerën origjinale, një vlerë të normalizuar të përdorur për kërkim, transportuesin, referencën e porosisë dhe kohën e kërkesës së fundit të suksesshme.

3. Një skemë e strukturuar përgjigjeje

Dokumentacioni i dobishëm i API-së së gjurmimit të UPS shpjegon si organizohen të dhënat e dërgesës dhe cilat fusha janë opsionale. Zhvilluesit duhet të shqyrtojnë modelin e përgjigjes për identitetin e dërgesës, statusin aktual, përshkrimin e statusit, vulat kohore të skanimeve, vendndodhjet, vlerësimet e dorëzimit, informacionin e shërbimit dhe detajet në nivel pakete. Një fushë që mungon nuk është domosdoshmërisht e njëjtë me një fushë që përmban vlerë bosh dhe asnjëra nuk duhet të trajtohet automatikisht si dërgesë e dështuar.

Ndërtoni një model të brendshëm të normalizuar në vend që ta lidhni të gjithë aplikacionin drejtpërdrejt me emrat specifikë të fushave të ofruesit. Për shembull, baza juaj e të dhënave mund të ruajë një identifikues dërgese, transportuesin, statusin aktual, kohën e ngjarjes së fundit, kohën e vlerësuar të dorëzimit, kohën e dorëzimit, kodin e përjashtimit dhe ngarkesën e papërpunuar të ofruesit. Fushat e normalizuara mbështesin raportimin dhe ndërfaqet e përdoruesit; ngarkesa e papërpunuar mbështet auditimet dhe ndryshimet e ardhshme të hartëzimit.

Ruani vulat kohore me zhvendosjen ose informacionin e zonës kohore kur ofrohet. Shfaqja e një skanimi nga një vend sikur të kishte ndodhur në kohën lokale të shikuesit mund të krijojë rrëfime konfuze për dorëzimin. Po kështu, mos e shndërroni një status të detajuar të transportuesit në një etiketë më të thjeshtë derisa rregulli i biznesit të jetë dokumentuar.

4. Historiku i skanimeve dhe interpretimi i statusit

Vlera e UPS tracking shpesh qëndron te sekuenca e ngjarjeve dhe jo te një etiketë e vetme aktuale. Një pako mund të kalojë përmes krijimit të etiketës, marrjes, transportit, skanimit të mbërritjes, një përjashtimi, daljes për dorëzim dhe dorëzimit. Një integrim i përdorshëm i ruan ngjarjet sipas rendit dhe mban përshkrimet e tyre origjinale kur është e mundur.

Hartëzimi i statusit kërkon gjykim editorial dhe operacional. “Në transport” mund të mbulojë disa faza të ndryshme, ndërsa “përjashtim” mund të kërkojë një shpjegim më specifik se emri i statusit. Aplikacioni juaj duhet të dallojë të paktën midis lëvizjes normale, aktivitetit të dorëzimit, të dorëzuarës, përjashtimit, kthimit dhe një statusi që ende nuk mund të përcaktohet. Hartëzimi i saktë duhet të ndjekë fushat dhe kodet e dokumentuara nga UPS, jo supozime të bazuara vetëm në përshkrimet në anglisht.

Për faqet e dukshme për klientin, shfaqni ngjarjen më të fundit kuptimplotë, kohën e saj dhe një shpjegim të shkurtër. Për operacionet e brendshme, ruani historikun e plotë të ngjarjeve dhe formulimin origjinal të transportuesit. Kjo u lejon stafit të mbështetjes të hetojë një ankesë pa i kërkuar klientit të përsërisë informacionin që sistemi e ka marrë tashmë.

5. Vlerësimet e dorëzimit dhe trajtimi i përjashtimeve

Zhvilluesit shpesh përqendrohen te rrjedha normale, por vlerësimet e dorëzimit dhe përjashtimet përcaktojnë nëse të dhënat e gjurmimit janë praktike. Një dërgesë mund të mos ketë vlerësim, vlerësimi mund të ndryshojë ose një përjashtim mund të ndërpresë përkohësisht lëvizjen normale. Dokumentacioni duhet të kontrollohet për fushat dhe kushtet që përfaqësojnë këto raste.

Mos e paraqitni kurrë një vlerësim si garanci, përveçse kur kushtet përkatëse të shërbimit të UPS e mbështesin shprehimisht këtë interpretim. Në ndërfaqen e përdoruesit, etiketojeni një vlerësim si vlerësim dhe shfaqeni datën ose intervalin kohor saktësisht siç e mbështesin të dhënat. Nëse API-ja nuk jep një vlerësim, shfaqni një mesazh neutral si “Aktualisht nuk ka vlerësim të disponueshëm për dorëzimin”, në vend që të shpikni një të tillë nga një rregull i përgjithshëm për kohën e transportit.

Rrjedhat e punës për përjashtimet duhet të jenë të qarta. Vendosni nëse një përjashtim i ri shkakton një email, një detyrë për ndihmën teknike, një veprim në menaxhimin e porosisë ose vetëm një ndryshim statusi. Shtoni deduplikimin në mënyrë që kërkimi i përsëritur të mos dërgojë të njëjtin sinjalizim disa herë. Një rregull praktik është të krahasoni identifikuesin e ngjarjes ose një kombinim të qëndrueshëm të kohës së ngjarjes, statusit dhe përshkrimit para se të krijoni një njoftim të ri.

6. Gabimet, riprovimet dhe kufizimet operacionale

Dokumentacioni i API-së duhet të lexohet si një kontratë operacionale dhe jo vetëm si një listë shembujsh të suksesshëm. Zhvilluesit duhet të kuptojnë gabimet e autentikimit, kërkesat e pavlefshme, numrat e panjohur të gjurmimit, dështimet e përkohshme të shërbimit, ndërprerjet dhe përgjigjet për kufirin e kërkesave. Çdo kategori meriton një përgjigje të ndryshme.

• Dështimet e autentikimit duhet të krijojnë një sinjalizim inxhinierik dhe nuk duhet të riprovohen pafundësisht.
• Gabimet e vërtetimit duhet të regjistrohen me kontekst të mjaftueshëm për korrigjimin e kërkesës.
• Dështimet e përkohshme mund të riprovohen me tërheqje eksponenciale dhe një numër maksimal përpjekjesh.
• Numrat e panjohur ose të krijuar rishtazi të gjurmimit mund të kontrollohen përsëri më vonë, por nuk duhet të klasifikohen si të humbur.
• Përgjigjet për kufirin e kërkesave duhet të ngadalësojnë planin e kërkimeve dhe të respektojnë kufijtë e përcaktuar në dokumentacionin aktual të UPS.

Përdorni kufizime kohore, ndërprerës qarku, identifikues kërkesash dhe regjistra të strukturuar. Ruani statusin e përgjigjes së ofruesit, ID-në e brendshme të dërgesës dhe vulën kohore, duke përjashtuar tokenët e aksesit dhe informacionin personal të panevojshëm. Nëse dokumentacioni specifikon tituj përgjigjesh ose udhëzime për riprovim, përfshijini ato në vend që të zbatoni një politikë të përgjithshme.

7. Testimi, monitorimi dhe gatishmëria për prodhim

Një integrim i API-së së gjurmimit duhet të testohet me më shumë se një numër gjurmimi të suksesshëm. Krijoni raste testimi për një etiketë të krijuar rishtazi, një dërgesë me disa skanime, një përjashtim, një pako të dorëzuar, një numër të panjohur, një kredencial të skaduar, një kërkesë të keqformuar, një ndërprerje dhe një ngjarje të kopjuar. Të dhënat e sakta të testimit dhe sjellja e sandbox-it duhet të konfirmohen në mjedisin e zhvilluesve të UPS, sepse të dhënat e dërgesave reale dhe mjediset e testimit nuk sillen gjithmonë në mënyrë identike.

Monitoroni rezultatet teknike dhe të biznesit. Metrikat teknike përfshijnë volumin e kërkesave, vonesën, shkallën e ndërprerjeve, dështimet e autentikimit, shkallën e gabimeve të ofruesit dhe numrin e riprovimeve. Metrikat e biznesit përfshijnë përqindjen e dërgesave me një ngjarje të fundit, moshën e dërgesës më të vjetër të papërditësuar dhe numrin e porosive të prekura nga një përjashtim. Një shërbim mund të ketë një shkallë të ulët gabimesh HTTP dhe gjithsesi të ofrojë informacion të vjetruar gjurmimi nëse kërkimi ose përpunimi i ngjarjeve është ndalur.

Para nisjes, dokumentoni si të ndaloni kërkimet, të rrotulloni kredencialet, të riluani përgjigjet e dështuara, të korrigjoni një hartëzim të gabuar statusi dhe të kontaktoni mbështetjen e UPS. Mbajeni ngarkesën e ofruesit për një periudhë të kontrolluar ruajtjeje nëse nevojitet për hetim dhe shqyrtoni kërkesat për privatësinë dhe ruajtjen e të dhënave me përgjegjësin përkatës.

Integrim i drejtpërdrejtë me UPS apo API me shumë transportues?

Një integrim i drejtpërdrejtë me UPS është një zgjedhje e arsyeshme kur UPS është i vetmi transportues në fushëveprim, ekipi dëshiron të menaxhojë modelin specifik të transportuesit dhe aksesi i kërkuar në API-në e UPS është i disponueshëm. Ai mund të ofrojë një përputhje të ngushtë me terminologjinë dhe proceset operacionale të UPS.

Një API me shumë transportues mund të jetë më e përshtatshme në aspektin arkitekturor kur i njëjti aplikacion duhet të gjurmojë pako nga UPS, operatorë postarë dhe ofrues të tjerë logjistikë. 17TRACK API documentation duhet të shqyrtohet për modelin aktual të autentikimit, operacionet e mbështetura, strukturën e përgjigjeve, sjelljen e webhook-eve, kushtet e përdorimit dhe mbulimin e transportuesve para se të merret një vendim teknik. Vlera e tij në këtë skenar nuk qëndron në zëvendësimin e nevojës për dokumentacion; qëndron në faktin se ekipi i zhvillimit mund të vlerësojë një shtresë integrimi kundrejt kostos së mirëmbajtjes së disa lidhjeve specifike për transportuesit.

Bëjeni krahasimin me një provë koncepti. Përdorni të njëjtin cikël jetësor të dërgesës për secilin opsion dhe matni përpjekjen e implementimit, plotësinë e fushave, freskinë e ngjarjeve, sjelljen e riprovimeve, kërkesat për webhook ose kërkim, vëzhgueshmërinë dhe punën e nevojshme kur një transportues ndryshon përgjigjen e tij. Mos zgjidhni një ofrues vetëm sepse një kërkesë shembull është e shkurtër. Zgjedhja më e mirë është ajo që mbështet rezultatin operacional që duhet të ofrojë aplikacioni juaj.

Një sekuencë praktike implementimi

1. Përcaktoni rezultatet për përdoruesit dhe operacionet, si një faqe gjurmimi për klientin ose një radhë përjashtimesh.
2. Konfirmoni nëse fushëveprimi është vetëm UPS apo përfshin disa transportues.
3. Lexoni dokumentacionin zyrtar aktual për autentikimin, kërkesat e gjurmimit, fushat e përgjigjeve, gabimet, kufijtë dhe testimin.
4. Krijoni një model neutral ndaj ofruesit për dërgesat dhe ngjarjet.
5. Implementoni autentikim të sigurt në anën e serverit dhe vërtetim të hyrjeve.
6. Ruani përgjigjet e papërpunuara dhe fushat e normalizuara veçmas.
7. Shtoni kërkimin ose marrjen e ngjarjeve me deduplikim dhe tërheqje progresive.
8. Testoni kërkesat normale, të vonuara, të jashtëzakonshme, të panjohura dhe të dështuara.
9. Niseni me monitorim për freskinë, dështimet dhe dërgesat e vjetruara.

Kjo sekuencë e pengon thirrjen e API-së të bëhet i gjithë dizajni. Gjurmimi është një proces i vazhdueshëm i të dhënave: aplikacioni duhet të marrë ngjarje, t'i interpretojë me kujdes, t'i paraqesë qartë dhe të rikuperohet kur ofruesi ose rrjeti nuk janë të disponueshëm.

Pyetje të shpeshta

Çfarë duhet të lexoj së pari në dokumentacionin e API-së së gjurmimit të UPS?

Filloni me autentikimin dhe operacionin e gjurmimit. Më pas shqyrtoni kërkesat e kërkesës, fushat e përgjigjes, sjelljen e gabimeve, kufijtë e përdorimit dhe udhëzimet e testimit. Këto seksione tregojnë nëse API-ja përshtatet me modelin tuaj të sigurisë dhe kërkesat e të dhënave para se të investoni në një integrim të plotë.

A mund të përdor një API gjurmimi të UPS për një faqe gjurmimi të dukshme për klientin?

Po, një API mund të ofrojë të dhëna për një faqe të dukshme për klientin, por faqja duhet të shërbehet përmes backend-it tuaj dhe jo të ekspozojë kredencialet e API-së në shfletues. Dizajnojeni faqen që të dallojë statusin aktual, historikun e skanimeve, vlerësimet dhe përjashtimet, dhe shmangni paraqitjen e vlerësimeve si garanci.

A duhet të kërkohen vazhdimisht numrat e gjurmimit?

Jo domosdoshmërisht. Frekuenca e kërkimit duhet të pasqyrojë fazën e dërgesës, urgjencën e biznesit, kufijtë e dokumentuar të përdorimit dhe nëse është e disponueshme një mundësi e bazuar në ngjarje. Përdorni tërheqje progresive për dërgesat pa ndryshime dhe ndaloni ose reduktoni kërkimet pas dorëzimit ose një statusi përfundimtar kthimi.

Cili është ndryshimi midis një numri të panjohur gjurmimi dhe një pakoje të humbur?

Një numër i panjohur gjurmimi do të thotë se kërkesa aktuale nuk ktheu një rezultat të njohur dërgese. Ai mund të jetë krijuar rishtazi, të jetë futur gabim, të jetë drejtuar te transportuesi i gabuar ose të jetë përkohësisht i padisponueshëm. Nuk duhet të etiketohet si i humbur pa një proces të veçantë biznesi dhe prova mbështetëse.

Kur ia vlen të merret në konsideratë një API gjurmimi me shumë transportues?

Ia vlen të vlerësohet kur aplikacioni juaj duhet të mbështesë disa transportues ose kur mirëmbajtja e autentikimit, skemave, hartëzimeve të statusit dhe politikave të gabimeve të ndara do të krijonte shumë punë operacionale. Krahasoni ofruesit duke përdorur skenarë realë dërgesash dhe verifikoni informacionin aktual për transportuesit dhe veçoritë në dokumentacionin e tyre zyrtar.

Burimet

• UPS Developer Portal — pikë zyrtare aksesi për produktet API të UPS, konfigurimin e aplikacioneve, autentikimin dhe burimet për zhvilluesit.
• UPS Tracking — shërbimi zyrtar i gjurmimit të UPS dhe referencë për terminologjinë.
• 17TRACK Tracking API — faqe zyrtare e produktit për vlerësimin e një integrimi gjurmimi me shumë transportues.
• 17TRACK API Documentation — dokumentacion zyrtar për zhvilluesit mbi detajet aktuale të API-së dhe kërkesat e integrimit.