Получить список значений справочника CRM v 3.0 crm.dictionary.<справочник>.list
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Scope:
crmКто может выполнять метод: пользователь с правом на чтение лидов, сделок или других объектов CRM
Метод относится к REST 3.0. Особенности вызова и формат ответа новой версии API описаны в обзоре REST 3.0.
Метод crm.dictionary.<справочник>.list возвращает значения справочника CRM с фильтром, сортировкой и постраничной навигацией. Справочник задает сегмент <справочник> в имени метода.
Имя метода для справочника
|
Справочник |
Метод |
Где используется значение |
|
Типы сделок |
|
Поле |
|
Типы контактов |
|
Поле |
|
Типы компаний |
|
Поле |
|
Обращения |
|
Поле |
|
Количество сотрудников |
|
Поле |
|
Сферы деятельности |
|
Поле |
|
Источники |
|
Поле |
|
Типы телефонов |
|
Ключ |
|
Типы электронной почты |
|
Ключ |
|
Типы сайтов |
|
Ключ |
|
Типы мессенджеров |
|
Ключ |
|
Типы адресов |
|
Поле |
|
Типы объектов CRM |
|
Поле |
|
Группы стадий |
|
Поле |
|
Провайдеры дел |
|
Поле |
Имя метода пишется в нижнем регистре: crm.dictionary.dealtype.list, а не crm.dictionary.dealType.list. На имя в другом регистре или с неизвестным справочником метод отвечает ошибкой «Метод не найден».
Одно значение по идентификатору возвращает метод crm.dictionary.<справочник>.get.
Параметры метода
Обязательные параметры отмечены *
|
Название |
Описание |
|
select |
Список полей, которые нужно вернуть для каждого значения. Описание параметра Если параметр не передан, метод возвращает все поля |
|
filter |
Условия отбора значений в формате REST 3.0. Описание параметра Если параметр не передан, метод возвращает все значения |
|
order |
Сортировка в формате |
|
pagination |
Параметры постраничной навигации. Описание параметра Если параметр не передан, справочники значений CRM возвращают первые 50 значений, остальные справочники — все значения |
Параметр select
Состав полей у каждого справочника свой, он описан в разделе Поля справочников.
Значения в ответе содержат только поля из select. Пустой массив [] возвращает все поля. Неизвестное поле вызывает ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION.
Путь через точку работает только для поля types справочника провайдеров дел: types.name возвращает названия типов дел без остальных ключей.
Параметр filter
Фильтр — массив условий. Метод соединяет условия массива логикой И. Условие записывается одним из способов:
["поле", "оператор", значение]— например["sort", ">=", 20]["поле", значение]— оператор=, а для значения-массиваin:["id", ["CALL", "WEB"]]
Операторы описаны в обзоре REST 3.0. Набор операторов зависит от справочника, он указан в разделе Поля справочников. Оператора like и поиска по части строки нет: ["name", "=", "Продажа"] найдет только значение с точно таким названием.
Значение должно соответствовать типу поля: число для integer, true или false для boolean, строка для string. Строка "10" для поля sort или "N" для поля isSystem вызывает ошибку валидации.
Чтобы соединить условия логикой ИЛИ, передайте группу — объект с ключами:
type— значениеfilterlogic—andилиor, по умолчаниюandnegative—trueинвертирует группу. Работает только в справочниках значений CRM и в справочникеentitytypeconditions— массив условий и вложенных групп
Пример: тип сделки SALE или типы с сортировкой больше 40.
{
"filter": [
{
"type": "filter",
"logic": "or",
"conditions": [
["id", "=", "SALE"],
["sort", ">", 40]
]
}
]
}
Если filter передан строкой, числом или объектом вида {"id": "SALE"}, метод отвечает ошибкой BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION.
Параметр order
Объект, где ключ — имя поля, а значение — направление сортировки:
ASC— по возрастаниюDESC— по убыванию
Регистр направления не важен. Поля, по которым можно сортировать, указаны в разделе Поля справочников.
Если order не передан, значения справочников значений CRM идут по возрастанию sort, группы стадий — по id, остальные — в том порядке, в котором их хранит Битрикс24.
Параметр pagination
|
Название |
Описание |
|
limit |
Количество значений на странице. Значения больше По умолчанию: |
|
page |
Номер страницы, начиная с Если передан |
|
offset |
Количество значений, которые нужно пропустить от начала списка. Отрицательное значение вызывает ошибку. По умолчанию: |
Неизвестные ключи в pagination метод не проверяет. Если передать {"size": 10} вместо {"limit": 10}, ошибки не будет, и ответ вернет до 50 значений.
Ответ не содержит общего количества значений. Если на странице вернулось меньше значений, чем указано в limit, это последняя страница.
Поля справочников
Справочники различаются составом полей, операторами фильтра и полями сортировки. Описание полей с признаками filterable и sortable возвращает метод crm.dictionary.<справочник>.field.list.
Справочники значений CRM
Справочники dealtype, contacttype, companytype, honorific, employees, industry, source. Значения этих справочников можно создавать, изменять и удалять методами crm.dictionary.<справочник>.add, crm.dictionary.<справочник>.update и crm.dictionary.<справочник>.delete.
|
Название |
Описание |
|
id |
Идентификатор значения, например |
|
name |
Название значения |
|
sort |
Порядок сортировки |
|
isSystem |
Признак стандартного значения. Возможные значения:
|
Фильтр — по всем полям, операторы =, !=, >, >=, <, <=, in. Оператор between — только для sort. Сортировка — по id, name, sort.
Типы связи
Справочники phonetype, emailtype, webtype, imtype — типы телефонов, электронной почты, сайтов и мессенджеров. Приложение передает идентификатор типа в ключе valueTypeId значения множественного поля, например {"valueTypeId": "WORK", "value": "+79990000000"}.
|
Название |
Описание |
|
id |
Идентификатор типа, например |
|
name |
Полное название, например «Рабочий телефон». Может быть |
|
nameShort |
Короткое название, например «Рабочий». Может быть |
|
isDeprecated |
Признак устаревшего типа. Возможные значения:
|
Фильтр — по всем полям, операторы =, !=, in. Сортировка — по всем полям.
Типы адресов
Справочник addresstype — типы адресов контакта и компании, например юридический или фактический.
|
Название |
Описание |
|
id |
Идентификатор типа адреса, например |
|
name |
Символьный код типа, например |
|
title |
Название типа, например «Юридический адрес» |
Фильтр — по всем полям, операторы =, !=, in. Сортировка — по всем полям.
Группы стадий
Справочник stagesemantic — группы, к которым относится стадия элемента CRM.
|
Название |
Описание |
|
id |
Идентификатор группы. Возможные значения:
|
|
name |
Название группы |
Фильтр — по всем полям, операторы =, !=, in. Сортировка — по всем полям.
Типы объектов CRM
Справочник entitytype содержит только системные типы объектов: лид, сделку, контакт, компанию, предложение, счет, документ и документ компании. Смарт-процессов в нем нет, их идентификаторы entityTypeId возвращает метод crm.type.list.
|
Название |
Описание |
|
id |
Идентификатор типа объекта |
|
code |
Символьный код типа, например |
|
title |
Название типа |
Фильтр — по всем полям, операторы =, !=, >, >=, <, <=, in. Оператор between — только для id. Сортировка — по всем полям.
Провайдеры дел
Справочник activityprovider — провайдеры дел CRM: универсальное дело, встреча, звонок, письмо, задача и другие.
|
Название |
Описание |
|
id |
Идентификатор провайдера, например |
|
name |
Название провайдера |
|
isAvailable |
Признак, что провайдер доступен в Битрикс24. Возможные значения:
|
|
isActive |
Признак, что провайдер включен. Возможные значения:
|
|
types |
Типы дел провайдера. У каждого типа есть идентификатор |
|
defaultTypeId |
Тип дела по умолчанию, например |
|
capabilities |
Возможности дел провайдера, например |
Фильтр — только по полям id, isAvailable, isActive, операторы =, !=, in. Сортировка — только по id.
Примеры кода
Как использовать примеры в документации
Вызов нового API отличается добавлением параметра /api/ в запросе:
https://{адрес_установки}/rest/api/{id_пользователя}/{токен_вебхука}/crm.dictionary.dealtype.list
Примеры получают типы сделок, которые можно удалить, — первую страницу из трех значений по возрастанию сортировки. Для другого справочника замените имя метода по таблице выше и проверьте поля в select, filter и order по разделу Поля справочников.
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","name","sort"],"filter":[["isSystem","=",false]],"order":{"sort":"ASC"},"pagination":{"limit":3}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.dictionary.dealtype.list
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","name","sort"],"filter":[["isSystem","=",false]],"order":{"sort":"ASC"},"pagination":{"limit":3},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/crm.dictionary.dealtype.list
Методы CRM пока не входят в список методов REST 3.0, который знает $b24.actions.v3.call.make: такой вызов вернет ошибку SDK JSSDK_CORE_METHOD_NOT_SUPPORT_IN_API_V3. Вызывайте метод через HTTP-клиент REST 3.0 — $b24.getHttpClient(ApiVersion.v3).call.
import { ApiVersion, Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
type DictionaryListResult = {
items: {
id: string
name: string
sort: number
}[]
}
try {
const response = await $b24.getHttpClient(ApiVersion.v3).call<DictionaryListResult>(
'crm.dictionary.dealtype.list',
{
select: ['id', 'name', 'sort'],
filter: [
['isSystem', '=', false],
],
order: {
sort: 'ASC',
},
pagination: {
limit: 3,
},
},
Text.getUuidRfc4122()
)
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Deal types:', result.items)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
Методы CRM пока не входят в список методов REST 3.0, который знает $b24.actions.v3.call.make. Вызывайте метод через HTTP-клиент REST 3.0 — $b24.getHttpClient(B24Js.ApiVersion.v3).call.
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function listDealTypes() {
try {
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.getHttpClient(B24Js.ApiVersion.v3).call(
'crm.dictionary.dealtype.list',
{
select: ['id', 'name', 'sort'],
filter: [
['isSystem', '=', false],
],
order: {
sort: 'ASC',
},
pagination: {
limit: 3,
},
},
B24Js.Text.getUuidRfc4122()
)
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Deal types:', result.items)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', listDealTypes)
</script>
У методов CRM нет готовых оберток в b24pysdk, и SDK отправляет в REST 3.0 только методы из списка Config().api_v3_methods. Добавьте метод в этот список и вызовите его через bitrix_token.call_method с prefer_version=3.
from b24pysdk import Config
from b24pysdk.errors import BitrixSDKException
from b24pysdk.errors.v3 import BitrixAPIError
method = "crm.dictionary.dealtype.list"
Config().configure(api_v3_methods=Config().api_v3_methods | {method})
try:
response = bitrix_token.call_method(
api_method=method,
params={
"select": ["id", "name", "sort"],
"filter": [
["isSystem", "=", False],
],
"order": {"sort": "ASC"},
"pagination": {"limit": 3},
},
prefer_version=3,
)
for item in response["result"]["items"]:
print(item["id"], item["name"], item["sort"])
except BitrixAPIError as error:
print(
"Ошибка Bitrix API",
f"code: {error.code}",
f"message: {error.error.message}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
print(f"Непредвиденная ошибка: {error}")
SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.
try {
$response = $b24Service
->core
->call(
'crm.dictionary.dealtype.list',
[
'select' => ['id', 'name', 'sort'],
'filter' => [
['isSystem', '=', false],
],
'order' => [
'sort' => 'ASC',
],
'pagination' => [
'limit' => 3,
],
]
);
$result = $response
->getResponseData()
->getResult();
print_r($result);
} catch (Throwable $e) {
echo $e->getMessage();
}
SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.
BX24.callMethod(
'crm.dictionary.dealtype.list',
{
select: ['id', 'name', 'sort'],
filter: [
['isSystem', '=', false],
],
order: {
sort: 'ASC',
},
pagination: {
limit: 3,
},
},
result => {
if (result.error())
console.error(result.error());
else
console.dir(result.data());
}
);
SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.
require_once('crest.php');
$result = CRest::call(
'crm.dictionary.dealtype.list',
[
'select' => ['id', 'name', 'sort'],
'filter' => [
['isSystem', '=', false],
],
'order' => [
'sort' => 'ASC',
],
'pagination' => [
'limit' => 3,
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.dictionary.dealtype.list", b24.Params{
"select": []string{"id", "name", "sort"},
"filter": []any{
[]any{"isSystem", "=", false},
},
"order": b24.Params{
"sort": "ASC",
},
"pagination": b24.Params{
"limit": 3,
},
}, b24.WithIdempotent())
if err != nil {
return fmt.Errorf("crm.dictionary.dealtype.list: %w", err)
}
raw, ok := b24.Unwrap(res.Result, "items")
if !ok {
return fmt.Errorf("в ответе нет ключа items")
}
var items []struct {
ID string `json:"id"`
Name string `json:"name"`
Sort int `json:"sort"`
}
if err := json.Unmarshal(raw, &items); err != nil {
return fmt.Errorf("разбор ответа: %w", err)
}
for _, it := range items {
fmt.Println(it.ID, it.Name, it.Sort)
}
Обработка ответа
HTTP-статус: 200
{
"result": {
"items": [
{
"id": "COMPLEX",
"name": "Комплексная продажа",
"sort": 20
},
{
"id": "GOODS",
"name": "Продажа товара",
"sort": 30
},
{
"id": "SERVICES",
"name": "Продажа услуги",
"sort": 40
}
]
},
"time": {
"start": 1793715427,
"finish": 1793715427.786939,
"duration": 0.7869389057159424,
"processing": 0,
"date_start": "2026-11-03T17:17:07+03:00",
"date_finish": "2026-11-03T17:17:07+03:00",
"operating_reset_at": 1793716020,
"operating": 0
}
}
Возвращаемые данные
|
Название |
Описание |
|
result |
Объект с данными ответа |
|
result.items |
Массив значений справочника текущей страницы. Если под фильтр ничего не подходит или страница за пределами списка, массив пустой |
|
result.items[] |
Значение справочника. Состав полей задает параметр |
|
time |
Информация о времени выполнения запроса |
Обработка ошибок
HTTP-статус: 400
{
"error": {
"code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION",
"message": "Ошибка при валидации объекта запроса",
"validation": [
{
"message": "В поле `sort` требуется тип данных `int` для такого запроса",
"field": "sort"
}
]
}
}
|
Название |
Описание |
|
error.code |
Строковый код ошибки. Используйте для идентификации типа исключения |
|
error.message |
Текстовое описание ошибки |
|
error.validation |
Массив c деталями ошибки. Присутствует только в ошибках валидации данных |
|
error.validation[].field |
Название поля, в котором возникла ошибка валидации |
|
error.validation[].message |
Описание ошибки, связанной с указанным полем |
Возможные коды ошибок
Ошибки валидации запроса
Код ошибки: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
В поле |
Передайте в условии фильтра значение типа поля |
|
|
В DTO |
Поле не участвует в фильтре. Поля для фильтра — в разделе Поля справочников |
|
|
В DTO |
Поле не участвует в сортировке. Поля для сортировки — в разделе Поля справочников |
Ошибки фильтра
Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Не удается распознать выражение фильтра |
Проверьте условие из текста ошибки, операторы и поддержку |
|
|
Не удается распознать выражение фильтра |
Передайте для |
Неизвестный оператор фильтра
Код ошибки: BITRIX_REST_V3_EXCEPTION_UNKNOWNFILTEROPERATOREXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Неизвестный оператор фильтра |
Используйте операторы из раздела Поля справочников. Оператора |
Ошибка неизвестного поля
Код ошибки: BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Неизвестное поле |
Проверьте имя поля в |
Ошибка сортировки
Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDORDEREXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Не удается распознать выражение сортировки |
Передайте |
Ошибка постраничной навигации
Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDPAGINATIONEXCEPTION
|
Поле |
Описание ошибки |
Как исправить |
|
|
Не удается распознать параметр пагинации |
Передайте в |
Ошибка доступа
Код ошибки: BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION, HTTP-статус 403
|
Поле |
Описание ошибки |
Как исправить |
|
|
Доступ запрещен |
Вызовите метод от имени пользователя с правом на чтение лидов, сделок или других объектов CRM |
Метод не найден
Код ошибки: BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION, HTTP-статус 404
|
Поле |
Описание ошибки |
Как исправить |
|
|
Метод |
Проверьте имя метода: оно пишется в нижнем регистре, например |
Статусы и коды системных ошибок
HTTP-статус: 4xx, 5xx
Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.
|
Статус |
Код |
Описание |
|
|
|
Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Превышен лимит на интенсивность запросов |
|
|
|
Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит |
|
|
|
В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука |
|
|
|
Методы вызываются только по протоколу HTTPS |
|
|
|
REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24 |
|
|
|
REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — |
|
|
|
Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом |
|
|
|
Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа |
|
|
|
Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на |
|
|
|
Срок действия access-токена истек |
|
|
|
Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям |
|
|
|
Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта |
Продолжите изучение
- Справочники CRM в REST 3.0: обзор методов
- Получить значение справочника CRM v 3.0 crm.dictionary.<справочник>.get
- Добавить значение справочника CRM v 3.0 crm.dictionary.<справочник>.add
- Изменить значение справочника CRM v 3.0 crm.dictionary.<справочник>.update
- Удалить значение справочника CRM v 3.0 crm.dictionary.<справочник>.delete