Інтеграція 1С-Бітрікс з МойСклад: API, синхронізація товарів та замовлень

Ми часто стикаємося з ситуацією, коли інтернет-магазин на 1С-Бітрікс використовує МойСклад для управління торгівлею, але штатного модуля інтеграції немає. Готові рішення з маркетплейсу покривають 60-70% сценаріїв. Решта — нестандартний мапінг властивостей, синхронізація залишків по складах, обробка характеристик — потребує кастомної розробки. Наш досвід показує, що грамотно налаштована інтеграція окупається за рахунок виключення ручного введення та помилок. Розберемо архітектуру, API МойСклад і типові проблеми. У цій статті ми докладно опишемо процес налаштування синхронізації товарів, залишків та замовлень, використовуючи МойСклад JSON API 1.2. Ви дізнаєтеся, як уникнути типових помилок та які інструменти використовувати для надійної роботи.

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

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

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

Як працює API МойСклад Remap 1.2?

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

Ключові endpoint:

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

Обмеження API:

Чому важливий правильний мапінг полів?

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

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

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

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

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

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

Для відображення залишків по складах на сайті (наприклад, «в наявності в магазині на Леніна») використовуйте механізм складського обліку Бітрікс: модуль catalog, таблиця b_catalog_store_product. Кожен склад МойСклад мапиться на склад Бітрікс (b_catalog_store). Частота: раз на 5 хвилин через cron-скрипт. Агенти Бітрікс для цього завдання не підходять — вони прив'язані до хітів і не гарантують інтервал.

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

При оформленні замовлення в Бітрікс (подія 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 контрагента зберігаємо в користувацькій властивості замовлення Бітрікс або в UF_-полі користувача.

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

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

Що входить в роботу

• Аналіз структури каталогу та складання карти мапінгу
• Розробка скриптів синхронізації товарів, цін, залишків
• Налаштування передачі замовлень та контрагентів
• Створення документації по інтеграції
• Навчання співробітників роботі з системою
• Технічна підтримка після запуску

Наша команда має досвід більше 5 років та 50+ успішних інтеграцій. Для точного розрахунку терміну та вартості зв'яжіться з нами.

Терміни

Замовте консультацію з інтеграції, і ми оцінимо ваш проект.