Интеграция 1С-Битрикс с amoCRM

Интеграция 1С-Битрикс с amoCRM

Заказы в Битрикс, лиды в amoCRM, менеджеры переключаются между двумя вкладками и вручную копируют данные. Контакт клиента в CRM не совпадает с данными в заказе, история переписки разорвана. Интеграция устраняет ручной труд и строит единую воронку: от первого визита на сайт до закрытия сделки. Разберём архитектуру, API amoCRM, типовые потоки данных и подводные камни.

Потоки данных

Основной поток — заказы и лиды из Битрикс в amoCRM. Обратный поток (статусы) нужен, если на сайте есть личный кабинет с отслеживанием обработки заказа.

API amoCRM v4

amoCRM использует OAuth 2.0 с long-lived refresh token. После авторизации через интеграцию (раздел Настройки → Интеграции в amoCRM) вы получаете client_id, client_secret, redirect_uri. Первичный обмен кода на токены — стандартный OAuth-флоу. Refresh token обновляется при каждом обновлении access token (срок жизни access token — 20 минут).

Хранение токенов в Битрикс: таблица b_option модуля или отдельная таблица. Обязательно шифруйте или храните вне публичной директории. Access token кэшируйте в runtime, refresh вызывайте только при 401.

Базовый URL API: https://{subdomain}.amocrm.ru/api/v4/.

Ключевые эндпоинты:

• POST /leads — создание сделки (лида).
• POST /contacts — создание контакта.
• POST /leads/complex — создание сделки с контактом и компанией одним запросом. Рекомендуемый метод — атомарная операция.
• GET /leads/{id} — получение сделки.
• PATCH /leads/{id} — обновление сделки (смена этапа, добавление полей).
• POST /catalogs/{catalog_id}/elements — товары в каталоге amoCRM.

Ограничения: 7 запросов в секунду на аккаунт. При превышении — HTTP 429 с заголовком Retry-After.

Создание сделки при оформлении заказа

Обработчик события OnSaleOrderSaved (модуль sale):

use Bitrix\Main\EventManager;

EventManager::getInstance()->addEventHandler(
    'sale', 'OnSaleOrderSaved',
    ['AmoCrmIntegration', 'onOrderSaved']
);

Метод onOrderSaved извлекает данные заказа и формирует запрос к amoCRM:

1. Поиск контакта — GET /contacts?query={phone_or_email}. Если найден — используем его ID. Если нет — создаём нового.
2. Создание сделки — POST /leads/complex с привязкой к контакту, названием «Заказ #{ORDER_ID}», суммой, UTM-метками в кастомных полях.

Маппинг полей заказа Битрикс → amoCRM:

UTM-метки — отдельная задача. Битрикс из коробки не сохраняет UTM в заказе. Нужно ловить их на фронте (JavaScript), сохранять в cookie или $_SESSION, а при оформлении заказа записывать в свойства (PROPERTY_UTM_SOURCE, PROPERTY_UTM_MEDIUM и т.д.). Оттуда — в кастомные поля сделки amoCRM.

Синхронизация статусов обратно

amoCRM поддерживает webhooks — при смене этапа сделки отправляет POST на указанный URL. Создаём обработчик /local/tools/amocrm_webhook.php:

1. Принимаем POST от amoCRM (массив leads[status][0]).
2. Извлекаем id сделки и status_id (ID этапа воронки).
3. По id сделки находим заказ Битрикс (через кастомное поле заказа PROPERTY_AMO_LEAD_ID или таблицу маппинга).
4. Обновляем статус заказа через \Bitrix\Sale\Order::load($orderId) → setField('STATUS_ID', $mappedStatus) → save().

Маппинг статусов воронки amoCRM → статусов заказа Битрикс хранится в конфигурации: массив [amo_status_id => bitrix_status_id].

Безопасность webhook: amoCRM не подписывает запросы. Проверяйте IP отправителя (список IP amoCRM в документации) или используйте секретный параметр в URL.

Обработка форм сайта

Формы обратной связи, callback, вопросы — всё это лиды. Два подхода:

1. Через веб-формы Битрикс — обработчик OnAfterResultAdd модуля form или OnAfterFormResultAdd создаёт сделку в amoCRM.
2. Через amoCRM формы — JS-виджет amoCRM на сайте, данные идут напрямую в CRM, минуя Битрикс. Проще, но теряется связь с Битрикс.

Рекомендация — первый вариант. Данные сначала сохраняются в Битрикс (надёжное хранение), затем асинхронно уходят в amoCRM.

Очередь и обработка ошибок

amoCRM API может быть недоступен (HTTP 500, 429, сетевая ошибка). Отправку заказов и лидов ставьте в очередь:

• Таблица amocrm_queue с полями id, type (lead/order/status), payload (JSON), attempts, status, last_error, created_at.
• Агент или cron-скрипт обрабатывает очередь каждую минуту. При ошибке — инкремент attempts, при attempts > 5 — status = 'failed', уведомление.

Сроки