UPS Tracking API Webhooks: Какво представляват, как работят и случаи на употреба
Уебхуковете на UPS tracking API позволяват на дадено приложение да получава актуализации за пратки, когато е налично събитие за проследяване, вместо многократно да отправя заявки към услуга за проследяване за най-новия статус. Те са полезни за електронни магазини, логистични екипи, онлайн пазари и разработчици, които изграждат работни процеси за управление на поръчки. Практическата им стойност не се изчерпва с по-бързата синхронизация на статусите: добре проектираният поток от уебхукове може да актуализира страниците, видими за клиентите, да задейства обработка на изключения и да намали ненужните заявки за проследяване.
Точният метод за удостоверяване, моделът на събитията, ограниченията за заявките, полетата в полезния товар и изискванията към акаунта зависят от продукта за разработчици на UPS и средата за интеграция. Разработчиците трябва да проверят тези подробности в актуалната документация на UPS, преди да изграждат връзка за продукционна среда.
Какво представлява уебхукът на UPS tracking API?
Tracking API предоставя програмно средство за заявяване на информация за пратки. Уебхукът добавя модел за изходящи известия: след като приложението се абонира за съответните актуализации, услугата изпраща HTTP заявка до крайна точка, контролирана от приложението, когато възникне събитие, отговарящо на зададените условия.
Например система за поръчки може да съхранява номер за проследяване на UPS и да регистрира крайна точка за уебхук. Когато статусът на пратката се промени, получаващата система може да получи известие, съдържащо комбинация от номера за проследяване, статус, времеви печат, местоположение, очаквана дата на доставка или информация за изключение. След това получаващата система валидира съобщението, актуализира собствения си запис и определя какво действие трябва да последва.
Уебхукът не е същото като страница за проследяване. Страницата за проследяване е предназначена за преглед от човек. Уебхукът е предназначен за обработка от софтуер. Той също така не гарантира, че всяко сканиране от превозвача ще бъде доставено точно веднъж или в идеален ред. Продукционните системи трябва да бъдат проектирани с оглед на дублирани съобщения, забавена доставка, повторни опити и периодична сверка.
Как обикновено работи процесът
- Разработчикът създава или конфигурира достъп чрез приложимия акаунт за разработчици на UPS и получава идентификационните данни, изисквани от API.
- Приложението изпраща или съхранява идентификатора на пратката, обикновено номера за проследяване, заедно с вътрешни препратки към поръчката и клиента.
- Разработчикът конфигурира публично достъпна HTTPS крайна точка и следва процедурата на доставчика за абонамент или регистрация, ако е необходимо.
- Услугата за проследяване изпраща HTTP известие, когато е налична абонирана актуализация.
- Крайната точка удостоверява или проверява заявката, анализира полезния товар и проверява дали пратката е позната.
- Приложението потвърждава заявката бързо, след което обработва бизнес действието чрез опашка или фонов работник.
- Системата записва събитието, прилага правила за идемпотентност и актуализира работния процес за поръчката, склада, поддръжката или известяването на клиента.
Това разделяне между потвърждаване и обработка е важно. Изпращачът на уебхука може да направи нов опит, ако крайната точка е бавна или върне грешка. Получател, който извършва обширни операции с база данни, изпращане на имейли или обработка в склада, преди да отговори, може да създаде изтичане на времето и дублирани доставки.
Известия чрез уебхукове спрямо периодично извличане
| Подход | Как работи | Основен компромис |
|---|---|---|
| Периодично извличане | Вашето приложение заявява най-новия статус по график. | Лесно е за разбиране, но повтарящите се заявки могат да добавят забавяне и ненужен трафик. |
| Доставка чрез уебхук | Услугата за проследяване изпраща известие, когато е налична актуализация. | Може да намали проверките по график, но изисква сигурен, надежден получател и процес за възстановяване. |
| Хибриден модел | Уебхуковете задействат обичайната обработка, докато периодичното извличане или сверяването проверява за пропуски. | Изисква повече проектна работа, но често е по-устойчив от разчитането на един канал за доставка. |
Уебхукът не премахва автоматично необходимостта от API заявки. Някои интеграции използват известието като сигнал и след това извикват tracking API, за да получат най-новия авторитетен запис. Това може да е полезно, когато полезният товар на уебхука е компактно събитие, когато приложението се нуждае от подробности за пратката, които не са включени в известието, или когато бизнесът иска единен път за нормализиране на всички актуализации.
Какво трябва да съдържа полезният товар на уебхука за проследяване?
Полезните товари се различават според доставчика и продукта. Не проектирайте базата си данни въз основа на предполагаеми имена на полета, преди да проверите актуалната документация и тестовите отговори. По принцип събитието за проследяване може да трябва да идентифицира:
- Пратката или номера за проследяване
- Събитието или статуса на пратката
- Часа на събитието и, когато е предоставена, местната часова зона
- Описание на сканирането или оперативно съобщение
- Информация за местоположението, когато е налична
- Прогнозна или потвърдена доставка, когато е предоставена
- Индикатор или описание на изключение
- Идентификатор на събитие от доставчика или друга стойност, полезна за премахване на дубликати
Третирайте текста на статуса като данни от доставчика, а не като универсално бизнес правило. Етикет като „в транзит“, „изключение“ или „доставено“ може да трябва да бъде преобразуван към вътрешен модел на статусите. Системата ви трябва да съхранява както оригиналния статус от превозвача, така и нормализирания статус, за да могат служителите по поддръжката да проучват разликите, без да губят изходното съобщение.
Практически случаи на употреба
Актуализации за доставката до клиента
Платформа за електронна търговия може да използва събитията за проследяване, за да обновява страница със статуса на поръчката или да изпраща известие до клиента. Най-добрият тригер зависи от бизнес правилото. Сканирането при приемане на пратката може да потвърди, че изпълнението е напреднало, докато събитие за изключение може да изисква съобщение от поддръжката, а не общ имейл със статус. Избягвайте изпращането на известие за всяко сканиране, освен ако клиентите изрично не са поискали такова ниво на подробност.
Управление на изключения
Уебхукът може да насочва потенциални проблеми с доставката към опашка за преглед. Примерите включват изключение при доставка, проблем, свързан с адреса, или пратка, която не е напреднала според очакванията. Интеграцията трябва да разграничава информационното сканиране от оперативното изключение. Тя също трябва да определи отговорността: поддръжката на клиенти може да се занимава с комуникацията, докато екипът по изпълнение може да проучва пратката или адреса.
Синхронизация на склада и управлението на поръчки
Складова система или система за управление на поръчки може да използва събитията за проследяване, за да актуализира записа за изпълнение, без служителите да проверяват ръчно сайта на превозвача. Това е особено полезно, когато една поръчка съдържа няколко пакета. Моделът на данните трябва да поддържа записи за проследяване на ниво пакет, вместо да приписва един статус на цялата поръчка, тъй като пакетите от една и съща поръчка могат да се придвижват или да пристигат по различно време.
Връщания и обратна логистика
Работните процеси за връщане могат да използват събитията за проследяване, за да определят кога даден пакет се връща към търговеца или кога достига до обект за връщания. Самото събитие не трябва да разрешава възстановяване на сумата, освен ако политиката на търговеца изрично не използва това условие. След като превозвачът съобщи за доставката, връщането може да изисква проверка, сверяване на наличностите или преглед за измама.
Оперативни отчети
Нормализираните събития за проследяване могат да подпомагат отчети за напредъка на пратките, обема на изключенията и резултатите от доставките. Отчетите трябва ясно да посочват своите определения. Например „доставено“ може да означава събитие за доставка, съобщено от превозвача, докато „навреме“ изисква определени обещана дата, краен час, часова зона и начин на третиране на промените в адреса или забавянията, поискани от клиента.
Интеграция само с UPS или API за множество превозвачи?
Специфичната за UPS интеграция може да е подходяща, когато бизнесът изпраща основно с UPS и иска да работи директно с официалната му среда за разработчици. Тя може да бъде и най-простият избор, когато съществуващата система за поръчки вече разполага с UPS конектор и необходимите работни процеси са ограничени.
API за проследяване на множество превозвачи е различен архитектурен избор. То може да осигури единен модел за интеграция между превозвачите, но приложението все пак трябва да обработва специфичната за всеки превозвач семантика на статусите, различията в обхвата, изискванията за удостоверяване и качеството на данните. Услуга за множество превозвачи не трябва да се избира само защото рекламира уебхук. Проверете поддържаните превозвачи, нормализирането на събитията, документацията, тестовата среда, правилата за съхранение и оперативната поддръжка.
Tracking API на 17TRACK е подходящо за екипи, които оценяват подход за проследяване на множество превозвачи, докато неговата официална API документация трябва да се използва за проверка на текущите възможности, форматите на заявките и изискванията за интеграция. То не заменя проверката дали превозвачите и събитията, необходими за конкретен UPS работен процес, се поддържат за предвидения случай на употреба.
Контролен списък за внедряване
- Потвърдете обхвата на продукта. Проверете дали избраната UPS услуга поддържа операциите за проследяване и модела на известията, от които се нуждае приложението ви.
- Използвайте HTTPS. Получателят трябва да бъде защитен при преноса и не трябва да разкрива идентификационни данни в URL адреси или логове.
- Проверявайте автентичността. Следвайте документирания от доставчика метод за подпис, токен или проверка. Ако няма наличен метод, използвайте мрежови ограничения и проверка на заявките, подходящи за услугата.
- Направете обработката идемпотентна. Съхранявайте идентификатор на събитието, когато е наличен, или създайте консервативен ключ за премахване на дубликати от стабилни полета на събитието.
- Приемайте събития извън ред. Използвайте времеви печати на събитията и документирана политика за преход между състоянията, вместо да приемате, че редът на пристигане съвпада с реда на сканиране.
- Връщайте бърз отговор. Поставяйте по-дългите задачи в опашка и наблюдавайте неуспешните доставки, повторните опити и съобщенията в опашката за неуспешни съобщения.
- Сверявайте пропуските. Планирайте контролиран процес за проверка на пратки без скорошна актуализация, с неуспешна доставка или с несъответстващо състояние.
- Защитавайте личните данни. Ограничете съхраняваната информация за адреса и получателя, ограничете достъпа и задайте правила за съхранение, съобразени с бизнес нуждите.
- Тествайте реални бизнес случаи. Включете доставени пратки, изключения, отменени поръчки, дублирани събития, неизвестни номера за проследяване и забавени известия.
Често срещани грешки, които трябва да се избягват
Най-честата грешка при проектирането е уебхукът да се третира като пълен източник на истина, без да се планира обработка на повторни опити или липсващи събития. Друга грешка е директното актуализиране на статуса на поръчката въз основа на свободен текст без слой за съпоставяне. Това може да доведе до неправилни съобщения към клиентите, когато терминологията на превозвача се промени или когато събитието се отнася само до един пакет.
Екипите трябва също да избягват излагането на крайна точка за уебхук без контрол срещу злоупотреби, записването на пълни полезни товари, съдържащи ненужна лична информация, и изпращането на известия до клиентите, преди събитието да е преминало базова проверка. Накрая, не обещавайте срокове за доставка само защото отговорът за проследяване съдържа прогноза. Прогнозите могат да се променят, а формулировката към клиента трябва да отразява тази несигурност.
Как да изберете подход за интеграция
Изберете директна интеграция с UPS, когато обхватът на превозвачите е ограничен, екипът се чувства уверен в поддръжката на специфична за превозвача логика и необходимите официални функции са налични. Обмислете API за проследяване на множество превозвачи, когато бизнесът се нуждае от единен вътрешен интерфейс за няколко превозвача и има достатъчен обем или сложност, които оправдават абстракционен слой. И в двата случая сравнявайте действителната документация и поведението при тестове, а не само имената на функциите.
Преди внедряването в продукционна среда проведете доказателство за концепция с представителни номера за проследяване и сценарии за отказ. Потвърдете как се създават абонаментите, как се сменят идентификационните данни, как се проверяват известията, как изглеждат дублираните събития, как се обработват историческите актуализации и какво се случва, ако получателят е недостъпен. Тези отговори определят дали интеграцията ще остане надеждна след първоначалната демонстрация.
ЧЗВ
По-добър ли е уебхукът на UPS tracking API от периодичното извличане?
Нито един от подходите не е автоматично по-добър. Уебхуковете могат да намалят проверките по график и да подпомогнат по-бързата реакция, докато периодичното извличане може да бъде по-лесно за контрол и да помогне при сверяването на пропуснати събития. Много продукционни системи използват известия чрез уебхукове заедно с ограничени заявки за сверка.
Нужен ли ми е уебхук, ако проследявам само малък брой пратки?
Не непременно. За малък работен процес с ниска честота може да е достатъчен документиран процес за периодично извличане или съществуваща интеграция на платформа. Уебхукът става по-привлекателен, когато актуализациите трябва да задействат автоматизирани действия или когато редовната ръчна проверка създава оперативна работа.
Може ли уебхукът да гарантира, че всяко сканиране на UPS достига до системата ми?
Не трябва да приемате, че може. Поведението при доставка, повторните опити, редът на събитията и съхранението зависят от конкретната услуга. Вградете наблюдение, идемпотентност и сверяване в интеграцията и потвърдете приложимите гаранции в актуалната документация на UPS.
Трябва ли всяко събитие за проследяване да задейства имейл до клиента?
Обикновено не. Съпоставяйте събитията на превозвача с правилата за комуникация с клиента и запазете съобщенията за важни етапи или изключения, които са полезни за получателя. Съхранявайте оригиналното събитие във вътрешната история, дори когато то не генерира известие.
Кога бизнесът трябва да използва API за проследяване на множество превозвачи?
Струва си да го оцените, когато бизнесът изпраща чрез множество превозвачи и иска споделен работен процес за проследяване. Решението трябва да отчита поддръжката на превозвачите, нормализираните данни, поведението на уебхуковете, документацията, сигурността, тестването и усилията, необходими за поддръжка на интеграцията.
