Яндекс Маркет добавил уведомление об изменении заказа: что проверить в API

Что изменилось в Partner API 21 августа

21 августа 2026 года Яндекс Маркет обновил официальный журнал Partner API для продавцов. В методе POST notification появился отдельный тип события об изменении заказа. В схеме он обозначен значением ORDER_UPDATED. Одновременно документация изменила частоту повторных запросов, которые Маркет делает, если магазин не успел ответить за десять секунд или вернул техническую ошибку.

Это два связанных изменения. Первое дает интеграции более точный сигнал: у заказа поменялась дата отгрузки или дата доставки. Второе определяет, что произойдет, если приемник уведомления недоступен. Продавцу не нужно менять обычные методы получения заказов, но webhook-обработчик, очередь задач и мониторинг следует проверить на новом типе и новом ритме повторов.

Короткая запись в журнале не означает автоматическую готовность вашей системы. Если код принимает только старый список notificationType, он может отвергнуть ORDER_UPDATED как неизвестное значение. Если ответ формируется дольше допустимого времени, один проблемный запрос способен задержать остальные уведомления. Поэтому новость важна и разработчику, и владельцу кабинета, который зависит от своевременной обработки заказов.

Кого касается новое уведомление

Обновление касается продавцов, которые подключили API-уведомления в кабинете Маркета. Интеграция необязательна: магазин может работать через опрос методов API и кабинет. Но если уведомления уже используются для склада, доставки, CRM, 1С или собственной панели, новый тип события становится частью рабочего контракта и должен обрабатываться предсказуемо.

В зоне риска находятся самописные обработчики с жесткой проверкой enum, коннекторы, где неизвестное событие завершает запрос кодом 500, и системы, выполняющие тяжелую бизнес-логику прямо внутри HTTP-ответа. Также стоит проверить no-code сценарии: фильтр может пропускать только знакомые значения и молча отбрасывать ORDER_UPDATED, хотя внешний endpoint формально вернул успешный код.

Менеджеру маркетплейса не обязательно читать код. Ему достаточно запросить у интегратора четыре подтверждения: новый тип принят, подробности заказа запрашиваются отдельно, повторное событие не создает дубль, а предупреждение срабатывает до четырнадцатидневного отключения. Для понимания общей операционной роли полезен материал о том, как работает менеджер маркетплейсов.

Чем ORDER_UPDATED отличается от смены статуса

ORDER_UPDATED не следует смешивать с ORDER_STATUS_UPDATED. Статус описывает этап обработки заказа, например переход между состояниями выполнения. Новое уведомление сообщает об изменении отдельных параметров заказа. В текущей официальной схеме названы два варианта: SHIPMENT_DATE_UPDATED для даты отгрузки и DELIVERY_DATE_UPDATED для даты доставки.

Разница важна для маршрутизации. Смена статуса может запускать сборку, отмену, сообщение клиенту или закрытие операции. Изменение даты чаще требует пересчитать обещание, смену склада, курьерское окно, контроль просрочки и внутреннюю задачу сотрудника. Если оба события отправить в один старый обработчик без различения, система может выполнить неправильное действие.

В перечислении также есть UNKNOWN. Это сигнал не падать из-за незнакомой причины изменения. Безопасная логика сохраняет событие, обновляет полную карточку заказа и пишет предупреждение для разбора. Она не придумывает значение и не считает неизвестный вариант безусловной ошибкой Маркета.

Какие данные приходят в событии

Для уведомления об изменении заказа документация описывает объект OrderUpdatedNotificationDTO. В нем приходят notificationType со значением ORDER_UPDATED, orderId, campaignId, updateType и updatedAt. Дата передается в ISO 8601 со смещением относительно UTC. Этого достаточно, чтобы определить магазин, заказ, вид изменения и момент события.

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

Проверяйте схему расширяемо. Обязательные поля валидируются, неизвестные дополнительные поля не должны ломать прием. Значение notificationType следует маршрутизировать явно, но новый тип лучше отправить в безопасную очередь неизвестных событий, чем ответить 500 и заблокировать весь поток. Жесткий отказ оправдан только для действительно некорректного запроса.

Почему после уведомления нужно запросить заказ

Само уведомление не является полной карточкой заказа. Официальная справка рекомендует получить подробную информацию методом POST v1/businesses/{businessId}/orders с фильтром orderIds. Это важная граница: webhook сообщает, что произошло, а актуальное состояние нужно читать из основного API.

Между отправкой события и вашим запросом заказ может измениться снова. Поэтому нельзя безусловно считать поля уведомления последней истиной. Документация предупреждает, что время в уведомлении, ответе API и вашей системе может различаться. Актуальным нужно считать более позднее время события, если вы можете надежно сравнить значения.

Практическая схема выглядит так: быстро принять POST notification, положить задание в очередь, вернуть корректный ответ, затем запросить заказ и обновить локальную модель. Такой разрыв снижает риск таймаута. Он также позволяет повторить внутреннюю обработку, не заставляя Маркет ждать, пока CRM, склад и аналитика закончат свою работу.

Как теперь устроены повторные запросы

Для обычного уведомления допустимое время ответа составляет десять секунд. Проверочный PING должен получить ответ за одну секунду. Если магазин не уложился в десятисекундный предел или POST notification вернул ошибку, кроме кода 400, Маркет начинает повторять проблемный запрос по документированному графику.

Сначала запрос повторяется каждую минуту в течение первого часа. Затем он приходит каждые пятнадцать минут в течение первых суток. После этого повтор выполняется раз в час. Если API магазина остается недоступным четырнадцать дней с первой попытки, Маркет отключает магазин от интеграции уведомлений, отменяет недоставленные сообщения и перестает отправлять новые.

Код 400 имеет иной смысл: магазин сообщает, что само уведомление некорректно. Возвращать 400 при внутреннем сбое опасно, потому что это не просьба повторить запрос. Для технической ошибки документация указывает 500. Но лучшая защита состоит в том, чтобы принять валидное событие быстро и вынести тяжелую работу за пределы HTTP-обработчика.

Почему одно зависшее событие тормозит очередь

При проблемном запросе Маркет прекращает отправку других уведомлений, пока не получит подходящий ответ на застрявшее событие. Это превращает локальный дефект в общую задержку. Например, необработанный ORDER_UPDATED может задержать уведомления о новых заказах, отменах, возвратах и чатах, хотя сами эти события исправны.

Поэтому метрика количества ошибок недостаточна. Нужны возраст самого старого необработанного события, время последнего успешного ответа и размер внутренней очереди. Если события перестали приходить, причина может находиться не в отсутствии заказов, а в одном запросе, который постоянно возвращает ошибку или не успевает завершиться.

Не пытайтесь решить проблему увеличением таймаута своего приложения выше десяти секунд. Внешний предел от этого не изменится. Правильнее отделить прием от исполнения: проверить источник, разобрать минимальную схему, записать задачу в надежное хранилище и ответить. Все медленные обращения к базе, 1С и сторонним сервисам выполняются после подтверждения приема.

Как защититься от дублей и перестановки событий

Яндекс Маркет может присылать несколько уведомлений об одном событии, и в некоторых сценариях это считается нормальным поведением. Значит, обработчик должен быть идемпотентным: повторная доставка не создает вторую задачу на склад, не дублирует сообщение сотруднику и не портит дату в локальной системе.

Ключ дедупликации удобно строить из устойчивых полей события и собственной версии обработчика. Для ORDER_UPDATED можно учитывать campaignId, orderId, updateType и updatedAt. Однако слепо отбрасывать все повторения тоже нельзя: запрос подробностей заказа может вернуть более новое состояние. Сначала сравните время, затем решите, требуется ли обновление.

Защита от перестановки событий строится на монотонном обновлении. Старое updatedAt не должно перезаписать более новое значение. Неизвестный updateType сохраняется для аудита, но не запускает опасное действие. Для общего понимания повторяемых операций пригодится соседний разбор об обновлении отчета Partner API, где та же дисциплина защищает финансовый импорт.

Как проверить безопасность endpoint

Endpoint уведомлений должен работать по HTTPS с сертификатом официального центра сертификации. Самоподписанный сертификат не подходит. Маркет также публикует диапазоны IP-адресов, по которым рекомендует проверять источник запроса. Такой фильтр нужно обновлять по документации, а не зашивать навечно без контроля изменений.

Не помещайте токен Partner API в адрес webhook и не выводите секреты в журнал. Для запроса полной карточки заказа используйте отдельное защищенное хранилище ключей и минимальные права. Обработчик внешнего POST не должен уметь выполнять произвольные команды или принимать идентификатор внутреннего ресурса без проверки схемы.

Добавьте ограничение размера тела, проверку Content-Type, строгий JSON-парсер и корреляционный идентификатор. Но не превращайте защиту в хрупкий фильтр, который падает от нового необязательного поля. Безопасность здесь означает принять только ожидаемую структуру и одновременно пережить совместимое расширение API.

Практические сценарии для продавца и интегратора

Сценарий первый: дата доставки изменилась после согласования заказа. ORDER_UPDATED с DELIVERY_DATE_UPDATED попадает в очередь, обработчик запрашивает актуальный заказ и обновляет обещание в CRM. Сообщение сотруднику создается только после сравнения старой и новой даты, поэтому повторный webhook не порождает второй тикет.

Сценарий второй: дата отгрузки сдвинулась, а складская система отвечает медленно. HTTP endpoint не ждет склад. Он фиксирует SHIPMENT_DATE_UPDATED, возвращает успешный ответ и запускает фоновую задачу. Если склад временно недоступен, повторяется внутренняя задача, а не внешний запрос Маркета.

Сценарий третий: новое значение updateType еще не известно вашему коду. Система сохраняет событие как UNKNOWN, обновляет заказ через основной API и ставит предупреждение разработчику. Заказ продолжает обрабатываться, другие уведомления не блокируются. Такой режим лучше аварийного ответа 500 на каждое совместимое расширение.

Сценарий четвертый: подрядчик утверждает, что интеграция работает, но в кабинете растет журнал ошибок. Продавец проверяет время старейшего события, коды ответов и PING. Затем воспроизводит тестовый заказ и убеждается, что webhook принимает изменение даты. Это конкретнее общего обещания и помогает оценить процессы работы с маркетплейсами.

Подтвержденная хронология изменения

До 21 августа API-уведомления уже сообщали о создании и отмене заказа, смене статуса, возвратах, заявках на отмену, чатах и других событиях. Документация также предупреждала о возможных повторных уведомлениях и необходимости учитывать более позднее время события.

21 августа 2026 года официальный журнал зафиксировал два изменения: добавлен тип уведомления об изменении заказа и изменена частота повторов при десятисекундном таймауте или ошибке магазина. В актуальной справке ORDER_UPDATED описан с полями orderId, campaignId, updateType и updatedAt.

После обновления документированный график повторов состоит из минутных попыток в первый час, попыток каждые пятнадцать минут в первые сутки и почасовых попыток далее. Граница отключения интеграции составляет четырнадцать дней. Эти значения нужно проверять в актуальной документации перед изменением аварийных регламентов, потому что владелец API может обновить правила снова.

Ограничения и важные оговорки

Новость не означает, что уведомления обязательны для каждого продавца. Без них можно продолжать работать через кабинет и обычные методы API. Но если интеграция подключена, неизвестный тип нельзя игнорировать без учета последствий. Выбор между webhook и периодическим опросом зависит от нагрузки, требований к скорости и готовности поддерживать endpoint.

ORDER_UPDATED пока перечисляет изменение даты отгрузки и даты доставки, а также UNKNOWN. Не следует придумывать дополнительные причины и строить бизнес-логику на догадке. Для полного состояния всегда запрашивайте заказ. Уведомление может прийти позже другого изменения, а повторная доставка не гарантирует новый факт.

Статья не заменяет тест в вашем кабинете. Роли, модели размещения и набор событий могут отличаться. Создайте тестовый заказ, проверьте PING и журнал уведомлений. Для более широкой картины данных продавца полезны материалы о том, как анализировать продажи, и о маркетплейсах в 1С.

Что сделать прямо сейчас

Сначала добавьте ORDER_UPDATED в допустимые notificationType и заведите отдельную ветку для SHIPMENT_DATE_UPDATED, DELIVERY_DATE_UPDATED и UNKNOWN. Затем убедитесь, что endpoint возвращает ответ быстрее десяти секунд, а PING проходит за одну секунду. Тяжелую работу перенесите в очередь с повторяемыми заданиями.

После этого проверьте дедупликацию и порядок событий. Повторите одинаковый payload дважды, отправьте сначала новое updatedAt, затем старое, и убедитесь, что локальное состояние не откатывается. Отдельно смоделируйте 500 и таймаут, чтобы мониторинг показал проблему до остановки потока.

Наконец, обновите регламент. Запишите график внешних повторов, четырнадцатидневную границу отключения, ответственного за журнал ошибок и способ повторного подключения. Владелец кабинета должен знать, где увидеть проблему, даже если разработчик недоступен. Базовые обязанности роли собраны в статье что не может менеджер маркетплейсов.

Вывод KGAM

Новое уведомление выглядит небольшим дополнением enum, но для живой интеграции оно меняет контракт. ORDER_UPDATED позволяет быстрее заметить перенос отгрузки или доставки, а новый график повторов делает цену медленного endpoint понятной. Один неразобранный запрос способен задержать весь поток, поэтому обработчик должен быть быстрым, расширяемым и наблюдаемым.

Рекомендация KGAM проста: принимайте событие за секунды, а не выполняйте внутри него весь бизнес-процесс. Полное состояние заказа читайте отдельным запросом, повторы переживайте идемпотентно, старое updatedAt не позволяйте записывать поверх нового. UNKNOWN сохраняйте и разбирайте, не блокируя остальные события.

Если Маркет расширит виды изменений, усиливайте этот canonical вместо создания второго материала с тем же интентом. Для дальнейшей настройки пригодятся объяснение устройства маркетплейса и разбор карточки товара, но сегодняшняя задача конкретна: проверить webhook, очередь и повторные запросы.