В современном мире бизнеса, где скорость обработки данных и автоматизация

процессов становятся критическими факторами успеха, умение эффективно работать

с API CRM-систем превращается из конкурентного преимущества в необходимость.

AmoCRM, будучи одним из лидеров на рынке CRM для малого и среднего бизнеса на

постсоветском пространстве, предоставляет мощный API (Application Programming

Interface), позволяющий интегрировать систему с любыми внешними сервисами —

от сайтов и телефонии до чат-ботов и корпоративных ERP-систем.

Данная статья представляет собой экспертное руководство, которое проведет вас

через все этапы работы с AmoCRM API: от поиска нужных настроек в интерфейсе и

выбора версии API до практических примеров кода и разбора типовых сценариев

интеграции. Материал рассчитан как на начинающих разработчиков, так и на

опытных интеграторов, желающих систематизировать знания о возможностях

платформы.

Ключевые понятия: AmoCRM API, REST API, OAuth 2.0, интеграция, автоматизация

продаж, вебхуки, сделки, контакты, разработка.

ВВЕДЕНИЕ: ПОЧЕМУ API — ЭТО СЕРДЦЕ СОВРЕМЕННОЙ CRM

Современная CRM-система не может существовать в вакууме. Она должна обмениваться

данными с десятками других инструментов: формами захвата лидов на сайте,

IP-телефонией, мессенджерами, сервисами email-рассылок, системами аналитики

и многими другими. Ручной ввод данных давно стал узким местом, ведущим к ошибкам,

потере времени и срыву сделок.

Именно здесь на сцену выходит API — интерфейс программирования приложений.

API AmoCRM позволяет:

1. Автоматизировать создание сущностей: Лиды, контакты и компании могут

   создаваться автоматически при отправке формы на сайте.

2. Синхронизировать данные: Подтягивать информацию из внешних систем или,

   наоборот, выгружать данные из CRM в корпоративное хранилище.

3. Реализовать сложную бизнес-логику: Например, при изменении статуса сделки

   автоматически создавать задачу, отправлять письмо клиенту или уведомление

   в Telegram менеджеру.

Понимание API AmoCRM открывает безграничные возможности для кастомизации и

автоматизации, превращая CRM из простого "справочника клиентов" в полноценную

операционную систему бизнеса.

ЧАСТЬ 1: НАВИГАЦИЯ В ЛАБИРИНТЕ — ГДЕ НАЙТИ API В AMOCRM

Первый и самый важный шаг для любого разработчика — найти в интерфейсе AmoCRM

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

от того, для какой цели создается интеграция: для внутренней (для своего аккаунта)

или для публичной (для продажи другим пользователям).

1.1. Устаревший, но простой метод: API-ключи (Legacy)

ВАЖНОЕ ПРЕДУПРЕЖДЕНИЕ: С 2020 года AmoCRM официально прекратила поддержку

API-ключей для новых публичных интеграций и ограничила их использование.

В интерфейсе новых аккаунтов вы можете не найти этот раздел. Однако старые

аккаунты или внутренние интеграции (используемые только внутри одного аккаунта)

могут продолжать его поддерживать.

ГДЕ ИСКАТЬ:

1. Войдите в ваш аккаунт AmoCRM под административной учетной записью.

2. Перейдите в раздел "Настройки" (значок шестеренки в правом верхнем углу).

3. В левом меню найдите раздел "API и вебхуки" или "Интеграции".

4. Внутри этого раздела будет вкладка или блок "API-ключи".

5. Нажмите "Добавить ключ", укажите название (например, "Интеграция с сайтом")

   и скопируйте сгенерированный ключ.

ЧТО НУЖНО ДЛЯ ЗАПРОСА:

- Поддомен (SUBDOMAIN): Часть вашего адреса "ваш_поддомен.amocrm.ru"

- API-ключ: Полученная строка символов

- Логин: Email администратора аккаунта

НЕДОСТАТКИ:

- Нет безопасного механизма ограничения прав (ключ дает почти полный доступ)

- Не подходит для создания приложений в маркетплейсе AmoCRM

1.2. Современный стандарт: OAuth 2.0 и создание интеграции

Начиная с 2020 года, AmoCRM требует использования протокола OAuth 2.0 для всех

новых внешних интеграций. Это более сложный, но и несравнимо более безопасный

протокол, использующий токены. Более того, API v4, представленный в последние

годы, полностью ориентирован на OAuth 2.0.

ГДЕ СОЗДАВАТЬ ИНТЕГРАЦИЮ:

1. Перейдите в "Настройки" -> "Интеграции"

2. Нажмите на кнопку "Создать интеграцию"

3. Вам будет предложено заполнить карточку приложения:

   - Название: Отображаемое имя вашего приложения

   - Описание: Что делает ваша интеграция

   - Redirect URI: Адрес, на который AmoCRM вернет код авторизации после того,

     как пользователь разрешит доступ. Для локальной разработки это может быть

     "https://ваш_сайт.com/oauth/callback" или даже "http://localhost:3000/callback"

4. После сохранения вы получите два критически важных параметра:

   - Client ID: Публичный идентификатор вашего приложения

   - Client Secret: Секретный ключ приложения (НИКОГДА не публикуйте его

     в клиентском коде!)

СХЕМА РАБОТЫ OAuth 2.0:

1. Вы ведете пользователя по ссылке авторизации, содержащей ваш Client ID.

2. Пользователь видит экран запроса прав и нажимает "Разрешить".

3. AmoCRM перенаправляет пользователя на ваш Redirect URI, передавая в параметрах

   "code" (временный код).

4. Ваш сервер обменивает этот "code" на "access_token" и "refresh_token",

   отправив POST-запрос с вашим Client Secret.

ВАЖНО: Access Token живет ограниченное время (обычно около суток).

Refresh Token нужен для его автоматического обновления без участия пользователя.

1.3. Различие между аккаунтами: AmoCRM vs Kommo

Стоит упомянуть, что в 2022-2023 годах международная версия продукта была

переименована в Kommo. С точки зрения API для разработчика почти ничего не

изменилось (изменились только URL документации и брендинг). Если вы работаете

с клиентами за пределами СНГ, вы можете встретить упоминания "Kommo API v4",

но технически это та же платформа.

ЧАСТЬ 2: ВЫБОР ИНСТРУМЕНТА — КАКОЙ ВЕРСИЕЙ API ПОЛЬЗОВАТЬСЯ

AmoCRM прошла долгий путь эволюции, и в настоящий момент разработчики имеют

дело с двумя основными версиями API: классической v2 и современной v4.

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

2.1. Сравнительный анализ: API v2 vs API v4

ХАРАКТЕРИСТИКА          | API v2                         | API v4

-------------------------------------------------------------------------------

Эндпоинты               | /api/v2/...                    | /api/v4/...

Авторизация             | API-ключи (Legacy) и OAuth 2.0 | Только OAuth 2.0

Формат данных           | Разрозненный                   | Унифицированный REST

Пагинация               | LIMIT/OFFSET                   | Параметры page/limit

Поддержка               | Прекращается                   | Активно развивается


РЕКОМЕНДАЦИЯ: Для ВСЕХ НОВЫХ ПРОЕКТОВ используйте API v4. Это требование

времени и залог совместимости с будущими обновлениями платформы. Использовать

v2 стоит только в двух случаях:

1. Вы поддерживаете легаси-интеграцию, написанную много лет назад.

2. Вам нужна специфическая функция, которая еще не перенесена в v4 (такое

   случается редко, например, с некоторыми методами работы с "Неразобранным"

   или старыми отчетами).

2.2. Языки и SDK: ускоряем разработку

Писать "голые" HTTP-запросы к API, конечно, можно, но это чревато рутиной:

формирование заголовков "Authorization: Bearer ...", обработка ошибок,

сериализация JSON. Гораздо эффективнее использовать официальные или популярные

community SDK (Software Development Kit).

PHP (самый популярный стек для AmoCRM):

- Официальный SDK от AmoCRM: Разработан самой компанией, но долгое время был

  в статусе "бета". Хорош для простых операций.

- andrey-tech/amocrm-api-php: Мощная обертка для v2/v4 с поддержкой OAuth,

  троттлингом (контролем частоты запросов) и блокировками для избежания

  конфликтов при одновременном обновлении одной сущности.

- dedomorozoff/kommo-api-php: Форк предыдущей библиотеки с акцентом на поддержку

  англоязычной версии Kommo.

Go (для высоконагруженных систем):

- chudno/amo_crm_sdk: Полноценный SDK на Go, покрывающий практически все

  сущности v4, поддерживающий контексты (context.Context) и долгоживущие токены.

JavaScript/Node.js:

- Официального SDK от AmoCRM нет, но community-решения активно развиваются.

  Можно использовать axios или node-fetch с готовыми сниппетами запросов.

ПРИМЕР ИСПОЛЬЗОВАНИЯ PHP ОБЕРТКИ (упрощенно):

// Установка: composer require andrey-tech/amocrm-api-php

$apiClient = new \AmoCRM\ApiClient(new \AmoCRM\OAuth2\OAuth2Config(

    'ваш_client_id',

    'ваш_client_secret',

    'ваш_redirect_uri'

));

// Устанавливаем токен и домен

$apiClient->setAccessToken($savedAccessToken);

$apiClient->setAccountDomain($subdomain);


// Получаем список сделок с фильтром

$leadsService = new \AmoCRM\Lead\Lead($apiClient);

$leads = $leadsService->get(['status' => 142]); // ID статуса "Успешно реализовано"

ЧАСТЬ 3: ГЛУБОКОЕ ПОГРУЖЕНИЕ — КЛЮЧЕВЫЕ СУЩНОСТИ И МЕТОДЫ API

API AmoCRM построен вокруг бизнес-сущностей. Понимание иерархии и связей между

ними — основа успешной интеграции.

3.1. Основные сущности ("Святая Троица" и не только)

СДЕЛКИ (Leads)

Центральная сущность, отражающая потенциальный доход. Сделка всегда находится

в воронке и имеет статус (этап). Через API можно:

- Создавать сделки с привязкой к контакту и компании (включая комплексное

  создание за один запрос — addComplex)

- Менять статус, бюджет, ответственного

- Добавлять товары в сделку (через каталоги)

КОНТАКТЫ (Contacts)

Хранят информацию о физических лицах: имя, телефоны, email, должность. Контакты

могут быть связаны со сделками и компаниями. API позволяет искать контакты по

любому полю, что критично для избежания дублей.

КОМПАНИИ (Companies)

Юридические лица или организации. Компания объединяет несколько контактов

и сделок.

ЗАДАЧИ (Tasks)

Инструмент контроля. Через API можно создавать задачи для менеджера с дедлайном

"на сегодня", "на завтра" или конкретную дату.

ПРИМЕЧАНИЯ (Notes)

Любое текстовое взаимодействие, история. Именно сюда интегрируются логи чатов,

тексты звонков, комментарии.

3.2. Пользовательские поля (Custom Fields) — гибкость без границ

Это "суперсила" AmoCRM. Если стандартных полей (Имя, Телефон, Бюджет) недостаточно —

создаются кастомные поля.

ТИПЫ ПОЛЕЙ:

- Текст

- Число

- Список (select)

- Мультисписок (multiselect)

- Дата

- Дата/Время

- Адрес

- Файл

- Радиокнопка


РАБОТА ЧЕРЕЗ API: При создании сделки вы должны передать не просто "Значение",

а массив с field_id и значением.

ПРИМЕР ЗАПРОСА К V4 ДЛЯ СДЕЛКИ С КАСТОМНЫМ ПОЛЕМ "Тип оплаты":


POST /api/v4/leads

{

  "name": "Заказ робота-пылесоса",

  "price": 25000,

  "status_id": 123456,

  "custom_fields_values": [

    {

      "field_id": 987654,

      "values": [

        { "value": "Банковская карта онлайн" }

      ]

    }

  ]

}

3.3. Звонки и телефония — отдельный пласт интеграции

API AmoCRM имеет специальные эндпоинты для интеграции с IP-телефонией.

Это позволяет:

- Фиксировать звонки: Создавать сущность "Звонок" с длительностью, ссылкой на

  запись разговора, направлением (входящий/исходящий).

- Привязывать к сущностям: Автоматически подтягивать карточку клиента при звонке

  с неизвестного номера (поиск контакта по телефону).

- Фиксировать результат: Статус звонка (дозвонился, не дозвонился, занято,

  договорился о звонке).

КОНСТАНТЫ СТАТУСОВ ЗВОНКОВ:

1 - оставил сообщение

2 - удачный звонок, нужен перезвон

4 - удачный разговор

6 - не дозвонился

7 - занято

ЧАСТЬ 4: ДИНАМИЧЕСКАЯ МАРШРУТИЗАЦИЯ ДАННЫХ — INCOMING И OUTGOING ВЕБХУКИ

API — это прекрасно, но как узнать, что в CRM произошло событие (например, статус

сделки сменился на "Оплата получена"), не дергая сервер каждую секунду?

Для этого существуют ВЕБХУКИ (Webhooks).

4.1. Incoming вебхуки (Исходящие из CRM)

При наступлении события AmoCRM отправляет HTTP POST запрос (обычно с JSON телом)

на указанный вами URL.

ГДЕ НАСТРАИВАТЬ:

"Настройки" -> "API и вебхуки" -> "Вебхуки" (или вкладка Webhooks)

ТИПИЧНЫЕ СОБЫТИЯ:

- add_lead — создана сделка

- update_lead — изменена сделка (важно для трекинга изменений статусов)

- add_contact / update_contact

- add_task / complete_task — задача создана / завершена

АРХИТЕКТУРНЫЙ ПАТТЕРН ДЛЯ ВЕБХУКОВ:

1. Ваш эндпоинт получает вебхук (например, POST /webhook/amocrm)

2. ВАЛИДАЦИЯ: Проверить, что запрос пришел действительно от AmoCRM (проверка IP

   или цифровой подписи заголовка User-Agent и Content-HMAC)

3. АСИНХРОННАЯ ОБРАБОТКА: Поскольку AmoCRM не будет ждать ответа долго (около

   5-10 секунд), получив вебхук, сразу возвращайте HTTP 200 OK, а задачу ставьте

   в очередь (RabbitMQ, Redis, базу данных)

4. ОБРАБОТКА: Медленный воркер забирает задачу из очереди, делает сложные

   запросы к API (который может тормозить) и выполняет бизнес-логику

4.2. Outgoing вебхуки (Исходящие от вас)

Это скорее возможность AmoCRM дергать ваши сервисы. Но вы также можете настроить

"Исходящие вебхуки", чтобы уведомлять AmoCRM о событиях из внешнего мира,

используя их API для массового обновления сущностей.

ЧАСТЬ 5: ПРАКТИКУМ — РЕАЛЬНЫЕ СЦЕНАРИИ ИНТЕГРАЦИИ


Рассмотрим несколько практических задач, которые решает API.

Сценарий 1: Форма на сайте "Заказать звонок"

ЗАДАЧА: Пользователь заполняет форму (Имя + Телефон). Нужно создать сделку

с низким бюджетом и назначить задачу менеджеру "Позвонить в течение 5 минут".

АЛГОРИТМ:

1. Бэкенд сайта принимает POST форму.

2. Ищет контакт по номеру телефона через GET /api/v4/contacts?query={phone}

3. Если контакт найден — берем его ID. Если нет — создаем новый контакт.

4. Создаем сделку POST /api/v4/leads с именем "Заявка с сайта", статус

   "Первичный контакт".

5. Привязываем сделку к контакту: POST /api/v4/leads/{id}/link, передав

   to_entity_id и to_entity_type = 'contacts'.

6. Создаем задачу POST /api/v4/tasks. В text пишем "Перезвонить клиенту, заявка

   с сайта". В complete_till передаем timestamp (текущее время + 5 минут).

   Указываем responsible_user_id = ID дежурного менеджера.

7. Возвращаем клиенту сайта: "Скоро вам перезвонят".

Сценарий 2: Интеграция с телефонией (на примере простой логики)

ЗАДАЧА: При пропущенном звонке от нового номера автоматически создавать контакт

и задачу на звонок.

АЛГОРИТМ (принимаем вебхук от телефонии):


1. Телефония в реальном времени шлет вебхук на ваш сервер:

   {"phone":"+79991234567", "status": "missed", "duration": 0}

2. Ваш сервер ищет контакт по +79991234567

3. Если не найден — создает контакт с именем "Новый лид с телефона" и этим номером

4. Находит воронку по умолчанию и создает сделку "Перезвон после пропущенного"

5. Создает задачу для ответственного менеджера с текстом "Пропущенный звонок

   от {User}, перезвоните!"


-------------------------------------------------------------------------------

Сценарий 3: Экспорт данных для аналитики в PowerBI или Data Studio

-------------------------------------------------------------------------------


ЗАДАЧА: Каждую ночь выгружать все закрытые сделки за последний месяц с их полями.


АЛГОРИТМ:


1. Запускаем PHP-скрипт по Cron или через планировщик задач Jenkins.

2. Получаем OAuth-токен (обновляем, если истек).

3. Делаем запрос к GET /api/v4/leads с фильтрами:

   - filter[statuses][0][pipeline_id]=[ID_ВОРОНКИ]

   - filter[statuses][0][status_id]=[ID_СТАТУСА_УСПЕХ]

   - filter[closed_at][from]=[timestamp_начала_месяца]

   - filter[closed_at][to]=[timestamp_конца_месяца]

   - Используем пагинацию limit=250 и page=1,2,3..., пока ответ не станет пустым

4. Параллельно подгружаем контакты к сделкам, используя with=contacts

5. Трансформируем JSON в CSV файл

6. Отправляем CSV на FTP-сервер или заливаем в Google Drive для дальнейшей

   загрузки в BI-систему


================================================================================

ЧАСТЬ 6: ПРОДВИНУТЫЕ ТЕХНИКИ И ОПТИМИЗАЦИЯ

================================================================================


-------------------------------------------------------------------------------

6.1. Контроль дублей (Duplication Control)

-------------------------------------------------------------------------------


AmoCRM позволяет избежать создания дублей контактов и компаний при массовом

импорте. Для этого нужно использовать специальный заголовок или параметр запроса.


Для API v4 при добавлении контакта можно использовать эндпоинт с управлением дублями:

- Позволяет задать критерии уникальности (например, по email или телефону)

- Если контакт найден — вы получите его существующий ID, а не ошибку


-------------------------------------------------------------------------------

6.2. Троттлинг и ограничения (Rate Limits)

-------------------------------------------------------------------------------


AmoCRM не дает бесконечно долбить свой сервер. Существуют ограничения:


- Общие лимиты: Количество запросов в минуту (обычно около 5-10 запросов в секунду)

- Обработка ошибки 429 Too Many Requests: Если вы превысили лимит, API вернет

  этот код. В ответе будет заголовок Retry-After (количество секунд, которое

  нужно подождать). Хорошая библиотека (например, andrey-tech/amocrm-api-php)

  умеет делать "троттлинг" автоматически, выдерживая паузу.


-------------------------------------------------------------------------------

6.3. Асинхронная работа с большими данными

-------------------------------------------------------------------------------


Для операций, которые могут выполняться долго (например, массовое обновление

10 000 сделок), не стоит делать синхронный запрос. Используйте АСИНХРОННЫЕ МЕТОДЫ API:


- Вы отправляете запрос на запуск операции

- AmoCRM возвращает ID задачи

- Вы периодически опрашиваете статус задачи

- Когда статус = "Готово", вы забираете результат


-------------------------------------------------------------------------------

6.4. Карта путей (Routing) — относительные ссылки

-------------------------------------------------------------------------------


API v4 придерживается принципов HATEOAS. В ответе на создание сущности вы часто

получаете не только ID, но и ссылку в заголовке Location или внутри тела ответа

(_links.self.href). Всегда старайтесь использовать эти ссылки, а не собирать

URL вручную — это сделает ваш код более устойчивым к изменениям.

ЧАСТЬ 7: БЕЗОПАСНОСТЬ И ЛУЧШИЕ ПРАКТИКИ

1. НИКОГДА не храните Client Secret в клиентской части (JavaScript в браузере,

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

   Implicit Flow (если AmoCRM его поддерживает) или организуйте свой бэкенд-прокси.


2. Используйте переменные окружения (.env). Жесткое кодирование CLIENT_ID и

   CLIENT_SECRET в коде — это прямой путь к утечке данных, если вы когда-нибудь

   случайно закоммитите файл в публичный репозиторий Git.


3. Храните токены в зашифрованном виде. Если вы пишете приложение для множества

   аккаунтов, токен доступа — это ключ к чужим данным. База данных с токенами

   должна быть надежно изолирована.


4. Минимизируйте объем данных в вебхуках. Не передавайте тяжелый JSON, если вам

   нужно только уведомление "Статус изменился". Лучше в обработчике вебхука

   сходить за актуальными данными через API.


5. Логируйте ошибки. Интеграция сломается. Без логов вы не поймете, что пошло

   не так: истек токен, изменилась структура кастомного поля, закончились лимиты

   запросов. Логируйте request и response (обрезая чувствительные данные).

AmoCRM API — это мощный, современный интерфейс (особенно версии 4), который

позволяет создавать практически любую автоматизацию, которую только можно

вообразить в рамках CRM-системы. От простого экспорта контактов до сложных

двухсторонних синхронизаций с ERP и телефонией.


РЕЗЮМЕ И ОТВЕТЫ НА ГЛАВНЫЕ ВОПРОСЫ СТАТЬИ:


1. ГДЕ НАЙТИ API В CRM?

   В разделе "Настройки" -> "Интеграции". Для OAuth создаем приложение,

   получаем ID и Secret. Для внутренних нужд (но это Legacy) ищем API-ключи.


2. КАКИМ API ПОЛЬЗОВАТЬСЯ?

   Однозначно V4. Это будущее платформы. V2 используйте только для поддержки

   старого кода.


3. ЧТО МОЖНО ПЕРЕДАТЬ?

   Практически все: сделки, контакты, компании, задачи, примечания, звонки,

   файлы, кастомные поля, товары из каталогов, теги.


Начните с малого: возьмите официальную документацию (английскую, т.к. русская

по v4 может устаревать), установите SDK для вашего языка программирования и

попробуйте выполнить авторизацию OAuth 2.0. Как только вы получите первый

access_token, весь мир автоматизации продаж станет для вас открытой книгой.

Успешных интеграций!

Официальная документация AmoCRM API v4 (англ.):

https://www.amocrm.com/developers/

Официальная документация Kommo API v4:

https://www.kommo.com/developers/

PHP SDK (andrey-tech):

https://github.com/andrey-tech/amocrm-api-php

Go SDK (chudno):

https://github.com/chudno/amo_crm_sdk

Сообщество разработчиков на Habr Q&A и ToSTER:

Разделы "API интеграции" и "AmoCRM"