Интеграция с amoCRM: пошагово для AI-агента

Интеграция с amoCRM через API v4: OAuth, сделки, контакты, вебхуки, лимиты 7 запросов в секунду. С примерами запросов.

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

Всё дальше — по официальной документации amoCRM: API v4, OAuth 2.0, вебхуки. Ни одного шага из головы, каждый сверен с разделом для разработчиков.

Шаг 1. Доступ: OAuth 2.0

Просто по ключу amoCRM работать не даст. Нужна интеграция, зарегистрированная в аккаунте, и токен по протоколу OAuth 2.0.

1. Регистрация интеграцииВ аккаунте создаётся интеграция: получаете client_id и client_secret. Права выдаются под конкретные сущности.
2. Код авторизацииПользователь подтверждает доступ, amoCRM возвращает code на ваш redirect_uri.
3. Обмен кода на токеныPOST на https://subdomain.amocrm.ru/oauth2/access_token с grant_type=authorization_code.
4. Работа по токенуЗапросы идут на адрес аккаунта с заголовком Authorization: Bearer <access_token>.

Про токены коротко:

• access_token живёт 86 400 секунд — сутки. В ответе приходят expires_in и server_time.
• Рядом приходит refresh_token. Когда access истёк, агент меняет refresh на новую пару с grant_type=refresh_token.
• access_token — это JWT, token_type — Bearer.
• Обращаться нужно на точный адрес аккаунта вида https://company.amocrm.ru, а не на общий домен. Так требует документация.

curl https://subdomain.amocrm.ru/oauth2/access_token -d '{
  "client_id": "xxx-xxx",
  "client_secret": "xxxxxx",
  "grant_type": "authorization_code",
  "code": "код из redirect",
  "redirect_uri": "https://ваш-сервис.ru/callback"
}'

Ответ:

{"token_type": "Bearer", "expires_in": 86400, "server_time": 1751621727,
 "access_token": "xxxxxx", "refresh_token": "xxxxx"}

• Токены хранить только на сервере, не в браузере
• client_secret и refresh_token — в секретах, не в коде
• Обновление токена делает фоновый процесс, а не человек
• При утечке сначала меняется client_secret, потом токены

Шаг 2. Сущности: что агент пишет в CRM

Основные сущности API v4 — сделки, контакты, компании, задачи, примечания. Чтобы обрабатывать заявки, агенту хватает четырёх действий:

Для заявок с сайта и из Telegram удобен метод POST /api/v4/leads/complex.

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

Минимальное создание сделки выглядит так:

curl -X POST "https://company.amocrm.ru/api/v4/leads" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"name": "Заявка с сайта — Иван", "price": 0}]'

Полный список полей — в разделе «Поля и группы полей» официальной документации. У каждого аккаунта состав полей свой. Поэтому агент сначала запрашивает поля, а потом собирает тело запроса. Иначе половина данных уйдёт в никуда.

amoCRM API работает по HTTPS и только через TLS 1.1 и 1.2.

Локальный тест «по http» не подойдёт. Чтение списков — GET /api/v4/leads с параметрами page, limit (максимум 250), filter, order. Ответ приходит в формате application/hal+json. Ошибки — application/problem+json.

Шаг 3. События: вебхуки

Вебхук — уведомление от amoCRM на ваш адрес. Агент не опрашивает CRM каждую минуту. Он получает событие и реагирует.

Факты из документации, от которых зависит архитектура:

• В одном аккаунте — не больше 100 вебхуков. Один вебхук можно подписать на несколько событий.
• Вебхуки настраиваются в интерфейсе (раздел амоМаркет) либо через API: POST /api/v4/webhooks с телом { "destination": "...", "settings": ["add_lead"], "sort": 10 }.
• Вебхуки amoCRM приходят в формате x-www-form-urlencoded, а не JSON.
• Сервис ждёт ответ не больше 2 секунд. Нет ответа или код вне диапазона 100–299 — хук считается недоставленным, а при повторных сбоях его могут отключить.
• Работа с вебхуками через API доступна на тарифах «Расширенный» и «Профессиональный».

Отсюда первое правило: обработчик вебхука ничего не считает. Он проверяет запрос, кладёт событие в очередь и сразу отвечает 200. Вся работа — в фоновом воркере.

Второе правило: вебхук — уведомление, а не полная карточка. Из тела агент берёт id и запрашивает сущность методом GET /api/v4/leads/{id}, чтобы работать с актуальными данными.

Список кодов событий зависит от сущности и действия. В документации приведён пример подписки на add_lead. Полный перечень доступных действий смотрите в настройках вебхука и в разделе «Вебхуки» официальной документации. Не угадывайте коды — выберите их в интерфейсе и сохраните.

Шаг 4. Лимиты и ошибки

Что делать агенту:

• 401 — токен истёк: обновить по refresh_token и повторить запрос
• 402 — аккаунт не оплачен: писать человеку, а не ретраить
• Превышение частоты — пауза и повтор с задержкой, а не долбёж
• Дубли — перед созданием искать контакт по телефону и почте
• Идемпотентность — хранить id созданной сделки рядом с id заявки

Интеграция с amoCRM без учёта лимитов упирается в отказы уже на второй день. Документация отдельно предупреждает: за бесконтрольный перебор данных и подозрительную активность доступ к API аккаунта могут заблокировать. Поэтому агент не «скачивает всё», а запрашивает по фильтру и по времени.

Интеграция с amoCRM: проверка перед запуском

1. Тест на копииСначала отдельная воронка или тестовый аккаунт. Реальные менеджеры не должны видеть отладку.
2. Один сценарийТолько входящие заявки: создание сделки, контакт, задача, примечание.
3. ЛогиКаждый запрос: метод, код ответа, id сущности, время. Без токенов в логах.
4. НаблюдениеНеделя работы: сколько заявок пришло, сколько дошло до CRM, где расхождения.
5. РасширениеПосле стабильной недели — смена этапов, ответы клиенту, отчёты.

Что в итоге делает агент

На этом интеграция с amoCRM заканчивается. Агент получает событие о новой заявке, вытаскивает карточку, проверяет дубль контакта, создаёт сделку в нужной воронке, ставит задачу менеджеру с резюме, пишет примечание и отправляет клиенту подтверждение. Менеджер открывает карточку и видит готовую работу, а не пустое поле «Название».

Общая схема и сравнение с Bitrix24 — в статье интеграция AI-агента с CRM. А про то, что агент делает с заявкой до записи в CRM, — в разборе агент для обработки заявок.

Сергей ЕзепенкоИнтеграция с amoCRM

Настрою интеграцию агента с amoCRM по официальному API. Бесплатная диагностика — 30 минут.

Написать в TelegramНаписать в MAX