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

Інтеграція 1С-Bitrix з amoCRM

Замовлення в Bitrix, ліди в amoCRM, менеджери переключаються між двома вкладками й вручну копіюють дані. Контакт клієнта в CRM не збігається з даними в замовленні, історія переписки розривається. Інтеграція усуває ручну роботу й будує єдину воронку: від першого відвідування сайту до закриття угоди. Розглянемо архітектуру, API amoCRM, типові потоки даних і підводні камені.

Потоки даних

Основний потік — замовлення й ліди з Bitrix в amoCRM. Обернений потік (статуси) потрібен, якщо на сайті є особистий кабінет із відслідковуванням обробки замовлення.

API amoCRM v4

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

Зберігання токенів у Bitrix: таблиця b_option модуля або окрема таблиця. Обов'язково шифруйте або зберігайте поза публічною директорією. Кешуйте access token в runtime, refresh викликайте лише при 401.

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

Ключові endpoint'и:

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

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

Створення угоди при оформленні замовлення

Обробник eventos 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-мітками в кастомних полях.

Відображення полів замовлення Bitrix → amoCRM:

UTM-мітки — окреме завдання. Bitrix з коробки не зберігає 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 угоди знаходимо замовлення Bitrix (через кастомне поле замовлення PROPERTY_AMO_LEAD_ID або таблицю відображення).
4. Оновлюємо статус замовлення через \Bitrix\Sale\Order::load($orderId) → setField('STATUS_ID', $mappedStatus) → save().

Відображення статусів воронки amoCRM → статусів замовлення Bitrix зберігається в конфігурації: масив [amo_status_id => bitrix_status_id].

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

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

Форми зворотного зв'язку, callback, запитання — усе це ліди. Два підходи:

1. Через веб-форми Bitrix — обробник OnAfterResultAdd (модуль form) або OnAfterFormResultAdd створює угоду в amoCRM.
2. Через форми amoCRM — JS-віджет amoCRM на сайті, дані йдуть напрямки в CRM, мінуючи Bitrix. Простіше, але втрачається зв'язок з Bitrix.

Рекомендація — перший варіант. Дані спочатку зберігаються в Bitrix (надійне зберігання), потім асинхронно йдуть в amoCRM.

Черга й обробка помилок

API amoCRM може бути недоступний (HTTP 500, 429, помилка мережі). Поставте відправку замовлень і лідів в чергу:

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

Строки