Push-уведомления Ozon API: как ловить новый заказ за секунды вместо опроса раз в 15 минут
Требования Ozon к адресу и сертификату для push-уведомлений, разбор типов событий, какой ответ площадка ждёт на каждый запрос, что происходит при недоступности вашего сервера и как догонять пропущенные события сверкой через обычный API.
Новый заказ FBS появляется у вас в системе не в момент покупки, а когда скрипт в очередной раз сходил в API. При опросе раз в 15 минут средняя задержка — 7–8 минут, и отъедаете вы их у себя же: на вечерних заказах эти минуты оборачиваются лишним кругом до пункта приёма. Push разворачивает схему — Ozon сам стучится на ваш адрес и приносит событие за секунды. Дальше по тексту: что площадка требует от адреса и сертификата, какие события приходят, какой ответ обязателен на каждый запрос, что происходит, когда ваш сервер лежит, и как догонять пропущенное.
Push против опроса: что меняется в цифрах
Опрос (polling) — это вы раз в N минут дёргаете v3/posting/fbs/unfulfilled/list и сравниваете список с тем, что уже знаете. Push — Ozon отправляет POST с JSON на ваш HTTPS-адрес, как только событие произошло. Разница не только в задержке, но и в нагрузке: в спокойный день почти каждый запрос возвращает ровно тот же список, что и предыдущий, и тратит лимит впустую.
| Подход | Средняя задержка | Запросов в сутки на магазин | Слабое место |
|---|---|---|---|
| Опрос раз в 15 минут | 7–8 минут | ~96 | Медленно вечером, перед дедлайном отгрузки |
| Опрос раз в минуту | ~30 секунд | ~1440 | Упирается в лимиты API, почти все запросы вхолостую |
| Только push | Секунды | 0 исходящих | События теряются, пока сервер недоступен |
| Push + сверка раз в 30 минут | Секунды | ~48 | Нужен свой приёмник и очередь |
Рабочая связка — последняя строка. Push даёт скорость, редкая сверка обычным API закрывает дыры. Оставлять только push опасно: доставка события — вещь вероятностная, а список неотгруженных отправлений — факт.
Требования к адресу и сертификату
Адрес вы указываете в кабинете продавца — в настройках Seller API, рядом со списком ключей (точное расположение вкладки проверьте в базе знаний Ozon Seller, интерфейс двигают). Требования площадки жёсткие, и почти все отказы при сохранении адреса упираются в один из пунктов:
- Только HTTPS. HTTP-адрес не примут даже на тесте, редирект с HTTP на HTTPS проблему не решает.
- Сертификат от доверенного центра. Самоподписанный, просроченный или с несовпадающим доменом — отказ. Let's Encrypt подходит, но следите за автопродлением.
- Публично резолвимый домен.
localhost, серый IP, адрес во внутренней сети или за VPN недоступны для Ozon. - Стандартный порт HTTPS. Экзотические порты лучше не пробовать: проверьте требования к портам в документации Ozon Seller API перед настройкой.
- Отдельный путь под приёмник. Не вешайте обработчик на корень сайта:
/hooks/ozon/<длинная случайная строка>— и адрес заодно работает как секрет. - Никакой авторизации на входе. Basic-auth, капча, защита от ботов, whitelist по User-Agent — всё это отрежет площадку. Ограничивайте доступ длинным путём и проверкой содержимого запроса, а не паролем.
При сохранении адреса Ozon сразу отправляет проверочное событие — пинг. Пока приёмник не ответит на него корректно, адрес не сохранится. Это и хорошая новость: если пинг прошёл, канал до вашего сервера работает целиком — DNS, сертификат, маршрут, обработчик.
Приёмник пишите так, чтобы сырое тело каждого запроса падало в лог до любой обработки. Когда через месяц заказ не долетит, только этот лог ответит на вопрос, чья это была потеря — площадки или ваша.
Типы событий: что именно присылает Ozon
В теле запроса есть поле с типом события, и по нему вы маршрутизируете обработку. Набор типов у Ozon шире, чем «пришёл заказ», и часть из них полезнее, чем кажется.
| Событие | Когда приходит | Что с ним делать |
|---|---|---|
| Проверочный пинг | При сохранении адреса и периодически потом | Ответить строго по формату, иначе адрес отключат |
| Новое отправление | Покупатель оформил заказ по FBS | Поставить в очередь на сборку, дёрнуть детали по API |
| Отмена отправления | Покупатель или площадка отменили заказ | Снять со сборки, вернуть товар в остаток |
| Смена статуса отправления | Переходы по стадиям доставки | Обновить статус у себя, закрыть заказ по факту вручения |
| Изменение даты отгрузки | Сдвинулся дедлайн отгрузки (cutoff) | Пересчитать очередь сборки на сегодня |
| Изменение даты доставки | Покупатель перенёс доставку | Обновить план, предупредить клиента, если пишете сами |
| Новое сообщение в чате | Покупатель написал в чат | Поднять в работу: скорость ответа влияет на показатели |
| Изменение остатков или индекса цены | Списались остатки, пересчитался ценовой индекс | Проверить остаток и не ушла ли цена ниже вашего порога |
Список и точные названия типов сверяйте с документацией Ozon Seller API: состав событий меняется, а обработчик, который падает на незнакомом типе, — это отказ всего канала. Правило простое: неизвестный тип логируем и отвечаем успехом, а не пятисоткой.
Обязательный ответ: почему «200 без тела» не считается
Здесь спотыкаются те, кто уже делал вебхуки для других сервисов. Ozon ждёт не просто HTTP 200 — он ждёт конкретное тело ответа. На обычное событие это короткий JSON с полем result и значением true. На проверочный пинг формат другой: площадка хочет видеть данные вашего сервиса — название, версию, время. Пустой ответ, HTML, редирект или 200 с текстом ok засчитываются как ошибка обработки. Точные схемы ответа для каждого типа события держите открытыми в документации Seller API, пока пишете обработчик.
Второе требование — скорость. Ответ должен уйти за секунды, а не за минуты, поэтому в обработчике нельзя делать ничего тяжёлого. Правильная последовательность: приняли запрос, проверили тип, положили сырое тело в очередь или таблицу, ответили площадке. Всё остальное — вызов v3/posting/fbs/get за составом отправления, запись в учётную систему, печать этикетки, сообщение в Telegram — делает фоновый воркер. Ходите за деталями прямо в обработчике — и скорость вашего ответа площадке начинает зависеть от чужого таймаута.
Если у вас реально сломалось — база недоступна, очередь не принимает — лучше вернуть ошибку в том формате, который описан в документации, чем ответить успехом и потерять событие молча. Площадка тогда повторит доставку.
Что происходит, когда ваш сервер недоступен
Сценарий обычный: деплой, перезапуск, упавший nginx, протухший сертификат. Ozon при неудачной доставке повторяет отправку — но не бесконечно и не навсегда. Точное число попыток и интервалы между ними смотрите в актуальной документации Ozon Seller API, а в проектировании исходите из худшего: несколько попыток в пределах небольшого окна, дальше событие потеряно.
Хуже потери одного события — отключение адреса. Если приёмник стабильно не отвечает или отвечает мусором, площадка перестаёт слать уведомления вообще, и узнаете вы об этом не сразу: тишина в канале выглядит точно так же, как день без заказов. Поэтому обязательный элемент — алерт на тишину: нет ни одного события дольше, чем ваш обычный интервал между заказами (например, 40–60 минут в рабочее время) — значит, идём проверять адрес в кабинете и логи приёмника.
И страховка, без которой push не ставят вообще: раз в 20–30 минут сверяйте список неотгруженных отправлений через обычный API. Нашли отправление, которого нет у вас в базе, — обработали его как обычное новое событие. Это дёшево (пара запросов в час), но именно эта сверка превращает push из красивой схемы в надёжную.
Разбор: как мы перевели сборку FBS на push
У нас в Starbox до перехода стоял cron на 15 минут: 96 запросов в сутки на магазин, заказ доезжал до чата сборки в среднем за 7,5 минуты. Больно это становилось в двух местах — вечером перед cutoff и на отменах: товар успевал уехать в сборку по отменённому заказу.
После перехода медиана «покупатель оформил → задача у сборщика» стала около 4 секунд. Обработчик отвечает площадке сразу и кладёт тело в очередь; воркер уже спокойно ходит за деталями отправления и рисует задачу.
За первый месяц было два инцидента, оба поучительные. Первый: деплой на 6 минут с перезапуском приёмника — три события пришли в окно недоступности, два Ozon повторил успешно, одно потерялось. Сверка подобрала его через 20 минут, сборщик ничего не заметил. Второй: не отработало автопродление сертификата, push перестал ходить — заметили через 41 минуту по алерту на тишину, а не по звонку покупателя. С тех пор к алерту добавилась проверка срока сертификата за 14 дней до истечения — это дешевле, чем разбираться ночью.
Схема приёмника, который не теряет заказы
Соберите приёмник по этим правилам — и он переживёт и деплои, и повторы, и странные события.
- Тонкий обработчик. Принял, записал сырое тело, ответил. Никаких походов в чужие сервисы внутри запроса.
- Идемпотентность. Один и тот же номер отправления и статус могут прилететь дважды: повтор площадки — норма. Ключ дедупликации — номер отправления плюс тип события плюс статус.
- Очередь с ретраями. Ваш фоновый воркер тоже падает; событие должно вернуться в очередь, а не исчезнуть.
- Сверка по расписанию. Раз в 20–30 минут — список неотгруженных, раз в сутки — сверка статусов за прошлые сутки.
- Алерт на тишину и на ошибки. Отдельно — «событий нет N минут», отдельно — «доля неуспешных обработок выше 1 %».
- Секрет в пути и проверка содержимого. Длинный случайный путь плюс валидация структуры тела: мусорные запросы отсекаются, а площадка не спотыкается об авторизацию.
Типичные ошибки при подключении push
Первая по частоте — приёмник живёт в том же процессе, что и витрина магазина. Всплеск заказов в акцию кладёт сразу оба, и разбираться приходится под нагрузкой. Вынесите приёмник отдельно: ему нужны пара воркеров и доступ к очереди, больше ничего.
Дальше — ошибки логики. Ответить успехом раньше, чем событие сохранено, значит терять его при любом падении в зазоре между ответом и записью. Уронить обработчик на незнакомом типе события значит выключить себе весь канал в тот день, когда Ozon добавит новый тип. Оставить адрес без секрета в пути значит регулярно вычищать из логов мусорные POST от сканеров.
И две самые обидные. Push без сверки: заказы теряются ровно в тот день, когда лёг сервер, а узнаёте вы об этом от покупателя. Push включили, а старый cron с опросом раз в минуту выключить забыли: лимиты API тратятся впустую, событие приезжает двумя путями сразу и без дедупликации обрабатывается дважды — два комплекта этикеток на одно отправление.
И то, про что забывают на старте: push — не замена запросам к API. В событии приходит минимум полей, за составом отправления вы всё равно идёте в обычные методы. Считайте лимиты так, будто push у вас вообще нет.
FAQ
Как подключить push-уведомления в Ozon API?
В кабинете продавца, в настройках рядом с API-ключами, укажите HTTPS-адрес вашего приёмника. Площадка сразу отправит проверочное событие, и адрес сохранится, только если ваш сервер ответит корректно. Точный путь в интерфейсе и формат ответа смотрите в базе знаний Ozon Seller и документации Seller API.
Можно ли принимать push на localhost или на сервер без белого IP?
Нет. Адрес должен быть доступен из интернета по HTTPS с валидным сертификатом. Для локальной разработки используют туннель с публичным доменом и нормальным сертификатом, но для боевого магазина нужен постоянный адрес — туннель отвалится, и вы потеряете события.
Подойдёт ли самоподписанный сертификат?
Нет, сертификат должен быть выпущен доверенным центром и соответствовать домену. Бесплатного Let's Encrypt достаточно, главное — настроить автопродление и алерт: истёкший сертификат обрывает push молча, без всяких сообщений в кабинете.
Почему перестали приходить push-уведомления Ozon?
Чаще всего виноваты две вещи: истёк сертификат или приёмник долго отвечал ошибками и мусором, после чего площадка перестала слать события на этот адрес. Проверяйте по порядку — срок сертификата, логи приёмника за последние сутки, сам адрес в настройках Seller API (на месте ли он и тот ли). Неудачную доставку Ozon повторяет ограниченное число раз и делает это молча: письма о проблеме не приходит, поэтому алерт на тишину нужен с первого дня.
Заменяет ли push обычные запросы к Ozon API?
Нет. Push сообщает, что событие произошло, и приносит минимум данных: за составом отправления, товарами и адресом доставки вы всё равно идёте в v3/posting/fbs/get. Он убирает задержку и холостые запросы, но регулярную сверку со списком неотгруженных не отменяет — её оставляйте в любом случае.
Вы развиваете магазин. ИИ разбирается с рутиной.
Поручите Starbox AI поиск потерь в прибыли, проверку рекламы и планирование запасов. Задавайте вопросы в чате и получайте рекомендации по своему магазину. Попробуйте ИИ-менеджера для Ozon 14 дней бесплатно, без карты.
Попробовать ИИ-менеджера бесплатно