# Битрикс24 REST API: Перевести сделку на стадию и поставить задачу менеджеру

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

Когда в твоей системе что-то произошло (оплата, отгрузка), сдвинуть сделку и напомнить ответственному.

1. Узнай коды стадий: crm.item.fields с entityTypeId = 2 покажет поля, а список стадий воронки виден в настройках CRM (например, NEW, PREPARATION, WON или C1:NEW для дополнительной воронки).
2. Переведи сделку: crm.item.update с entityTypeId = 2, id сделки и fields.stageId. Если значения не изменились, сохранения не будет; после сохранения запускаются роботы стадии.
3. Поставь задачу: tasks.task.add с TITLE и RESPONSIBLE_ID (обычно assignedById сделки). Чтобы задача была видна в карточке сделки, передай UF_CRM_TASK = ["D_<id сделки>"]. Для вебхука нужен скоуп task.

```bash
curl -X POST "$HOOK/crm.item.update.json" \
  -H 'Content-Type: application/json' \
  -d '{"entityTypeId": 2, "id": 342, "fields": {"stageId": "PREPARATION"}}'

curl -X POST "$HOOK/tasks.task.add.json" \
  -H 'Content-Type: application/json' \
  -d '{
        "fields": {
          "TITLE": "Позвонить клиенту: оплата получена",
          "RESPONSIBLE_ID": 6,
          "DEADLINE": "2026-11-01T18:00:00+03:00",
          "UF_CRM_TASK": ["D_342"]
        }
      }'
```

## Базовые 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.update — Изменить элемент

Если значения полей не изменились, сохранение не выполняется. После сохранения запускаются роботы.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `entityTypeId` | body | integer | да | Тип объекта CRM |
| `id` | body | integer | да | ID элемента |
| `fields` | body | object | да | Новые значения полей |
| `useOriginalUfNames` | body | boolean | нет | Формат имён пользовательских полей |

### crm.item.fields — Поля элемента CRM

Список полей и их настроек (тип, обязательность, только чтение, множественность) для типа объекта.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `entityTypeId` | body | integer | да | Тип объекта CRM |
| `useOriginalUfNames` | body | boolean | нет | Формат имён пользовательских полей |

### tasks.task.add — Создать задачу

Скоуп `task`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `fields` | body | object | да | Поля задачи; обязательны TITLE (название) и RESPONSIBLE_ID (ответственный) |

## Нюансы

- Методы `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/sozdat-sdelku-s-kontaktom-iz-zayavki.md)
- [Выгрузить все сделки на нужной стадии](https://mcp-everything.ru/integrations/bitrix24/scenarios/vygruzit-vse-sdelki-na-nuzhnoy-stadii.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