Типы данных и форматы параметров в REST API

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

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

Страница описывает типы данных, которые используются в параметрах методов, структурах объектов и ответах REST API. Для каждого типа приведены формат значения и особенности использования. Это общий словарь типов: точный состав поля, допустимые значения и дополнительные ограничения нужно смотреть на странице конкретного метода или объекта.

Базовые типы данных

Тип

Описание

integer

Целое число. Например 10116

boolean

Логическое значение. Чаще всего принимает значения Y или N. В некоторых методах может принимать значения 0 или 1, а также true или false

char

Строковый тип фиксированной длины, обычно CHAR(1). Часто используется как замена boolean и хранит Y или N

double

Число с плавающей точкой. Например, 100.15

date

Дата в формате YYYY-MM-DD. Например, 2025-12-28, 28 декабря 2025 года

datetime

Дата и время в формате YYYY-MM-DDThh:mm:ss±hh:mm. Например, 2023-12-28T14:05:48+03:00

timestamp

Дата и время в формате Unix Timestamp, обычно целое число с количеством секунд от 1 января 1970 года. Например, 1719826800

string

Однострочное строковое значение. Например, Договор поставки

text

Многострочное строковое значение, применимое в некоторых специальных полях объектов

file

Прикрепленный файл. Может принимать числовое значение с уникальным идентификатором файла в системе или значение в виде массива, описывающего параметры файла.

Подробнее о работе с файлами читайте в статьях:

enum

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

array

Набор элементов простого типа. Например, массив целых чисел [1, 5, 67] или строк ["deal", "lead", "quote"]

object

Структура произвольного уровня вложенности, содержащая пары «ключ — значение». Ключ — параметр или поле. Пример:

{
  "data": {
    "foo": "bar",
    "bar": "foo",
    "items": [
      1,
      100,
      200
    ]
  }
}

function

Функция. Используется в JavaScript-примерах и js-интерфейсах Битрикс24 для описания обработчика

callable

Вызываемый обработчик, обычно функция обратного вызова. В JavaScript это может быть обычная функция или ее краткая запись через =>

any

В качестве значения параметра могут выступать различные типы данных

null

Отсутствие значения. Самостоятельно не используется — указывается вторым типом для полей, которые могут вернуть значение или пустоту. Например, string | null

Особенности дат и времени

При работе с полями типов date и datetime обратите внимание, что у каждого пользователя в Битрикс24 может быть указан в настройках собственный часовой пояс. В пользовательском интерфейсе Битрикс24 показывает даты и время, адаптируя их под конкретного пользователя, однако на уровне API все даты и время хранятся с учетом параметров сервера.

Как записаны составные типы

Кроме одиночных типов в описаниях параметров и полей встречаются составные записи.

Запись

Что означает

тип[]

Массив значений указанного типа. Например, string[] — массив строк, integer[] — массив целых чисел

тип1 | тип2

Поле принимает значение одного из перечисленных типов. Например, string | null — строка или пустое значение

Типы данных для ссылок на объекты и справочники

Поля объектов Битрикс24 могут содержать значения, ссылающиеся на другие объекты или на значения из справочников. Технически такие значения, чаще всего, хранятся и указываются в виде целочисленных идентификаторов конкретных объектов или элементов справочников. Но для удобства и подчеркивания таких связей, в документации мы будем использовать специальные типы вроде _crm_company_ или _crm_status_. Ниже приводятся примеры таких типов со ссылками на методы получения возможных значений.

Тип

Описание

user

Целочисленный идентификатор пользователя Битрикс24, например, 1.

Получить идентификаторы пользователей можно с помощью метода user.get

crm

Привязка к элементам CRM. Значение передается в формате {PREFIX}_{ID}, где PREFIX — краткий символьный код типа объекта CRM, ID — числовой идентификатор элемента. Например, D_1 — сделка с идентификатором 1, C_2 — контакт с идентификатором 2.

При множественной привязке передается массив строк: ["C_123", "CO_456"].

Полный список PREFIX и правила вычисления PREFIX для смарт-процессов описаны в разделе Формат значений для пользовательского поля «Привязка к элементам CRM»

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

Объект uf_enum_element

Вариант значения пользовательского поля списочного типа enumeration. Поля с этим типом множественные: в них передается массив таких объектов.

Название
тип

Описание

ID
integer

Идентификатор варианта. Заполняется у существующих вариантов, при добавлении нового не передается

VALUE
string

Значение варианта

DEF
char

Признак значения по умолчанию. Принимает значения Y или N

SORT
integer

Порядок сортировки

XML_ID
string

Внешний идентификатор варианта

DEL
char

Признак удаления существующего варианта. Принимает значения Y или N

Методы группы *.userfieldconfig.* используют для тех же полей запись в camelCase — id, value, def, sort, xmlId, del.

Объект time

Объект time присутствует в ответах на все запросы к REST и содержит в себе информацию о времени выполнения запроса.

Состав полей объекта time может отличаться в зависимости от метода и окружения. В полном варианте ответ может содержать все поля из примера ниже.

Пример структуры:

{
    "time": {
        "start": 1757424671.509725,
        "finish": 1757424672.203906,
        "duration": 0.694180965423584,
        "processing": 0.6726489067077637,
        "date_start": "2025-09-09T16:31:11+03:00",
        "date_finish": "2025-09-09T16:31:12+03:00",
        "operating_reset_at": 1757425271,
        "operating": 0.6726338863372803
    }
}

Название
тип

Описание

start
double

Временная метка времени в формате Unix Timestamp для момента инициализации запроса. Возвращается как число с дробной частью, потому что время передается в секундах с точностью до долей секунды

finish
double

Временная метка времени в формате Unix Timestamp для момента завершения выполнения запроса. Возвращается как число с дробной частью, потому что время передается в секундах с точностью до долей секунды

duration
double

Длительность выполнения запроса в секундах, то есть разница между finish и start

processing
double

Время обработки запроса в секундах

date_start
string

Строковое представление даты и времени момента инициализации запроса

date_finish
string

Строковое представление даты и времени момента завершения запроса

operating_reset_at
timestamp

Временная метка времени в формате Unix Timestamp для момента, когда будет высвобождена часть лимита на ресурсоемкость метода. Обычно возвращается как целое число

Подробнее в статье лимит на операции

operating
double

Накопленное время выполнения запросов к конкретному методу в секундах. Используется для контроля ресурсоемкости REST API.

Подробнее в статье лимит на операции
Предыдущая
Инструменты и сценарии
Следующая
Обзор REST 3.0