Статус на испорака во Shipping API: кодови на статуси, веб-куки и известувања за исклучоци

Статусот на испорака во shipping API го опишува напредокот на пратката, а не дали API-барањето било успешно. За да изградите сигурно следење, одвојте ги HTTP-кодовите за одговор од статусите на пратката, обработувајте ги webhook-овите без да претпоставувате дека пристигнуваат еднаш или по редослед, и претворете ги исклучоците што бараат дејство во известувања со јасно назначени одговорни лица. За инженерските и ecommerce оперативните тимови, целта е записот за пратката да остане доверлив кога ажурирањата од превозникот доцнат, се дуплираат или се коригираат.

Овој водич објаснува како да го структурирате тој запис, како да се справите со дојдовните настани за следење и како да разликувате проблем со испораката од проблем со интеграцијата за следење.

Одвојте ги 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-барање испратено до вашиот endpoint за известување за настан. Тој може да ја намали потребата од повторено испитување, но не треба да се третира како гаранција за непосредна, подредена или точно еднаш испорака. Дизајнирајте го приемникот да толерира повторни обиди, прекини и неочекувани payload-и, освен ако давателот изречно не гарантира поинаку.

1. Автентицирајте го барањето. Применете го документираниот метод за проверка на давателот. Ако се поддржуваат потписи, проверете ги со наведениот алгоритам и со необработените бајтови на барањето. Не измислувајте заглавие за потпис и не претпоставувајте дека секоја услуга користи HMAC.
2. Проверете го payload-от. Проверете ги задолжителните полиња, типовите, големината на payload-от и поврзаноста со пратка со која управува вашата сметка. Обработувајте ги непознатите опционални полиња без непотребно нарушување на компатибилноста со идни верзии.
3. Зачувајте пред да потврдите. Зачувајте го прифатениот настан или ставете го во трајна редица пред да го испратите документираниот успешен одговор. Ако зачувувањето не успее, не потврдувајте дека настанот е безбедно примен.
4. Обработувајте асинхроно. Кога е практично, извршувајте го мапирањето на статусите, ажурирањата на нарачките и одлуките за известувања надвор од обработувачот на барањето.
5. Направете ги несаканите ефекти идемпотентни. Повторен настан не треба да создаде нов тикет за поддршка или да испрати нова копија од истата порака до клиентот.

Точниот код за потврда, timeout-от, распоредот за повторни обиди и однесувањето при повторно пуштање зависат од давателот. Проверете ги овие детали експлицитно. Општото упатство „вратете 200“ не е замена за договорот за webhook.

Користете HTTPS и чувајте ги акредитивите надвор од URL-адресите и рутинските логови. Применете контроли за пристап до зачуваните payload-и бидејќи податоците за следење може да содржат лични информации. OWASP REST Security Cheat Sheet обезбедува релевантни насоки за заштита на преносот, проверка на влезот и безбедност на endpoint-ите.

Дедуплицирајте ги настаните без потиснување на вистинските ажурирања

Кога е достапен, претпочитајте документиран и стабилен идентификатор на настанот. Во спротивно, изведете клуч за дедупликација од внимателно избрана комбинација на идентитетот на пратката, временската ознака на настанот, кодот на настанот и локацијата. Тестирајте го овој пристап со вистински payload-и: два легитимни настани може да имаат иста временска ознака, а истиот настан може да пристигне со малку различен описен текст.

Користете одделни контроли за дедупликација за приемот на настани и за дејствата што следуваат. Ажурирањето на статусот можеби треба повторно да се зачува како корекција, додека известувањето до клиентот треба да остане потиснато. На секое известување или дејство со тикет доделете сопствен траен идентитет.

Одвојте го времето на настанот од времето на прием

Да претпоставиме дека настан за пратка во транзит стигнува до вашиот систем по настан „на достава“, но временската ознака на превозникот е порана. Зачувајте го во историјата без автоматски да го менувате тековниот статус назад во „во транзит“.

Самото подредување според временските ознаки не е доволно за секој случај. Недостигот на временски зони, коригираните скенирања и конфликтните извори бараат експлицитни правила. Зачувајте ја прецизноста и отстапувањата на временските ознаки, евидентирајте кога вашиот систем го примил секој настан и користете документирани информации за редоследот од давателот кога се достапни. Не наметнувајте строго скалило на статуси што може да се движат само напред: обидите за испорака, пренасочувањата, враќањата и корекциите може да создадат легитимни транзиции што изгледаат како враќање назад.

Претворете ги исклучоците во дејства со назначени одговорни лица

Известувањето за исклучок треба да објасни што се случило, какво дејство е потребно и кој е одговорен за следниот чекор. Општата порака „исклучок на пратката“ ги остава оперативните работници повторно да ја спроведуваат истата истрага и може да ги вознемири клиентите без да им помогне.

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

• Проблем со адресата или пристапот: Насочете го случајот до корисничката поддршка за да го потврди проблемот и да ја провери достапната постапка за корекција кај превозникот. Не ветувајте промена на адресата пред да потврдите дека е можна.
• Потребно е преземање: Известете го примачот кога изворот обезбедува употребливи упатства за преземање. Зачувајте го секој потврден рок.
• Потребно е царинско дејство: Доделете го случајот според тоа кој треба да ги обезбеди бараните документи или информации. Сам настан поврзан со царина не утврдува дека треба да се изврши плаќање.
• Неуспешен обид за испорака: Проверете го пријавениот следен чекор пред да советувате повторна испорака или преземање.
• Враќање до испраќачот: Отворете оперативна проверка. Не издавајте автоматски поврат само врз основа на широка ознака за следење, освен ако вашата политика изречно го дозволува тоа.
• Загуба или оштетување пријавено од превозникот: Насочете го случајот до одговорното лице за побарувања и зачувајте ги доказите за настанот. Одлуките за побарувањата одвојте ги од општото откривање доцнења.

Секое известување треба да содржи идентификатор на пратката, референца на нарачката, причина за настанот, изворна временска ознака, последна позната состојба, назначено одговорно лице и следно дејство. Вклучете врска до релевантниот интерен запис наместо да изложувате непотребни детали за клиентот во споделени канали за пораки.

Третирајте го „нема ажурирање“ како посебна состојба

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

Дефинирајте ги праговите на неактивност според услугата, маршрутата, фазата на испорака и деловната обврска, наместо да применувате еден универзален тајмер. Разликувајте пратка што никогаш не добила скенирање за прием од пратка што престанала да се ажурира по влезот во мрежата. Ако историските докази се ограничени, користете го прагот за активирање истрага, а не за прогласување загуба.

Потиснете ги повторените известувања додека непроменетиот случај останува отворен. Ескалирајте кога ќе се појават нови докази, ќе биде пропуштено договореното следење или обврската за испорака до клиентот бара интервенција.

Следете го здравјето на интеграцијата одделно од успешноста на испораката

Следењето на API одговара дали вашата интеграција за следење функционира. Следењето на испораката одговара што се случува со пратките. Здрав endpoint може да прима застарени податоци од превозникот, додека недостапен endpoint може да пропушти ажурирања за пратки што нормално се движат.

• Здравје на барањата: Следете ги неуспесите при автентикација, timeout-ите, одговорите со ограничување на стапката, грешките на серверот и одбивањата на апликативно ниво.
• Здравје на webhook-овите: Следете ги неуспесите при проверка, латентноста на потврдата, неуспесите при зачувување, дуплираните испораки и грешките при обработка.
• Здравје на обработката: Следете ја староста на редицата, необработените настани, неуспесите во мапирањето и неуспесите на известувањата.
• Актуелност на следењето: Мерете го времето од последниот настан од изворот одделно од времето од последниот успешен прием во вашиот систем.
• Оперативни резултати: Следете ги нерешените исклучоци, времето до преземање на одговорноста и задоцнетите следни дејства.

За повторните обиди на барањата, следете ги насоките на давателот за ограничување на стапката и повторување. Избегнувајте слепо повторување операции што може да создадат дуплирани регистрации или други несакани ефекти; користете документирани механизми за идемпотентност кога се достапни.

Кога е поддржано, користете процес на усогласување за да го преземете најновиот запис за следење по прекини или сомнителни пропуштени настани. Поставете ја неговата фреквенција во рамките на договорните и стапковните ограничувања. Webhook-овите и усогласувањето имаат различни цели: едното доставува промени, а другото помага да се откријат и поправат празнините.

Тестирајте ги случаите на неуспех пред да ги овозможите известувањата до клиентите

Започнете со обработка само за интерна употреба и проверете репрезентативни пратки пред статусните промени да почнат да испраќаат пораки до клиентите. Тестирајте повеќе од нормалниот напредок од „во транзит“ до „доставено“.

• Дуплиран webhook создава едно планирано известување до клиентот.
• Подоцнежниот прием на постар настан не ја заменува погрешно тековната состојба.
• Непознат статус се зачувува и се означува наместо тивко да се мапира во „доставено“.
• Неуспешното трајно запишување не создава успешно потврдување.
• Привремениот прекин на downstream-системот ги остава настаните достапни за повторен обид.
• Настан „доставено“ проследен со корекција останува ревидлив.
• Нарачка со повеќе пратки не станува целосно доставена кога е доставена само една пратка.
• Прекинот на 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 endpoint-и.
• 17TRACK Tracking API — официјална референца за производот и опцијата за интеграција за следење.
• 17TRACK API Documentation — официјална референца за барањата специфични за интеграцијата со давателот; илустративните шеми и препораките за работниот тек во овој водич не се замена за тој договор.