Интеграция с API маркетплейсов: лимиты, ошибки и почему остатки расходятся

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

Разберём, что именно ломается и какая обвязка нужна.

Лимиты: не один на всё API

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

Практическое следствие: считать «мы делаем сто запросов в минуту, лимит тысяча, всё хорошо» бесполезно. Упереться можно в один конкретный метод, продолжая укладываться в общий бюджет. Учёт нужен по каждому методу.

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

Буфер с приоритетами

Решение известное — накапливать изменения и отправлять пакетами в пределах лимита. Но есть нюанс, который отличает рабочую реализацию от учебной.

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

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

Асинхронные операции

Часть методов площадок не возвращает результат сразу: запрос создаёт задачу, а результат забирается отдельным вызовом по идентификатору.

Это меняет логику интеграции. Ответ «200 OK» на создание задачи не означает, что данные приняты, — он означает, что задача поставлена. Она может завершиться ошибкой через минуту, и об этом узнает только тот, кто пришёл за статусом.

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

Ошибки: временные против постоянных

Обработка ошибок «залогировать и продолжить» приводит к тихой потере данных. Ошибки нужно различать.

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

Постоянные — товар не найден, некорректный формат, нет прав, невалидное значение. Повторять бессмысленно: сколько ни отправляй, результат не изменится. Такие случаи уходят в отдельную очередь на разбор человеком.

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

Идемпотентность

При повторах возникает вопрос: не создаст ли повторная отправка дубль?

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

Практическое правило: прежде чем добавлять автоматический повтор, надо ответить, что произойдёт при двойном выполнении. Если ответ «не знаю» — повтор добавлять рано.

Данные, изменённые задним числом

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

Интеграция, которая один раз забрала отчёт и записала итог, будет опираться на устаревшие цифры. Рабочий подход — сохранять сырые ответы и пересчитывать витрины, а не хранить только результат. Тогда изменение истории обрабатывается пересчётом, а не ручным разбором.

Подробнее про это — в разборе юнит-экономики на WB и Ozon, где staging-слой является центральным решением.

Сверка обязательна

Никакая обработка ошибок не даёт гарантии. Сообщение теряется, задача падает, площадка принимает запрос и не применяет его.

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

Что должно быть в мониторинге

Минимальный набор, без которого интеграцию нельзя считать законченной:

• задержка от изменения в учётной системе до применения на площадке;
• доля запросов, отклонённых по лимиту, — растёт, значит буфер настроен неверно;
• размер очереди на разбор постоянных ошибок;
• число расхождений по последней сверке;
• алерты в мессенджер команды на остановку очереди и на всплеск ошибок.

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

Итог

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

Каждый из этих пунктов добавляется позже дороже, чем закладывается сразу, — и именно их отсутствие, а не качество кода, объясняет большинство историй про «остатки опять разъехались».

Если задача близка — посмотрите услугу маркетплейс-агрегатора и кейс единого кабинета для пяти площадок. Про то, как это стыкуется с учётной системой, — в разборе интеграции 1С с маркетплейсами.