Как да използвате UPS Tracking API: Ръководство за настройка стъпка по стъпка

За да използвате UPS Tracking API, създайте UPS Developer акаунт, регистрирайте приложение, получете идентификационни данни за OAuth 2.0, поискайте токен за достъп и изпращайте удостоверени заявки за проследяване с валиден номер за проследяване на UPS. Точните наименования в портала, стъпките за одобрение и изискванията към API могат да се променят, затова потвърдете актуалните инструкции в официалния UPS Developer Portal, преди да активирате интеграция в производствена среда.

Това ръководство е предназначено за разработчици и екипи по електронна търговия, които трябва да показват статуса на пратките в онлайн магазин, система за управление на поръчки, складов процес, инструмент за обслужване на клиенти или вътрешно табло. То се фокусира върху последователността на интеграцията, решенията, които влияят на надеждността, и проверките, предотвратяващи често срещани проблеми при проследяването.

Какво прави UPS Tracking API

Интеграцията чрез API позволява на софтуера да заявява информация за пратките от UPS, вместо служител или клиент ръчно да отваря страницата за проследяване на превозвача. Вашето приложение може да използва отговора, за да показва последния известен статус, да идентифицира събития по доставката, да подпомага разследванията на обслужването на клиенти или да задейства вътрешен процес.

API не е същото като страница за проследяване. Страницата за проследяване е предназначена за прочит от човек. Отговорът от API е структурирани данни, които софтуерът трябва да анализира, съхранява и представя. Вашата система продължава да отговаря за удостоверяването, обработката на грешки, периодичното извличане или събирането на събития, съхранението на данни, дизайна на потребителския интерфейс и всички бизнес правила, изградени около събитията по доставката.

Преди да започнете

Подгответе следните елементи, преди да отворите портала за разработчици:

• UPS Developer акаунт или типа акаунт, изискван от текущия процес за регистрация в UPS.
• Регистрирано приложение и идентификационните данни, издадени за него.
• Тестов номер за проследяване или друг одобрен метод за тестване. Не започвайте с реални клиентски данни, ако документацията на UPS предоставя отделна тестова среда или процедура за тестване.
• Ясно решение коя система управлява записите за пратките, събитията по проследяването и съобщенията за статуса, предназначени за клиентите.
• Сигурно място за съхранение на идентификационните данни на клиента и токените за достъп. Никога не поставяйте тайни в код на браузъра, публични хранилища, екранни снимки или мобилни приложения, които потребителите могат да инспектират.

Трябва също да решите дали приложението ви се нуждае само от проследяване или от по-широка интеграция с UPS. Проследяването, изчисляването на тарифи, изпращането, валидирането на адреси и услугите за документи могат да имат различни продукти, разрешения, формати на заявките и оперативни изисквания.

Стъпка 1: Отворете UPS Developer Portal

Започнете от официалния UPS Developer Portal. Прегледайте актуалния каталог на API, указанията за удостоверяване, изискванията за регистрация, условията и информацията за средите. Потърсете конкретно документацията за Tracking API, вместо да предполагате, че инструкциите за друга услуга на UPS важат и за проследяването.

Порталът е подходящият източник за актуалните полета на заявките, обхватите за оторизация, дефинициите на отговорите, ограниченията на честотата, кодовете за грешки и подробностите за средите. Тези подробности могат да се променят, а пример от код на трета страна може да използва по-стар интерфейс на UPS или остарял метод за удостоверяване.

Стъпка 2: Регистрирайте приложение

Създайте приложение в портала за разработчици и изберете UPS API, от които приложението действително се нуждае. За проект, предназначен само за проследяване, поискайте само възможност за проследяване, освен ако процесът ви не изисква допълнителни услуги. Ограничаването на разрешенията намалява сложността на конфигурацията и улеснява последващото отстраняване на проблеми.

Запишете идентификатора и тайната на приложението в сървърен мениджър на тайни или защитена система за променливи на средата. Третирайте тайната като парола. Ако бъде разкрита, сменете я чрез процеса, предоставен от UPS, и прегледайте регистрационните файлове за неоторизирана употреба.

Ако порталът поиска информация за акаунта, фактурирането, бизнеса или приложението, предоставете точни данни. Не измисляйте производствен сценарий на употреба и не използвайте информация от чужд акаунт само за да завършите тест. Достъпът до дадена услуга може да зависи от конфигурацията на акаунта и текущия процес на одобрение от UPS.

Стъпка 3: Реализирайте удостоверяване с OAuth 2.0

Актуалната документация за разработчици на UPS използва удостоверяване, базирано на OAuth, за своите API. Обикновено сървърът ви обменя идентификационните данни на приложението чрез документирания поток за токен и получава токен за достъп. След това включва този токен в заглавката за оторизация на заявката към API.

Дръжте удостоверяването отделно от логиката за проследяване. Практическият дизайн има един компонент, който получава и кешира валиден токен, и друг, който извиква крайната точка за проследяване. Компонентът за токена трябва да:

• Изпраща идентификационни данни само към документираната крайна точка за оторизация на UPS.
• Използва типа съдържание и параметрите на предоставянето, посочени в актуалната документация на UPS.
• Съхранява токена временно и го използва повторно до изтичането му, вместо да заявява нов токен за всеки номер за проследяване.
• Обновява или получава отново токена при настъпване на документираното условие за изтичане.
• Заличава идентификационните данни и токените от регистрационните файлове на приложението, отчетите за грешки и заявките към екипа за поддръжка.

Не копирайте токен от сесия в браузър в постоянна интеграция. Сървърната услуга обикновено е по-сигурното място за управление на идентификационни данни, тъй като държи тайните далеч от публичния клиентски код.

Стъпка 4: Изградете заявката за проследяване

Използвайте формата на заявката, показан в официалната справка за Tracking API. Типичната заявка включва номер за проследяване в пътя или параметрите на заявката, токен за достъп в заглавката за оторизация и заглавки, изисквани от UPS API. Не приемайте, че номерът за проследяване е единствената необходима стойност: актуалната справка може да посочва заглавки за версия, транзакция, тип съдържание или корелация.

Опростеният модел на заявка изглежда така:

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

Това е структурен пример, а не крайна точка за копиране и поставяне. Използвайте крайната точка, версията, заглавките и имената на параметрите, публикувани в документацията на UPS за вашето приложение. Поддържайте номера за проследяване нормализиран съгласно собствените си правила за данните за поръчките, но не премахвайте символи, освен ако документацията на превозвача не потвърди, че това е безопасно.

Стъпка 5: Преобразувайте събитията във вашия модел на данни

Отговорите на превозвача често съдържат повече информация от един етикет на статуса. Преди да програмирате страницата, предназначена за клиентите, преобразувайте отговора във вътрешен модел, например идентификатор на пратката, превозвач, последен статус, код на събитието, описание на събитието, времеви печат на събитието, местоположение, информация за очакваната доставка и времеви печат на доставката, когато е наличен.

Запазвайте оригиналния отговор на превозвача, когато политиките ви за съхранение и поверителност го позволяват. Суровият отговор може да помогне за диагностициране на грешка при преобразуването или да обясни защо нормализираният ви статус се различава от формулировката на превозвача. Същевременно избягвайте да показвате технически кодове на събитията на клиентите без разбираемо обяснение.

Не третирайте всеки статус като краен резултат от доставката. Например събитие „в транзит“, изключение, опит за доставка и събитие „доставено“ не трябва да се свеждат до едно и също клиентско съобщение. Създайте изрични преобразувания и определете какво се случва, когато UPS добави стойност на събитие, която кодът ви не разпознава.

Стъпка 6: Добавете повторни опити, валидация и наблюдение

Производствената интеграция изисква повече от успешна заявка в конзола за разработка. Добавете валидация и оперативни предпазни мерки:

• Валидация на входа: отхвърляйте празни, неправилно форматирани или очевидно непълни номера за проследяване, преди да изпращате заявки.
• Изчаквания: предотвратявайте блокирането на целия процес на плащане, поддръжка или склад от бавен отговор на превозвача.
• Правила за повторни опити: повтаряйте внимателно опитите при временни мрежови или сервизни повреди, с постепенно увеличаване на интервала. Не повтаряйте многократно опитите при грешки в удостоверяването или невалидни номера за проследяване.
• Съобразяване с честотата: спазвайте ограниченията и правилата за употреба в документацията на UPS. Кеширайте последните резултати, когато бизнес процесът ви го позволява.
• Неизвестни състояния: запазвайте неразпознато събитие за преглед, вместо неправилно да го обозначавате като доставено или изгубено.
• Наблюдаемост: записвайте времето на заявката, категорията на отговора и информацията за корелация, без да регистрирате тайни или ненужни лични данни.

Системата за проследяване трябва също да определи колко често обновява дадена пратка. Прекалено честото извличане може да създаде ненужно натоварване и да не предостави нова информация. Твърде рядкото извличане може да направи страницата, предназначена за клиентите, да изглежда остаряла. Изберете интервал въз основа на обема на пратките, оперативната спешност, правилата на превозвача и актуалността, от която действително се нуждаят потребителите ви.

Стъпка 7: Тествайте с реалистични сценарии

Тествайте повече от успешно доставена пратка. Включете неизвестен номер за проследяване, пратка в транзит, изключение, пратка с множество събития, изтекъл токен, изчакване, грешка при оторизация и отговор, съдържащ полета, които анализаторът ви не очаква. Ако UPS предоставя отделна тестова среда или тестови идентификационни данни, първо следвайте тази процедура.

Проверете целия път от заявката до потребителския интерфейс. Уверете се, че правилната поръчка получава правилната пратка, времевите печати се показват в желаната часова зона, дублираните събития не създават дублирани клиентски съобщения и прекъсване на услугата на превозвача не заменя предишен валиден статус с подвеждащ текст.

Кога API за проследяване на множество превозвачи е по-подходящо

Директната интеграция с UPS може да е подходяща, когато дейността ви изпраща предимно с UPS и се нуждае от строг контрол върху работния процес на превозвача. Тя става по-малко удобна, когато поръчките могат да преминават през няколко превозвачи, пазари, пощенски оператори или регионални компании за доставки. В такава ситуация отделните идентификационни данни, формати на отговорите, речници на статусите и правила за повторни опити могат да увеличат работата по поддръжката.

Услуга за множество превозвачи като 17TRACK Tracking API може да предостави алтернативен модел на интеграция за приложения, които се нуждаят от проследяване през множество превозвачи. Документацията за разработчици трябва да се прегледа директно за поддържаните превозвачи, форматите на заявките, удостоверяването, условията за употреба и наличните възможности. Това не означава автоматично, че тя е по-добра от директната връзка с UPS: правилният избор зависи от комбинацията от превозвачи, изискванията към данните, контрола върху интеграцията и търговските или регулаторните ограничения.

За справка, предназначена за потребители, а не за интеграция от разработчици, страницата за проследяване на 17TRACK може да е по-подходяща от изграждането на API връзка. За онлайн магазин, който се нуждае от брандирани актуализации след покупка, прегледайте отделно съответната интеграция с платформата, вместо да добавяте API работа, от която магазинът не се нуждае.

Често срещани грешки при реализацията

• Използване на стари примери: примерният код може да се отнася до изведена от употреба версия, стар метод за удостоверяване или друга услуга на UPS.
• Поставяне на тайни във frontend кода: всичко, изпратено към браузър, трябва да се счита за достъпно за инспектиране.
• Приемане, че празният резултат означава липса на пратка: проверете номера за проследяване, разрешенията на акаунта, средата и съобщението в отговора, преди да направите бизнес заключение.
• Преобразуване само на текст: описанията на статусите могат да се различават. Използвайте документираните кодове и запазвайте неизвестните стойности за преглед.
• Пренебрегване на изискванията към акаунта и употребата: техническият код може да е правилен, докато приложението не е конфигурирано за заявената услуга.
• Обновяване без бизнес правило: ненужното периодично извличане може да увеличи разходите, натоварването и оперативния шум, без да подобри потребителското изживяване.

Практически контролен списък за стартиране

1. Потвърдете, че приложението използва актуалната документация на UPS и одобрена среда.
2. Проверете дали идентификационните данни се съхраняват от страна на сървъра и могат да бъдат сменяни.
3. Тествайте неуспешно удостоверяване, грешки на превозвача, неправилен вход и изчаквания.
4. Сравнете нормализираните статуси с оригиналния отговор за представителни пратки.
5. Задайте политика за обновяване и наблюдавайте обема на заявките.
6. Определете отговорността за неидентифицирани събития, забавени актуализации и ескалации от клиенти.
7. Документирайте интеграцията, така че друг разработчик да може безопасно да обновява идентификационните данни, версиите на крайните точки и преобразуванията на статусите.

ЧЗВ

Нужен ли ми е UPS акаунт, за да използвам Tracking API?

Прегледайте актуалните изисквания на UPS за регистрация и достъп в Developer Portal. Достъпът до API може да зависи от регистрацията на приложението, идентификационните данни, конфигурацията на акаунта и конкретната заявена услуга. Не приемайте, че входът в публичната страница за проследяване е взаимозаменяем с достъпа до API за разработчици.

Безплатен ли е UPS Tracking API?

Не приемайте, че достъпът до API няма търговски условия или ограничения за употреба. UPS публикува актуална информация за услугите и акаунтите чрез официалните си канали, а някои изисквания могат да зависят от продукта, акаунта или споразумението. Потвърдете приложимите условия директно, преди да планирате производствения бюджет.

Мога ли да извиквам UPS API директно от JavaScript в браузър?

Заявка от браузър може да разкрие идентификационните данни на приложението и да създаде проблеми с междудомейнните заявки, сигурността и контрола на употребата. Сървърната интеграция обикновено е по-сигурният модел за съхранение на тайни, получаване на токени, прилагане на правила за повторни опити и ограничаване на достъпа до данните за пратките.

Колко често приложението ми трябва да заявява актуализации за проследяване?

Използвайте политика за обновяване въз основа на документираните ограничения на превозвача, обема на пратките, оперативната спешност и актуалността, изисквана от потребителите ви. Кеширайте последните резултати, когато е подходящо, използвайте постепенно увеличаване на интервала след временни повреди и не приемайте, че повтарящото се извличане е заместител на документирана възможност за събития или известия.

Трябва ли да използвам директна интеграция с UPS или API за множество превозвачи?

Директната интеграция с UPS може да е подходяща за работен процес, съсредоточен върху UPS, който се нуждае от специфичен контрол върху превозвача. API за множество превозвачи може да намали броя на интеграциите, когато пратките ви използват няколко превозвачи. Сравнете поддържаните превозвачи, удостоверяването, полетата с данни, изискванията за надеждност, условията за употреба и усилията за реализация, преди да изберете.

Източници

• UPS Developer Portal — официален каталог на API, достъп до приложения, удостоверяване и документация за разработчици.
• UPS Technology Integration — официална информация за интегрирането на технологиите на UPS с бизнес системи.
• 17TRACK Tracking API — официална продуктова страница и входна точка за разработчици за проследяване на множество превозвачи.
• 17TRACK API Documentation — официална API документация за удостоверяване, заявки и обработка на отговори.