Перейти к содержимому
← Все статьи
9 мин чтения

API Wildberries и Ozon: токены, лимиты, очереди и синхронизация остатков

Чтобы надёжно работать с API Wildberries и Ozon, относитесь к ним как к медленной внешней системе с лимитами. Держите токены с минимальными правами, отправляйте запросы через очередь с паузой на 429, пишите остатки абсолютным числом, храните сырые ответы и следите за тишиной. Дальше разберём каждое решение.

Токены и права: что создать и где хранить

Оба маркетплейса выдают доступ в личном кабинете продавца. Wildberries использует API-токен в заголовке Authorization. Ozon использует пару: Client-Id и Api-Key в двух заголовках. Это не логин пользователя: утёкший ключ работает с любой машины, пока вы его не отзовёте.

Токены Wildberries делятся по категориям, например маркетплейс, цены, статистика, контент, аналитика, поставки, возвраты и другие, и по режиму «только чтение» или «чтение и запись». У ключей Ozon тоже есть роль. Создавайте отдельный токен на каждую интеграцию и давайте ей только нужные категории. Синхронизатор остатков не должен менять цены, а отчётная задача не должна уметь писать.

По документации Wildberries токен действует 180 дней с момента создания. После этого запросы получают 401. Храните дату окончания у себя в настройках и предупреждайте за несколько недель. Просроченный токен — самая скучная и самая частая причина, по которой интеграция встаёт за ночь.

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

  • Отдельный токен на интеграцию и на окружение, никаких общих «админских» ключей.
  • Минимум категорий; только чтение там, где вы не пишете.
  • Срок действия лежит рядом с токеном, и по нему есть оповещение.
  • Ротация описана: создать новый, выкатить, проверить, отозвать старый.
  • Проверка живости: один дешёвый авторизованный запрос на кабинет, 401 и 403 отдельно.

Лимиты и ошибка 429: почему простого повтора мало

У обоих API есть ограничения частоты запросов, и они различаются по группам методов. При превышении приходит HTTP 429. Для этого случая Wildberries описывает заголовки ответа: X-Ratelimit-Retry показывает, сколько секунд ждать, X-Ratelimit-Limit — размер допустимого всплеска, X-Ratelimit-Reset — время восстановления. Повтор раньше срока даёт только новые 429.

Числовые лимиты мы здесь сознательно не называем. Они заданы по методам, меняются, и верить стоит только актуальной справке по тому методу, который вы вызываете. Прочитайте её до того, как проектировать расписание, и держите значения в конфигурации, а не в коде.

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

5xx и таймауты обрабатывайте иначе, чем 429. Это не сигнал «подождать известное время», и запрос мог всё-таки выполниться. Отсюда прямой путь к вопросу об идемпотентности.

Очереди и фоновые задачи вместо вызовов из обработчика

Пользователь нажал кнопку в вашей админке, но ждать ответа маркетплейса он не должен. Запишите задачу в таблицу Postgres, сразу ответьте, а отправкой займётся воркер. Устройство таких воркеров разобрано в статье про фоновые задачи и очереди на Go.

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

Разделяйте работу по важности. Заказы и изменения остатков срочные. Каталог, цены и отчёты могут подождать. Дайте им разные очереди или приоритеты, чтобы долгая выгрузка отчёта не задерживала обновление остатков.

Есть и чтение, и запись. Заказы приходят опросом списка с сохранённой отметкой времени или курсором, остатки уходят методом записи. Сохраняйте курсор только после обработки страницы и читайте с небольшим перекрытием, чтобы сбой не пропустил заказ.

Идемпотентность: что делать, если запрос завис

Таймаут не говорит, применил ли маркетплейс изменение. Слепой повтор для одних операций безвреден, для других дублирует результат. Не рассчитывайте, что маркетплейс сам отсечёт дубль, если в справке метода этого не сказано. Общий подход описан в статье про идемпотентность API и повторы.

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

Для всего, что создаёт объекты — поставки, этикетки, отгрузочные документы, — ведите собственную запись операции с уникальным ключом. Перед отправкой проверьте, есть ли по ключу результат. После неопределённой ошибки запросите у маркетплейса текущее состояние объекта, а не создавайте его заново.

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

Синхронизация остатков: часть, где теряются деньги

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

Заведите внутреннюю таблицу доступного количества по товарам и журнал каждого изменения с причиной: продажа, возврат, приход, ручная правка. Публикуемое число считайте из неё, вычитайте резерв и отправляйте результат. Запоминайте, что именно вы отправили в каждый маркетплейс: так вы отправляете только изменения и потом можете объяснить любое расхождение.

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

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

  • Один источник истины по количеству и журнал изменений.
  • Только абсолютные количества, никаких дельт.
  • Резерв на товар или на маркетплейс.
  • Пачки с отложенной отправкой: побеждает последнее значение.
  • Сверка с данными маркетплейса по расписанию.
  • Ручной выключатель по кабинету на случай аварии.

Ошибки, сырые ответы и мониторинг

Классифицируйте ошибки: каждому классу нужна своя реакция. 400 — ваша ошибка или плохие данные: не повторять, показать человеку. 401 и 403 — токен или права: остановить очередь кабинета и уведомить. 429 — подождать. 5xx и таймауты — повторить с задержкой. Не сваливайте всё в «запрос не удался».

Сохраняйте сырое тело ответа важных вызовов вместе с идентификатором запроса, кабинетом, методом, статусом и временем. Документация и реальные ответы со временем расходятся, а поле, которое вы сегодня не разбираете, может понадобиться через квартал. Когда продавец спрашивает, почему в 14:05 остаток был неверным, сохранённые запрос и ответ дают ответ за минуту.

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

Следите за результатом, а не только за процессом. Полезные сигналы: возраст самой старой необработанной задачи, доля ответов 429 и 5xx, время с последнего успешного получения заказов по кабинету, число товаров, где опубликованный остаток отличается от внутреннего. Хуже всего тишина, поэтому оповещайте, когда ничего не приходит. Подробнее — в статье про сопровождение после запуска.

  • Возраст самой старой ожидающей задачи.
  • Доля 429 и 5xx по кабинетам и методам.
  • Время с последнего успешного получения заказов.
  • Число расхождений остатков, найденных сверкой.
  • Дней до окончания срока токена.

Когда своя интеграция вам не нужна

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

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

Проверьте также, есть ли в вашей учётной системе или ERP готовый обмен с маркетплейсами. Если есть, оцените его до того, как что-то писать, и прочтите сравнение в статье про 1С и маркетплейсы.

Когда нужен подрядчик

Он оправдан, если несколько кабинетов или площадок должны делить один остаток, если заказы должны попадать в вашу CRM или складскую систему, или если ошибки уже стоят денег: перепродажи и отменённые заказы. Также если в команде некому поддерживать воркер очереди и следить за ним.

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

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

Вопросы

Частые вопросы

Не нашли ответ — спросите на созвоне или в Telegram.

Как подключиться к API Wildberries?

Создайте в кабинете продавца токен только с нужными категориями и передавайте его в заголовке Authorization. По документации токен живёт 180 дней, поэтому следите за сроком. Вызывайте хост той группы методов, которую используете, как указано в справке, и обрабатывайте 401, 403 и 429 отдельно.

Как работает авторизация в Ozon Seller API?

Вы создаёте ключ в кабинете продавца и передаёте в каждом запросе два заголовка: Client-Id и Api-Key. У ключа есть роль, которая ограничивает доступные методы. Заведите отдельный ключ на каждую интеграцию, храните его как секрет, не в репозитории, и отзывайте сразу при утечке.

Что делать, если API Wildberries вернул 429?

Прекратите отправку в эту группу методов и подождите. Wildberries отдаёт X-Ratelimit-Retry с числом секунд ожидания, а также X-Ratelimit-Limit и X-Ratelimit-Reset. Прочитайте их, отложите задачу и добавьте джиттер. Ранний повтор даёт только новые 429. Лимиты держите в конфигурации, а не в коде, и обновляйте по справке метода.

Как сделать синхронизацию остатков Wildberries и Ozon?

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

Нужна ли очередь для работы с API маркетплейсов?

Да, как только запросы могут запускать несколько процессов или пользователей. Очередь даёт единое место для ограничения частоты, повторов, приоритетов и журнала. Таблицы задач в Postgres и воркера хватает большинству продавцов; отдельный брокер на старте нужен редко, а добавить его можно позже.

Стоит ли хранить сырые ответы API Wildberries и Ozon?

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

Связанная услуга

Интеграции 1С, CRM и внешних API

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

Об услуге
Другие статьи
6 мин чтения

Интеграция с 1С, amoCRM и ERP: архитектура надёжного обмена данными

Интеграция с 1С, amoCRM и маркетплейсами через API: организация очередей, обработка лимитов, идемпотентность запросов и сквозной мониторинг обмена данными.

Читать статью: Интеграция с 1С, amoCRM и ERP: архитектура надёжного обмена данными →
6 мин чтения

Идемпотентность API: как обрабатывать повторные запросы без дублей

Как работает идемпотентность API: заголовок Idempotency-Key, уникальные индексы в БД, повторы вебхуков и алгоритм exponential backoff с джиттером.

Читать статью: Идемпотентность API: как обрабатывать повторные запросы без дублей →
Контакт

Обсудим вашу задачу?

Тридцать минут созвона — и у вас есть понимание архитектуры, сроков и формата работы. Без обязательств.

Или напишите в Telegram →Читайте наш канал в Telegram →

Укажите Telegram или email, чтобы мы могли ответить.

Отвечаем в течение 15 минут.