Розробка модуля інтеграції з маркетплейсами 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+ замовлень одночасно, оновлення остатків до нуля.