amoCRM API v4: POST /api/v4/leads — Добавление сделок

Тело — массив сделок; обязательных полей нет.

Параметр	Где	Тип	Обяз.	Описание
name	body	string	нет	Название сделки
price	body	int	нет	Бюджет
status_id	body	int	нет	Этап; по умолчанию первый этап главной воронки
pipeline_id	body	int	нет	Воронка
created_by	body	int	нет	Создатель; 0 — робот
updated_by	body	int	нет	Изменивший; 0 — робот
closed_at	body	int	нет	Дата закрытия (Unix Timestamp)
created_at	body	int	нет	Дата создания (Unix Timestamp)
updated_at	body	int	нет	Дата изменения (Unix Timestamp)
loss_reason_id	body	int	нет	Причина отказа
responsible_user_id	body	int	нет	Ответственный
custom_fields_values	body	array	нет	Значения дополнительных полей
tags_to_add	body	array	нет	Теги для добавления: id или name
_embedded[tags]	body	array	нет	Привязываемые теги
_embedded[contacts][0][id]	body	int	нет	Привязываемый контакт
_embedded[contacts][0][is_main]	body	string	нет	Главный контакт
_embedded[companies][0][id]	body	int	нет	Привязываемая компания
_embedded[source][external_id]	body	string	нет	Внешний ID источника
_embedded[source][type]	body	string	нет	Тип источника; для интеграций — widget

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

[
    {
        "name": "Сделка для примера 1",
        "created_by": 0,
        "price": 20000,
        "custom_fields_values": [
            {
                "field_id": 294471,
                "values": [
                    {
                        "value": "Наш первый клиент"
                    }
                ]
            }
        ],
        "tags_to_add": [
            {
                "name": "Первый тег"
            }
        ]
    }
]

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 10185151,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/10185151"
                    }
                }
            }
        ]
    }
}

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

Нюансы

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