Методы REST API: что можно и что нельзя
REST API Битрикс24 — это способ связать портал с другими программами: сайтом, учётной системой, мобильным приложением. Программа отправляет запрос к методу — команде API, например «создать сделку». Битрикс24 выполняет действие и возвращает результат.
Но не всё, что можно сделать в интерфейсе, доступно через API. И не всё, что доступно, разрешено конкретному приложению или вебхуку. Понимание методов и ограничений помогает не тратить время на то, что «не работает», и не создавать рисков для данных.
В этой статье — какие методы есть в REST API, что можно и что нельзя, какие ограничения по правам и скоупам, как обходить лимиты. Если нужна разработка интеграции через API — поможем.
Содержание статьи
Что такое метод
Метод — это команда API. Каждый метод выполняет конкретное действие: создать сделку, получить список задач, обновить контакт. Названия методов обычно состоят из модуля и действия: `crm.item.add`, `tasks.task.list`, `user.get` .
Как вызвать
Запрос отправляется по HTTP на адрес Битрикс24. В запросе передаются авторизационные данные и параметры метода. Ответ приходит в формате JSON: данные — в поле `result`, ошибки — в `error` и `error_description` .
Пример вызова через вебхук:
https://ваш-портал.bitrix24.ru/rest/1/код_вебхука/crm.item.add.json
Для методов с параметрами используется POST с JSON-телом. Для простых запросов можно использовать GET.
Что можно
REST API покрывает большинство модулей Битрикс24. Вот основные группы методов.
| Модуль | Что можно делать | Примеры методов |
|---|---|---|
| CRM | Создавать, читать, обновлять, удалять лиды, сделки, контакты, компании, счета, смарт-процессы | crm.item.add, crm.deal.list, crm.contact.update |
| Задачи | Создавать, читать, обновлять задачи, управлять проектами | tasks.task.add, tasks.task.list, tasks.task.update |
| Пользователи | Получать данные сотрудников, искать по отделам | user.get, user.search |
| Структура компании | Работа с отделами и командами (REST 3.0) | humanresources.node.list, humanresources.node.add |
| Диск | Загружать и скачивать файлы | disk.file.upload, disk.file.get |
| Календарь | Создавать и читать события | calendar.event.add, calendar.event.list |
Это не полный список. Документация описывает сотни методов. Если метода нет — возможно, действие пока не поддерживается через API или требует контекста приложения.
Что нельзя
Не всё, что доступно в интерфейсе, можно сделать через API. Вот основные ограничения.
1. Методы, требующие контекста приложения
Некоторые методы недоступны через вебхук. Например, встраивание виджетов (placement.bind), часть методов телефонии, некоторые сценарии чат-ботов. Они требуют контекста приложения.
2. Действия, не описанные в API
Если метода нет в документации — действие, скорее всего, не поддерживается. Например, некоторые операции с бизнес-процессами или настройками портала.
3. Данные вне прав пользователя
Метод выполняется от имени конкретного сотрудника. Если у него нет доступа к сделке в интерфейсе — API её не вернёт.
4. Методы вне выданного скоупа
Если приложению или вебхуку не выдан нужный скоуп — метод вернёт ошибку insufficient_scope.
Скоупы
Скоуп — это группа методов, к которой приложение или вебхук имеет доступ. Без нужного скоупа метод не выполнится.
Основные скоупы
| Скоуп | Что открывает |
|---|---|
crm | CRM: лиды, сделки, контакты, компании |
task | Задачи и проекты |
user | Пользователи |
department | Структура компании |
disk | Файлы и папки |
calendar | Календарь |
im | Чат и уведомления |
Скоупы выбираются при создании вебхука или приложения. Если метод возвращает ошибку доступа — проверьте, выдан ли нужный скоуп.
💡 Важно
Не выдавайте приложению все скоупы «на всякий случай». Чем меньше прав — тем безопаснее. Если метод не нужен — не добавляйте его скоуп.
Права пользователя
Даже с нужным скоупом метод выполняется с правами конкретного сотрудника. Это важно понимать: API не «обесценивает» права, а строго их соблюдает.
Как это работает
- Вебхук — выполняется от имени создателя. Если создатель не видит сделки — API не вернёт их;
- OAuth-приложение — выполняется от имени пользователя, который авторизовался. Права те же, что в интерфейсе ;
- Администратор — видит больше, но не всё (некоторые данные скрыты даже от админа).
Это защита, а не ограничение. Если бы API мог обходить права, это была бы дыра в безопасности.
REST 3.0: что нового
В 2027 году Битрикс24 развивает новую версию API — REST 3.0. Она отличается от предыдущей версии.
Ключевые изменения
| Что | REST 3.0 |
|---|---|
| Адрес | /rest/api/ вместо /rest/ |
| Формат ответа | Единый для всех методов |
| Связанные данные | Можно запросить одним запросом через точку: responsible.name |
| Документация | OpenAPI, вызывается методом documentation |
| SDK | Пока не поддерживают адрес /rest/api/ |
REST 3.0 пока покрывает не все модули. Если метода нет в новой версии — используйте предыдущую.
Наши рекомендации
Что вы получаете, заказывая разработку API у нас
- Аудит методов — что можно, что нельзя
- Настройку скоупов — минимум прав
- Проверку прав — что вернёт API
- Документацию — для команды
- Поддержку — после запуска
📌 Итоговый вывод
REST API Битрикс24 покрывает большинство модулей, но не всё. И права никто не отменял.
Что нужно знать:
- Методы: CRM, задачи, пользователи, структура, диск, календарь;
- Что нельзя: методы с контекстом приложения, действия без метода, данные вне прав, методы вне скоупа;
- Скоупы: без нужного — ошибка
insufficient_scope; - Права: API строго соблюдает права сотрудника;
- REST 3.0: новый формат, связанные данные, OpenAPI, но не все модули.
Также рекомендуем: API, авторизация, вебхуки, все статьи об API.