Обзор REST API 3.0

REST 3.0 — новая версия API в Битрикс24, которая делает работу с интеграциями более предсказуемой и структурированной. Ключевые улучшения:

• единый формат ответов,
• получение связанных данных одним запросом,
• встроенная OpenAPI-документация.

Таблица сравнения версий REST

Как вызвать новую версиюКак вызвать новую версию

Адрес вызова: https://{адрес_установки}/rest/api/{id_пользователя}/{код_вебхука}/{method}.

• {адрес_установки} — адрес Битрикс24.

• /rest/api/ — указание на версию REST. После rest/ укажите /api/ — это главное отличие вызова новой версии от старой. Если не указать /api/, Битрикс24 выполнит метод старой версии REST, если он существует, или вернет ошибку Method not found для методов, доступных только в REST 3.0.

• /{id_пользователя}/{код_вебхука}/ — данные авторизации вебхука. Для приложения передавайте токен авторизации в поле auth в теле запроса.

• {method} — вызываемый метод.

Пример вызова нового метода с авторизацией вебхука

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"taskId":51,"text":"Сообщение из внешней системы"}}' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.chat.message.send
        

Пример вызова нового метода с авторизацией приложения

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"taskId":51,"text":"Сообщение из внешней системы"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/api/tasks.task.chat.message.send
        

Технические требованияТехнические требования

• Тело запроса передавайте в формате JSON с заголовком Content-Type: application/json.

• Все запросы с параметрами передавайте только в формате POST, например метод tasks.task.chat.message.send с параметрами taskId и text.

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"taskId":51,"text":"Сообщение из внешней системы"}}' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.chat.message.send
        

• Запросы без параметров можно отправлять как GET или POST, например метод без параметров rest.documentation.openapi.

curl -X GET "https://{portal}/rest/api/{user_id}/{webhook}/documentation"
        

OpenAPI-документацияOpenAPI-документация

В REST 3.0 доступна автоматически генерируемая документация в стандарте OpenAPI.

Чтобы получить документацию, вызовите метод rest.documentation.openapi или documentation без параметров.

curl -X POST "https://{portal}/rest/api/{user_id}/{webhook}/documentation"
        

Результат — JSON в формате OpenAPI.

Метод можно вызвать в Swagger, Postman или другой программе, которая работает с OpenAPI.

Единый формат ответаЕдиный формат ответа

В предыдущей версии REST разные модули по-разному возвращали результат. Например, идентификатор созданного элемента мог быть вложенным объектом "result": { "id": 1823 } или сразу возвращаться в результате "result": 1823. Для разных методов необходимо было писать свою логику обработки ответа.

Новая версия REST возвращает ответ на запрос в едином формате, который применяется ко всем методам, независимо от модуля.

Структура успешного ответаСтруктура успешного ответа

Если метод возвращает данные, например список найденных элементов или идентификатор созданного элемента, они вернутся вложенным объектом внутри "result": {...}.

{
          "result": {
            "item": {
              "id": 42,
              "title": "Подготовить отчет"
            }
          }
        }
        

Если метод возвращает результат выполнения операции true или false, например при удалении элемента, он вернется вложенным объектом внутри "result": {...}.

{
          "result": {
            "result": true
          }
        } 
        

Структура неуспешного ответаСтруктура неуспешного ответа

Любой метод может вернуть ошибку, например из-за запрета доступа или неверных параметров запроса. В новом формате ошибка содержит:

• code — код ошибки, возвращается всегда,

• message — сообщение об ошибке на языке вашего Битрикс24, возвращается всегда,

• validation — подробности об ошибке, возвращаются, если ошибка связана с параметрами запроса.

{
            "error": {
                "code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION",
                "message": "Ошибка при валидации объекта запроса",
                "validation": [
                    {
                        "message": "Обязательное поле `id` не указано",
                        "field": "id"
                    }
                ]
            }
        }
        

Связи между объектамиСвязи между объектами

REST 3.0 позволяет получать данные связанных объектов сразу в одном ответе. Например, у задачи есть поле responsible — это поле с идентификатором другого объекта, пользователя. В старой версии REST необходимо сначала получить идентификатор из поля responsible старым методом tasks.task.get, затем отдельно вызвать метод user.get, чтобы получить данные по идентификатору пользователя.

В новой версии REST можно сразу в запросе tasks.task.get указать поля связанных объектов в select: "select": ["responsible.name", "responsible.email"].

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"id":3835,"select":["responsible.name","responsible.email"]}' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.get
        

Связанные поля указываются в запросе через точку: responsible.name, group.title, company.phone. В ответе связанные поля превращаются в объект со структурой, соответствующей выбранным полям.

{
            "result": {
                "item": {
                    "id": 3835,
                    "title": "задача",
                    "...": "", // другие поля
                    "responsible": {
                        "name": "Имя",
                        "email": "mail@bitrix.ru"
                    },
                }
            },
        }
        

Если в select указаны некорректные или недоступные поля, запрос вернет ошибку.

{
            "error": {
                "code": "BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION",
                "message": "Неизвестное поле `stageId` для сущности `UserDto`"
            }
        }
        

Чтобы узнать, какие связи и поля поддерживаются, используйте OpenAPI-документацию или статью Поля задачи в REST 3.0.

ФильтрацияФильтрация

В REST 3.0 фильтрация данных построена на логических выражениях, которые можно комбинировать. Все методы, поддерживающие параметр filter, работают по этой схеме.

Принципы работы фильтраПринципы работы фильтра

• Условия внутри одного уровня соединяются логикой И — то есть должны выполняться все сразу.

• Группы условий можно объединять логикой ИЛИ с помощью специального объекта с ключом "logic": "or".

Пример простого фильтра. Найти все записи, у которых одновременно выполняется два условия:

1. Статус = "NEW".

2. ID равен 3, 4 или 5.

{
            "filter": [
                ["status", "=", "NEW"],
                ["id", "in", [3,4,5]]
            ]
        }
        

Все элементы в массиве filter соединяются между собой логикой И -> Статус = NEW И (ID = 3, 4 или 5).

Пример сложного фильтра с логикой. Найти все записи, у которых одновременно выполняется два условия:

1. Статус = "NEW".

2. ID равен 1 или 2, ИЛИ ID равен 3, 4 или 5.

{
            "filter": [
                ["status", "=", "NEW"],
                {
                    "logic": "or", 
                    "conditions": [
                        ["id", [1,2]], // id in (1,2)
                        ["id", "in", [3,4,5]]
                    ]
                }
            ]
        }
        

1. ["status", "=", "NEW"] -> Это простое условие: найди все элементы, где поле status равно значению NEW.
2. { "logic": "or", "conditions": [...] } -> Это группа условий, соединенных логикой ИЛИ (or). Внутри группы два условия:
   • ["id", [1,2]] — это сокращенная запись для ["id", "in", [1,2]] -> «ID должен быть одним из этих чисел: 1 или 2»,
   • ["id", "in", [3,4,5]] -> «ID должен быть 3, 4 или 5». "logic": "or" обозначает, что элемент подойдет, если хотя бы одно из этих двух условий выполнено.
3. Все элементы в массиве filter соединяются логикой И между собой -> Статус = NEW И (ID = 1 или 2 ИЛИ ID = 3 или 4 или 5).

Поддерживаемые операторыПоддерживаемые операторы

Сравнение REST 3.0 со старой версией APIСравнение REST 3.0 со старой версией API