Битрикс24 REST API 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-статусу.
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 — подожди и повтори.
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.
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.
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.
# Вызов от имени приложения: токен передаётся в параметре 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

Авторизация

Тип: Другое

Два способа:

Без данных авторизации запрос отклоняется с ошибкой 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 элемента

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

{
    "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 нет Доп. настройки события

Нюансы

Ошибки

Код Описание
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 не отвечает

Ограничения

Источники

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