Разработка модуля интеграции с маркетплейсами 1С-Битрикс

Разработка модуля интеграции с маркетплейсами 1С-Битрикс

Задача звучит просто: синхронизировать каталог и заказы между сайтом на 1С-Битрикс и маркетплейсом — Ozon, Wildberries, Яндекс Маркет или Aliexpress. На практике это выливается в сотни edge-кейсов: маркетплейс меняет схему API без предупреждения, товары отклоняются из-за несоответствия атрибутов, остатки расходятся из-за гонки состояний между несколькими складами.

Что реально нужно реализовать в модуле

Стандартный модуль интеграции для 1С-Битрикс работает в рамках системы модулей (/bitrix/modules/). Он регистрируется через RegisterModule(), добавляет агентов через CAgent::AddAgent() и вешает обработчики на события инфоблоков (OnAfterIBlockElementAdd, OnAfterIBlockElementUpdate, OnAfterIBlockElementDelete).

Минимальный набор функций:

• Выгрузка товаров — маппинг полей инфоблока на схему маркетплейса, загрузка изображений по URL, передача характеристик (для Ozon это attributes[], для WB — addin[])
• Синхронизация остатков — обновление CATALOG_QUANTITY в таблице b_iblock_element_prop и передача на маркетплейс; критично делать это быстро, отдельным агентом с интервалом 5–15 минут
• Получение заказов — создание заказов в b_sale_order, b_sale_basket, b_sale_order_props через CSaleOrder::Add() или API модуля Sale
• Обработка статусов — двусторонняя: изменение статуса в Битрикс → push на маркетплейс; получение обновлений от маркетплейса → обновление через CSaleOrder::StatusOrder()

Архитектура: почему очередь обязательна

Прямой вызов API маркетплейса из обработчика события — антипаттерн. Ozon допускает не более 10 RPS на большинство методов, WB имеет rate limit 1 запрос/секунду на /api/v3/orders. Если товаров 5000+, обработчик OnAfterIBlockElementUpdate при массовом редактировании в админке создаст шквал запросов и получит 429.

Правильная схема:

Событие Битрикс → запись задачи в очередь (b_highload_element или отдельная таблица)
    ↓
Агент каждые N минут → читает очередь пачками → вызывает API маркетплейса
    ↓
Результат → лог + обновление статуса задачи в очереди

Таблицу очереди удобно реализовать через HighLoad-инфоблок (модуль highloadblock) или через прямые запросы к собственной таблице, созданной при установке модуля в методе DoInstall().

Структура таблицы очереди:

Маппинг атрибутов — самое трудоёмкое место

У каждого маркетплейса своя система категорий и обязательных атрибутов. Для Ozon нужно получить список атрибутов категории через /v3/category/attribute, сопоставить их с полями инфоблока и сохранить маппинг. Для WB — аналогично через /content/v2/object/charcs/{subjectId}.

В модуле это реализуется через административный интерфейс: страница настроек в /bitrix/admin/, где для каждого маркетплейса можно задать:

• Соответствие категорий — b_iblock_section ↔ ID категории маркетплейса
• Маппинг свойств — UF_* или PROPERTY_* полей инфоблока ↔ attribute_id маркетплейса
• Маппинг складов — CATALOG_STORE ↔ warehouse_id маркетплейса
• Правила трансформации значений — например, числовые значения характеристик WB передаются как строки "180", а не 180

Без нормального UI для маппинга модуль будет использоваться через боль: придётся лезть в код при каждом изменении структуры каталога.

Торговые предложения (SKU) и вариативные товары

WB и Ozon работают с вариативностью по-разному. На WB номенклатура (nmId) содержит массив размеров sizes[], каждый из которых имеет свой skuId. На Ozon базовый товар имеет offer_id, а варианты передаются через color_image.

В Битрикс торговые предложения хранятся как элементы дочернего инфоблока, связанного с основным через IBLOCK_ID в b_catalog_iblock. При выгрузке нужно:

1. Получить все ТП через CCatalogSKU::GetOffersList()
2. Собрать из них структуру, соответствующую формату конкретного маркетплейса
3. При обновлении остатков обновлять каждый SKU отдельно, поскольку маркетплейс хранит остатки на уровне SKU/размера

Получение и обработка заказов

Заказы с маркетплейсов приходят либо через polling (агент запрашивает новые заказы каждые N минут), либо через webhook (маркетплейс делает POST на ваш URL). WB поддерживает оба варианта, Ozon — webhook через настройки личного кабинета.

При создании заказа в Битрикс важные детали:

• Покупатель создаётся как анонимный или с привязкой к существующему пользователю по email — через CSaleOrder::DoFinalAction()
• Способ доставки и оплаты должны быть заведены в системе заранее (b_sale_delivery_service, b_sale_pay_system) и прописаны в настройках модуля
• Артикул маркетплейса (offer_id / nmId) должен совпадать с CATALOG_ARTICLE или XML_ID элемента инфоблока — это ключ для сопоставления
• Внешний ID заказа маркетплейса нужно сохранять в b_sale_order_props для обратной синхронизации статусов

Обработка ошибок и мониторинг

Модуль без логирования — чёрный ящик. Минимальный лог пишется в таблицу b_event_log через CEventLog::Add(). Для production лучше писать собственную таблицу логов с полями: уровень, маркетплейс, действие, ID сущности, HTTP-код ответа, тело ответа (truncate до 4KB).

Отдельный агент раз в час должен проверять задачи со статусом error и количеством попыток ATTEMPTS < 3, повторять их. Задачи с ATTEMPTS >= 3 — алертировать через CEvent::Send() или Telegram webhook.

Сроки разработки

Сроки указаны для разработки с нуля. Если использовать готовое ядро очереди и переиспользовать адаптеры для API — можно сократить на 25–30%.

Тестирование и приёмка

Каждый адаптер маркетплейса должен иметь набор unit-тестов для маппинга данных и интеграционные тесты с sandbox-окружением (Ozon и Яндекс Маркет предоставляют sandbox, WB — нет, там тестирование только через бой с тестовыми артикулами). Перед релизом обязательно проверить сценарии: массовое обновление цен (500+ позиций за раз), приход 50+ заказов одновременно, обновление остатков до нуля.