---
slug: "bitrix24"
name: "Битрикс24 REST API"
vendor: "Битрикс24"
industry: "crm"
docsUrl: "https://apidocs.bitrix24.ru/"
version: 2
updatedAt: "2026-10-24"
---

# Битрикс24 REST API

Отрасль: CRM и продажи. Актуально на 2026-10-24.

REST API облачного и коробочного Битрикс24: CRM (лиды, сделки, контакты, компании, смарт-процессы), задачи, пользователи, события и многое другое. Методы вызываются HTTP-запросом к адресу конкретного портала и выполняются от имени пользователя с его правами. Для CRM основной набор — универсальные методы `crm.item.*`, которые работают с любым типом объекта через `entityTypeId`.

## Сценарии

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

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

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]"
        }
      }'
```

### Выгрузить все сделки на нужной стадии

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

1. Запроси список: crm.item.list с entityTypeId = 2, filter (например, по stageId или по дате изменения) и select с нужными полями — так ответ будет легче.
2. Страница всегда содержит 50 записей. Следующую получай с параметром start = 50, 100 и так далее, пока в ответе есть next.
3. Для больших выгрузок собирай до 50 вызовов crm.item.list с разными start в один batch — это в десятки раз быстрее отдельных запросов.
4. Учитывай лимит частоты: на обычных тарифах — примерно 2 запроса в секунду. При превышении приходит HTTP 503 с QUERY_LIMIT_EXCEEDED — подожди и повтори.

```bash
curl -X POST "$HOOK/crm.item.list.json" \
  -H 'Content-Type: application/json' \
  -d '{
        "entityTypeId": 2,
        "select": ["id", "title", "stageId", "opportunity", "currencyId", "contactIds", "updatedTime"],
        "filter": {"stageId": "WON", ">=updatedTime": "2026-01-01T00:00:00+03:00"},
        "order": {"id": "ASC"},
        "start": 0
      }'
```

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

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

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"]
        }
      }'
```

### Заполнить пользовательские поля сделки

У каждого портала свои поля (UF_CRM_…): источник заявки, номер договора, ссылка на заказ. Узнать их имена и записать значения.

1. Получи список полей: crm.item.fields с entityTypeId = 2. Пользовательские поля в crm.item.* называются в camelCase, например ufCrm1700000000; с useOriginalUfNames = Y — как в интерфейсе, UF_CRM_1700000000.
2. Посмотри в ответе тип поля, isRequired и isMultiple: множественное поле принимает массив, список — id варианта, а не текст.
3. Запиши значения: crm.item.update с fields, где ключи — имена полей из шага 1. При создании сделки те же поля передаются в crm.item.add.

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

curl -X POST "$HOOK/crm.item.update.json" \
  -H 'Content-Type: application/json' \
  -d '{"entityTypeId": 2, "id": 342, "fields": {"ufCrm1700000000": "Договор № 15/2026"}}'
```

### Получать уведомления о новых лидах

Реагировать на появление лида в Битрикс24 сразу: отправить приветственное письмо, записать в свою базу.

1. Подписка на события работает только в приложении (OAuth), не во входящем вебхуке — вебхук вернёт WRONG_AUTH_TYPE. Создай локальное приложение на портале.
2. Зарегистрируй обработчик: event.bind с event = ONCRMLEADADD и handler — адрес твоего сервера (с доменом, localhost не принимается).
3. Битрикс24 пришлёт POST-запрос с data[FIELDS][ID] — id нового лида. Проверь application_token из запроса, чтобы отсечь чужие вызовы.
4. Получи сам лид: crm.item.get с entityTypeId = 1 и этим id.
5. access_token приложения живёт час — обновляй его через https://oauth.bitrix.info/oauth/token/ по refresh_token.

```bash
# Вызов от имени приложения: токен передаётся в параметре auth
curl -X POST "https://<портал>.bitrix24.ru/rest/event.bind.json" \
  -H 'Content-Type: application/json' \
  -d '{"auth": "<access_token>", "event": "ONCRMLEADADD", "handler": "https://example.ru/b24/lead-added"}'

curl -X POST "https://<портал>.bitrix24.ru/rest/crm.item.get.json" \
  -H 'Content-Type: application/json' \
  -d '{"auth": "<access_token>", "entityTypeId": 1, "id": 253}'
```

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

### crm.item.get — Получить элемент по ID

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

### crm.item.list — Список элементов

Возвращает только элементы, на которые у пользователя есть право чтения. Размер страницы всегда 50 записей.

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

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `entityTypeId` | body | integer | да | Тип объекта CRM |
| `select` | body | array | нет | Поля для выборки или '*' |
| `filter` | body | object | нет | Фильтр вида {поле: значение}, допускает вложенность и логику |
| `order` | body | object | нет | Сортировка вида {поле: "ASC" \| "DESC"} |
| `start` | body | integer | нет | Смещение для пагинации: 50 — вторая страница |
| `useOriginalUfNames` | body | boolean | нет | Формат имён пользовательских полей |

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

```
{
    "result": {
        "items": [
            {
                "id": 253,
                "assignedById": 6,
                "stageId": "NEW",
                "opportunity": 19000,
                "sourceId": "WEB",
                "title": "Lead #253",
                "name": "Admin",
                "lastName": null,
                "isManualOpportunity": "Y"
            }
        ]
    }
}
```

### crm.item.update — Изменить элемент

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

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

### crm.item.delete — Удалить элемент

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `entityTypeId` | body | integer | да | Тип объекта CRM |
| `id` | body | integer | да | ID элемента |

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

```json
{
    "result": [],
    "time": {
        "start": 1721657688.755373,
        "finish": 1721657689.65017,
        "duration": 0.8947970867156982,
        "processing": 0.6092040538787842,
        "date_start": "2024-07-22T16:14:48+02:00",
        "date_finish": "2024-07-22T16:14:49+02:00",
        "operating": 0
    }
}
```

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

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

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

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

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

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

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

Скоуп `task`.

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

### event.bind — Подписаться на событие

Регистрирует обработчик события (например `ONCRMLEADADD`). Работает только в контексте приложения: через вебхук вернёт `WRONG_AUTH_TYPE`. Bitrix24 отправляет данные события POST-запросом на адрес обработчика.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `event` | body | string | да | Код события, например ONCRMLEADADD |
| `handler` | body | string | да | URL обработчика; хост должен содержать точку, localhost не принимается |
| `auth_type` | body | integer | нет | Пользователь, под которым авторизуется обработчик |
| `event_type` | body | string | нет | online (по умолчанию) или offline |
| `auth_connector` | body | string | нет | Ключ источника для офлайн-событий |
| `options` | body | object | нет | Доп. настройки события |

## Нюансы

- Методы `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 (без доступа к данным портала).

## Ошибки

| Код | Описание |
|---|---|
| `NO_AUTH_FOUND` | В запросе нет ни токена, ни кода вебхука |
| `INVALID_CREDENTIALS` | Не найден активный вебхук с такой парой ID пользователя и кода |
| `INVALID_REQUEST` | Запрос по http — замените на https |
| `QUERY_LIMIT_EXCEEDED` | Превышена интенсивность запросов (HTTP 503) |
| `OPERATION_TIME_LIMIT` | Исчерпан лимит ресурсоёмкости метода; ориентируйтесь на operating_reset_at |
| `OVERLOAD_LIMIT` | Ручная блокировка — повторять бесполезно, нужна техподдержка |
| `ACCESS_DENIED` | Со статусом 401 — нужен коммерческий тариф; с другим статусом — ошибка метода |
| `ERROR_METHOD_NOT_FOUND` | Неверное имя метода или нет нужного скоупа |
| `insufficient_scope` | Добавьте недостающий скоуп приложению или вебхуку |
| `expired_token` | Обновите токены и повторите вызов |
| `user_access_error` | Администратор должен дать пользователю доступ к приложению |
| `WRONG_AUTH_TYPE` | Метод недоступен при этом способе авторизации |
| `INTERNAL_SERVER_ERROR` | Повторите вызов через несколько секунд |
| `PORTAL_DELETED` | Публичная часть сайта закрыта — REST API не отвечает |

## Ограничения

- Облако: один запрос должен выполниться за 60 секунд, иначе прерывается по таймауту.
- Частота запросов — алгоритм Leaky Bucket: Enterprise — счётчик уменьшается на 5 в секунду, блокировка после 250; остальные тарифы — 2 в секунду, блокировка после 50. При превышении — HTTP 503 `QUERY_LIMIT_EXCEEDED`.
- Лимиты считаются отдельно для каждого портала.
- `batch` — до 50 команд в одном запросе.
- Для каждого метода считается накопленное время выполнения (`time.operating`); при превышении — `OPERATION_TIME_LIMIT`.

## Источники

- [Официальная документация REST API (репозиторий)](https://github.com/bitrix24/b24restdocs)
- [Авторизация в REST](https://github.com/bitrix24/b24restdocs/blob/main/settings/how-to-call-rest-api/authorization.md)
- [OAuth 2.0](https://github.com/bitrix24/b24restdocs/blob/main/settings/oauth/index.md)
- [crm.item.add](https://github.com/bitrix24/b24restdocs/blob/main/api-reference/crm/universal/crm-item-add.md)
- [crm.item.list](https://github.com/bitrix24/b24restdocs/blob/main/api-reference/crm/universal/crm-item-list.md)
- [batch](https://github.com/bitrix24/b24restdocs/blob/main/settings/how-to-call-rest-api/batch.md)
- [Коды ошибок](https://github.com/bitrix24/b24restdocs/blob/main/error-codes.md)
- [Лимиты](https://github.com/bitrix24/b24restdocs/blob/main/limits.md)
- [MCP-сервер](https://github.com/bitrix24/b24restdocs/blob/main/ai-tools/mcp.md)

---

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