Справочник REST API: инструменты и методы Битрикс24

С помощью REST API приложение работает с инструментами Битрикс24. Например, оно может создать сделку в CRM, получить задачу, загрузить файл на Диск, обработать событие об изменении данных или встроить виджет в карточку CRM.

Быстрый переход: все разделы справочника

Как найти нужный методКак найти нужный метод

Имя метода подсказывает объект и действие: crm.deal.add создает сделку, tasks.task.get возвращает задачу, disk.file.get возвращает файл.

Метод можно проверить программно, не открывая его страницу. Метод method.get показывает, существует ли метод и доступен ли он приложению. Метод scope возвращает список выданных скоупов. Полный машиночитаемый перечень методов новой версии есть в OpenAPI-документации.

Порядок работы с REST APIПорядок работы с REST API

Если вы еще не отправляли запросы к REST API, начните с раздела Первый запрос к REST API. Шаги ниже описывают работу со старой версией REST API. Отличия новой версии собраны в блоке Какую версию API выбрать.

1. Определите объект и найдите метод в обзоре разделов справочника.

2. Выдайте права. Почти каждый метод входит в скоуп — группу методов, к которой приложение получает доступ. Скоупы перечисляют при настройке прав приложения. Системные методы работают без отдельного скоупа: в блоке Scope на их страницах стоит базовый. Скоуп не открывает доступ сам по себе — приложение работает только с теми данными, которые видит пользователь, выполняющий запрос.

3. Выберите способ авторизации. Вебхук подходит для интеграции внутри своего Битрикс24, приложение с авторизацией по OAuth 2.0 — для решений, которые устанавливают на разные Битрикс24. Оба способа описаны в разделе Авторизация в REST, а инструменты для локальных интеграций — в разделе Инструменты для локальных интеграций.

4. Вызовите метод. Адрес зависит от способа авторизации:

   • вебхук — идентификатор пользователя и секретный код передают в пути: https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/method
   • приложение — токен передают в параметре auth: https://your-domain.bitrix24.com/rest/method?auth=ACCESS_TOKEN

   Правила передачи параметров описаны в разделе Как выполняется запрос, форматы значений — в разделе Типы данных и форматы параметров. Имена полей и формат логических значений зависят от модуля и версии API, поэтому сверяйте их на странице метода.

5. Разберите ответ. Данные метода возвращаются в поле result, время выполнения — в поле time. Списочные методы возвращают не более 50 элементов за раз и передают смещение для следующей страницы в поле next. Подробности — в разделах Как вызывать методы REST API и Особенности списочных методов.

6. Обработайте ошибки. Вместо данных сервер возвращает поля error и error_description. Общий перечень — в разделе Коды ошибок, ошибки конкретного метода — на его странице.

После первого рабочего вызова пригодятся:

• События — регистрация обработчиков, если интеграция должна реагировать на изменения в Битрикс24, а не только запрашивать данные
• batch — объединяет до 50 вызовов в один запрос
• Лимиты REST API — ограничения на интенсивность и ресурсоемкость запросов
• Библиотеки для разработки — готовые клиенты для JavaScript, PHP, Python и Go

Какую версию API выбратьКакую версию API выбрать

Обе версии REST API работают одновременно и не заменяют друг друга. На REST 3.0 переведена часть разделов. В таблицах ниже такие разделы помечены, остальные методы вызывают по-прежнему. Один и тот же метод может существовать в обеих версиях с разными параметрами и ответом. Если метод доступен и там, и там, для новой разработки рекомендуется REST 3.0: единый формат ответа, связанные объекты в одном запросе и защита от повторного выполнения по заголовку Idempotency-Key.

В REST 3.0 отличаются вызов и разбор ответа:

• адрес содержит сегмент /rest/api/
• тело запроса передают только в формате JSON
• список приходит массивом в ключе items внутри result
• размер и смещение страницы задают объектом pagination в запросе — состав его полей описан на странице метода
• ошибка приходит объектом error с полями code, message и validation
• тело пакета batch передают JSON-массивом объектов с полями method и query
• формат пакета с оберткой cmd в новой версии не работает

Плашка в начале страницы метода показывает его версию. Там же стоит предупреждение, если развитие семейства методов остановлено, — так бывает и вне раздела устаревших методов. Полное сравнение версий — в таблице Сравнение REST 3.0 со старой версией API.

Когда открывать туториалКогда открывать туториал

Страницы методов помогают подготовить отдельные запросы, но не описывают рабочий сценарий целиком. Если задачу нужно решить от начала до конца, начните с обзорной страницы инструмента или откройте Туториалы — там разобраны готовые сценарии из нескольких вызовов.

Обзор разделов справочникаОбзор разделов справочника

Разделы сгруппированы по задачам. Список методов раздела находится в блоке с якорем #all-methods в конце его страницы. В больших разделах в этом же блоке перечислены подразделы и их методы. Три раздела устроены иначе:

• «Бот-платформа» — методы разложены по подразделам, точка входа на индексной странице раздела
• «Виджеты» — методы placement.* лежат в корне раздела, каталог точек встраивания находится на странице Точки встраивания
• «Устаревшие методы» — методы вынесены в подраздел RPA

Собственных методов не содержат «Типы данных и форматы параметров», «Скоупы методов» и «Как работать с файлами» — это правила, общие для всего API. Раздел REST 3.0 описывает правила новой версии и два ее собственных метода: rest.documentation.openapi и rest.scope.list.

Основы REST APIОсновы REST API

Раздел	Описание
Типы данных и форматы параметров	Базовые типы, форматы дат, файлов и сложных параметров
Скоупы методов	Права доступа приложения к группам методов
Общие методы и события	Системные методы, настройки приложения, пользователи и общие события
События	Регистрация обработчиков, офлайн-очередь и удаление событий REST API
REST 3.0	Правила вызова и формат ответа новой версии REST API, перечень переведенных на нее разделов
Устаревшие методы	Методы роботизации (RPA), развитие которых остановлено — не для новых решений

Продажи и клиентыПродажи и клиенты

Раздел	Описание
CRM	Лиды, сделки, контакты, компании, смарт-процессы, предложения, реквизиты, дела таймлайна, стадии и воронки, события CRM
Интернет-магазин	Заказы, корзина, оплаты, отгрузки, кассы и события магазина
Торговый каталог	Товары, торговые предложения, цены, склады, складские документы и события каталога
Платежные системы	Платежные обработчики и настройки оплаты
Генератор документов	Документы, шаблоны, нумераторы и роли
КЭДО	Кадровый электронный документооборот, подписание документов сотрудниками, интеграция с системами кадрового учета и события подписания

Автоматизация и работа компанииАвтоматизация и работа компании

Раздел	Описание
Бизнес-процессы и роботы	Шаблоны, запуск процессов, задания, роботы и действия бизнес-процессов
Задачи	Задачи, чек-листы, комментарии, шаблоны, стадии, потоки и события. REST 3.0: часть методов — сама задача, ее чат, результаты, файлы, права доступа и связи диаграммы Ганта
Рабочие группы и проекты	Рабочие группы, проекты, участники, скрам и события групп
Календарь	Календари, записи, ресурсы и события
Онлайн-запись	Ресурсы и их типы, слоты, бронирования, лист ожидания, клиенты, связи с внешними системами и события онлайн-записи
Журнал событий	Входы сотрудников в Битрикс24 и другие записи журнала событий. REST 3.0: весь раздел
Структура компании	Отделы, команды, участники и сотрудники. REST 3.0: часть методов — humanresources.*, а методы department.* работают по старой версии
Учет рабочего времени	Рабочее время, расписания и контроль времени. REST 3.0: часть методов — записи о рабочем времени
Пользователи	Пользователи и пользовательские поля

КоммуникацииКоммуникации

Раздел	Описание
Чаты	Чаты, сообщения, файлы, пользователи и уведомления
Бот-платформа	Чат-боты, команды, сообщения и события ботов. Актуальная ветка — imbot.v2, а предыдущее поколение imbot.* не развивается
Открытые линии	Открытые линии, сессии, операторы, чаты, коннекторы и события линий
Телефония	Звонки, линии Voximplant и события телефонии. REST 3.0: часть методов — Follow-up звонков
Провайдеры сообщений, СМС-провайдеры	Сторонние провайдеры для отправки клиентам СМС и других сообщений, статусы доставки
Лента новостей	Новости, комментарии и события ленты
Опросы, голосования	Опросы в чатах и ленте новостей, голоса, результаты и отчеты
Почта	Почтовые ящики, письма и получатели. REST 3.0: весь раздел
Почтовые сервисы	Почтовые сервисы с параметрами IMAP, через которые подключают ящики Яндекса, Mail.ru, Gmail и других сервисов

Данные, файлы и контентДанные, файлы и контент

Раздел	Описание
Диск	Файлы, папки, хранилища, версии и права доступа
Как работать с файлами	Форматы передачи файлов в REST API
Хранилище данных	Собственные данные приложения: хранилища entity, их разделы, элементы и свойства
Универсальные списки	Списки, разделы, поля и элементы
Сайты и магазины	Сайты, страницы, блоки, шаблоны и права
База знаний 2.0	Коллекции, документы и файлы. REST 3.0: весь раздел

Платформенные возможностиПлатформенные возможности

Раздел	Описание
Виджеты	Точки встраивания интерфейса приложения в Битрикс24
BIconnector	Коннекторы, источники и таблицы BI-аналитики
BitrixGPT	Собственные AI-сервисы, подключаемые методами ai.engine.*
Вайб	Собственные виджеты для страницы Вайба, которая приходит на смену Ленте новостей
Пользовательские соглашения	Соглашения, их тексты и согласия пользователей