Токены и права: что создать и где хранить
Оба маркетплейса выдают доступ в личном кабинете продавца. 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 для интеграций.
Доступы оставляйте у себя: токены в ваших кабинетах, репозиторий в вашей организации, инструкции по эксплуатации в документации. Интеграция должна продолжать работать, если вы смените подрядчика.