Автоматизация логистики и контента на Ozon через API

Иван Корнев·21 июля 2026·⏱5 мин

Для масштабирования бизнеса на маркетплейсе необходима бесшовная синхронизация данных между вашей учетной системой и площадкой. Работа с API Ozon позволяет автоматически передавать заказы в транспортные системы (TMS), мгновенно обновлять статусы доставок и обогащать карточки товаров видеоконтентом без ручного вмешательства. В этом руководстве мы разберем технические аспекты интеграции ключевых модулей Seller API: логистики, трекинга и медиа.

Оглавление

Основы авторизации и безопасности

Доступ к функционалу Seller API осуществляется через пару ключей: Client-ID и Api-Key. Они генерируются в личном кабинете продавца в разделе «Настройки» → «API-ключи».

Каждый HTTP-запрос должен содержать следующие заголовки:

  • Client-Id: уникальный идентификатор вашего приложения или интеграции.
  • Api-Key: секретный токен доступа.

Хранение ключей в открытом коде или публичных репозиториях недопустимо. Используйте переменные окружения или специализированные хранилища секретов (например, HashiCorp Vault или AWS Secrets Manager). Регулярно обновляйте ключи при подозрении на компрометацию.

Ozon постоянно оптимизирует производительность интерфейса, заменяя устаревшие версии методов (v1, v2) на более эффективные v3 и v4. Новые версии поддерживают пакетную обработку данных, что критически важно для снижения нагрузки при работе с большими объемами заказов.

Интеграция с TMS и управление отправлениями

Транспортная система (TMS) управляет цепочкой доставки от момента создания заказа до его вручения покупателю. Интеграция с Ozon позволяет автоматически забирать новые заказы и передавать трек-номера обратно на маркетплейс.

Получение списка отправлений

Для схемы FBS (продажа со склада продавца) основной метод — POST /v3/posting/fbs/list. Он возвращает список отправлений, соответствующих заданным фильтрам.

Ключевые параметры запроса:

  • filter: объект для фильтрации по статусам (например, awaiting_deliver — ожидает отгрузки), датам создания или идентификаторам складов.
  • dir: направление сортировки (ASC или DESC).
  • limit: количество записей в ответе (до 1000 штук за один запрос).

Для схемы rFBS (доставка силами Ozon, сборка продавцом) используются методы группы PostingRFBS, логика работы с которыми аналогична.

Передача трек-номеров

Если доставка осуществляется сторонней службой, не интегрированной напрямую с Ozon, необходимо вручную или автоматически передавать трек-номер через метод POST /v2/fbs/posting/tracking-number/set.

Настраивайте передачу трек-номера сразу после генерации этикетки в вашей TMS. Это ускоряет переход заказа в статус «В пути» и снижает количество обращений покупателей в поддержку с вопросом «Где мой заказ?».

При использовании собственной логистики Ozon (Ozon Доставка) метод POST /v1/delivery/check помогает проверить доступность доставки в выбранный регион до подтверждения заказа, минимизируя риск отмен из-за логистических ограничений.

Трекинг заказов: вебхуки против polling

Отслеживание изменений статусов — ресурсоемкая задача. Традиционный метод постоянного опроса API (polling) создает избыточную нагрузку и может привести к временной блокировке ключей при превышении лимитов запросов.

Настройка Webhook

Оптимальное решение — использование вебхуков (push-уведомлений). Ozon самостоятельно отправляет запрос на ваш сервер при наступлении важных событий:

  • Создание нового заказа.
  • Отмена заказа покупателем или площадкой.
  • Изменение статуса отправления (передан в доставку, доставлен и т.д.).

Это обеспечивает практически мгновенную реакцию вашей ERP или TMS на изменения и освобождает квоты API для других операций. Для тестирования корректности приема уведомлений используйте метод /v1/notification/check.

Точечный запрос статуса

Если вебхук был пропущен или требуется актуализация данных по конкретному заказу, используйте метод POST /v3/posting/fbs/get. Он принимает один параметр — posting_number — и возвращает детальную информацию, включая полную историю смены статусов. Этот метод идеален для ретрай-логики или ручной проверки спорных ситуаций.

Работа с видеоконтентом

Видео в карточке товара повышает конверсию и время пребывания пользователя на странице. API Ozon предоставляет инструменты для программного управления медиаконтентом.

Загрузка видео через API

Метод /v3/product/import поддерживает передачу ссылок на видеофайлы. При обновлении или создании карточки товара вы можете указать URL видеообложки или основного ролика.

Технические требования:

  • Форматы: MP4, MOV.
  • Ссылка должна быть прямой и вести на публичное облачное хранилище (S3, Google Cloud Storage и аналоги).
  • Контент должен проходить модерацию: отсутствие водяных знаков конкурентов, запрещенных материалов и низкокачественного звука.

API не принимает файлы в формате base64 или бинарные данные в теле запроса из-за ограничений на размер пакета. Всегда используйте внешние ссылки на уже загруженные файлы.

Интеграция с Ozon Moments

Ozon развивает формат коротких видео Moments, который позволяет монетизировать контент через прямые ссылки на товары. Хотя прямого метода для публикации в ленту Moments через API пока нет, качественное видео, загруженное в карточку товара, может автоматически подтягиваться в рекламные форматы площадки.

Для централизованного управления медиа-ассетами рекомендуется использовать PIM-системы, которые синхронизируют контент с Ozon и другими каналами продаж через единый интерфейс.

Сравнение стратегий получения данных

Выбор метода зависит от объема данных и требований к актуальности информации.

Стратегии мониторинга заказов

СтратегияИнструментПреимуществаНедостатки
Пакетная выгрузкаPOST /v3/posting/fbs/listПолучение больших массивов данных за один вызовВысокая нагрузка при частых запросах; данные могут устареть к моменту обработки
Реальное времяWebhook (Push)Мгновенная реакция; экономия лимитов APIТребует наличия внешнего сервера с белым IP для приема запросов
Точечный запросPOST /v3/posting/fbs/getМаксимальная детализация конкретного заказаНеприменимо для массового анализа; требует знания ID заказа

Частые ошибки при интеграции

  1. Игнорирование лимитов запросов. Ozon строго регулирует частоту обращений. При получении ошибки 429 Too Many Requests обязательно реализуйте механизм экспоненциальной задержки (exponential backoff) перед повторной попыткой.
  2. Использование устаревших версий методов. Следите за уведомлениями в канале разработчиков. Методы старых версий отключаются без возможности восстановления, что может парализовать работу интеграции.
  3. Некорректная смена статусов. Иерархия статусов жесткая. Нельзя перевести заказ из статуса «Доставлен» обратно в «Сборка». Перед любым изменяющим действием всегда проверяйте текущий статус через GET-запрос.
  4. Обработка пустых ответов. При пакетной выгрузке список заказов может быть пустым. Убедитесь, что ваша система корректно обрабатывает пустые массивы, а не падает с ошибкой парсинга.

FAQ

Как часто можно опрашивать API без вебхуков? Частота зависит от тарифа и текущего состояния системы, но рекомендуется не чаще раза в 5–10 минут для списочных методов. Использование вебхуков снимает это ограничение для событийных задач.

Можно ли загрузить видео напрямую из файла через API? Нет. API работает только со ссылками на внешние ресурсы. Вам необходимо предварительно загрузить файл на свой сервер или в облачное хранилище и передать полученную URL-ссылку.

Что делать, если трек-номер не привязывается к заказу? Проверьте формат трек-номера и статус заказа. Привязка возможна только для заказов в статусах, предшествующих фактической передаче в доставку. Также убедитесь, что служба доставки поддерживается Ozon или вы используете метод для сторонних служб.