UPS Tracking API: Kezdők útmutatója az első lépésekhez
A UPS Tracking API lehetővé teszi a vállalkozások számára, hogy lekérjék a küldemények állapotát, és megjelenítsék a kézbesítési frissítéseket saját webhelyükön, alkalmazásukban, rendeléskezelő rendszerükben vagy ügyfélszolgálati eszközeikben. A kezdés általában egy UPS fejlesztői fiók létrehozásából, egy alkalmazás regisztrálásából, hitelesítési adatok beszerzéséből, egy nyomkövetési kérés elküldéséből, valamint a válasz hasznos, ügyfelek számára látható eseményekké alakításából áll. Ez az útmutató a folyamatot korábbi API-tapasztalat feltételezése nélkül ismerteti.
A példák a nyomkövetésre összpontosítanak, nem pedig a címkekészítésre, díjszámításra vagy címellenőrzésre. A UPS külön API-termékeket és dokumentációt biztosít, ezért a produktív munkafolyamatok létrehozása előtt győződjön meg arról, hogy a regisztrált alkalmazás hozzáfér a szükséges nyomkövetési funkcióhoz.
Mire szolgál a UPS Tracking API?
Az API strukturált módot biztosít arra, hogy egy szoftverrendszer információt kérjen egy másik rendszertől. Egy nyomkövetési munkafolyamatban a rendszer egy küldeményazonosítót, például egy nyomkövetési számot küld a fuvarozónak vagy egy nyomkövetési platformnak. A szolgáltatás olyan küldeményadatokat ad vissza, amelyek a szolgáltatástól, a küldeménytől és a kérés időpontjában elérhető válaszmezőktől függően tartalmazhatják az aktuális állapotot, az állapot leírását, a helyadatokat, a dátumokat és a csomag mérföldköveit.
Ezek az adatok több gyakorlati funkciót is támogathatnak:
- E-kereskedelmi webáruházba beágyazott nyomkövetési oldal.
- A küldemények láthatósága egy rendeléskezelő vagy vállalati erőforrás-tervezési rendszerben.
- Ügyfélszolgálati képernyők, amelyek csökkentik a fuvarozó webhelyének manuális ellenőrzésére fordított időt.
- Belső riasztások kézbesítési kivételekről, késésekről vagy befejezett kézbesítésekről.
- Küldeményeseményeken alapuló vásárlás utáni üzenetek.
Az API nem helyettesíti az alkalmazás logikáját. Továbbra is Önnek kell eldöntenie, milyen gyakran kér frissítéseket, hogyan tárolja a válaszokat, hogyan kezeli a hiányos adatokat, és hogyan magyarázza el a fuvarozói állapotokat az ügyfeleknek.
UPS Tracking API és a UPS webhelye
A UPS webhelyét arra tervezték, hogy egy személy megadjon egy nyomkövetési számot, majd elolvassa az eredményt. Az API-kat szoftverek számára tervezték. Akkor hasznosak, ha a nyomkövetési információknak automatikusan meg kell jelenniük egy másik rendszerben, vagy belső folyamatot kell elindítaniuk.
Ez a különbség azért fontos, mert az API-integráció olyan felelősségekkel jár, amelyek manuális lekérdezés esetén nem merülnek fel. A csapatnak védenie kell a hitelesítő adatokat, ellenőriznie kell a felhasználói beviteleket, megfelelően kell rögzítenie a kéréseket és válaszokat, kezelnie kell az ideiglenes hibákat, valamint figyelnie kell, hogy az integráció továbbra is működik-e a fuvarozói platform változásai után.
A jelenlegi regisztrációs és műszaki követelményekhez a UPS fejlesztői platformja a megfelelő kiindulópont. Dokumentációja elsőbbséget élvez a régebbi útmutatókkal, kódpéldákkal vagy fórumbejegyzésekkel szemben, mivel a hitelesítési módszerek, az API-verziók, a kötelező fejlécek és a termék-hozzáférési szabályok változhatnak.
Mire van szüksége egy kérés elküldése előtt?
Az integráció megírása előtt készítse elő a következőket:
- UPS fejlesztői fiók. A rendelkezésre álló API-k áttekintéséhez és egy alkalmazás létrehozásához használja a hivatalos UPS Developer Portalt.
- Alkalmazás-hitelesítő adatok. A pontos hitelesítőadat-neveket és a hitelesítési folyamatot az aktuális UPS-dokumentáció alapján határozza meg. Ne helyezzen kliens-titkos kulcsokat böngészőkódba, mobilalkalmazásokba, nyilvános tárolókba vagy ügyfelek által látható oldalakra.
- Érvényes nyomkövetési szám teszteléshez. Olyan küldeményekkel teszteljen, amelyekhez szervezete jogosult hozzáférni, és kerülje a személyes vagy kereskedelmi küldeményadatok naplókban való közzétételét.
- Szerveroldali integrációs pont. A háttérszolgáltatás általában biztonságosabb, mint a fuvarozó közvetlen hívása egy nyilvános weboldalról, mivel titokban tarthatja a hitelesítő adatokat és szabályozhatja a kérések számát.
- Választárolási terv. Döntse el, mely mezőkre van szüksége, meddig őrzi meg őket, és hogyan kapcsolja össze a fuvarozói eseményt egy belső rendeléssel.
Kezdők számára is érthető integrációs munkafolyamat
1. Erősítse meg az üzleti követelményt
Először határozza meg, mit jelent a termékében a „nyomkövetés”. Egy ügyfeleknek szánt oldalnak csak az aktuális állapotra és a várható kézbesítési információkra lehet szüksége. Egy raktári vagy támogatási irányítópultnak szüksége lehet a szkennelési előzményekre, időbélyegekre, kivételleírásokra és az eredeti nyomkövetési számra is.
Ne kérjen le minden elérhető mezőt indok nélkül. A kisebb adatmodell könnyebben karbantartható, és kisebb valószínűséggel tesz közzé olyan információkat, amelyekre a felhasználóknak nincs szükségük.
2. Regisztrálja az alkalmazást
Hozzon létre egy alkalmazást a UPS fejlesztői környezetében, és az aktuális portálutasításoknak megfelelően válassza ki a megfelelő nyomkövetési terméket. Az alkalmazásazonosítót biztonságosan tárolja. Ha a UPS jóváhagyást, fiók-hozzárendelést vagy további beállítást igényel a produktív hozzáféréshez, végezze el ezeket a lépéseket, mielőtt éles indulási dátumot ígérne.
Ahol a platform támogatja ezt a modellt, használjon külön hitelesítő adatokat és konfigurációt a teszteléshez és a produktív környezethez. Ez csökkenti annak esélyét, hogy egy tesztprogram hatással legyen egy éles munkafolyamatra.
3. Valósítsa meg a hitelesítést
A hitelesítés bizonyítja, hogy az alkalmazás jogosult a szolgáltatás hívására. Kövesse az aktuális UPS-dokumentációban megadott hitelesítési módszert, tokenvégpontot, hatókör-követelményeket és fejlécformátumot. A hozzáférési tokeneket ideiglenes titkokként kezelje, és ne írja őket az alkalmazás naplóiba.
Ésszerű megoldás esetén csak szükség szerint kér tokent, az engedélyezett élettartama alatt újra felhasználja, lejárat után pedig újat szerez be. A kódnak meg kell különböztetnie a hitelesítési hibát a nyomkövetési szám hibájától is. A megoldás eltérő: az első a hitelesítő adatok vagy a konfiguráció felülvizsgálatát, a második pedig a bevitel ellenőrzését igényelheti.
4. Küldjön nyomkövetési kérést
A hitelesítés után küldjön kérést a UPS által meghatározott nyomkövetési művelettel és azonosítóformátummal. A pontos URL, HTTP-metódus, fejlécek és válaszséma a kiválasztott API-verzió hivatalos dokumentációjában található.
Egy elvi kérés így néz ki:
POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"trackingNumber": "YOUR_TRACKING_NUMBER"
}Ez tanulási példa, nem pedig közvetlenül bemásolható éles kérés. A művelet nevét, a végpontot, a fejléceket és a törzset cserélje ki az aktuális UPS API-referenciában szereplő értékekre. Egyes API-k útvonalparamétert vagy eltérő kérésstruktúrát használnak.
5. Normalizálja a választ
A fuvarozói válaszok nem mindig azon a nyelven íródnak, amelyet ügyfelei elvárnak. Hozzon létre egy belső eseménymodellt stabil mezőkkel, például:
- Belső rendelés- vagy küldeményazonosító.
- Fuvarozó neve és nyomkövetési száma.
- Legutóbbi fuvarozói állapotkód és nyers leírás.
- Az alkalmazás által használt normalizált állapot.
- Esemény-időbélyeg és, ha rendelkezésre áll, helyszín.
- Az utolsó sikeres frissítés időpontja.
Lehetőség szerint őrizze meg az eredeti fuvarozói állapotot. A „Szállítás alatt” jellegű normalizált címke hasznos az ügyfélfelületen, de a nyers leírás segíthet a támogatási munkatársaknak egy szokatlan esemény kivizsgálásában.
6. Döntse el, hogyan szerzi be a frissítéseket
Egyes rendszerek ütemezett lekérdezést használnak: a háttérrendszer meghatározott időközönként ellenőrzi a jogosult küldeményeket, és tárolja a változásokat. Mások eseményértesítéseket használnak, amikor a megfelelő platform támogatja ezeket. Ne feltételezze, hogy minden UPS nyomkövetési termék ugyanazt az értesítési mechanizmust kínálja. Webhook-alapú munkafolyamat tervezése előtt ellenőrizze az aktuális dokumentációt és a kereskedelmi feltételeket.
A lekérdezés legyen szelektív. A nemrég feladott vagy éppen mozgó csomagok gyakoribb ellenőrzést indokolhatnak, mint a kézbesített vagy törölt küldemények. Ideiglenes hibák esetén alkalmazzon fokozatosan növekvő várakozási idejű újrapróbálkozást, tartsa be a dokumentált korlátokat, és terminális állapot után állítsa le a szükségtelen kéréseket, kivéve, ha üzleti folyamata későbbi ellenőrzést igényel.
Gyakori hibák és kezelésük
| Helyzet | Valószínű válasz | Gyakorlati teendő |
|---|---|---|
| Hitelesítési hiba | A kérés nincs engedélyezve. | Ellenőrizze a hitelesítő adatokat, a tokenkezelést, a hatóköröket, a környezetet és a kötelező fejléceket. |
| Érvénytelen nyomkövetési bevitel | Az azonosító hiányzik, hibás formátumú vagy nem fogadható el. | Ellenőrizze a bevitelt, és jelenítsen meg egyértelmű javítási üzenetet. |
| Még nincs hasznos esemény | Lehet, hogy a küldemény még nem kapta meg az első szkennelést. | Ne nyilvánítsa kézbesítési hibának; jelenítsen meg semleges függőben lévő üzenetet, majd próbálkozzon később. |
| Sebesség- vagy kvótaválasz | Az alkalmazás túl gyorsan küldi a kéréseket, vagy elérte a megengedett keretet. | Csökkentse a lekérdezések gyakoriságát, sorolja be a feladatokat, és kövesse a szolgáltató útmutatását. |
| Ideiglenes szerver- vagy hálózati hiba | A szolgáltatás rövid ideig elérhetetlen lehet. | Biztonságosan próbálkozzon újra fokozatosan növekvő várakozási idővel, és őrizze meg az utolsó ismert állapotot. |
A felhasználói élmény legfontosabb szabálya, hogy a hiányzó adatokat ne alakítsa magabiztos következtetéssé. Az „Nincs új szkennelés” nem jelenti automatikusan azt, hogy „elveszett”, és a „Címke létrehozva” sem feltétlenül jelent „szállítás alatt” állapotot. Gondosan képezze le az állapotokat, és tegye láthatóvá a kivételkezelést a támogatási csapatok számára.
Mikor jobb választás a többfuvarozós API?
A közvetlen UPS-integráció ésszerű választás lehet, ha küldeményeit elsősorban a UPS kezeli, és csapata közvetlen ellenőrzést szeretne a fuvarozói kapcsolat felett. Ennek ára, hogy minden további fuvarozó újabb hitelesítési modellt, adatsémát, hibakezelési szabályt és karbantartási folyamatot igényelhet.
Ha működése több fuvarozót használ, egy többfuvarozós szolgáltatás csökkentheti a különálló integrációk számát. A 17TRACK's Tracking API alkalmazásalapú küldeménykövetésre készült, elérhető integrációs modelljét pedig a hivatalos fejlesztői dokumentáció ismerteti. Érdemes lehet megvizsgálni, ha a valódi követelmény nem csupán a UPS nyomkövetése, hanem a fuvarozókon átívelő egységes nyomkövetési réteg.
Ez nem indok arra, hogy automatikusan lecserélje a közvetlen UPS-kapcsolatot. Hasonlítsa össze a szükséges fuvarozói lefedettséget, az események részletességét, az adatmegőrzési követelményeket, a hitelesítési modellt, az üzemeltetési korlátokat, a támogatási folyamatot és a teljes megvalósítási ráfordítást. A szolgáltató nyilvános dokumentációját tekintse egy műszaki proof of concept kiindulópontjának, ne pedig a saját küldeménymintáinak tesztelését helyettesítő anyagnak.
Éles használatra való felkészültségi ellenőrzőlista
- A hitelesítő adatokat titokkezelőben tárolják, és soha nem teszik elérhetővé a böngészőben.
- A teszt- és produktív környezet egyértelműen el van választva.
- A kérések időkorláttal, szabályozott újrapróbálkozással és hasznos hib naplózással rendelkeznek.
- A nyomkövetési számokat elküldés előtt ellenőrzik.
- A rendszer tárolja az utolsó sikeres frissítést, és nem írja felül üres válasszal.
- A nyers fuvarozói üzeneteket és az ügyfeleknek szánt címkéket külön kezelik.
- A lekérdezési gyakoriság követi a szolgáltató közzétett korlátait és az üzemeltetési igényeket.
- A megfigyelés képes észlelni a hitelesítési hibákat, a megemelkedett hibaarányokat és az elavult küldeményállapotokat.
- A támogatási munkatársak elegendő részletet látnak az ügyfélkérdések kivizsgálásához.
- Az integrációt újratesztelik, amikor a UPS módosítja a dokumentációt, a hitelesítő adatokat, a végpontokat vagy a válaszmezőket.
Kezdjen egy teljes folyamattal: hitelesítsen, kövessen nyomon egy tesztküldeményt, tárolja a választ, jelenítsen meg egy egyszerű állapotot, és kezelje a hibát. Csak akkor bővítse, ha ez a folyamat már megbízható. Ez általában biztonságosabb, mint egy nagy, ügyfeleknek szánt nyomkövetési élmény felépítése azelőtt, hogy megértené az alapul szolgáló adatok és hibák viselkedését.
GYIK
Szükségem van API-ra, ha csak néhány csomagot követek nyomon?
Általában nem. Az alkalmi lekérdezésekhez praktikusabb lehet a manuális nyomkövetés a fuvarozó webhelyén. Az API akkor válik értékesebbé, amikor a nyomkövetés egy ismételhető munkafolyamat része, vagy egy másik alkalmazáson belül kell megjelennie.
Hívhatom a UPS Tracking API-t Shopify-témából vagy böngészőből?
A közvetlen böngészőhívás felfedheti a hitelesítő adatokat, és megnehezítheti a kérések szabályozását. Általában biztonságosabb egy szerveroldali szolgáltatás vagy egy meglévő nyomkövetési integráció. Ellenőrizze a műszaki követelményeket és az engedélyezett architektúrát az aktuális UPS-dokumentációban.
Létrehoz szállítási címkéket a nyomkövetési API?
Nem feltétlenül. A nyomkövetés, a címkekészítés, a díjszámítás, a címellenőrzés és más logisztikai funkciók külön API-termékek lehetnek. A szükséges műveletnek megfelelő terméket válassza.
Miért adhat kevés információt egy érvényes nyomkövetési szám?
Előfordulhat, hogy a csomagot még nem szkennelték be először, az adatok még nem érhetők el, vagy a kérés nem felel meg az API által megkövetelt formátumnak vagy hozzáférési jogosultságoknak. Az üres vagy korlátozott választ vizsgálandó állapotként kezelje, ne annak bizonyítékaként, hogy a küldemény elveszett.
Közvetlenül a UPS-t válasszam, vagy többfuvarozós nyomkövetési API-t?
Válasszon közvetlen kapcsolatot, ha a UPS a fő fuvarozó, és célzott integrációt szeretne. Fontolja meg a többfuvarozós szolgáltatást, ha működési célja egyetlen nyomkövetési munkafolyamat több fuvarozón keresztül. A végső döntés előtt tesztelje a szükséges fuvarozókat és eseményforgatókönyveket.
