Разработка модуля интеграции с CRM 1С-Битрикс

Разработка модуля интеграции с CRM 1С-Битрикс

Заказ оформлен на сайте — менеджер должен его увидеть в CRM и взять в работу. Без интеграции данные копируются вручную: это медленно, рождает ошибки и не даёт воронки. Модуль интеграции строит двусторонний канал между Битрикс-сайтом и CRM: лиды, сделки, контакты создаются автоматически, статусы синхронизируются.

Какие CRM интегрируются

• Битрикс24 — через REST API и вебхуки (наиболее распространённый сценарий).
• amoCRM — через oAuth 2.0 и REST API.
• RetailCRM — специализированная CRM для e-commerce, богатое API.
• Salesforce, HubSpot — реже, для западных рынков.

Принципы одинаковые, различается только API. Рассмотрим архитектуру на примере Битрикс24 и RetailCRM.

Что передаётся в CRM

При оформлении заказа:

• Создаётся сделка или лид с данными покупателя, составом заказа, суммой, UTM-метками.
• Создаётся или обновляется контакт/компания по номеру телефона или email.
• К сделке прикрепляется товарный позиционный список.

При изменении статуса заказа:

• Статус сделки в CRM обновляется соответственно.
• При оплате заказ помечается как оплаченный.

Обратная синхронизация:

• Менеджер меняет статус сделки в CRM → статус заказа на сайте обновляется через вебхук.

Архитектура модуля

local/modules/vendor.crmintegration/
├── lib/
│   ├── Adapter/
│   │   ├── Bitrix24Adapter.php
│   │   └── RetailCrmAdapter.php
│   ├── Mapper/
│   │   ├── OrderMapper.php    # Заказ → сделка
│   │   └── UserMapper.php     # Пользователь → контакт
│   ├── SyncService.php
│   └── WebhookHandler.php     # Обработка входящих вебхуков
└── install/db/install.sql

Таблица b_crm_sync_log — лог синхронизаций:

Интеграция с Битрикс24

Для Битрикс24 используется REST API. Создание сделки при новом заказе:

$dealData = [
    'TITLE'        => 'Заказ #' . $orderId . ' с сайта',
    'OPPORTUNITY'  => $order->getPrice(),
    'CURRENCY_ID'  => $order->getCurrency(),
    'SOURCE_ID'    => 'WEB',
    'UF_ORDER_ID'  => $orderId,  // пользовательское поле в Б24
];

$response = $this->callBitrix24(
    'crm.deal.add',
    ['fields' => $dealData]
);

$dealId = $response['result'];

// Добавляем товары к сделке
foreach ($basket as $item) {
    $this->callBitrix24('crm.deal.productrows.set', [
        'id' => $dealId,
        'rows' => [[
            'PRODUCT_NAME' => $item->getField('NAME'),
            'PRICE'        => $item->getPrice(),
            'QUANTITY'     => $item->getQuantity(),
            'PRODUCT_ID'   => $item->getProductId(),
        ]],
    ]);
}

Метод callBitrix24 выполняет запрос к https://portal.bitrix24.ru/rest/{token}/. Токен хранится в настройках модуля (b_option).

Дедупликация контактов

Перед созданием нового контакта ищем существующий по телефону:

$existing = $this->callBitrix24('crm.contact.list', [
    'filter' => ['PHONE' => $normalizedPhone],
    'select' => ['ID', 'NAME'],
]);

if (!empty($existing['result'])) {
    $contactId = $existing['result'][0]['ID'];
    // Обновляем существующий, не создаём дубль
} else {
    $contactId = $this->callBitrix24('crm.contact.add', [...]);
}

Нормализация телефона перед поиском обязательна: +7 (999) 123-45-67 и 89991234567 — один и тот же номер.

Интеграция с RetailCRM

RetailCRM имеет нативную поддержку интернет-магазинов. Заказ передаётся методом POST /api/v5/orders/create. RetailCRM поддерживает концепцию «магазинов» — один портал может принимать заказы с нескольких сайтов.

Ключевое отличие от Битрикс24: RetailCRM понимает структуру e-commerce — корзина, доставка, оплата, статусы заказа — без маппинга в абстрактные сделки.

Обработка входящих вебхуков

Когда менеджер меняет статус в CRM, CRM отправляет POST-запрос на URL вебхука. Битрикс получает уведомление и обновляет заказ:

// local/api/crm/webhook/index.php
$payload = json_decode(file_get_contents('php://input'), true);

\Vendor\CrmIntegration\WebhookHandler::handle($payload);

Обработчик по CRM_ID из b_crm_sync_log находит ORDER_ID, обновляет статус через $order->setField('STATUS_ID', $mappedStatus) и сохраняет.

Очередь для надёжной доставки

Все исходящие запросы к CRM помещаются в очередь в таблице b_crm_queue. Cron обрабатывает очередь каждую минуту, повторяет неудачные попытки. Это важно: при недоступности API CRM заказы не теряются.

Сроки разработки