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

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

МойСклад — один із найпоширеніших виборів для малого та середнього e-commerce: зручний інтерфейс, API з гарною документацією, нативний мобільний застосунок для комірника. Інтеграція з 1С-Бітрікс виглядає простою на папері, але на практиці ламається у трьох місцях: синхронізація модифікацій товарів, обробка часткових відвантажень і маппінг статусів замовлень.

API МойСклад і точки інтеграції

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

Основні сутності, з якими працює інтеграція:

• entity/product — товари (без модифікацій)
• entity/variant — модифікації (торгові пропозиції у термінах Бітрікс)
• entity/customerorder — замовлення покупців
• entity/demand — відвантаження
• entity/stock — залишки (лише читання через звіт)

Отримання залишків по всіх складах: GET /report/stock/all?groupBy=variant — повертає JSON з полями stock (вільний залишок), reserve (резерв), inTransit (у дорозі).

Найскладніша частина: синхронізація модифікацій

У 1С-Бітрікс торгові пропозиції (модифікації) зберігаються в b_catalog_sku і пов'язані з батьківським товаром через IBLOCK_ID торгових пропозицій. У МойСклад це variant із посиланням на product.

Проблема виникає при первинному завантаженні: потрібно правильно пов'язати variant.id із МойСклад із ID торгової пропозиції в Бітрікс. Без таблиці маппінгу кожен запуск синхронізації намагатиметься створити дублі. Зберігаємо відповідність в окремій таблиці custom_moysklad_mapping (або у властивості інфоблоку MOYSKLAD_ID).

При оновленні залишків модифікацій спочатку отримуємо variant.id → знаходимо в таблиці маппінгу відповідний ID торгової пропозиції → оновлюємо b_catalog_product для цієї пропозиції.

// Оновлення залишку торгової пропозиції
\Bitrix\Catalog\ProductTable::update($offerBitrixId, [
    'QUANTITY' => $stockData['stock'],
    'QUANTITY_RESERVED' => $stockData['reserve'],
]);
\Bitrix\Catalog\Catalog::clearProductCache($offerBitrixId);

Передача замовлень у МойСклад

Нове замовлення в Бітрікс → створення customerorder у МойСклад. Мінімальний набір полів:

• organization — посилання на організацію продавця (обов'язкове)
• agent — покупець (counterparty у МойСклад), створюється автоматично або маппиться за email
• positions — позиції замовлення з посиланнями на variant або product та кількістю
• vatEnabled, vatIncluded — налаштування ПДВ повинні збігатися з налаштуваннями організації

Часткове відвантаження — сценарій, який ламає прості інтеграції. Замовлення на 5 позицій, відвантажено 3. У МойСклад створюється demand із 3 позиціями, пов'язаний із customerorder. Статус замовлення в Бітрікс повинен перейти в «Частково відвантажено», а не в «Виконано». Це обробляється через вебхук МойСклад на подію створення demand — порівнюємо demand.positions із customerorder.positions і вибираємо потрібний статус Бітрікс.

Вебхуки МойСклад

МойСклад підтримує вебхуки для подій: CREATE, UPDATE, DELETE по будь-якій сутності. Підписка:

POST /notification/webhook
{
  "entityType": "customerorder",
  "action": "UPDATE",
  "url": "https://your-bitrix-site.ru/api/moysklad/webhook/"
}

На боці Бітрікс створюємо контролер (нащадок \Bitrix\Main\Engine\Controller) або простий init.php-обробник. Важливо повернути HTTP 200 протягом 3 секунд — МойСклад вважає вебхук невдалим, якщо відповідь не надійшла вчасно, і повторює його.

Типові граблі

Ліміти API. МойСклад обмежує запити: 45 на секунду на безкоштовному тарифі, 100 на платних. При масовому оновленні залишків (1000+ позицій) додаємо usleep(100000) між пакетами.

Різниця часових поясів. МойСклад зберігає дати в UTC+3. Бітрікс працює в серверному часовому поясі. При порівнянні дат синхронізації («що змінилося з останнього запуску») враховуємо зсув.

Видалені товари. Якщо товар видалено з МойСклад, він не з'явиться у відповіді /entity/product. Бітрікс про видалення не дізнається. Потрібна періодична повна звірка або перевірка через archived: true.

Орієнтири за строками

Вартість розраховується індивідуально після аналізу номенклатури, схеми складів і бізнес-процесів обробки замовлень.