amoCRM API v4: Перевести сделку на этап или закрыть её

Сценарий из mcp-everything. Актуально на 2026-10-24.

Обновить сделку из своей системы: оплата прошла — «Успешно реализовано», клиент отказался — «Закрыто» с причиной.

Измени сделку: PATCH /api/v4/leads — тело массив объектов, в каждом обязателен id. Для перевода на этап передай status_id (и pipeline_id, если воронка другая).
Чтобы закрыть успешно, передай status_id = 142; неуспешно — 143 и loss_reason_id. Дату закрытия задаёт closed_at в Unix-времени.
Заодно можно поправить бюджет price, ответственного responsible_user_id, добавить или снять теги через tags_to_add и tags_to_delete.
Ошибки валидации приходят в validation-errors с request_id и списком errors: по нему видно, какое поле не прошло.

curl -X PATCH "https://<поддомен>.amocrm.ru/api/v4/leads" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[
        {"id": 54886, "status_id": 142, "price": 46333, "tags_to_add": [{"name": "Оплачено"}]},
        {"id": 54887, "status_id": 143, "loss_reason_id": 7323}
      ]'

Базовые URL

Боевой: https://{subdomain}.amocrm.ru/api/v4/
Авторизация OAuth: https://www.amocrm.ru/oauth

Авторизация

Тип: OAuth 2.0

Два способа:

OAuth 2.0 (authorization code). Пользователь открывает https://www.amocrm.ru/oauth?client_id={Integration ID}&state={state}&mode={popup или post_message}, интеграция получает код (живёт 20 минут) и обменивает его на токены запросом POST /oauth2/access_token к поддомену аккаунта. Refresh token можно использовать только один раз; без использования он истекает через 3 месяца.
Долгосрочный токен — создаётся на вкладке «Ключи» для внешних и приватных интеграций, срок от 1 дня до 5 лет, без refresh token. Повторно посмотреть его нельзя.

Токен передаётся в заголовке Authorization: Bearer {access token}.

Пример запроса токена:

Пример ответа:

{
  "client_id": "xxxx",
  "client_secret": "xxxx",
  "grant_type": "authorization_code",
  "code": "xxxxxxx",
  "redirect_uri": "https://test.test"
}

Методы сценария

PATCH /api/v4/leads — Редактирование сделок

Пакетное изменение; для одной сделки можно отправить модель на /api/v4/leads/{id}.

Параметр	Где	Тип	Обяз.	Описание
`id`	body	int	да	ID изменяемой сделки
`name`	body	string	нет	Название
`price`	body	int	нет	Бюджет
`status_id`	body	int	нет	Этап
`pipeline_id`	body	int	нет	Воронка
`closed_at`	body	int	нет	Дата закрытия
`loss_reason_id`	body	int	нет	Причина отказа
`responsible_user_id`	body	int	нет	Ответственный
`custom_fields_values`	body	array	нет	Доп. поля
`tags_to_add`	body	array	нет	Добавить теги
`tags_to_delete`	body	array	нет	Удалить теги

Пример запроса:

[
    {
        "id": 54886,
        "pipeline_id": 47521,
        "status_id": 143,
        "closed_at": 1589297221,
        "loss_reason_id": 7323,
        "updated_by": 0,
        "tags_to_add": [
            {
                "name": "Второй тег"
            }
        ],
        "tags_to_delete": [
            {
                "name": "Первый тег"
            }
        ]
    }
]

Нюансы

Создание и изменение — пакетное: тело запроса всегда массив, даже для одной сущности.
Успешные ответы приходят с Content-Type: application/hal+json, ошибки — application/problem+json; в запросах с телом указывайте Content-Type: application/json.
Запрос несуществующей сущности по ID возвращает 204 без тела, а не 404.
Refresh token одноразовый: после обновления сохраняйте новый, иначе доступ придётся получать заново.
Ошибки валидации возвращаются массивом validation-errors с request_id и списком errors (code, path, detail).
После окончания подписки запросы на добавление и изменение сразу отклоняются с 402, доступ к данным закрывается через 30 дней.
Повторные превышения лимита приводят к блокировке аккаунта: все запросы получают 403.

Другие сценарии

Если этого недостаточно — официальная документация: https://www.amocrm.ru/developers/content/crm_platform/api-reference Вся интеграция одним документом: https://mcp-everything.ru/integrations/amocrm.md