Как синхронизировать интернет-магазин с Ozon и Wildberries
Как выбрать способ интеграции, сопоставить товары и склады, проверить передачу остатков и заказов и принять обмен при повторах и сбоях API.
Чтобы связать сайт с Ozon и Wildberries, нужен обмен, который узнаёт один и тот же вариант товара во всех системах, передаёт количество на правильный склад и загружает заказы без дублей. Подключение проверяют по результату: записанный остаток читают обратно с площадки, а заказ сопоставляют с конкретным товаром и стадией исполнения. Зелёного индикатора «соединение установлено» для приёмки недостаточно.
Ниже — порядок настройки и проверки для магазина, который исполняет заказы сайта и площадок со своего склада по модели FBS. Разберём выбор готового модуля или собственной интеграции, необходимые идентификаторы, методы и контрольный прогон. API — программный интерфейс обмена — и его версии сверены с официальной документацией 29 октября 2026 года. Реальные кабинеты не подключались и запросы на изменение товаров не выполнялись; пример приёмки учебный.
Что должно быть определено до подключения
Сначала запишите, где хранится товар и кто его отгружает на каждой площадке. Для FBS в этом разборе товар находится у продавца: интеграция передаёт доступное количество на склад продавца и забирает задания или отправления. Если часть ассортимента лежит на складах площадок по FBO у Ozon или FBW у Wildberries, для неё нужен другой порядок учёта. Такое наличие нельзя менять как остаток своего склада FBS.
Выберите систему, в которой утверждается доступный запас: это может быть учётная система, складская программа или сайт с необходимыми возможностями. Назначьте один процесс, который рассчитывает значения для выгрузки. Два модуля, одновременно записывающие остаток одного товара, могут перезаписывать результаты друг друга.
Распределение запаса между каналами и правила резервирования должны существовать до обмена. Здесь мы проверяем, исполняет ли интеграция эти правила. Само распределение разобрано в статье о том, как продавать через сайт и маркетплейсы одновременно, а состояние физического товара — в управлении запасами магазина.
Со стороны сайта проверьте возможность получать изменения заказов, различать варианты товара и записывать остатки или резервы в выбранную систему учёта. Если готового обмена нет, выясните, какие операции доступны через API вашей платформы или поддерживаемую выгрузку. Собственная разработка не создаст недостающий интерфейс сайта: иногда сначала требуется сменить способ учёта или установить поддерживаемый модуль.
Готовый модуль или собственная интеграция
Готовый модуль подходит, если он поддерживает вашу платформу, обе площадки, нужную схему исполнения и уже принятую модель учёта. Собственная интеграция оправдана, когда стандартный обмен не покрывает существенные условия: несколько складов, особые комплекты, распределение запасов или нестандартную обработку заказов. Решение принимают по проверяемым возможностям и ответственности за поддержку.
| Что проверить | У готового модуля или облачного сервиса | При собственной разработке |
|---|---|---|
| Поддержка нужных операций | Исполнитель показывает обмен именно для FBS, ваших складов и вариантов | Составляется перечень операций сайта, системы учёта и площадок |
| Совместимость с текущим API | Известны версии методов и порядок обновления после изменений площадки | Назначен ответственный за изменения контрактов и повторную приёмку |
| Ошибки и восстановление | Доступны журнал по товарам, очередь ошибок и повторная сверка | Эти механизмы входят в задание на разработку |
| Доступы | Есть подходящий способ авторизации для конкретного сервиса | Выбраны минимальные права, защищённое хранение и ротация ключей |
| Стоимость владения | Учтены подписка, настройка, ограничения объёма и поддержка | Учтены разработка, размещение, мониторинг и дальнейшие изменения |
До оплаты внедрения попросите показать проверку одного варианта товара, частичную ошибку пакета и повторное получение заказа. Если модуль не позволяет увидеть, какая позиция обновилась и что вернул API, принимать его по общему счётчику «отправлено» рискованно. Эти же требования применимы к работе собственного разработчика.
Таблица соответствий товаров и складов
Совпадающий артикул в двух кабинетах удобен человеку, но сам по себе не связывает записи. Интеграции нужна явная таблица: внутренний вариант → идентификатор на площадке → склад. Размер, цвет и единица продажи должны совпадать. Если сайт продаёт штуку, а площадка упаковку из двух, в соответствии также должно быть правило пересчёта количества.
| Система | Что хранить в соответствии | Для чего это нужно |
|---|---|---|
| Магазин | Внутренний код варианта, размер, цвет, единицу продажи и внутренний склад | Понять, какую позицию резервировать и откуда её отгружать |
| Wildberries | chrtId размера и warehouseId склада продавца | Записать и прочитать остаток нужного размера на нужном складе |
| Ozon | offer_id продавца либо product_id, а также warehouse_id; отдельно полученный sku, если он нужен выбранному методу | Не смешать код продавца, идентификатор товара, SKU площадки и склад |
Для записи остатка WB нужен именно chrtId, а не только номер карточки или произвольный артикул. warehouseId относится к складу продавца, а не к складу Wildberries. На Ozon метод записи принимает offer_id или product_id: если передать оба, приоритет имеет offer_id. Для однозначности в одной операции используйте один из них, а остальные значения сохраняйте для сверок.
Ниже — учебная строка соответствия. Номера вымышлены и не подходят для запросов в реальный кабинет.
Внутренний вариант: TSHIRT-BLUE-M
Товар: футболка, синий, M; единица продажи: 1 штука
Внутренний склад: MAIN
WB: chrtId = 710001; warehouseId = 410
Ozon: offer_id = TSHIRT-BLUE-M; warehouse_id = 820
Перед запуском проверьте не только заполненность строки, но и сам товар в каждом кабинете. Неизвестный размер или неоднозначное соответствие отправляйте на разбор: автоматическая подстановка первого похожего артикула может изменить наличие другого варианта.
Какие доступы выдать интеграции
У WB для рассматриваемых методов заказов FBS, складов и остатков нужна категория токена «Маркетплейс». Права на карточки относятся к другой задаче; доступ к контенту не заменяет права на этот обмен. Разделите чтение и запись в соответствии с тем, какие действия выполняет модуль.
Тип токена тоже имеет значение. Персональный токен WB используют для собственных или локально размещённых систем с учётом ограничений площадки; его нельзя передавать третьим лицам или использовать в облачных решениях. Для сервиса из каталога используется сервисный токен, привязанный к этому сервису. Перед подключением выясните поддерживаемый способ авторизации, а не выдавайте стороннему модулю все права по его первой просьбе.
Ozon Seller API использует Client-Id и Api-Key; для методов, которые его поддерживают, доступен OAuth. Поддержку OAuth проверьте отдельно для каждой нужной операции: отдельные методы требуют API-ключ. Сообщение «требуется API-ключ» может означать как недействительный токен, так и отсутствие поддержки OAuth у метода. В роли ключа выбирают нужные методы, а не полный административный доступ по умолчанию. Для новых ключей установлен срок 90 дней; дату истечения проверяют по expires_at метода /v1/roles. Запишите, кто и как заменяет ключ до остановки обмена.
Обмен с Ozon должен выполняться на стороне серверов: прямое обращение к Seller API из браузера покупателя не поддерживается. Ключи храните в защищённых настройках сервера или интегратора, исключите их из клиентского кода, снимков экрана и журнала ошибок. Для приёмки нужны идентификатор операции и текст ошибки, а не секрет авторизации.
Как проверить запись остатков
Передавайте утверждённое доступное количество для конкретной пары «вариант — склад». На Ozon /v2/products/stocks записывает наличие без зарезервированных товаров: резерв нельзя прибавлять к значению для свободной продажи. Если канал получает квоту, интеграция отправляет квоту, а не весь физический запас.
Wildberries: ответ 204 проверяют чтением
Сначала получите склады продавца через GET /api/v3/warehouses и сопоставьте их id с внутренними складами. Запись выполняет PUT /api/v3/stocks/{warehouseId}. В текущей схеме stocks содержит chrtId и amount; в одном запросе допускается до 1 000 позиций.
Учебное тело записи трёх единиц для нашей строки соответствия выглядит так:
{
"stocks": [
{ "chrtId": 710001, "amount": 3 }
]
}
В пути запроса должен стоять учебный склад 410. Но ответ 204 ещё не подтверждает изменение: документация WB прямо предупреждает, что неверные имена параметров могут привести к такому ответу без обновления остатка.
После записи выполните POST /api/v3/stocks/{warehouseId} для того же склада с телом {"chrtIds":[710001]}. При успешном чтении ответ содержит stocks с chrtId и amount. В спокойном учебном прогоне ожидается {"stocks":[{"chrtId":710001,"amount":3}]}. Если между операциями прошёл заказ, сопоставьте время и изменение с ним; не объявляйте расхождение ошибкой до проверки событий.
Ozon: проверяют каждую позицию и конкретный склад
Текущий список складов FBS получают через POST /v2/warehouse/list. В запросе используются limit и cursor, в ответе — warehouses, has_next и cursor. Пройдите все страницы, если has_next=true, и сопоставьте warehouse_id нужного склада.
Для записи используется POST /v2/products/stocks. Учебный запрос для того же варианта:
{
"stocks": [
{ "offer_id": "TSHIRT-BLUE-M", "stock": 3, "warehouse_id": 820 }
]
}
Ответ HTTP 200 нужно разобрать по позициям: в result проверяют updated и errors. Один запрос может содержать удачные и неудачные обновления; нельзя пометить весь пакет выполненным только по коду HTTP.
Затем прочитайте конкретный склад через POST /v1/product/info/warehouse/stocks, передав warehouse_id, limit и cursor. В ответе сверяют товар и склад, present, reserved, free_stock и updated_at; при has_next=true продолжают чтение следующих страниц. Для приёмки важен результат по нужной паре «товар — склад», а не найденная на первой странице похожая позиция.
У Ozon есть и агрегированный отчёт POST /v4/product/info/stocks с наличием и резервами по схемам исполнения. Он полезен для общей сверки, но не заменяет проверку конкретного склада, если складов несколько. Старые примеры с /v1/warehouse/list и /v3/posting/fbs/list не используйте как действующий контракт: для рассматриваемого обмена актуальны /v2/warehouse/list и /v4/posting/fbs/list.
У каждой группы методов свои ограничения частоты и размера пакета. Зафиксируйте действующие лимиты при внедрении и настройте очередь под них; универсального интервала «обновлять всё раз в минуту» нет. Плановая сверка также нужна после событийного обмена: получение уведомлений не доказывает, что все изменения уже отражены.
Как загружать заказы и понимать статусы
Сохраняйте исходные идентификаторы и статусы площадки рядом с внутренним состоянием заказа. Названия внутренних стадий выбирает магазин, но переход на каждую из них должен опираться на конкретное поле API. Нельзя переводить одинаково звучащие статусы двух площадок по одному общему словарю.
Wildberries: задание и две независимые стадии
GET /api/v3/orders/new возвращает новые сборочные задания на момент запроса. Одно задание соответствует одной единице товара: десять единиц могут дать десять заданий. orderUid позволяет группировать задания одной корзины, но для обработки и проверки статуса нужен ID каждого задания.
Текущие статусы получают через POST /api/v3/orders/status, передавая массив orders с ID заданий. Метод возвращает два поля, которые нужно хранить раздельно.
| Поле | Примеры значений | Что учесть в своём процессе |
|---|---|---|
supplierStatus | new, confirm, complete, cancel | confirm — на сборке; complete — в доставке, а не получено покупателем |
wbStatus | waiting, sorted, sold, canceled, declined_by_client | sold означает получение покупателем; отмена или отказ требуют проверки дальнейшего движения товара |
Для сверки истории есть GET /api/v3/orders, но он не возвращает актуальный статус: после загрузки списка нужен отдельный запрос статусов. В текущей документации история ограничена созданными за последние три месяца заданиями, интервал одного запроса — до 30 дней; учитывайте пагинацию и отдельный архив. Один опрос новых заданий не заменяет восстановление пропуска истории.
Ozon: отправление, состав и подробный статус
Список FBS-отправлений получает POST /v4/posting/fbs/list: задают filter, limit, cursor и направление сортировки. При has_next=true нужно запрашивать следующие страницы. Во внутреннем реестре сохраняйте posting_number как идентификатор отправления; order_id или order_number не подменяют его. В составе берут products.offer_id, sku и quantity, склад — из delivery_method.warehouse_id.
Подробности отправления можно получить через POST /v3/posting/fbs/get по posting_number. Основной status и уточняющий substatus храните отдельно.
| Поле Ozon | Примеры | Как трактовать |
|---|---|---|
status | awaiting_packaging, awaiting_deliver, delivering, delivered, cancelled | Ожидает упаковки, ожидает отгрузки, доставляется, доставлено, отменено |
substatus | posting_in_pickup_point, posting_received, posting_returned_to_warehouse | Уточнение: в пункте выдачи, получено, возвращено на склад; проверяйте его вместе с основным состоянием |
Ключ внутренней записи составьте из площадки, кабинета продавца и ID задания WB либо posting_number Ozon. Для заказов сайта также нужен устойчивый внешний номер в связке с источником. Повторное получение такой записи обновляет её состояние, а не создаёт ещё один резерв или сборку. Состав Ozon учитывайте с quantity: отправление не равно одной штуке и не обязательно равно всей корзине.
Отмену заказа отделяйте от физического возврата. Неотгруженный резерв освобождают по принятому правилу один раз; уже отправленный товар нельзя вернуть в доступное количество только по сообщению об отмене. Для возврата необходимо подтверждение приёмки и пригодности товара к новой продаже.
Что должно происходить при сбоях
Попросите исполнителя показать не только успешный обмен, но и обработку следующих ситуаций. Удобно проверять их на имитации ответов API и локальной очереди; намеренно портить рабочий остаток или расходовать лимиты реального кабинета для этого не требуется.
| Ситуация | Ожидаемое поведение | Признак, по которому принимают работу |
|---|---|---|
| WB вернул 204, число не изменилось | Выполнить чтение и разобрать параметры, ID и склад | Операция не отмечена успешной по одному коду 204 |
| Ozon вернул 200 с ошибкой части позиций | Сохранить результат каждой позиции; исправить и повторить только нерешённые операции | Успешные товары отличимы от ошибочных в журнале |
| Ответ записи потерян по таймауту | Сначала проверить фактическое состояние, затем решить, нужна ли повторная запись | Старое количество не перезаписывает более новое после восстановления связи |
| Получен 429 | Сохранить операцию в очереди и выдержать ограничение; использовать Retry-After, если оно передано | Нет потери операции и непрерывного потока повторов |
| Получен 5xx | Сохранить операцию, повторять с паузой и проверкой результата записи | Временная ошибка не теряет изменение и не запускает бесконечные повторы |
| Ошибка прав 401/403 или истёкший ключ | Приостановить затронутый обмен и исправить доступы | Ответственный видит причину; ключи не попали в журнал |
| В ответе есть следующая страница | Продолжить чтение по механизму пагинации метода | Итоговый реестр включает нужную запись за пределами первой страницы |
| Повторно пришло уже известное задание или отправление | Узнать его по сохранённому ключу и обновить существующую запись | Резерв и задание на сборку остались в одном экземпляре |
| Пришёл неизвестный вариант или новый статус | Сохранить исходные данные и отправить на разбор | Другой размер не списан; неизвестный статус не считается доставкой |
В очередь записывайте актуальное целевое количество и его версию или время расчёта. Если после неудачной отправки «3» уже рассчитано «2», повтор старой операции не должен возвращать «3». Это правило обработки очереди, а не обещание, что каждый метод API предоставляет готовую защиту от устаревшей записи.
Минимальный журнал содержит площадку и кабинет, внутренний вариант, внешние ID, склад, время и версию изменения, метод, отправленное значение, ответ по позиции, результат чтения и решение о повторе. Для заказов добавьте внешний ID и оба исходных поля статуса. Время приводите к единому виду: Ozon Seller API использует UTC, а запись в местном времени без часового пояса затрудняет разбор порядка событий.
Учебный прогон приёмки
Возьмём вымышленный вариант TSHIRT-BLUE-M из таблицы соответствий. Магазин уже утвердил девять доступных единиц и квоты по три для сайта, WB и Ozon. Это исходные условия проверки обмена, а не способ вычислить запас. Посторонних продаж во время учебного прогона нет; отдельные сбои ниже воспроизводятся имитацией ответов, не запросами к реальным кабинетам.
| Шаг | Действие | Ожидаемый результат |
|---|---|---|
| 1. Начальное наличие | Передать WB и Ozon по три единицы, прочитать обратно соответствующие склады | WB возвращает amount=3; на Ozon для той же пары проверено свободное количество 3, ошибок позиции нет |
| 2. Задание WB | Загрузить одно новое задание на нашу футболку и применить принятое резервирование | Одна единица зарезервирована; свободный общий запас 8, целевое количество WB 2 |
| 3. Повтор задания | Повторно получить тот же ID WB с теми же событиями | В реестре одно задание; запас остаётся 8, количество WB — 2 |
| 4. Отправление Ozon | Загрузить новое отправление с этим offer_id, quantity=1 и складом 820 | Создан один резерв; свободный общий запас 7; квоты теперь сайт 3, WB 2, Ozon 2 |
| 5. Заказ сайта | Передать заказ на одну футболку в систему учёта и проверить наличие на сайте | Один новый резерв; общий свободный запас 6; квоты сайт 2, WB 2, Ozon 2. Повтор события сайта не списывает вторую единицу |
| 6. Сбои записи | Имитировать 204 без изменения WB, ошибку второй позиции пакета Ozon и таймаут | WB проверяется чтением; Ozon не считает весь пакет удачным; после таймаута сверяется последняя цель 2 |
| 7. Лимит и страницы | Имитировать 429 и выдачу нужного отправления на второй странице списка | Очередь сохраняется, повтор не идёт непрерывно; отправление найдено без дубля |
| 8. Неизвестный размер | Получить заказ на вариант без строки соответствия | Он отправлен на разбор; остаток синего M не изменился |
| 9. Доставка и отмена | Проверить WB complete и Ozon cancelled для уже отправленного товара | complete не помечен как получение; отмена не прибавила товар на полку без приёмки |
Если чтение после записи вернуло не то количество, сохраните ответ и сначала проверьте склад, размер, порядок операций и появление новых заказов. Повторная полная выгрузка без разбора может закрепить ошибку. После исправления повторите затронутый шаг и убедитесь, что восстановление не создало дубль.
Для своей приёмки замените учебные значения в заготовке ниже. На каждую проверяемую пару «вариант — склад» нужна отдельная запись, а для сбоя — исходное событие и ожидаемое действие.
Площадка, кабинет, модель исполнения:
Внутренний вариант, единица продажи, внутренний склад:
Внешний ID варианта и ID склада:
Источник расчёта и версия целевого остатка:
Отправленное количество, время и метод записи:
Ответ по позиции: обновлено / ошибка / результат неизвестен:
Метод чтения, пройденные страницы, фактическое количество:
Внешний ID задания/отправления и состав с количеством:
Исходные статусы и соответствующая внутренняя стадия:
Результат повторной загрузки и имитации сбоя:
Расхождение, действие, ответственный и повторная проверка:
Когда товар находится на складе площадки
Если магазин работает по FBO у Ozon или FBW у WB, учебный прогон выше меняется: интеграция не отправляет наличие на склад площадки как остаток собственного FBS-склада. Проверяют поступление и отражение товара в данных площадки, получение заказов и отчётов для этой модели. Товар на складе площадки учитывают отдельно от запаса для заказов сайта.
Готовый модуль, поддерживающий только FBS, нельзя принимать для FBO/FBW по тому же тесту. Попросите другой перечень операций и отдельную приёмку, а при смешанной модели сохраните разделение по складам и схемам. Если модель продаж ещё не определена, начните с порядка запуска продаж на маркетплейсах.