# amoCRM API v4: Создать сделку с контактом из заявки на сайте

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

Одним запросом создать сделку, контакт и компанию из формы на сайте. Если в аккаунте включён контроль дублей, amoCRM сам склеит повторную заявку.

1. Получи токен: для одной своей CRM проще всего долгосрочный токен из настроек приватной интеграции (вкладка «Ключи»), для тиражной интеграции — OAuth, см. сценарий про токены.
2. Отправь заявку: POST /api/v4/leads/complex. Тело — массив (даже из одной сделки): name, price, pipeline_id и status_id, а в _embedded — новый контакт с телефоном и email. Телефон и email передаются в custom_fields_values с field_code PHONE и EMAIL.
3. В ответе для каждой сделки придут id, contact_id и company_id, а merged = true — если сработал контроль дублей.
4. В одном запросе — до 50 сделок, на сделку — 1 контакт и 1 компания. Чтобы заявка попала в «Неразобранное», передай _embedded.metadata с category = forms.

```bash
curl -X POST "https://<поддомен>.amocrm.ru/api/v4/leads/complex" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[{
        "name": "Заявка с сайта: кухня на заказ",
        "price": 150000,
        "_embedded": {
          "contacts": [{
            "first_name": "Екатерина",
            "custom_fields_values": [
              {"field_code": "PHONE", "values": [{"value": "+79990001122", "enum_code": "WORK"}]},
              {"field_code": "EMAIL", "values": [{"value": "kate@example.ru", "enum_code": "WORK"}]}
            ]
          }]
        },
        "request_id": "form-1042"
      }]'
```

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

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

### POST /api/v4/leads/complex — Комплексное добавление сделок с контактом и компанией

Создаёт сделки сразу с контактом и компанией; при включённом контроле дублей применяет его. На сделку — 1 контакт и 1 компания, до 40 доп. полей на сущность, до 50 сделок в запросе.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `name` | body | string | нет | Название сделки |
| `price` | body | int | нет | Бюджет |
| `status_id` | body | int | нет | Этап |
| `pipeline_id` | body | int | нет | Воронка |
| `request_id` | body | string | нет | Идентификатор запроса, возвращается в ответе |
| `_embedded[contacts][0]` | body | object | нет | Существующий контакт (id) или модель нового |
| `_embedded[companies][0]` | body | object | нет | Существующая компания (id) или модель новой |
| `_embedded[metadata]` | body | array | нет | Метаданные для создания неразобранного; статус тогда игнорируется |
| `_embedded[metadata][category]` | body | string | нет | Категория неразобранного: sip или forms |

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

```
[
   {
      "name": "Название сделки",
      "price": 3422,
      "_embedded": {
         "contacts": [
            {
               "first_name": "Екатерина",
               "responsible_user_id": 2004184
            }
         ],
         "companies": [
            {
               "name": "ООО Рога и Копыта"
            }
         ]
      },
      "status_id": 33929752,
      "pipeline_id": 3383152,
      "request_id": "qweasd"
   }
]
```

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

```json
[
   {
      "id": 15198335,
      "contact_id": 19663157,
      "company_id": 19663155,
      "request_id": [
         "qweasd"
      ],
      "merged": false
   }
]
```

## Нюансы

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

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

- [Получить токены OAuth и не потерять доступ](https://mcp-everything.ru/integrations/amocrm/scenarios/poluchit-tokeny-oauth-i-ne-poteryat.md)
- [Найти контакт по телефону, чтобы не создавать дубли](https://mcp-everything.ru/integrations/amocrm/scenarios/nayti-kontakt-po-telefonu-chtoby.md)
- [Выгрузить сделки воронки по этапу](https://mcp-everything.ru/integrations/amocrm/scenarios/vygruzit-sdelki-voronki-po-etapu.md)
- [Перевести сделку на этап или закрыть её](https://mcp-everything.ru/integrations/amocrm/scenarios/perevesti-sdelku-na-etap-ili-zakryt-ee.md)

---

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