Статус на доставката на Shipping API: кодове на състоянието, уебхукове и сигнали за изключения

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

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

Отделяйте HTTP кодовете, резултатите от API и статусите на пратките

Изразът „код на статуса“ може да се отнася до три различни слоя. Смесването им създава подвеждащи табла и ненужни известия към клиентите.

Слой	Какво ви показва	Примерно тълкуване
HTTP отговор	Резултатът от HTTP заявката	Отговор 200 показва успех на HTTP ниво; това не означава, че пратката е доставена.
Бизнес резултат от API	Дали заявената операция е изпълнена успешно съгласно приложните правила на доставчика	Тялото на отговора може да съобщи, че регистрацията за проследяване е отхвърлена, включително в успешен HTTP отговор, ако API използва такъв дизайн.
Статус на пратката	Съобщеното физическо или оперативно състояние на пратката	В транзит, очаква получаване или доставена.

Стандартът за семантика на HTTP определя значенията на HTTP отговорите. Например 202 Accepted означава, че заявката е приета за обработка, но обработката не е непременно завършила. Това не е доказателство, че превозвачът е приел пратка.

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

Създайте модел на статусите, без да губите подробностите от превозвача

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

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

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

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

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

Изградете обработката на webhook около надеждното получаване

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

1. Удостоверете заявката. Прилагайте документирания метод за проверка на доставчика. Ако се поддържат подписи, валидирайте ги чрез посочения алгоритъм и необработените байтове на заявката. Не измисляйте header за подпис и не приемайте, че всяка услуга използва HMAC.
2. Валидирайте полезния товар. Проверявайте задължителните полета, типовете, размера на полезния товар и връзката с пратка, която се управлява от вашия акаунт. Обработвайте неизвестните незадължителни полета, без излишно да нарушавате обратната съвместимост.
3. Запазете преди потвърждение. Съхранете приетото събитие или го поставете в устойчива опашка, преди да изпратите документирания успешен отговор. Ако запазването е неуспешно, не потвърждавайте, че събитието е безопасно получено.
4. Обработвайте асинхронно. Когато е практично, извършвайте съпоставянето на статуси, актуализациите на поръчки и решенията за известия извън обработчика на заявката.
5. Направете страничните ефекти идемпотентни. Повторно събитие не трябва да създава нова заявка към поддръжката или да изпраща ново копие на същото клиентско съобщение.

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

Използвайте HTTPS и не съхранявайте идентификационни данни в URL адреси и обичайни логове. Прилагайте контрол на достъпа към съхранените полезни товари, тъй като данните за проследяване могат да съдържат лична информация. OWASP REST Security Cheat Sheet предоставя подходящи насоки за защита на преноса, валидиране на входа и сигурност на крайните точки.

Дедупликирайте събитията, без да потискате реалните актуализации

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

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

Отделяйте часа на събитието от часа на получаване

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

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

Превръщайте изключенията в действия с определен отговорник

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

Започнете с малка политика за маршрутизиране:

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

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

Разглеждайте „няма актуализация“ като отделно състояние

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

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

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

Наблюдавайте състоянието на интеграцията отделно от ефективността на доставката

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

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

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

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

Тествайте случаите на откази, преди да активирате известията към клиентите

Започнете с обработка само за вътрешна употреба и проверете представителни пратки, преди да разрешите промените на статуси да изпращат клиентски съобщения. Тествайте повече от нормалното преминаване от „в транзит“ към „доставена“.

• Дублиран webhook създава едно планирано клиентско известие.
• По-старо събитие, пристигнало със закъснение, не заменя неправилно текущото състояние.
• Неизвестен статус се запазва и маркира, вместо тихо да бъде съпоставен с „доставена“.
• Неуспешно устойчиво записване не води до успешно потвърждение.
• Временно прекъсване на последваща система оставя събитията налични за повторен опит.
• Събитие „доставена“, последвано от корекция, остава одитируемо.
• Поръчка с множество пратки не става напълно доставена, когато е доставена само една пратка.
• Прекъсване на API известява инженерния екип, без автоматично да съобщава на клиентите, че пратките им са забавени.

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

ЧЗВ

Означава ли HTTP 200, че пакетът е доставен?

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

Трябва ли да използвам webhook или polling за актуализациите на проследяването?

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

Защо статусът на проследяването може да се промени след „доставена“?

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

Колко бързо трябва да бъде изпратено известието за изключение?

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

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

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

Източници

• RFC 9110: HTTP Semantics — справочник за значенията на HTTP кодовете за статус, включително 200 и 202.
• OWASP REST Security Cheat Sheet — насоки за сигурност, свързани с API и webhook крайни точки.
• 17TRACK Tracking API — официален продуктов справочник за разглежданата възможност за интеграция с проследяването.
• 17TRACK API Documentation — официален справочник за специфичните за доставчика изисквания за интеграция; илюстративните схеми и препоръки за работния процес в това ръководство не са заместител на този договор.