Сначала разграничим продукты
Путаница в названиях ломает интеграции ещё на этапе оценки. «Битрикс» в разговоре может означать два разных продукта:
- Битрикс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-токена, которые ломают интеграции чаще всего:
- Refresh-токен действует 3 месяца. Если интеграция не использовалась и не было ни одного запроса на актуализацию ключа, доступ к данным теряется и разрешение придётся запрашивать у пользователя заново.
- 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 минут, затем снизить нагрузку: разбить выборку, убрать лишние поля |
...QUERYTIMELIMITEXCEPTION | SQL внутри метода выполнялся слишком долго | повторять не раньше, чем через время из 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 вызовов в пакете, последовательное выполнение, учёт времени вложенных вызовов.
Тарифы, лимиты и состав методов меняются, поэтому перед работами я сверяюсь с актуальной документацией обеих систем, а не с примерами из чужих статей.
Комментарии
Оставить комментарийКомментариев пока нет. Будьте первым.
Оставить комментарий
Комментарий появится после проверки модератором.