API интеграция amoCRM — это способ связать CRM с любым внешним сервисом напрямую, через HTTP-запросы, без посредников в виде платных коннекторов. Работает по схеме OAuth 2.0: получаешь токены доступа, делаешь запросы к эндпоинтам вида https://домен.amocrm.ru/api/v4/leads, получаешь или отправляешь данные в JSON. Это позволяет создавать сделки с сайта, передавать лиды из телефонии, синхронизировать данные с 1С, ERP или любым самописным решением. Если коротко: всё, что умеет делать менеджер в интерфейсе amoCRM — можно сделать программно через API.
С чего начинается работа с API amoCRM
Первый шаг — создать интеграцию в настройках аккаунта. Заходишь в «Настройки» → «Интеграции» → «Создать интеграцию». Указываешь название, redirect URI (куда вернётся пользователь после авторизации), выбираешь права доступа. Получаешь client_id и client_secret.
Дальше — авторизация. amoCRM использует OAuth 2.0, и это немного сложнее, чем просто передать логин и пароль. Нужно получить authorization code, обменять его на access_token и refresh_token. Access_token живёт 24 часа. Refresh_token — 3 месяца, но каждый раз при обновлении access_token выдаётся новый refresh_token. Это важно: если не сохранить новый refresh — потеряешь доступ, и нужно будет проходить авторизацию заново.
Именно здесь чаще всего ломаются начинающие разработчики. Видел проект, где обновление токена было написано, но результат не сохранялся в БД. Через три месяца интеграция тихо умерла, а в CRM перестали падать заявки с сайта. Обнаружили случайно — когда менеджеры начали жаловаться, что «лиды пропали».
Основные методы: что реально используется
API v4 — актуальная версия. Старый v2 ещё иногда встречается в легаси-проектах, но его поддержка официально прекращена.
Самые используемые эндпоинты:
- POST /api/v4/leads — создать сделку
- PATCH /api/v4/leads/{id} — обновить сделку
- POST /api/v4/contacts — создать контакт
- POST /api/v4/leads/{id}/notes — добавить примечание к сделке
- GET /api/v4/account — получить данные аккаунта (полезно при отладке)
- POST /api/v4/leads/complex — создать сделку с контактом и компанией одним запросом
Метод complex сильно недооценён. Вместо трёх отдельных запросов (создать контакт, создать компанию, создать сделку и привязать) — один. Особенно актуально при высоком потоке заявок, когда важна скорость и атомарность.
Вебхуки: когда amoCRM сама отправляет данные
Вебхуки — это обратная сторона интеграции. Не ты опрашиваешь CRM, а CRM сама стучится на твой сервер при определённых событиях: смена статуса сделки, создание контакта, изменение поля.
Настраиваются в «Настройки» → «Интеграции» → «Вебхуки». Указываешь URL и выбираешь события. Дальше amoCRM шлёт POST-запросы с данными.
Тут есть один неочевидный момент — amoCRM не гарантирует порядок доставки и может слать несколько вебхуков подряд при пакетных изменениях. Если на стороне получателя нет идемпотентной обработки, можно получить задвоения. Особенно больно, если вебхук запускает что-то дорогостоящее — например, отправку SMS или создание задачи во внешней системе.
Три реальных кейса — с цифрами и факапами
Кейс 1. Медицинская клиника, Москва. Нужно было передавать заявки с сайта записи на приём в amoCRM и обратно — статус визита в личный кабинет пациента. Стек: PHP, MySQL, самописный сайт на Laravel. Интеграцию написали за 3 недели. На четвёртой неделе выяснилось, что при одновременных запросах с нескольких форм иногда создавались дубли контактов — один пациент, две карточки. Причина: не использовали поиск перед созданием. Добавили GET /api/v4/contacts?query=email до создания — дублей стало 0. Стоимость правки: 8 часов разработчика.
Кейс 2. Логистическая компания. Синхронизация amoCRM с 1С через API. Сделки из CRM при переходе на этап «Договор подписан» должны были создавать заказ в 1С, и обратно — статус доставки из 1С обновлял поле в amoCRM. Запустили. Через 11 дней 1С начала присылать статусы с задержкой до 40 минут — очередь переполнялась. Оказалось, что вебхуки от amoCRM не обрабатывались асинхронно, а сразу лезли в 1С напрямую. Переписали на очередь (RabbitMQ), задержки упали до 3–7 секунд. Переработка заняла 5 недель и стоила примерно 140 000 ₽.
Кейс 3. Онлайн-школа, B2C. Автоматизация: при покупке курса на платформе — сделка в amoCRM со статусом «Оплачено», тег с названием курса, задача менеджеру на онбординг. Использовали метод complex. Работало хорошо, пока не начали акции с одновременными покупками — в пике 200 транзакций за 4 минуты. amoCRM вернула 429 (rate limit). Решение: буферизация запросов на своей стороне с отправкой батчами по 50 объектов (API поддерживает). Конверсия в онбординг выросла на 23% просто за счёт того, что задачи стали реально создаваться, а не теряться.
Частые ошибки, которые видел лично
Хранение access_token в коде или конфиге — без автообновления. Работает три недели, потом «всё сломалось».
Игнорирование rate limits. amoCRM ограничивает: 7 запросов в секунду на аккаунт. При массовых операциях — батчи обязательно.
Создание контакта без проверки на дубль. Особенно актуально для форм, куда один человек может отправить заявку дважды.
Не логировать ответы API. Когда что-то ломается — непонятно где. Логируй и запрос, и ответ, и время. Звучит банально, но в половине проектов этого нет.
Вопросы, которые задают чаще всего
Нужен ли разработчик для API интеграции amoCRM?
Для базовых сценариев — передача лидов с сайта — да, нужен хотя бы джун с опытом работы с HTTP и JSON. Для сложных двусторонних синхронизаций — нужен человек, понимающий асинхронность, очереди и обработку ошибок. Без этого интеграция будет работать до первой нагрузки.
Можно ли обойтись без кода — через Zapier или Albato?
Да, и для простых задач это разумно. Но у no-code коннекторов есть потолок: они не умеют в сложную логику, батчинг, кастомную обработку ошибок. Плюс стоимость при большом объёме событий может удивить — один клиент платил 18 400 ₽ в месяц за Zapier там, где собственная интеграция окупилась бы за 2 месяца.
Как тестировать API без риска сломать продакшн?
У amoCRM нет официальной sandbox-среды. Используй тестовый аккаунт (можно зарегистрировать бесплатно на 14 дней) или отдельный субдомен. Для тестирования вебхуков — ngrok или схожие инструменты, чтобы получать запросы на локальный сервер.
Что делать, если API вернул ошибку 401?
Истёк access_token. Нужно обновить через refresh_token. Если и refresh_token недействителен — нужна повторная авторизация через браузер.
Можно ли через API работать с кастомными полями?
Да. Сначала получаешь список полей через GET /api/v4/leads/custom_fields, находишь нужный id, потом при создании или обновлении сделки передаёшь значение с этим id. Немного неудобно, но работает стабильно.
API amoCRM — инструмент нормальный, документация приличная по меркам российских CRM. Но дьявол в деталях: обновление токенов, rate limits, дубли контактов — всё это не написано большими буквами, и именно на этом горят чаще всего. Кто читал документацию внимательно — тот не горел.
