Інтеграція 1С-Бітрікс з RetailCRM

Інтеграція 1С-Бітрікс з RetailCRM

RetailCRM — спеціалізована CRM для ecommerce: складський облік, збирання замовлень, доставка, аналітика за когортами. Bitrix24 — універсальна CRM; RetailCRM — заточена під операційну роботу інтернет-магазину. Інтеграція є доцільною, коли обсяг замовлень перевищує 50–100 на добу.

Готовий модуль vs. власна інтеграція

RetailCRM надає офіційний модуль для 1С-Бітрікс через маркетплейс. Модуль покриває базові сценарії. Власна інтеграція потрібна, коли:

• Нестандартні статуси замовлень або властивості, яких немає в модулі.
• Складна логіка маппінгу (кілька магазинів, різні склади).
• Потрібна інтеграція з іншими системами через RetailCRM (телефонія, служби доставки).

REST API RetailCRM v5

Базовий URL: https://yourdomain.retailcrm.ru/api/v5/. Автентифікація — заголовок X-API-KEY.

class RetailCRMClient {
    private string $apiKey;
    private string $siteKey; // код магазину в RetailCRM
    private string $baseUrl;

    public function createOrder(\Bitrix\Sale\Order $order): ?string {
        $basket = $order->getBasket();
        $props  = $order->getPropertyCollection();

        $items = [];
        foreach ($basket as $item) {
            $items[] = [
                'offer'    => ['xmlId' => (string)$item->getProductId()],
                'quantity' => $item->getQuantity(),
                'initialPrice' => $item->getBasePrice(),
                'discountPercent' => 0,
            ];
        }

        $orderData = [
            'number'      => 'BX-' . $order->getId(),
            'externalId'  => (string)$order->getId(),
            'site'        => $this->siteKey,
            'status'      => $this->mapStatus($order->getField('STATUS_ID')),
            'customer'    => [
                'externalId' => (string)$order->getUserId(),
                'email'      => $props->getUserEmail(),
                'phone'      => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            ],
            'items'       => $items,
            'delivery'    => [
                'code'    => $this->mapDelivery($order->getDeliveryId()),
                'address' => ['text' => $this->getOrderAddress($props)],
            ],
            'paymentType' => $this->mapPayment($order->getPaymentSystemId()),
        ];

        $http = new \Bitrix\Main\Web\HttpClient();
        $http->setHeader('X-API-KEY', $this->apiKey);
        $http->setHeader('Content-Type', 'application/x-www-form-urlencoded');

        $response = json_decode($http->post(
            $this->baseUrl . 'orders/create',
            'order=' . urlencode(json_encode($orderData)) . '&site=' . $this->siteKey
        ), true);

        return $response['id'] ?? null; // ID замовлення в RetailCRM
    }
}

Двостороння синхронізація статусів

RetailCRM змінює статус замовлення (менеджер обробив, поставив на збірку, передав у доставку) — сайт повинен оновити статус.

RetailCRM підтримує вихідні вебхуки. Налаштовуємо в розділі «Адміністрування → Вебхуки»:

// Обробник вебхука від RetailCRM
$payload = json_decode(file_get_contents('php://input'), true);

foreach ($payload['orders'] as $orderData) {
    $externalId = $orderData['externalId']; // ID замовлення в 1С-Бітрікс
    $newStatus  = $statusMap[$orderData['status']] ?? null;

    if ($newStatus) {
        $order = \Bitrix\Sale\Order::load($externalId);
        $order->setField('STATUS_ID', $newStatus);
        $order->save();
    }
}

Маппінг довідників

RetailCRM зберігає довідники: статуси, типи доставки, методи оплати — кожен з кодом. Коди потрібно привести до кодів 1С-Бітрікс:

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

Кейс: розрив синхронізації при піковому навантаженні

Магазин одягу під час розпродажу: 800 замовлень за 2 години. Пряма синхронна передача в RetailCRM при кожному OnSaleOrderSaved призвела до таймаутів — RetailCRM API відповідав із затримкою 3–5 секунд, що блокувало обробку замовлення на сайті.

Рішення: черга на основі агентів 1С-Бітрікс. Замовлення записуються в таблицю черги (b_retailcrm_queue), агент кожні 10 секунд надсилає порцію по 10 замовлень. Пікове навантаження згладжується, замовлення проходять за 1–5 хвилин.