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

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

Забрать сделки в отчёт или учётную систему с контактами.

Узнай id воронки и этапов (в настройках воронки или в данных существующих сделок: pipeline_id, status_id). У всех воронок общие системные этапы: 142 — «Успешно реализовано», 143 — «Закрыто и не реализовано».
Запроси список: GET /api/v4/leads с filter[statuses][0][pipeline_id] и filter[statuses][0][status_id], limit = 250 и with = contacts, чтобы сразу получить привязанные контакты.
Листай страницы через page, пока в _links есть next.
Для выгрузки изменений с прошлого раза добавь filter[updated_at][from] с Unix-временем последней выгрузки и сортировку order[updated_at] = asc.

curl -G "https://<поддомен>.amocrm.ru/api/v4/leads" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -d 'filter[statuses][0][pipeline_id]=3383152' \
  -d 'filter[statuses][0][status_id]=142' \
  -d 'with=contacts' \
  -d 'limit=250' \
  -d 'page=1'

Базовые 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"
}

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

GET /api/v4/leads — Список сделок

Пример ответа (сокращён):

Параметр	Где	Тип	Обяз.	Описание
`with`	query	string	нет	Доп. данные через запятую: catalog_elements, is_price_modified_by_robot, loss_reason, contacts, only_deleted, source_id, source
`page`	query	int	нет	Номер страницы
`limit`	query	int	нет	Записей на страницу, максимум 250
`query`	query	string	нет	Поиск по заполненным полям сделки
`filter`	query	object	нет	Фильтр
`order`	query	object	нет	Сортировка по created_at, updated_at или id: asc/desc, например order[updated_at]=asc

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

{
    "_page": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=2"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=3"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 19619,
                "name": "Сделка для примера",
                "price": 46333,
                "status_id": 142,
                "pipeline_id": 1300,
                "is_deleted": false,
                "account_id": 5135160
            }
        ]
    }
}

Нюансы

Создание и изменение — пакетное: тело запроса всегда массив, даже для одной сущности.
Успешные ответы приходят с 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