Si të përdorni API-në e gjurmimit të UPS: Udhëzues konfigurimi hap pas hapi

Për të përdorur UPS Tracking API, krijoni një llogari UPS Developer, regjistroni një aplikacion, merrni kredencialet OAuth 2.0, kërkoni një token aksesi dhe dërgoni kërkesa të autentikuara për gjurmim me një numër të vlefshëm gjurmimi UPS. Etiketat e sakta të portalit, hapat e miratimit dhe kërkesat e API-së mund të ndryshojnë, prandaj konfirmoni udhëzimet aktuale në UPS Developer Portal zyrtar para se ta aktivizoni një integrim prodhimi.

Ky udhëzues është për zhvilluesit dhe ekipet e operacioneve të tregtisë elektronike që kanë nevojë për statusin e dërgesave brenda një dyqani online, sistemi të menaxhimit të porosive, rrjedhe pune të magazinës, mjeti të shërbimit ndaj klientit ose paneli të brendshëm. Ai përqendrohet te sekuenca e integrimit, vendimet që ndikojnë në besueshmëri dhe kontrollet që parandalojnë dështimet e zakonshme të gjurmimit.

Çfarë bën UPS Tracking API

Një integrim API i lejon softuerit të kërkojë informacion për dërgesat nga UPS, në vend që të kërkojë nga një punonjës ose klient të hapë manualisht faqen e gjurmimit të transportuesit. Aplikacioni juaj mund ta përdorë përgjigjen për të shfaqur statusin më të fundit të njohur, për të identifikuar ngjarjet e dorëzimit, për të mbështetur hetimet e shërbimit ndaj klientit ose për të aktivizuar një rrjedhë pune të brendshme.

API-ja nuk është e njëjtë me një faqe gjurmimi. Një faqe gjurmimi është krijuar që ta lexojë një person. Përgjigjja e API-së është e dhënë e strukturuar që softueri duhet ta analizojë, ta ruajë dhe ta paraqesë. Sistemi juaj mbetet përgjegjës për autentikimin, trajtimin e gabimeve, kërkesat periodike ose mbledhjen e ngjarjeve, ruajtjen e të dhënave, dizajnin e ndërfaqes së përdoruesit dhe çdo rregull biznesi të ndërtuar rreth ngjarjeve të dorëzimit.

Para se të filloni

Përgatitni artikujt e mëposhtëm para se të hapni portalin e zhvilluesve:

• Një llogari UPS Developer ose llojin e llogarisë që kërkohet nga procesi aktual i regjistrimit në UPS.
• Një aplikacion të regjistruar dhe kredencialet e lëshuara për atë aplikacion.
• Një numër testimi gjurmimi ose një metodë tjetër testimi të miratuar. Mos filloni me të dhëna reale të klientëve nëse dokumentacioni i UPS ofron një mjedis ose procedurë të veçantë testimi.
• Një vendim të qartë se cili sistem zotëron regjistrat e dërgesave, ngjarjet e gjurmimit dhe mesazhet e statusit të shfaqura për klientët.
• Një vend të sigurt për ruajtjen e kredencialeve të klientit dhe tokenëve të aksesit. Mos vendosni kurrë sekrete në kodin e shfletuesit, depo publike, pamje ekrani ose aplikacione celulare që mund të inspektohen nga përdoruesit.

Duhet të vendosni gjithashtu nëse aplikacioni juaj ka nevojë vetëm për gjurmim apo për një integrim më të gjerë me UPS. Gjurmimi, tarifimi, transporti, vërtetimi i adresës dhe shërbimet e dokumenteve mund të kenë produkte, leje, formate kërkesash dhe kërkesa operacionale të ndryshme.

Hapi 1: Hapni UPS Developer Portal

Filloni te UPS Developer Portal zyrtar. Rishikoni katalogun aktual të API-ve, udhëzimet e autentikimit, kërkesat e regjistrimit, kushtet dhe informacionin për mjediset. Kërkoni posaçërisht dokumentacionin e Tracking API, në vend që të supozoni se udhëzimet për një shërbim tjetër të UPS zbatohen edhe për gjurmimin.

Portali është burimi i duhur për fushat aktuale të kërkesave, fushat e autorizimit, përkufizimet e përgjigjeve, kufijtë e kërkesave, kodet e gabimeve dhe detajet e mjedisit. Këto detaje mund të ndryshojnë dhe një shembull kodi nga palë të treta mund të përdorë një ndërfaqe më të vjetër të UPS ose një metodë autentikimi të vjetruar.

Hapi 2: Regjistroni një aplikacion

Krijoni një aplikacion në portalin e zhvilluesve dhe zgjidhni API-të e UPS që aplikacioni ka realisht nevojë të përdorë. Për një projekt vetëm për gjurmim, kërkoni vetëm aftësinë e gjurmimit, përveçse kur rrjedha juaj e punës kërkon shërbime shtesë. Kufizimi i lejeve zvogëlon kompleksitetin e konfigurimit dhe e bën më të lehtë zgjidhjen e problemeve më vonë.

Regjistroni identifikuesin dhe sekretin e aplikacionit në një menaxher sekretesh në anën e serverit ose në një sistem të mbrojtur të variablave të mjedisit. Trajtojeni sekretin si një fjalëkalim. Nëse ekspozohet, rrotullojeni përmes procesit të ofruar nga UPS dhe shqyrtoni regjistrat për përdorim të paautorizuar.

Nëse portali kërkon informacion për llogarinë, faturimin, biznesin ose aplikacionin, jepni të dhëna të sakta. Shmangni shpikjen e një rasti përdorimi në prodhim ose përdorimin e informacionit të llogarisë së dikujt tjetër vetëm për të përfunduar një test. Qasja në një shërbim mund të varet nga konfigurimi i llogarisë dhe procesi aktual i miratimit nga UPS.

Hapi 3: Implementoni autentikimin OAuth 2.0

Dokumentacioni aktual i zhvilluesve të UPS përdor autentikim të bazuar në OAuth për API-të e tij. Serveri juaj zakonisht shkëmben kredencialet e aplikacionit përmes rrjedhës së dokumentuar të tokenit dhe merr një token aksesi. Më pas e përfshin atë token në kokën e autorizimit të një kërkese API.

Mbajeni autentikimin të ndarë nga logjika e gjurmimit. Një dizajn praktik ka një komponent që merr dhe ruan në cache një token të vlefshëm dhe një tjetër që thërret pikën fundore të gjurmimit. Komponenti i tokenit duhet të:

• Dërgojë kredencialet vetëm te pika fundore e autorizimit të UPS të dokumentuar.
• Përdorë llojin e përmbajtjes dhe parametrat e grantit të përcaktuar në dokumentacionin aktual të UPS.
• Ruajë tokenin përkohësisht dhe ta ripërdorë derisa të skadojë, në vend që të kërkojë një token të ri për çdo numër gjurmimi.
• Rifreskojë ose rimarrë tokenin kur ndodh kushti i skadimit të dokumentuar.
• Fshehë kredencialet dhe tokenët nga regjistrat e aplikacionit, raportet e gabimeve dhe kërkesat e mbështetjes.

Mos kopjoni një token nga një sesion shfletuesi në një integrim të përhershëm. Një shërbim në backend është përgjithësisht vend më i sigurt për menaxhimin e kredencialeve, sepse i mban sekretet larg kodit publik të klientit.

Hapi 4: Ndërtoni kërkesën e gjurmimit

Përdorni formatin e kërkesës të paraqitur në referencën zyrtare të Tracking API. Një kërkesë tipike përfshin një numër gjurmimi në shteg ose në parametrat e kërkesës, një token aksesi në kokën e autorizimit dhe kokat e kërkuara nga API-ja e UPS. Mos supozoni se numri i gjurmimit është e vetmja vlerë e kërkuar: referenca aktuale mund të përcaktojë koka për versionin, transaksionin, llojin e përmbajtjes ose korrelacionin.

Një model i thjeshtuar kërkese duket kështu:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Ky është një shembull strukturor, jo një pikë fundore për kopjim dhe ngjitje. Përdorni pikën fundore, versionin, kokat dhe emrat e parametrave të publikuar në dokumentacionin e UPS për aplikacionin tuaj. Mbajeni numrin e gjurmimit të normalizuar sipas rregullave të të dhënave të porosive tuaja, por mos hiqni karaktere nëse dokumentacioni i transportuesit nuk konfirmon se kjo është e sigurt.

Hapi 5: Analizoni ngjarjet në modelin tuaj të të dhënave

Përgjigjet e transportuesit shpesh përmbajnë më shumë informacion se një etiketë të vetme statusi. Para se të kodoni faqen e shfaqur për klientët, hartëzoni përgjigjen në një model të brendshëm, si identifikuesi i dërgesës, transportuesi, statusi më i fundit, kodi i ngjarjes, përshkrimi i ngjarjes, vula kohore e ngjarjes, vendndodhja, informacioni i parashikuar i dorëzimit dhe vula kohore e dorëzimit kur është e disponueshme.

Ruajeni përgjigjen origjinale të transportuesit kur politikat tuaja të ruajtjes dhe privatësisë e lejojnë. Një përgjigje e papërpunuar mund të ndihmojë në diagnostikimin e një gabimi hartëzimi ose të shpjegojë pse statusi juaj i normalizuar ndryshon nga formulimi i transportuesit. Në të njëjtën kohë, shmangni shfaqjen e kodeve teknike të ngjarjeve për klientët pa një shpjegim të kuptueshëm.

Mos e trajtoni çdo status si rezultat përfundimtar të dorëzimit. Për shembull, një ngjarje gjatë transportit, një përjashtim, një përpjekje dorëzimi dhe një ngjarje dorëzimi nuk duhet të bashkohen në të njëjtin mesazh për klientin. Krijoni hartëzime të qarta dhe përcaktoni se çfarë ndodh kur UPS shton një vlerë ngjarjeje që kodi juaj nuk e njeh.

Hapi 6: Shtoni riprovimet, vërtetimin dhe monitorimin

Një integrim prodhimi kërkon më shumë se një kërkesë të suksesshme në një konsolë zhvillimi. Shtoni vërtetime dhe masa mbrojtëse operacionale:

• Vërtetimi i hyrjes: refuzoni numrat e gjurmimit bosh, me format të gabuar ose dukshëm të paplotë para se të dërgoni kërkesa.
• Kohët e ndërprerjes: parandaloni që një përgjigje e ngadaltë e transportuesit të bllokojë një rrjedhë të tërë pune të arkëtimit, mbështetjes ose magazinës.
• Rregullat e riprovimit: riprovoni me kujdes dështimet e përkohshme të rrjetit ose shërbimit, duke përdorur vonesë progresive. Mos riprovoni vazhdimisht gabimet e autentikimit ose numrat e pavlefshëm të gjurmimit.
• Ndërgjegjësimi për kufijtë: ndiqni kufijtë dhe rregullat e përdorimit në dokumentacionin e UPS. Ruani në cache rezultatet e fundit kur procesi i biznesit e lejon.
• Gjendjet e panjohura: ruani një ngjarje të panjohur për shqyrtim, në vend që ta etiketoni gabimisht si të dorëzuar ose të humbur.
• Vëzhgueshmëria: regjistroni kohën e kërkesës, kategorinë e përgjigjes dhe informacionin e korrelacionit pa regjistruar sekrete ose të dhëna personale të panevojshme.

Një sistem gjurmimi duhet të përcaktojë gjithashtu sa shpesh rifreskon një dërgesë. Kërkesat shumë të shpeshta mund të krijojnë ngarkesë të shmangshme dhe mund të mos prodhojnë informacion të ri. Kërkesat shumë të rralla mund ta bëjnë një faqe të shfaqur për klientët të duket e vjetruar. Zgjidhni një interval bazuar në vëllimin e dërgesave, urgjencën operacionale, rregullat e transportuesit dhe freskinë që u nevojitet realisht përdoruesve.

Hapi 7: Testoni me skenarë realistë

Testoni më shumë se një dërgesë të dorëzuar me sukses. Përfshini një numër gjurmimi të panjohur, një dërgesë gjatë transportit, një përjashtim, një dërgesë me ngjarje të shumta, një token të skaduar, një ndërprerje kohe, një dështim autorizimi dhe një përgjigje që përmban fusha që analizuesi juaj nuk i pret. Nëse UPS ofron një mjedis ose kredenciale të veçanta testimi, ndiqeni fillimisht atë procedurë.

Kontrolloni të gjithë rrugëtimin nga kërkesa te ndërfaqja e përdoruesit. Konfirmoni që porosia e saktë merr dërgesën e saktë, që vulat kohore shfaqen me zonën kohore të synuar, që ngjarjet e dyfishta nuk krijojnë mesazhe të dyfishta për klientët dhe që një ndërprerje e transportuesit nuk mbishkruan një status më parë të vlefshëm me tekst mashtrues.

Kur një API gjurmimi për shumë transportues është zgjedhje më e mirë

Një integrim i drejtpërdrejtë me UPS mund të jetë i përshtatshëm kur operacioni juaj transporton kryesisht me UPS dhe kërkon kontroll të afërt mbi rrjedhën e punës së transportuesit. Ai bëhet më pak praktik kur porositë mund të kalojnë përmes disa transportuesve, tregjeve, operatorëve postarë ose kompanive rajonale të dorëzimit. Në atë situatë, kredencialet, formatet e përgjigjeve, fjalorët e statuseve dhe rregullat e riprovimit të ndara mund të rrisin punën e mirëmbajtjes.

Një shërbim për shumë transportues si 17TRACK Tracking API mund të ofrojë një model alternativ integrimi për aplikacionet që kanë nevojë për gjurmim nëpër transportues të shumtë. Dokumentacioni i tij për zhvilluesit duhet të shqyrtohet drejtpërdrejt për transportuesit e mbështetur, formatet e kërkesave, autentikimin, kushtet e përdorimit dhe aftësitë e disponueshme. Kjo nuk e bën automatikisht më të mirë se një lidhje e drejtpërdrejtë me UPS: zgjedhja e duhur varet nga përzierja e transportuesve, kërkesat për të dhëna, kontrolli mbi integrimin dhe kufizimet tregtare ose të pajtueshmërisë.

Për një kërkim të drejtpërdrejtë nga konsumatori dhe jo për një integrim zhvilluesi, faqja e gjurmimit të 17TRACK mund të jetë më e përshtatshme se ndërtimi i një lidhjeje API. Për një dyqan online që ka nevojë për përditësime të markuara pas blerjes, shqyrtoni veçmas integrimin përkatës të platformës, në vend që të shtoni punë API që dyqani nuk i kërkon.

Gabime të zakonshme të implementimit

• Përdorimi i shembujve të vjetër: një shembull kodi mund t'i referohet një versioni të hequr, një metode të vjetër autentikimi ose një shërbimi tjetër të UPS.
• Vendosja e sekreteve në kodin frontend: çdo gjë e dërguar në një shfletues duhet të trajtohet si e inspektueshme.
• Supozohet se një rezultat bosh do të thotë mungesë dërgese: verifikoni numrin e gjurmimit, lejet e llogarisë, mjedisin dhe mesazhin e përgjigjes para se të nxirrni një përfundim biznesi.
• Hartëzimi vetëm i tekstit: përshkrimet e statuseve mund të ndryshojnë. Përdorni kodet e dokumentuara dhe ruani vlerat e panjohura për shqyrtim.
• Injorimi i kërkesave të llogarisë dhe përdorimit: kodi teknik mund të jetë i saktë, ndërsa aplikacioni nuk është konfiguruar për shërbimin e kërkuar.
• Rifreskimi pa rregull biznesi: kërkesat e panevojshme mund të rrisin koston, ngarkesën dhe zhurmën operacionale pa përmirësuar përvojën e klientit.

Listë praktike kontrolli para aktivizimit

1. Konfirmoni që aplikacioni përdor dokumentacionin aktual të UPS dhe mjedisin e miratuar.
2. Verifikoni që kredencialet ruhen në anën e serverit dhe mund të rrotullohen.
3. Testoni dështimin e autentikimit, gabimet e transportuesit, hyrjen me format të gabuar dhe ndërprerjet e kohës.
4. Krahasoni statuset e normalizuara me përgjigjen origjinale për dërgesa përfaqësuese.
5. Vendosni një politikë rifreskimi dhe monitoroni vëllimin e kërkesave.
6. Përcaktoni përgjegjësinë për ngjarjet e paidentifikuara, përditësimet e vonuara dhe përshkallëzimet e klientëve.
7. Dokumentoni integrimin në mënyrë që një zhvillues tjetër të mund të përditësojë në mënyrë të sigurt kredencialet, versionet e pikave fundore dhe hartëzimet e statuseve.

FAQ

A më duhet një llogari UPS për të përdorur Tracking API?

Duhet të shqyrtoni kërkesat aktuale të regjistrimit dhe aksesit në UPS Developer Portal. Qasja në API mund të varet nga regjistrimi i aplikacionit, kredencialet, konfigurimi i llogarisë dhe shërbimi specifik që kërkohet. Mos supozoni se hyrja në faqen publike të gjurmimit mund të përdoret në mënyrë të ndërsjellë me aksesin në API për zhvillues.

A është falas UPS Tracking API?

Mos supozoni se qasja në API nuk ka kushte tregtare ose përdorimi. UPS publikon informacionin aktual për shërbimet dhe llogaritë përmes kanaleve të tij zyrtare dhe disa kërkesa mund të varen nga produkti, llogaria ose marrëveshja. Konfirmoni drejtpërdrejt kushtet e zbatueshme para se të planifikoni buxhetin e prodhimit.

A mund ta thërras API-në e UPS drejtpërdrejt nga JavaScript në një shfletues?

Një kërkesë nga shfletuesi mund të ekspozojë kredencialet e aplikacionit dhe të krijojë probleme ndërorigjinore, sigurie dhe kontrolli përdorimi. Një integrim në anën e serverit është përgjithësisht modeli më i sigurt për ruajtjen e sekreteve, marrjen e tokenëve, zbatimin e rregullave të riprovimit dhe kufizimin e qasjes në të dhënat e dërgesave.

Sa shpesh duhet që aplikacioni im të kërkojë përditësime të gjurmimit?

Përdorni një politikë rifreskimi të bazuar në kufijtë e dokumentuar të transportuesit, vëllimin e dërgesave, urgjencën operacionale dhe freskinë e kërkuar nga përdoruesit. Ruani në cache rezultatet e fundit kur është e përshtatshme, përdorni vonesë progresive pas dështimeve të përkohshme dhe shmangni trajtimin e kërkesave të përsëritura si zëvendësim për një aftësi të dokumentuar ngjarjesh ose njoftimesh.

A duhet të përdor një integrim të drejtpërdrejtë me UPS apo një API për shumë transportues?

Një integrim i drejtpërdrejtë me UPS mund t'i përshtatet një rrjedhe pune të përqendruar te UPS që kërkon kontroll specifik mbi transportuesin. Një API për shumë transportues mund të zvogëlojë numrin e integrimeve kur dërgesat tuaja përdorin disa transportues. Krahasoni transportuesit e mbështetur, autentikimin, fushat e të dhënave, kërkesat për besueshmëri, kushtet e përdorimit dhe përpjekjen e implementimit para se të zgjidhni.

Burimet

• UPS Developer Portal — katalogu zyrtar i API-ve, aksesi i aplikacioneve, autentikimi dhe dokumentacioni për zhvilluesit.
• UPS Technology Integration — informacion zyrtar për integrimin e teknologjisë së UPS me sistemet e biznesit.
• 17TRACK Tracking API — pikënisja zyrtare e produktit dhe zhvilluesve për gjurmimin nëpër shumë transportues.
• 17TRACK API Documentation — dokumentacioni zyrtar i API-së për autentikimin, kërkesat dhe trajtimin e përgjigjeve.