Інтеграція 1С-Бітрікс з МійСклад

Інтеграція 1С-Bitrix з МойСклад

Інтернет-магазин на 1С-Bitrix і МойСклад (хмарна система управління торговлею) — поширена комбінація у малого та середнього бізнесу. Але штатного модуля інтеграції в Bitrix немає, а готові рішення з маркетплейсу охоплюють 60-70% сценаріїв. Решта — нестандартне відображення властивостей, синхронізація залишків за складами, обробка характеристик — потребує кастомної розробки. Розглянемо архітектуру інтеграції, API МойСклад і типові проблеми.

Що синхронізуємо

Інтеграція Bitrix ↔ МойСклад зазвичай включає чотири потоки даних:

Напрямок «МойСклад як master» для товарів — типовий. Менеджер контенту працює в МойСклад, сайт отримує актуальні дані. Обернена синхронізація товарів (Bitrix → МойСклад) потрібна рідко й створює ризик конфліктів.

API МойСклад: Remap API 1.2

МойСклад надає REST API (JSON API 1.2) за адресою https://api.moysklad.ru/api/remap/1.2/. Авторизація — Basic Auth або Bearer Token.

Ключові endpoint'и:

• GET /entity/product — список товарів. Підтримує фільтрацію (filter=updated>2024-03-01), пагінацію (limit, offset), розкриття вкладених сутностей (expand=group,productFolder).
• GET /entity/assortment — об'єднаний список товарів, модифікацій, комплектів і послуг. Зручніше за product, якщо потрібно все одночасно.
• GET /report/stock/all — залишки за всіма товарами. Можна фільтрувати за складом (stockstore).
• POST /entity/customerorder — створення замовлення покупця.
• GET /entity/customerorder/{id} — отримання замовлення зі статусами.

Обмеження API:

• Rate limit: 45 запитів за 3 секунди на акаунт. При перевищенні — HTTP 429. Парсер має враховувати затримки.
• Максимум 1000 об'єктів в одній відповіді. Для вивезення повного каталогу потрібна пагінація.
• Webhook-сповіщення (МойСклад → ваш сервер) — доступні, але ненадійні: немає гарантії доставки, немає повторних спроб. Для критичних даних (залишки) використовуйте polling.

Синхронізація товарів

Алгоритм інкрементальної синхронізації:

1. Запитуємо GET /entity/assortment?filter=updated>${lastSyncTime}&limit=1000.
2. Для кожного товару шукаємо відповідність в інфоблоці Bitrix за зовнішнім кодом (XML_ID = UUID товара в МойСклад).
3. Якщо знайшли — CIBlockElement::Update() з оновленими полями.
4. Якщо не знайшли — CIBlockElement::Add().
5. Зберігаємо lastSyncTime = now() в b_option.

Відображення полів — ядро інтеграції. Таблиця відповідності:

Характеристики (модифікації) в МойСклад — це variant всередину товара. У Bitrix їм відповідають торгові пропозиції (SKU) в окремому інфоблоці. Кожен variant → елемент SKU-інфоблока з привязкою до батьківського товара через CHL_LINK (властивість CML2_LINK).

Синхронізація залишків

Залишки — найчутливіший потік. Продаж товара з нульовим залишком — прямі збитки.

Викликаємо GET /report/stock/all з фільтром за складами, які беруть участь в інтернет-продажах. Результат містить assortmentId й quantity. Оновлюємо поле CATALOG_QUANTITY в b_catalog_product або через \Bitrix\Catalog\ProductTable::update().

Для відображення залишків за складами на сайті (наприклад, «в наявності в магазині на Ленина») використовуйте механізм складського обліку Bitrix: модуль catalog, таблиця b_catalog_store_product. Кожен склад МойСклад відображається на склад Bitrix (b_catalog_store).

Частота: раз у 5 хвилин через cron-скрипт. Агенти Bitrix для цього завдання не підходять — вони прив'язані до хітів і не гарантують інтервал.

Передача замовлень

При оформленні замовлення в Bitrix (подія OnSaleOrderSaved або OnSaleComponentOrderComplete) створюємо замовлення в МойСклад через POST /entity/customerorder.

Структура тіла запиту:

{
  "organization": {"meta": {"href": "...entity/organization/{id}"}},
  "agent": {"meta": {"href": "...entity/counterparty/{id}"}},
  "positions": [
    {
      "assortment": {"meta": {"href": "...entity/product/{id}"}},
      "quantity": 2,
      "price": 150000
    }
  ]
}

Контрагент (agent) — покупець. При першому замовленні створюємо через POST /entity/counterparty, при повторному — шукаємо за email/телефоном. UUID контрагента зберігаємо у користувацькій властивості замовлення Bitrix або в користувацькому полі UF_ користувача.

Обробка помилок і черга

Мережа ненадійна, API МойСклад іноді повертає 500. Для замовлень використовуйте чергу: при помилці відправки зберігаємо замовлення в таблиці parser_queue (або b_sale_order з прапором «не відправлено в МойСклад»), агент повторює відправку кожні 5 хвилин. Максимум 5 спроб, після цього — сповіщення менеджеру.

Для товарів і залишків черга не потрібна — наступний цикл синхронізації підхопить зміни.

Строки