UPS Tracking API: Ръководство за начинаещи как да започнете

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

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

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

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

Тези данни могат да поддържат няколко практически функции:

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

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

UPS Tracking API спрямо уебсайта на UPS

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

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

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

Какво ви е необходимо, преди да направите заявка

Подгответе следните елементи, преди да напишете интеграцията:

1. Акаунт за разработчици на UPS. Използвайте официалния UPS Developer Portal, за да прегледате наличните API и да създадете приложение.
2. Идентификационни данни за приложението. Точните имена на идентификационните данни и потокът за удостоверяване трябва да бъдат взети от актуалната документация на UPS. Не поставяйте клиентски тайни в браузърен код, мобилни приложения, публични хранилища или страници, видими за клиентите.
3. Валиден номер за проследяване за тестване. Тествайте с пратки, до които организацията ви има право на достъп, и избягвайте излагането на лични или търговски данни за пратки в журналите.
4. Сървърна точка за интеграция. Backend услуга обикновено е по-безопасна от директно извикване на превозвача от публична уебстраница, защото може да пази идентификационните данни в тайна и да контролира обема на заявките.
5. План за съхранение на отговорите. Решете кои полета са ви нужни, колко дълго да ги съхранявате и как да свържете събитие от превозвача с вътрешна поръчка.

Работен процес за интеграция, подходящ за начинаещи

1. Потвърдете бизнес изискването

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

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

2. Регистрирайте приложението

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

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

3. Реализирайте удостоверяването

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

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

4. Изпратете заявка за проследяване

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

Концептуалната заявка изглежда така:

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

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

5. Нормализирайте отговора

Отговорите на превозвача невинаги са написани на езика, който клиентите ви очакват. Създайте вътрешен модел на събитията със стабилни полета, например:

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

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

6. Решете как ще се извличат актуализациите

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

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

Често срещани грешки и как да ги обработвате

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

Кога multi-carrier API е по-подходящо

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

Ако операцията ви използва няколко превозвача, multi-carrier услуга може да намали броя на отделните интеграции. Tracking API на 17TRACK е предназначено за проследяване на пратки чрез приложения, а неговата официална документация за разработчици обяснява наличния модел за интеграция. Струва си да го оцените, когато реалното изискване не е само проследяване на UPS, а единен слой за проследяване при различни превозвачи.

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

Контролен списък за готовност за продукция

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

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

Често задавани въпроси

Нуждая ли се от API, ако проследявам само няколко пакета?

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

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

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

Създава ли API за проследяване транспортни етикети?

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

Защо валиден номер за проследяване може да върне малко информация?

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

Трябва ли да избера директно UPS или multi-carrier API за проследяване?

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

Източници

• UPS Developer Portal
• Документация и ресурси за продукта UPS Tracking API
• 17TRACK Tracking API
• Документация за 17TRACK API