Особенности списочных методов

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Списочные методы возвращают наборы однотипных элементов, например сделки, пользователей или комментарии к задаче. Результат может состоять из нескольких страниц. Рассмотрим, как последовательно получать страницы с помощью параметра start и поля next, а также какой способ выбрать для больших объемов данных.

Как работает постраничная навигация

Битрикс24 возвращает не более 50 элементов на одной странице.

Чтобы получить все элементы:

  1. Выполните списочный метод без параметра start, чтобы получить первую страницу
  2. Если в ответе есть поле next, передайте его значение в параметре start следующего запроса
  3. Повторяйте запрос, пока поле next не исчезнет из ответа. Отсутствие поля означает, что получена последняя страница

Пример запроса и ответа

В примере метод crm.item.list запрашивает первую страницу элементов смарт-процесса с идентификатором 183:

https://your-domain.bitrix24.com/rest/crm.item.list?entityTypeId=183&auth=YOUR_ACCESS_TOKEN

В ответе поле next содержит значение для запроса следующей страницы:

{
    "result": {
        "items": [
            {
                "id": 101
            },
            {
                "id": 102
            }
        ]
    },
    "total": 73,
    "next": 50
}

Замените YOUR_ACCESS_TOKEN на токен авторизации. Не публикуйте токен и не храните его в исходном коде приложения.

Поля ответа

При вызове списочных методов REST возвращает следующие поля:

Поле

Тип

Когда возвращается

Описание

result

array или object

В успешном ответе

Результат выполнения метода. Структура зависит от конкретного метода

error

string

В ответе с ошибкой

Код ошибки выполнения метода

total

integer

В успешном ответе списочного метода, если метод подсчитывает общее количество элементов

Общее количество элементов, которые соответствуют условиям запроса

next

integer

Если после текущей страницы есть следующая

Значение для параметра start следующего запроса. На последней странице поле next не возвращается

Как получить следующую страницу

Повторите первый запрос и передайте значение 50 из поля next в параметре start:

https://your-domain.bitrix24.com/rest/crm.item.list?entityTypeId=183&start=50&auth=YOUR_ACCESS_TOKEN

Способ получения следующей страницы зависит от инструмента:

  • при прямом обращении к REST API передавайте значение next в параметре start
  • при работе с SDK BX24.js вызывайте метод result.next(). SDK сформирует запрос следующей страницы

Ограничения и большие объемы данных

Стандартная постраничная навигация подходит для небольших выборок и разовых операций. Обработка большого количества элементов создает дополнительную нагрузку и может привести к превышению лимитов REST API.

Для регулярной выгрузки больших объемов данных применяйте рекомендации из статьи Как получать большие объемы данных из Битрикс24.

Продолжите изучение

Предыдущая
Кодирование данных
Следующая
Как выполнить пакет запросов