Интеграция сайта с amoCRM и Битрикс24: подключение и лимиты API

Чем отличаются способы подключения к amoCRM и Битрикс24, как устроена авторизация и обновление токенов, какие лимиты запросов действуют и почему метод может заблокироваться на 5 минут. Разбираю создание сделок, неразобранное, вебхуки, коды ошибок и защиту от дублей — с примерами запросов.

Интеграция сайта с amoCRM и Битрикс24: подключение и лимиты API

Сначала разграничим продукты

Путаница в названиях ломает интеграции ещё на этапе оценки. «Битрикс» в разговоре может означать два разных продукта:

  • Битрикс24 — CRM и корпоративный портал. У него есть публичный REST API, входящие и исходящие вебхуки, локальные приложения и OAuth 2.0.
  • «1С-Битрикс: Управление сайтом» — CMS, на которой работает сайт. Готового публичного REST-интерфейса с генерацией вебхуков, как в Битрикс24, у неё нет. API у CMS есть, но внешний HTTP-интерфейс для партнёров — это собственная разработка или готовое решение.

Поэтому типовая связка выглядит так: сайт на CMS → CRM. Со стороны сайта я делаю приёмник формы и отправщик, со стороны CRM использую её штатный API. Дальше в статье «Битрикс24» — это всегда CRM.

Как подключаться: способы и когда какой

СистемаСпособКогда подходитЧто важно учесть
amoCRMПриватная интеграция + OAuth 2.0Один аккаунт, своя автоматизацияНужны права администратора аккаунта для создания интеграции
amoCRMДолгосрочный токенНебольшая интеграция под конкретный аккаунтСрок от 1 дня до 5 лет, показывается один раз, refresh не нужен
amoCRMПубличная интеграцияРешение для многих аккаунтовЕсть отдельные требования к публичным интеграциям
Битрикс24Входящий вебхукВнутренняя интеграция с одним порталомРаботает в рамках выбранных scope и прав создавшего сотрудника
Битрикс24Исходящий вебхукРеакция на изменения в CRMОбработчик должен быть публично доступен
Битрикс24Локальное приложение или OAuth 2.0Установка на разные порталы, интерфейс внутри CRM, методы, требующие контекста приложенияЧасть методов через вебхук недоступна в принципе

Два практических следствия, которые я проговариваю с заказчиком до старта:

Вебхук Битрикс24 — не универсальный ключ. Часть методов требует контекста приложения и через вебхук не работает: например, встраивание виджетов placement.bind, часть методов телефонии и некоторые сценарии чат-ботов. Если в задаче есть виджет внутри CRM — это сразу приложение, а не вебхук.

У вебхука Битрикс24 есть срок действия. Механизм поддерживает дату окончания; когда срок истёк, запрос перестаёт проходить и возвращает ошибку авторизации. Это отдельная строка в регламенте поддержки, иначе через год интеграция «сама сломается».

И ещё про доступы: создать входящий вебхук может администратор или сотрудник, которому администратор разрешил это в настройках безопасности. Секретный код виден только создателю; если администратор отредактирует чужой вебхук, код обновится, а владельцем станет администратор — то есть правка чужого вебхука ломает работающую интеграцию.

Авторизация в amoCRM: что нужно знать про токены

amoCRM использует OAuth 2.0. Логика стандартная, но дьявол в сроках и в однократности обмена.

Код авторизации живёт 20 минут. За это время его нужно обменять на пару токенов. Получить код можно тремя способами: скопировать из модального окна установленной интеграции (подходит для одного аккаунта), получить вебхуком при установке виджета или пройти по адресу предоставления доступа.

Обмен кода на токены — POST на /oauth2/access_token:

{
  "client_id": "ID интеграции",
  "client_secret": "Секрет интеграции",
  "grant_type": "authorization_code",
  "code": "полученный код авторизации",
  "redirect_uri": "https://example.ru/amocrm/callback/"
}

redirect_uri должен чётко совпадать с указанным в настройках интеграции. В ответ приходят token_type, expires_in, server_time, access_token в формате JWT и refresh_token.

Дальше — два ограничения refresh-токена, которые ломают интеграции чаще всего:

  1. Refresh-токен действует 3 месяца. Если интеграция не использовалась и не было ни одного запроса на актуализацию ключа, доступ к данным теряется и разрешение придётся запрашивать у пользователя заново.
  2. Refresh-токен можно обменять только один раз. После обмена старая пара становится неактуальной, и новый refresh нужно обязательно сохранить. Не сохранили — потеряли доступ.

Отсюда моё правило: обновление токена — это транзакция. Сначала успешно получили ответ, потом атомарно записали новую пару, и только потом считаем операцию завершённой. Хранить токены в файле, который перезаписывается параллельными процессами, — прямой путь к потере доступа.

Запросы к API идут с заголовком Authorization: Bearer {access_token} и на точный адрес аккаунта, а не на общий домен:

curl -s "https://company.amocrm.ru/api/v4/account" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Токен имеет права того пользователя, который предоставил доступ. Отдельно документация требует хранить access, refresh и client_secret в безопасном хранилище, а при утечке сначала обновить client_secret интеграции, затем токены.

Долгосрочные токены amoCRM добавила в феврале 2024 года. Они генерируются на вкладке «Ключи», срок выбирается от 1 дня до 5 лет, токен показывается один раз, refresh-токена у него нет — то есть не нужно писать логику актуализации. Для небольшой интеграции под один аккаунт это заметно меньше кода и меньше точек отказа. Токен можно отозвать в разделе выданных доступов.

Хук об отключении интеграции. Можно указать адрес, на который придёт GET-запрос при отключении интеграции пользователем, с параметрами account_id и client_id. Подлинность проверяется подписью: HMAC-SHA256 от конкатенации client_uuid и account_id с секретным ключом интеграции, подпись приходит в параметре signature. Я всегда его указываю — иначе интеграция продолжает стучаться в отключённый аккаунт и собирать 401.

Авторизация в Битрикс24: вебхук проще, но не всегда достаточен

Входящий вебхук — это секретный URL, который вызывает методы REST от имени создавшего его сотрудника:

https://example.bitrix24.ru/rest/1/xxxxxxxx/crm.item.get.json?entityTypeId=2&id=662

Разбор URL: адрес портала, /rest, идентификатор сотрудника, секретный код, имя метода, суффикс формата (.json можно не указывать, он по умолчанию), затем параметры метода.

Права вебхука определяются двумя вещами: выбранными scope и правами сотрудника. Проверять надо оба — метод может быть разрешён скоупом, но недоступен сотруднику по правам на объект.

Про GET и POST документация говорит прямо: GET подходит для быстрых проверок простых вызовов, но URL вебхука может сохраниться в истории браузера, логах и сервисах мониторинга. Для рабочих интеграций, вложенных параметров, файлов и изменения данных — только POST. Секретный URL нельзя публиковать в клиентском коде.

curl -s -X POST "https://example.bitrix24.ru/rest/1/xxxxxxxx/crm.lead.add.json" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"TITLE":"Заявка с сайта","NAME":"Иван","PHONE":[{"VALUE":"+79000000000","VALUE_TYPE":"WORK"}]}}'

Когда вебхука недостаточно — интеграцию нужно ставить на разные порталы, нужен интерфейс внутри Битрикс24, нужны методы, работающие только в контексте приложения, или хочется централизованно управлять авторизацией без передачи секретного URL. Тогда это локальное приложение или полноценный OAuth 2.0.

Лимиты: главная причина «интеграция работала и встала»

Это раздел, ради которого стоит читать статью целиком.

amoCRM

ОграничениеЗначение
Частота запросов на одну интеграциюне более 7 в секунду
Частота запросов на аккаунтдо 50 в секунду
Максимум возвращаемых сущностейне более 500, большинство методов — не более 250
Максимум создаваемых или изменяемых сущностей в запросене более 250, рекомендуется не более 50

Что происходит при нарушении:

  • превышение частоты — HTTP 429;
  • многократное нарушение — аккаунт блокируется, и на любой запрос приходит 403;
  • при подозрительной активности или сбое интеграции доступ к API аккаунта может быть заблокирован — документация приводит примеры: выборка одних и тех же данных раз за разом за короткий промежуток, бесконтрольный перебор всех данных;
  • при ответе 504 рекомендуется уменьшить количество передаваемых сущностей и повторить запрос;
  • при 401 — проверить корректность и срок действия access-токена, обновить его через refresh и повторить.

Отдельный пункт, о котором забывают на проектах с сезонностью: после окончания подписки запросы на добавление и изменение блокируются сразу, а доступ к данным через API закрывается через 30 дней; в ответ приходит HTTP 402. То есть неоплаченный аккаунт CRM — это остановленная интеграция, а не «поработает пока».

Битрикс24

Здесь два независимых механизма, и путать их нельзя.

Интенсивность запросов работает по алгоритму Leaky Bucket: каждый запрос увеличивает счётчик, раз в секунду счётчик уменьшается на Y, при превышении порога X следующий запрос блокируется со статусом 503 и кодом QUERY_LIMIT_EXCEEDED.

ТарифСкорость уменьшения счётчика YЛимит до блокировки X
Энтерпрайз5 в секунду250
Прочие2 в секунду50

Кратковременно можно превышать Y, постоянно — нельзя. Для планирования объёмов документация предлагает считать по минимальной устойчивой интенсивности: 2 запроса в секунду, это 172 800 запросов в сутки. Важная деталь: лимит считается по HTTP-запросам, а не по записям в ответе, и учитывается по IP-адресу — если несколько приложений на одном сервере работают с одним порталом, лимит у них общий.

Ресурсоемкость — накопленное время выполнения метода, отдельно для каждого приложения или вебхука. Время учитывается в 10 одноминутных «корзинах»: текущая минута плюс девять предыдущих. Если накопленное время превышает лимит, метод блокируется для этого приложения или вебхука на 5 минут, а на вызовы приходит статус 429 с кодом OPERATION_TIME_LIMIT. Другие методы и приложения продолжают работать.

Смотреть это можно прямо в ответе — ключ operating в объекте time:

{
  "time": {
    "duration": 0.6196250915527344,
    "operating_reset_at": 1778747792,
    "operating": 3.3076241016387939
  }
}

Ещё ограничения, которые нужно держать в голове:

  • один REST-запрос в облаке должен выполниться не дольше 60 секунд, иначе таймаут;
  • есть лимит времени SQL-запроса внутри метода: при превышении приходит ошибка BITRIX_REST_V3_EXCEPTION_LIMITER_QUERYTIMELIMITEXCEPTION со статусом 503 и заголовком Retry-After; классические методы на контроллерах Engine возвращают 400 без Retry-After;
  • в коробочной версии ограничение ресурсоемкости по умолчанию выключено; если включить, лимит по умолчанию 420 секунд, и работает он только при подключении к Redis.

Как реагировать на ошибки лимитов

ОшибкаПричинаЧто делать
QUERY_LIMIT_EXCEEDEDпревышена интенсивность запросовснизить частоту, повторять с увеличивающейся задержкой, не запускать параллельные серии с одного IP
OPERATION_TIME_LIMITнакопленное время метода превысило лимитприостановить вызовы этого метода на 5 минут, затем снизить нагрузку: разбить выборку, убрать лишние поля
...QUERYTIMELIMITEXCEPTIONSQL внутри метода выполнялся слишком долгоповторять не раньше, чем через время из Retry-After; сузить фильтры и страницу

Практический вывод: редкие запросы не гарантируют отсутствие блокировок. Тяжёлый crm.item.list по большому порталу может упереться в ресурсоемкость при частоте значительно ниже 2 запросов в секунду. Поэтому я логирую operating и duration из каждого ответа — это единственный способ увидеть проблему до того, как метод встанет на 5 минут.

batch: экономия запросов, а не времени

Метод batch передаёт до 50 вызовов в одном HTTP-запросе, вызовы выполняются последовательно, и данные предыдущего доступны в последующих через $result:

{
  "cmd": {
    "contact": "crm.contact.add?fields[NAME]=Иван&fields[PHONE][0][VALUE]=%2B79000000000",
    "deal": "crm.deal.add?fields[TITLE]=Заявка&fields[CONTACT_ID]=$result[contact]"
  }
}

Но batch не отменяет лимит ресурсоемкости: время вложенных вызовов входит в operating самого batch, причём с половинным весом — пакет, выполнявшийся 2 секунды, увеличивает operating примерно на 1 секунду. И документация прямо говорит: REST API не предназначен для массового и интенсивного обмена большими данными; для отчётов и аналитики по большим объёмам есть BI-конструктор, который получает данные не через REST.

Что отправлять: сделки, контакты, неразобранное

amoCRM

Создание сделок — POST на /api/v4/leads, тело это массив объектов. Обязательное поле при добавлении — name; ответственному по умолчанию становится пользователь, чей токен использован.

[
  {
    "name": "Заявка с сайта: расчёт стоимости",
    "price": 15000,
    "custom_fields_values": [
      { "field_id": 123456, "values": [ { "value": "https://example.ru/uslugi/" } ] }
    ],
    "_embedded": {
      "contacts": [ { "id": 456789 } ]
    }
  }
]

Три момента, которые я всегда проверяю:

  • custom_fields_values требует field_id или field_code и непустой массив values. Для полей типа «ссылка» значение передаётся объектом с value.
  • Связь с контактом и компанией передаётся во _embedded. Можно передать существующий id, а для компании также поддерживается создание «на лету» — тогда контакт создастся и привяжется к сделке.
  • Комплексное добавление через /api/v4/leads/complex создаёт сделку вместе с контактом и компанией, но документация предупреждает: при добавлении через этот метод не срабатывают триггеры и не выполняется контроль дублей. Это критично, если в аккаунте настроена автоматизация.

Для заявок «сначала в разбор, потом менеджер решает» есть неразобранное — POST на /api/v4/leads/unsorted/forms. Обязательные поля: source_uid, source_name, metadata (обязательны form_id, form_name, form_page, ip, form_send_at, referer), _embedded с leads и contacts. Важное ограничение: при добавлении неразобранного не проверяются права пользователя и не проверяются обязательные поля — то есть валидацию данных надо делать на своей стороне, а не надеяться на CRM.

Битрикс24

Классические методы crm.lead.add, crm.contact.add, crm.deal.add работают с объектом fields. У универсальных методов crm.item.* добавляется entityTypeId — например, для сделки это 2, что видно в официальном примере разбора исходящего вебхука.

Практическая рекомендация: перед создением проверять дубли. В Битрикс24 для этого есть поиск по коммуникациям, в amoCRM — контроль дублей на стороне аккаунта, но, как показано выше, он не срабатывает при комплексном добавлении.

Вебхуки: приём событий и проверка подлинности

Исходящий вебхук Битрикс24 не вызывает метод сам — он передаёт событие на ваш обработчик. Данные приходят как application/x-www-form-urlencoded, в PHP их удобно читать через $_REQUEST:

Array
(
    [event] => ONCRMDEALUPDATE
    [data] => Array
        (
            [FIELDS] => Array
                (
                    [ID] => 662
                )
        )
    [ts] => 1724140800
    [auth] => Array
        (
            [domain] => example.bitrix24.ru
            [member_id] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
            [application_token] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        )
)

В data[FIELDS][ID] приходит только идентификатор. За полными данными нужно идти отдельным вызовом — в типовом сценарии crm.item.get с entityTypeId = 2. Это значит, что каждое событие генерирует минимум один дополнительный запрос, и это надо учитывать в расчёте лимитов.

Проверка подлинности обязательна: сравните auth[application_token] из запроса с токеном, который показан в настройках исходящего вебхука. Не совпало — запрос не считается доверенным.

<?php
$token = $_REQUEST['auth']['application_token'] ?? '';
if (!hash_equals(EXPECTED_APP_TOKEN, $token)) {
    http_response_code(403);
    exit;
}

$dealId = (int)($_REQUEST['data']['FIELDS']['ID'] ?? 0);
if ($dealId > 0) {
    // ставим задачу в очередь, а не тянем данные прямо в обработчике
    $queue->push('sync_deal', ['id' => $dealId]);
}

http_response_code(200);

Требования к обработчику: публичный URL, доступный из внешней сети, принимающий POST. localhost, адреса локальной сети и самоподписанный SSL-сертификат не подходят. В коробочной версии для исходящего вебхука нужна активная лицензия, на деморежимах он недоступен.

Со стороны amoCRM есть вебхуки на события сущностей; при настройке указываются адрес и события, а подлинность проверяется по секрету, который выдаётся при создании вебхука.

Надёжность: что я закладываю в любую интеграцию

Это не требования вендоров, а моя практика, которая выросла из разборов чужих интеграций.

Очередь вместо прямого вызова из формы. Обработчик формы принимает данные, кладёт задачу в очередь и сразу отвечает пользователю. Отправка в CRM идёт отдельным процессом. Иначе таймаут CRM превращается в «заявка не отправилась» для человека, который заполнил форму.

Идемпотентность. У каждой заявки свой ключ. Повторная обработка задачи не должна создавать вторую сделку. Без этого любой ретрай после таймаута даёт дубль.

Ретраи с увеличивающейся задержкой и уважением к Retry-After. Для 429 и 503 это обязательное поведение, а не «попробуем ещё раз сразу».

Один поток на аккаунт. И amoCRM, и Битрикс24 наказывают за параллельные серии запросов; у Битрикс24 лимит ещё и общий на IP.

Журнал запросов и ответов. Для amoCRM — код ответа и тело ошибки, для Битрикс24 — дополнительно duration и operating. Без этого невозможно доказать, что заявка была отправлена и принята.

Сверка с CRM. Раз в период сравниваю три числа: заявки в журнале сайта, отправленные запросы и сущности в CRM. Расхождение — задача на разбор, а не погрешность.

Реакция на отключение и на 401. Хук об отключении в amoCRM, срок действия вебхука в Битрикс24, истёкший refresh — всё это должно приводить к уведомлению ответственному, а не к тихой потере заявок.

Чек-лист перед запуском

  • Определено, что за продукт: Битрикс24 или CMS, и какой способ подключения выбран осознанно.
  • Проверено, что нужные методы доступны по выбранному scope и по правам сотрудника.
  • Для amoCRM: redirect_uri совпадает с настройками интеграции, новая пара токенов сохраняется атомарно, указан хук об отключении.
  • Секреты не в клиентском коде и не в репозитории; для Битрикс24 рабочие вызовы идут POST, а не GET.
  • Для исходящего вебхука: URL публичный, POST, валидный сертификат, проверка application_token реализована.
  • Учтено, что событие даёт только ID и требует дополнительного запроса.
  • Частота запросов ограничена на своей стороне, ретраи уважают Retry-After, параллельных серий нет.
  • Логируются operating и duration для Битрикс24 и коды ошибок для amoCRM.
  • Есть очередь, идемпотентность и журнал заявок.
  • Проверено поведение при 401, 402, 403, 429, 503 и 504 — не «в теории», а тестовыми запросами.
  • Есть регламент: кто получает уведомление о сбое и кто продлевает токены и вебхуки.

Коротко

Подключиться к amoCRM или Битрикс24 сегодня несложно: у обоих есть штатные механизмы, и первый запрос можно сделать за час. Сложность начинается позже — на сроках токенов, лимитах интенсивности и ресурсоемкости, на дублях при ретраях и на событиях, которые приносят только идентификатор.

Поэтому интеграцию я оцениваю не по количеству методов, а по тому, что произойдёт в плохой день: когда CRM ответила 429, токен истёк, аккаунт не оплачен, а менеджер уже ждёт заявку. Если на каждый из этих случаев есть заранее продуманное поведение — интеграция рабочая. Если нет — она просто ещё не сломалась.

Источники

  • amoCRM, ограничения и рекомендации — раздел для разработчиков amocrm.ru: частота запросов на интеграцию и аккаунт, лимиты возвращаемых и создаваемых сущностей, поведение при 429, 403, 402, 504 и 401, требования к HTTPS и хранению ключей.
  • amoCRM, авторизация по шагам — там же: регистрация интеграции, срок кода авторизации, метод /oauth2/access_token, ограничения refresh-токена, долгосрочные токены, хук об отключении и проверка его подписи, обработка ошибок.
  • amoCRM, сделки и неразобранное — описание методов добавления сделок, комплексного добавления и форм неразобранного, обязательные поля и предупреждения о триггерах и контроле дублей.
  • Битрикс24, входящие и исходящие вебхуки — apidocs.bitrix24.ru: устройство URL, права и scope, ограничения GET, дата окончания вебхука, методы, недоступные через вебхук, структура данных исходящего вебхука и проверка application_token.
  • Битрикс24, лимиты REST API — apidocs.bitrix24.ru: таймаут запроса, лимит SQL-запроса, алгоритм Leaky Bucket и значения по тарифам, ресурсоемкость и блокировка метода, коды ошибок и рекомендации по реакции.
  • Битрикс24, batch — apidocs.bitrix24.ru: до 50 вызовов в пакете, последовательное выполнение, учёт времени вложенных вызовов.

Тарифы, лимиты и состав методов меняются, поэтому перед работами я сверяюсь с актуальной документацией обеих систем, а не с примерами из чужих статей.

АН
Автор

Алексей Нестеров

Веб-разработчик. Пишу о PHP, 1С-Битрикс, интеграциях и инструментах разработки.

Обо мне

Комментариев пока нет. Будьте первым.

Оставить комментарий

Комментарий появится после проверки модератором.