A UPS Tracking API használata: lépésről lépésre bemutatott beállítási útmutató

A UPS Tracking API használatához hozzon létre UPS Developer-fiókot, regisztráljon egy alkalmazást, szerezze be az OAuth 2.0 hitelesítő adatokat, kérjen hozzáférési tokent, majd érvényes UPS nyomkövetési számmal küldjön hitelesített nyomkövetési kéréseket. A portál pontos címkéi, a jóváhagyási lépések és az API-követelmények változhatnak, ezért éles integráció indítása előtt ellenőrizze az aktuális útmutatást a hivatalos UPS Developer Portalon.

Ez az útmutató azoknak a fejlesztőknek és e-kereskedelmi üzemeltetési csapatoknak szól, akiknek egy online áruházban, rendeléskezelő rendszerben, raktári munkafolyamatban, ügyfélszolgálati eszközben vagy belső irányítópulton van szükségük a küldemények állapotára. Az integrációs sorrendre, a megbízhatóságot befolyásoló döntésekre és a gyakori nyomkövetési hibákat megelőző ellenőrzésekre összpontosít.

Mire használható a UPS Tracking API?

Az API-integráció lehetővé teszi, hogy a szoftver a fuvarozó nyomkövetési oldalának manuális megnyitása helyett közvetlenül a UPS-től kérjen le szállítási információkat. Az alkalmazás a választ felhasználhatja a legutóbb ismert állapot megjelenítésére, kézbesítési események azonosítására, ügyfélszolgálati vizsgálatok támogatására vagy belső munkafolyamatok elindítására.

Az API nem azonos a nyomkövetési oldallal. A nyomkövetési oldalt emberek általi olvasásra tervezték. Az API-válasz strukturált adat, amelyet a szoftvernek fel kell dolgoznia, tárolnia és megjelenítenie. A rendszer továbbra is felelős a hitelesítésért, a hibakezelésért, a lekérdezésért vagy az események gyűjtéséért, az adatmegőrzésért, a felhasználói felület kialakításáért és a kézbesítési eseményekhez kapcsolódó üzleti szabályokért.

Mielőtt elkezdené

A fejlesztői portál megnyitása előtt készítse elő a következőket:

• UPS Developer-fiók vagy az aktuális UPS-regisztrációs folyamat által megkövetelt fióktípus.
• Regisztrált alkalmazás és az ahhoz kiadott hitelesítő adatok.
• Tesztelési nyomkövetési szám vagy más jóváhagyott tesztelési módszer. Ne élő ügyféladatokkal kezdjen, ha a UPS dokumentáció külön tesztkörnyezetet vagy tesztelési eljárást biztosít.
• Egyértelmű döntés arról, hogy melyik rendszer kezeli a küldeményrekordokat, a nyomkövetési eseményeket és az ügyfeleknek megjelenő állapotüzeneteket.
• Biztonságos hely az ügyfél-hitelesítő adatok és a hozzáférési tokenek tárolására. Soha ne helyezzen titkos adatokat böngészőkódba, nyilvános tárhelyekre, képernyőképekre vagy olyan mobilalkalmazásokba, amelyeket a felhasználók megvizsgálhatnak.

Azt is el kell döntenie, hogy alkalmazásának csak nyomkövetésre vagy szélesebb körű UPS-integrációra van-e szüksége. A nyomkövetés, díjszámítás, szállítás, címellenőrzés és dokumentumszolgáltatások eltérő termékekkel, jogosultságokkal, kérésformátumokkal és üzemeltetési követelményekkel rendelkezhetnek.

1. lépés: Nyissa meg a UPS Developer Portalt

Kezdje a hivatalos UPS Developer Portalon. Tekintse át az aktuális API-katalógust, a hitelesítési útmutatót, a regisztrációs követelményeket, a feltételeket és a környezetre vonatkozó információkat. Kifejezetten a Tracking API dokumentációját keresse, és ne feltételezze, hogy egy másik UPS-szolgáltatáshoz tartozó útmutatás a nyomkövetésre is érvényes.

A portál a jelenlegi kérésmezők, engedélyezési hatókörök, válaszdefiníciók, sebességkorlátok, hibakódok és környezeti részletek megfelelő forrása. Ezek az adatok változhatnak, és egy külső kódpélda régebbi UPS-felületet vagy elavult hitelesítési módszert használhat.

2. lépés: Regisztráljon egy alkalmazást

Hozzon létre egy alkalmazást a fejlesztői portálon, és válassza ki azokat a UPS API-kat, amelyekre az alkalmazásnak ténylegesen szüksége van. Kizárólag nyomkövetési projekt esetén csak a nyomkövetési funkciót kérje, kivéve, ha a munkafolyamat további szolgáltatásokat igényel. A jogosultságok korlátozása csökkenti a konfiguráció összetettségét, és megkönnyíti a későbbi hibaelhárítást.

Az alkalmazásazonosítót és a titkos kulcsot szerveroldali titkoskulcs-kezelőben vagy védett környezeti változórendszerben tárolja. A titkos kulcsot jelszóként kezelje. Ha nyilvánosságra kerül, a UPS által biztosított folyamaton keresztül cserélje le, és ellenőrizze a naplókat jogosulatlan használat jelei után kutatva.

Ha a portál fiók-, számlázási, üzleti vagy alkalmazásinformációkat kér, adjon meg pontos adatokat. Ne találjon ki éles használati esetet, és ne használja más fiókadatait pusztán egy teszt befejezéséhez. A szolgáltatáshoz való hozzáférés a fiók konfigurációjától és az aktuális UPS-jóváhagyási folyamattól függhet.

3. lépés: Valósítsa meg az OAuth 2.0 hitelesítést

A jelenlegi UPS-fejlesztői dokumentáció API-jai OAuth-alapú hitelesítést használnak. A szerver általában a dokumentált tokenfolyamaton keresztül kicseréli az alkalmazás hitelesítő adatait, és hozzáférési tokent kap. Ezt követően a tokent az API-kérés engedélyezési fejlécében küldi el.

A hitelesítést tartsa külön a nyomkövetési logikától. Praktikus kialakítás esetén az egyik komponens érvényes tokent szerez be és gyorsítótáraz, egy másik pedig meghívja a nyomkövetési végpontot. A tokenkomponensnek a következőket kell tennie:

• Csak a dokumentált UPS-engedélyezési végpontra küldjön hitelesítő adatokat.
• Az aktuális UPS-dokumentációban megadott tartalomtípust és grant-paramétereket használja.
• Ideiglenesen tárolja és lejáratáig használja újra a tokent, ahelyett hogy minden nyomkövetési számhoz új tokent kérne.
• A dokumentált lejárati feltétel bekövetkezésekor frissítse vagy szerezze be újra a tokent.
• Takarja ki a hitelesítő adatokat és tokeneket az alkalmazásnaplókból, hibajelentésekből és támogatási jegyekből.

Ne másoljon böngésző-munkamenetből származó tokent állandó integrációba. A háttérszolgáltatás általában biztonságosabb hely a hitelesítő adatok kezelésére, mivel távol tartja a titkos adatokat a nyilvános klienskódtól.

4. lépés: Építse fel a nyomkövetési kérést

A hivatalos Tracking API-referenciában bemutatott kérésformátumot használja. Egy tipikus kérés tartalmazza a nyomkövetési számot az útvonalban vagy a kérés paraméterei között, a hozzáférési tokent az engedélyezési fejlécben és a UPS API által megkövetelt fejléceket. Ne feltételezze, hogy csak a nyomkövetési szám szükséges: az aktuális referencia verzió-, tranzakció-, content-type- vagy korrelációs fejléceket is előírhat.

Egy leegyszerűsített kérésminta így néz ki:

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

Ez szerkezeti példa, nem bemásolható végpont. Az alkalmazásához a UPS dokumentációjában közzétett végpontot, verziót, fejléceket és paraméterneveket használja. A nyomkövetési számot saját rendelési adatszabályai szerint normalizálja, de karaktereket csak akkor távolítson el, ha a fuvarozó dokumentációja megerősíti, hogy ez biztonságos.

5. lépés: Képezze le az eseményeket az adatmodellbe

A fuvarozói válaszok gyakran több információt tartalmaznak, mint egyetlen állapotcímke. Az ügyfeleknek megjelenő oldal kódolása előtt képezze le a választ egy belső modellbe, például a küldeményazonosítót, a fuvarozót, a legfrissebb állapotot, az eseménykódot, az esemény leírását, az esemény időpontját, a helyszínt, a kézbesítés várható adatait és – ha elérhető – a kézbesítés időpontját.

Őrizze meg az eredeti fuvarozói választ, ha ezt az adatmegőrzési és adatvédelmi szabályzata engedi. A nyers válasz segíthet egy leképezési hiba diagnosztizálásában, illetve annak megértésében, hogy normalizált állapota miért tér el a fuvarozó megfogalmazásától. Ugyanakkor ne jelenítsen meg technikai eseménykódokat az ügyfeleknek olvasható magyarázat nélkül.

Ne kezeljen minden állapotot végleges kézbesítési eredményként. Például a szállítás alatt állapotot, a kivételt, a kézbesítési kísérletet és a kézbesített eseményt nem szabad ugyanabba az ügyfélüzenetbe összevonni. Hozzon létre explicit leképezéseket, és határozza meg, mi történik, ha a UPS olyan eseményértéket ad hozzá, amelyet a kód nem ismer fel.

6. lépés: Adjon hozzá újrapróbálkozást, ellenőrzést és felügyeletet

Egy éles integrációhoz több kell, mint egy sikeres kérés egy fejlesztői konzolban. Adjon hozzá ellenőrzéseket és üzemeltetési védelmi intézkedéseket:

• Bemeneti ellenőrzés: a kérések elküldése előtt utasítsa el az üres, hibás formátumú vagy nyilvánvalóan hiányos nyomkövetési számokat.
• Időtúllépések: akadályozza meg, hogy egy lassú fuvarozói válasz teljes pénztár-, ügyfélszolgálati vagy raktári munkafolyamatot blokkoljon.
• Újrapróbálkozási szabályok: az ideiglenes hálózati vagy szolgáltatási hibákat körültekintően, fokozatos várakozással próbálja újra. Hitelesítési hibák vagy érvénytelen nyomkövetési számok esetén ne próbálkozzon ismételten.
• Sebességkorlátok figyelembevétele: kövesse a UPS dokumentációjában szereplő korlátokat és használati szabályokat. Ha az üzleti folyamat engedi, gyorsítótárazza a legutóbbi eredményeket.
• Ismeretlen állapotok: őrizze meg az ismeretlen eseményt felülvizsgálatra, ahelyett hogy tévesen kézbesítettként vagy elveszettként címkézné.
• Megfigyelhetőség: rögzítse a kérés időzítését, a válasz kategóriáját és a korrelációs információkat, de ne naplózzon titkos adatokat vagy szükségtelen személyes adatokat.

A nyomkövetési rendszernek azt is meg kell határoznia, milyen gyakran frissíti a küldeményt. A túl agresszív lekérdezés elkerülhető terhelést okozhat, és nem feltétlenül eredményez új információt. A túl ritka lekérdezés miatt az ügyféloldal elavultnak tűnhet. Az időközt a küldemények száma, az üzemeltetési sürgősség, a fuvarozó szabályai és a felhasználók által ténylegesen igényelt frissesség alapján válassza meg.

7. lépés: Teszteljen életszerű forgatókönyvekkel

Ne csak sikeresen kézbesített küldeményt teszteljen. Vegyen fel ismeretlen nyomkövetési számot, szállítás alatt álló küldeményt, kivételt, több eseménnyel rendelkező küldeményt, lejárt tokent, időtúllépést, engedélyezési hibát és olyan választ, amely a feldolgozó által nem várt mezőket tartalmaz. Ha a UPS külön tesztkörnyezetet vagy teszt-hitelesítő adatokat biztosít, először ezt az eljárást kövesse.

Ellenőrizze a teljes útvonalat a kéréstől a felhasználói felületig. Győződjön meg arról, hogy a megfelelő rendeléshez a megfelelő küldemény tartozik, az időbélyegek a kívánt időzónában jelennek meg, a duplikált események nem hoznak létre ismétlődő ügyfélüzeneteket, és egy fuvarozói kiesés nem írja felül félrevezető szöveggel a korábban érvényes állapotot.

Mikor lehet jobb választás a többfuvarozós nyomkövetési API?

A közvetlen UPS-integráció megfelelő lehet, ha működése főként UPS-szel történik, és szoros ellenőrzést igényel a fuvarozói munkafolyamat felett. Kevésbé kényelmes, ha a rendelések több fuvarozón, piactéren, postai szolgáltatón vagy regionális kézbesítőcégen keresztül mozoghatnak. Ilyenkor a külön hitelesítő adatok, válaszformátumok, állapot-szókincsek és újrapróbálkozási szabályok növelhetik a karbantartási munkát.

Egy többfuvarozós szolgáltatás, például a 17TRACK Tracking API, alternatív integrációs modellt biztosíthat azoknak az alkalmazásoknak, amelyek több fuvarozón keresztül igényelnek nyomkövetést. A támogatott fuvarozókat, kérésformátumokat, hitelesítést, használati feltételeket és elérhető képességeket közvetlenül a fejlesztői dokumentációban kell áttekinteni. Ez nem jelenti automatikusan azt, hogy jobb a közvetlen UPS-kapcsolatnál: a megfelelő választás a fuvarozói összetételtől, az adatigényektől, az integráció feletti ellenőrzéstől, valamint a kereskedelmi és megfelelőségi korlátoktól függ.

Fejlesztői integráció helyett fogyasztói keresés esetén a 17TRACK nyomkövetési oldala megfelelőbb lehet, mint egy API-kapcsolat kiépítése. Márkázott vásárlás utáni frissítéseket igénylő online áruház esetén külön vizsgálja meg a megfelelő platformintegrációt, ahelyett hogy olyan API-munkát végezne, amelyre az áruháznak nincs szüksége.

Gyakori megvalósítási hibák

• Régi példák használata: egy kódminta hivatkozhat megszüntetett verzióra, régi hitelesítési módszerre vagy más UPS-szolgáltatásra.
• Titkos adatok frontendkódban történő elhelyezése: minden böngészőbe küldött adatot megtekinthetőnek kell tekinteni.
• Az üres eredmény küldeményhiányként való értelmezése: üzleti következtetés levonása előtt ellenőrizze a nyomkövetési számot, a fiókjogosultságokat, a környezetet és a válaszüzenetet.
• Csak szöveg leképezése: az állapotleírások változhatnak. Használja a dokumentált kódokat, és őrizze meg az ismeretlen értékeket felülvizsgálatra.
• A fiók- és használati követelmények figyelmen kívül hagyása: a technikai kód lehet helyes, miközben az alkalmazás nincs konfigurálva a kért szolgáltatásra.
• Frissítés üzleti szabály nélkül: a szükségtelen lekérdezés növelheti a költséget, a terhelést és az üzemeltetési zajt anélkül, hogy javítaná az ügyfélélményt.

Gyakorlati élesítési ellenőrzőlista

1. Erősítse meg, hogy az alkalmazás az aktuális UPS-dokumentációt és jóváhagyott környezetet használja.
2. Ellenőrizze, hogy a hitelesítő adatok szerveroldalon vannak tárolva, és cserélhetők.
3. Tesztelje a hitelesítési hibát, a fuvarozói hibákat, a hibás bemenetet és az időtúllépéseket.
4. Hasonlítsa össze a normalizált állapotokat az eredeti válasszal reprezentatív küldemények esetén.
5. Állítson be frissítési szabályzatot, és kövesse a kérések mennyiségét.
6. Határozza meg az ismeretlen események, a késedelmes frissítések és az ügyféleszkalációk felelőseit.
7. Dokumentálja az integrációt, hogy egy másik fejlesztő biztonságosan frissíthesse a hitelesítő adatokat, a végpontverziókat és az állapotleképezéseket.

GYIK

Szükségem van UPS-fiókra a Tracking API használatához?

Tekintse át az aktuális UPS-regisztrációs és hozzáférési követelményeket a Developer Portalon. Az API-hozzáférés függhet az alkalmazás regisztrációjától, a hitelesítő adatoktól, a fiók konfigurációjától és a kért konkrét szolgáltatástól. Ne feltételezze, hogy a nyilvános nyomkövetési oldal bejelentkezése felcserélhető a fejlesztői API-hozzáféréssel.

Ingyenes a UPS Tracking API?

Ne feltételezze, hogy az API-hozzáférésnek nincsenek kereskedelmi vagy használati feltételei. A UPS hivatalos csatornáin teszi közzé az aktuális szolgáltatási és fiókinformációkat, és egyes követelmények a terméktől, a fióktól vagy a megállapodástól függhetnek. Éles költségvetés tervezése előtt közvetlenül erősítse meg az alkalmazandó feltételeket.

Közvetlenül JavaScriptből, böngészőben is meghívhatom a UPS API-t?

A böngészőalapú hívás felfedheti az alkalmazás hitelesítő adatait, valamint kereszt-domain, biztonsági és használat-szabályozási problémákat okozhat. A szerveroldali integráció általában biztonságosabb minta a titkos adatok tárolására, a tokenek beszerzésére, az újrapróbálkozási szabályok alkalmazására és a küldeményadatokhoz való hozzáférés korlátozására.

Milyen gyakran kérjen az alkalmazásom nyomkövetési frissítéseket?

A frissítési szabályzatot a fuvarozó dokumentált korlátai, a küldemények száma, az üzemeltetési sürgősség és a felhasználók által igényelt frissesség alapján alakítsa ki. Ahol megfelelő, gyorsítótárazza a legutóbbi eredményeket, ideiglenes hibák után alkalmazzon fokozatos várakozást, és ne tekintse az ismételt lekérdezést dokumentált esemény- vagy értesítési funkció helyettesítőjének.

Közvetlen UPS-integrációt vagy többfuvarozós API-t használjak?

A közvetlen UPS-integráció megfelelhet egy UPS-központú munkafolyamatnak, amely fuvarozóspecifikus ellenőrzést igényel. A többfuvarozós API csökkentheti az integrációk számát, ha küldeményei több fuvarozót használnak. A választás előtt hasonlítsa össze a támogatott fuvarozókat, a hitelesítést, az adatmezőket, a megbízhatósági követelményeket, a használati feltételeket és a megvalósítás ráfordítását.

Források

• UPS Developer Portal — hivatalos API-katalógus, alkalmazáshozzáférés, hitelesítés és fejlesztői dokumentáció.
• UPS Technology Integration — hivatalos információ a UPS-technológia üzleti rendszerekkel való integrációjáról.
• 17TRACK Tracking API — hivatalos termék- és fejlesztői belépési pont a többfuvarozós nyomkövetéshez.
• 17TRACK API Documentation — hivatalos API-dokumentáció hitelesítéshez, kérésekhez és válaszkezeléshez.