# Битрикс24 REST API: Создать сделку с контактом из заявки на сайте

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

Заявка с сайта превращается в контакт и сделку, привязанную к нему, — менеджер сразу видит её в воронке.

1. Создай входящий вебхук в Битрикс24 (Разработчикам → Другое → Входящий вебхук) со скоупом crm. Адрес вида https://<портал>.bitrix24.ru/rest/<id пользователя>/<код>/ — это пароль, храни его только на сервере.
2. Создай контакт: crm.item.add с entityTypeId = 3 и полями name, lastName, phone, email. Запомни id из result.item.
3. Создай сделку: crm.item.add с entityTypeId = 2, title, opportunity, currencyId и contactIds = [id контакта]. stageId и categoryId задают стадию и воронку; по умолчанию — первая стадия основной воронки.
4. Чтобы сделать оба вызова за один HTTP-запрос, отправь их через batch: результат первой команды подставляется во вторую как $result[contact][item][id].
5. Ошибку проверяй по полям error и error_description в ответе, а не по HTTP-статусу.

```bash
HOOK='https://<портал>.bitrix24.ru/rest/<id пользователя>/<код вебхука>'

# Контакт и сделка одним запросом
curl -X POST "$HOOK/batch.json" \
  -H 'Content-Type: application/json' \
  -d '{
        "halt": 1,
        "cmd": {
          "contact": "crm.item.add?entityTypeId=3&fields[name]=Иван&fields[lastName]=Петров&fields[phone][0][value]=%2B79990001122&fields[phone][0][valueType]=WORK",
          "deal": "crm.item.add?entityTypeId=2&fields[title]=Заявка с сайта&fields[opportunity]=15000&fields[currencyId]=RUB&fields[contactIds][0]=$result[contact][item][id]"
        }
      }'
```

## Базовые URL

- Боевой (входящий вебхук): `https://<ваш-портал>.bitrix24.ru/rest/<id пользователя>/<код вебхука>/<метод>.json`
- Боевой (приложение OAuth 2.0): `https://<ваш-портал>.bitrix24.ru/rest/<метод>.json`
- Сервер авторизации OAuth: `https://oauth.bitrix.info/`

## Авторизация

Тип: Другое

Два способа:

- **Входящий вебхук** — постоянный секретный код в URL запроса вместе с ID пользователя, создавшего вебхук. Метод выполняется с правами этого пользователя и в рамках выбранных в настройках вебхука скоупов. Подходит для интеграции с одним порталом. Код вебхука — это пароль: не публикуйте его и не передавайте в браузерный код.
- **OAuth 2.0** — для локальных и тиражных приложений. Временный `access_token` передаётся в параметре `auth`; живёт один час и обновляется через `https://oauth.bitrix.info/oauth/token/` с помощью `refresh_token`. `client_secret` используется только в запросах к oauth.bitrix.info.

Без данных авторизации запрос отклоняется с ошибкой `NO_AUTH_FOUND`.

```
curl -X POST \
-H "Content-Type: application/json" \
-d '{
	"entityTypeId": 2,
	"fields": {
		"title": "New Deal",
		"typeId": "SALE",
		"stageId": "NEW"
	}
}' \
https://your-domain.bitrix24.com/rest/1/8g9l071eismy9q2l/crm.item.add.json
```

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

### crm.item.add — Создать элемент CRM

Универсальный метод создания лидов, сделок, контактов, компаний и элементов смарт-процессов. Скоуп `crm`. При создании проверяются права и обязательные поля, запускаются роботы.

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

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `entityTypeId` | body | integer | да | Тип объекта CRM |
| `fields` | body | object | да | Поля элемента; набор зависит от типа объекта |
| `fields.title` | body | string | нет | Название; по умолчанию по шаблону {entityTypeName} #{id} |
| `fields.stageId` | body | crm_status | нет | Стадия, например NEW |
| `fields.categoryId` | body | integer | нет | Воронка (для сделок), по умолчанию 0 |
| `fields.typeId` | body | crm_status | нет | Тип, например SALE для сделки |
| `fields.opportunity` | body | double | нет | Сумма |
| `fields.currencyId` | body | crm_currency | нет | Валюта |
| `fields.assignedById` | body | user | нет | Ответственный; по умолчанию вызывающий пользователь |
| `fields.companyId` | body | crm_company | нет | Привязанная компания |
| `fields.contactIds` | body | crm_contact[] | нет | Привязанные контакты |
| `fields.sourceId` | body | crm_status | нет | Источник, например CALL |
| `fields.comments` | body | text | нет | Комментарий |
| `useOriginalUfNames` | body | boolean | нет | Y — оригинальные имена пользовательских полей (UF_CRM_...) |

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

```
{
    "result": {
        "item": {
            "id": 342,
            "createdTime": "2024-07-18T14:00:14+02:00",
            "assignedById": 6,
            "categoryId": 9,
            "stageId": "C9:UC_KN8KFI",
            "title": "New deal (specifically for rest method examples)",
            "typeId": "SERVICE",
            "opportunity": 999
        }
    }
}
```

### batch — Пакетный запрос

Выполняет несколько вызовов за один HTTP-запрос — независимых или связанных (результат одного передаётся в следующий). Скоуп `basic`. В одном batch — не больше 50 команд.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `cmd` | body | array | да | Подзапросы: ключ — идентификатор, значение — строка method?parameter=value |
| `halt` | body | boolean | нет | Прерывать последовательность при ошибке |

## Нюансы

- Методы `crm.deal.*`, `crm.lead.*` и аналогичные больше не развиваются; для новых интеграций используйте `crm.item.*`.
- Ошибку распознают по полям ответа, а не по HTTP-статусу: подзапросы `batch` с ошибкой приходят со статусом 200, а поле `error` может быть пустым — тогда причина только в `error_description`.
- В ответе `batch` поле `result.result_error` есть всегда; признак ошибки — непустое содержимое.
- Методы `*.list` отдают по 50 записей; для больших выгрузок используйте пагинацию без подсчёта общего количества и `batch`.
- Некоторые методы (например `placement.bind`, `event.bind`) недоступны вебхуку и возвращают `WRONG_AUTH_TYPE`.
- Несколько приложений с одного сервера к одному порталу делят общий лимит частоты запросов — лимит учитывает IP-адрес источника.
- Запрос по `http` вместо `https` вернёт `INVALID_REQUEST`.
- У Битрикс24 есть MCP-сервер `b24-dev-mcp` для AI-инструментов: он даёт доступ к официальной документации REST API (без доступа к данным портала).

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

- [Выгрузить все сделки на нужной стадии](https://mcp-everything.ru/integrations/bitrix24/scenarios/vygruzit-vse-sdelki-na-nuzhnoy-stadii.md)
- [Перевести сделку на стадию и поставить задачу менеджеру](https://mcp-everything.ru/integrations/bitrix24/scenarios/perevesti-sdelku-na-stadiyu-i-postavit.md)
- [Заполнить пользовательские поля сделки](https://mcp-everything.ru/integrations/bitrix24/scenarios/zapolnit-polzovatelskie-polya-sdelki.md)
- [Получать уведомления о новых лидах](https://mcp-everything.ru/integrations/bitrix24/scenarios/poluchat-uvedomleniya-o-novyh-lidah.md)

---

Если этого недостаточно — официальная документация: https://apidocs.bitrix24.ru/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/bitrix24.md