UPS Tracking API: Sprievodca pre začiatočníkov, ako začať
UPS Tracking API umožňuje firme získavať stav zásielok a zobrazovať aktualizácie doručenia na vlastnej webovej stránke, v aplikácii, systéme na správu objednávok alebo nástrojoch zákazníckej podpory. Začatie používania zvyčajne zahŕňa vytvorenie účtu vývojára UPS, registráciu aplikácie, získanie autentifikačných údajov, odoslanie požiadavky na sledovanie a preloženie odpovede do užitočných udalostí určených zákazníkom. Táto príručka vysvetľuje celý proces bez predpokladu predchádzajúcich skúseností s API.
Príklady sa zameriavajú na sledovanie, nie na vytváranie štítkov, výpočet cien alebo overovanie adries. UPS spravuje samostatné produkty API a dokumentáciu, preto si pred vytváraním produkčných pracovných postupov overte, či má registrovaná aplikácia prístup k potrebnej funkcii sledovania.
Čo robí UPS Tracking API
API je štruktúrovaný spôsob, ktorým jeden softvérový systém požaduje informácie od iného. V pracovnom postupe sledovania váš systém odošle identifikátor zásielky, napríklad sledovacie číslo, dopravcovi alebo platforme na sledovanie. Služba vráti údaje o zásielke, ktoré môžu v závislosti od služby, zásielky a polí dostupných v odpovedi v čase požiadavky obsahovať aktuálny stav, jeho popis, informácie o polohe, dátumy a míľniky balíka.
Tieto údaje môžu podporovať viaceré praktické funkcie:
- Stránka sledovania vložená do internetového obchodu.
- Viditeľnosť zásielok v systéme na správu objednávok alebo v systéme plánovania podnikových zdrojov.
- Obrazovky zákazníckej podpory, ktoré znižujú potrebu manuálne kontrolovať webovú stránku dopravcu.
- Interné upozornenia na výnimky pri doručení, oneskorenia alebo dokončené doručenia.
- Správy po nákupe založené na udalostiach zásielky.
API nenahrádza logiku vašej aplikácie. Stále musíte rozhodnúť, ako často požadovať aktualizácie, ako ukladať odpovede, ako spracovať neúplné údaje a ako zákazníkom vysvetliť stavy dopravcu.
UPS Tracking API verzus webová stránka UPS
Webová stránka UPS je určená pre človeka, ktorý zadá sledovacie číslo a prečíta si výsledok. API je určené pre softvér. Je užitočné vtedy, keď sa majú informácie o sledovaní automaticky zobrazovať v inom systéme alebo spúšťať interný proces.
Toto rozlíšenie je dôležité, pretože integrácia API prináša povinnosti, ktoré manuálne vyhľadávanie nemá. Váš tím musí chrániť prihlasovacie údaje, overovať vstupy používateľov, primerane zaznamenávať požiadavky a odpovede, riešiť dočasné zlyhania a sledovať, či integrácia naďalej funguje po zmenách na platforme dopravcu.
Vývojárska platforma UPS je vhodným východiskovým bodom pre aktuálne požiadavky na registráciu a technické požiadavky. Jej dokumentácia by mala mať prednosť pred staršími príručkami, ukážkami kódu alebo príspevkami na fórach, pretože autentifikačné metódy, verzie API, povinné hlavičky a pravidlá prístupu k produktom sa môžu meniť.
Čo potrebujete pred odoslaním požiadavky
Pred písaním integrácie si pripravte tieto položky:
- Účet vývojára UPS. Pomocou oficiálneho UPS Developer Portal si prezrite dostupné API a vytvorte aplikáciu.
- Prihlasovacie údaje aplikácie. Presné názvy prihlasovacích údajov a autentifikačný postup získajte z aktuálnej dokumentácie UPS. Tajné kľúče klienta neumiestňujte do kódu prehliadača, mobilných aplikácií, verejných úložísk ani na stránky viditeľné zákazníkom.
- Platné sledovacie číslo na testovanie. Testujte so zásielkami, ku ktorým má vaša organizácia oprávnený prístup, a vyhnite sa odhaľovaniu osobných alebo obchodných údajov o zásielkach v protokoloch.
- Serverový integračný bod. Backendová služba je zvyčajne bezpečnejšia než priame volanie dopravcu z verejnej webovej stránky, pretože dokáže uchovať prihlasovacie údaje v tajnosti a riadiť objem požiadaviek.
- Plán ukladania odpovedí. Rozhodnite, ktoré polia potrebujete, ako dlho ich budete uchovávať a ako priradíte udalosť dopravcu k internej objednávke.
Integračný pracovný postup vhodný pre začiatočníkov
1. Potvrďte obchodnú požiadavku
Najprv definujte, čo vo vašom produkte znamená „sledovanie“. Stránka určená zákazníkom môže potrebovať iba aktuálny stav a informácie o očakávanom doručení. Skladový panel alebo panel podpory môže potrebovať aj históriu skenovaní, časové pečiatky, popisy výnimiek a pôvodné sledovacie číslo.
Nevyžadujte každé dostupné pole bez dôvodu. Menší dátový model sa ľahšie udržiava a je menej pravdepodobné, že odhalí informácie, ktoré používatelia nepotrebujú.
2. Zaregistrujte aplikáciu
Vytvorte aplikáciu vo vývojárskom prostredí UPS a podľa aktuálnych pokynov portálu vyberte príslušný produkt na sledovanie. Identifikátor aplikácie bezpečne uložte. Ak UPS vyžaduje schválenie, priradenie účtu alebo ďalšie nastavenie produkčného prístupu, dokončite tieto kroky ešte pred prisľúbením dátumu spustenia.
Ak to platforma podporuje, používajte samostatné prihlasovacie údaje a konfiguráciu pre testovanie a produkciu. Znížite tak pravdepodobnosť, že testovací skript ovplyvní živý pracovný postup.
3. Implementujte autentifikáciu
Autentifikácia dokazuje, že vaša aplikácia má povolenie volať službu. Postupujte podľa autentifikačnej metódy, koncového bodu tokenu, požiadaviek na rozsah a formátu hlavičiek uvedených v aktuálnej dokumentácii UPS. S prístupovými tokenmi zaobchádzajte ako s dočasnými tajnými údajmi a nezapisujte ich do aplikačných protokolov.
Rozumná implementácia vyžiada token iba v prípade potreby, znovu ho použije počas povolenej doby platnosti a po jeho vypršaní získa nový. Kód by mal tiež rozlišovať autentifikačné zlyhanie od chyby sledovacieho čísla. Náprava je odlišná: prvá vyžaduje kontrolu prihlasovacích údajov alebo konfigurácie, zatiaľ čo druhá môže vyžadovať overenie vstupu.
4. Odošlite požiadavku na sledovanie
Po autentifikácii odošlite požiadavku pomocou operácie sledovania a formátu identifikátora špecifikovaného spoločnosťou UPS. Presná URL, metóda HTTP, hlavičky a schéma odpovede patria do oficiálnej dokumentácie vybranej verzie API.
Konceptuálna požiadavka vyzerá takto:
POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"trackingNumber": "YOUR_TRACKING_NUMBER"
}Toto je vzdelávací príklad, nie produkčná požiadavka pripravená na kopírovanie. Názov operácie, koncový bod, hlavičky a telo nahraďte hodnotami z aktuálnej referencie UPS API. Niektoré API používajú parameter cesty alebo inú štruktúru požiadavky.
5. Normalizujte odpoveď
Odpovede dopravcu nie sú vždy napísané v jazyku, ktorý očakávajú vaši zákazníci. Vytvorte interný model udalostí so stabilnými poľami, ako sú:
- Interné ID objednávky alebo zásielky.
- Názov dopravcu a sledovacie číslo.
- Najnovší kód stavu dopravcu a nespracovaný popis.
- Normalizovaný stav používaný aplikáciou.
- Časová pečiatka udalosti a, ak je uvedená, poloha.
- Čas poslednej úspešnej aktualizácie.
Pôvodný stav dopravcu uchovajte vždy, keď je to možné. Normalizované označenie, napríklad „Na ceste“, je užitočné pre zákaznícke rozhranie, ale nespracovaný popis môže pomôcť pracovníkom podpory preskúmať nezvyčajnú udalosť.
6. Rozhodnite, ako sa budú získavať aktualizácie
Niektoré systémy používajú plánované dotazovanie: backend v určených intervaloch kontroluje oprávnené zásielky a ukladá zmeny. Iné používajú oznámenia o udalostiach, ak ich príslušná platforma podporuje. Nepredpokladajte, že každý produkt UPS na sledovanie ponúka rovnaký mechanizmus oznámení. Pred návrhom pracovného postupu založeného na webhookoch si overte aktuálnu dokumentáciu a obchodné podmienky.
Dotazovanie by malo byť selektívne. Nedávno odoslané alebo aktívne prepravované balíky môžu odôvodňovať častejšie kontroly než doručené alebo zrušené zásielky. Pri dočasných zlyhaniach používajte opakované pokusy s postupne sa predlžujúcim oneskorením, rešpektujte zdokumentované limity a po dosiahnutí konečného stavu zastavte nepotrebné požiadavky, ak váš obchodný proces nevyžaduje neskoršie overenie.
Bežné chyby a spôsob ich riešenia
| Situácia | Pravdepodobná odpoveď | Praktické opatrenie |
|---|---|---|
| Autentifikačné zlyhanie | Požiadavka nie je autorizovaná. | Skontrolujte prihlasovacie údaje, spracovanie tokenu, rozsahy, prostredie a povinné hlavičky. |
| Neplatný vstup sledovania | Identifikátor chýba, má nesprávny formát alebo nie je akceptovaný. | Overte vstup a zobrazte jasnú správu s pokynom na opravu. |
| Zatiaľ žiadna užitočná udalosť | Zásielka možno ešte nebola prvýkrát naskenovaná. | Neoznačujte doručenie ako neúspešné; zobrazte neutrálnu čakajúcu správu a skúste to neskôr. |
| Odpoveď o limite alebo kvóte | Aplikácia odosiela požiadavky príliš rýchlo alebo dosiahla povolený limit. | Obmedzte dotazovanie, zaraďte prácu do frontu a postupujte podľa pokynov poskytovateľa. |
| Dočasná chyba servera alebo siete | Služba môže byť krátkodobo nedostupná. | Bezpečne opakujte požiadavku s oneskorením a zachovajte posledný známy stav. |
Najdôležitejším pravidlom používateľského prostredia je nepremeniť chýbajúce údaje na sebavedomý záver. „Žiadne nové skenovanie“ automaticky neznamená „stratené“ a „štítok vytvorený“ nemusí znamenať „na ceste“. Stavy mapujte opatrne a zabezpečte, aby tím podpory videl spracovanie výnimiek.
Kedy je vhodnejšie API pre viacerých dopravcov
Priama integrácia UPS môže byť rozumnou voľbou, keď vaše zásielky spracúva najmä UPS a váš tím chce mať priame riadenie pripojenia k dopravcovi. Nevýhodou je, že každý ďalší dopravca môže vyžadovať iný autentifikačný model, dátovú schému, pravidlá chýb a proces údržby.
Ak vaša prevádzka využíva viacerých dopravcov, služba pre viacerých dopravcov môže znížiť počet samostatných integrácií. 17TRACK's Tracking API je navrhnuté na sledovanie zásielok prostredníctvom aplikácií a jeho official developer documentation vysvetľuje dostupný model integrácie. Oplatí sa ho vyhodnotiť, ak skutočnou požiadavkou nie je iba sledovanie UPS, ale konzistentná vrstva sledovania naprieč dopravcami.
Toto nie je dôvod na automatické nahradenie priameho pripojenia UPS. Porovnajte potrebné pokrytie dopravcov, podrobnosť udalostí, požiadavky na uchovávanie údajov, autentifikačný model, prevádzkové limity, proces podpory a celkové úsilie potrebné na implementáciu. Verejnú dokumentáciu poskytovateľa považujte za východisko pre technický koncept, nie za náhradu testovania vlastných typov zásielok.
Kontrolný zoznam pripravenosti na produkciu
- Prihlasovacie údaje sú uložené v správcovi tajných údajov a nikdy nie sú vystavené prehliadaču.
- Testovacie a produkčné prostredia sú jasne oddelené.
- Požiadavky majú časové limity, riadené opakovania a užitočné zaznamenávanie chýb.
- Sledovacie čísla sa pred odoslaním overujú.
- Systém ukladá poslednú úspešnú aktualizáciu a neprepíše ju prázdnou odpoveďou.
- Nespracované správy dopravcu a označenia určené zákazníkom sa spracúvajú oddelene.
- Frekvencia dotazovania rešpektuje zverejnené limity poskytovateľa a prevádzkové potreby.
- Monitorovanie dokáže odhaliť autentifikačné zlyhania, zvýšenú mieru chýb a neaktuálne zásielky.
- Pracovníci podpory vidia dostatok podrobností na preskúmanie otázky zákazníka.
- Integrácia sa opätovne testuje pri zmenách dokumentácie, prihlasovacích údajov, koncových bodov alebo polí odpovede UPS.
Začnite jednou kompletnou cestou: autentifikujte sa, sledujte jednu testovaciu zásielku, uložte odpoveď, zobrazte jednoduchý stav a spracujte zlyhanie. Rozširujte až potom, keď bude táto cesta spoľahlivá. Tento prístup je zvyčajne bezpečnejší než vytvárať rozsiahle zákaznícke prostredie na sledovanie skôr, ako pochopíte základné údaje a správanie pri chybách.
Často kladené otázky
Potrebujem API, ak sledujem iba niekoľko balíkov?
Zvyčajne nie. Manuálne sledovanie na webovej stránke dopravcu môže byť pri príležitostných kontrolách praktickejšie. API je hodnotnejšie vtedy, keď je sledovanie súčasťou opakovateľného pracovného postupu alebo sa musí zobrazovať v inej aplikácii.
Môžem volať UPS Tracking API z témy Shopify alebo prehliadača?
Priame volanie z prehliadača môže odhaliť prihlasovacie údaje a sťažiť kontrolu požiadaviek. Serverová služba alebo zavedená integračná služba na sledovanie je vo všeobecnosti bezpečnejšia. Technické požiadavky a povolenú architektúru si overte v aktuálnej dokumentácii UPS.
Vytvára tracking API prepravné štítky?
Nie nevyhnutne. Sledovanie, vytváranie štítkov, výpočet cien, overovanie adries a ďalšie logistické funkcie môžu byť samostatnými produktmi API. Vyberte produkt, ktorý zodpovedá požadovanej operácii.
Prečo môže platné sledovacie číslo vrátiť málo informácií?
Balík možno ešte nebol prvýkrát naskenovaný, údaje ešte nemusia byť dostupné alebo požiadavka nemusí zodpovedať požadovanému formátu či oprávneniam prístupu API. Prázdnu alebo obmedzenú odpoveď považujte za stav, ktorý treba preskúmať, nie za dôkaz, že sa zásielka stratila.
Mám si vybrať priamo UPS alebo API na sledovanie viacerých dopravcov?
Priame pripojenie si vyberte vtedy, keď je UPS hlavným dopravcom a chcete cielenú integráciu. O službe pre viacerých dopravcov uvažujte vtedy, keď je vaším prevádzkovým cieľom jeden pracovný postup sledovania pre viacerých dopravcov. Pred konečným rozhodnutím otestujte potrebných dopravcov a scenáre udalostí.
