Получить список элементов CRM v 3.0 crm.<тип>.list

Scope: crm

Кто может выполнять метод: пользователь с правом на чтение элементов этого типа объекта CRM. Для моей компании — администратор CRM

Метод crm.<тип>.list возвращает список элементов CRM с фильтрацией, сортировкой и постраничной навигацией. Тип объекта задает сегмент <тип> в имени метода.

В список попадают только элементы, которые пользователь может читать. Элементы без доступа метод пропускает без ошибки.

Имя метода для типа объектаИмя метода для типа объекта

Для смарт-процесса в имя метода подставляется идентификатор его типа entityTypeId. Идентификаторы типов смарт-процессов возвращает метод crm.type.list в поле entityTypeId.

Имя метода пишется в нижнем регистре: crm.smartinvoice.list, а не crm.smartInvoice.list. На имя в другом регистре или с несуществующим entityTypeId метод отвечает ошибкой «Метод не найден».

Количество элементов по тому же фильтру без выгрузки списка возвращает метод crm.<тип>.aggregate.

Параметры методаПараметры метода

Обязательные параметры отмечены *

Параметр selectПараметр select

Имена полей пишутся в camelCase: title, stageId, assignedById. Состав полей у каждого типа объекта свой, описания полей — на страницах:

• поля сделки
• поля лида
• поля контакта
• поля компании
• поля предложения
• поля счета
• поля моей компании
• поля смарт-процесса

Список полей возвращает метод crm.<тип>.field.list.

Элементы в ответе содержат только поля из select. Поле id не добавляется автоматически — передайте его в списке, если оно нужно в ответе. Пустой массив [] возвращает элементы пустыми массивами. Звездочка * не поддерживается.

Связанные объекты запрашиваются по имени поля без суффикса Id: assignedBy, stage, category, company. Есть два способа:

• имя связанного объекта целиком, например assignedBy, возвращает все поля объекта
• путь через точку, например assignedBy.firstName, stage.name или company.title, возвращает только выбранные поля

Путь допускает одну точку: company.assignedBy.firstName вызывает ошибку неизвестного поля. У сотрудников — assignedBy, createdBy и других — имя хранится в полях firstName и lastName, поля name нет. Подробнее о связанных полях — в обзоре REST 3.0.

Пользовательские поля передаются по имени, например UF_CRM_1687529546. Их список возвращает метод crm.<тип>.field.custom.list.

Неизвестное поле в select — у самого элемента или у связанного объекта — вызывает ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION. Метод не пропускает такое поле молча.

Параметр filterПараметр filter

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

• ["поле", "оператор", значение] — например ["opportunity", ">=", 10000]
• ["поле", значение] — оператор =, а для значения-массива in: ["id", [17, 19]]

Операторы: =, !=, >, >=, <, <=, in, between. Их описание — в обзоре REST 3.0. Других операторов нет: like и поиск по части строки не поддерживаются, ["title", "=", "Поставка"] находит только элементы с точно таким названием.

Фильтровать можно по полям, у которых в ответе crm.<тип>.field.list признак filterable равен true. Значение должно соответствовать типу поля:

Группы условийГруппы условий

Чтобы соединить условия логикой ИЛИ, передайте группу — объект с ключами:

• type — значение filter. Внутри массива filter ключ обязателен: группа без него вызывает ошибку BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION
• logic — and или or, по умолчанию and
• negative — true инвертирует группу: подходят элементы, для которых условие группы не выполнено
• conditions — массив условий и вложенных групп

Пример: элементы воронки 69 с суммой от 10 000, у которых стадия DT1038_69:CLIENT или ответственный — пользователь 1.

{
    "filter": [
        ["categoryId", "=", 69],
        ["opportunity", ">=", 10000],
        {
            "type": "filter",
            "logic": "or",
            "conditions": [
                ["stageId", "=", "DT1038_69:CLIENT"],
                ["assignedById", "=", 1]
            ]
        }
    ]
}

Если весь фильтр — одна группа, ее можно передать объектом вместо массива: "filter": {"logic": "or", "conditions": [...]}. В этом случае type можно не указывать.

Ограничения фильтра:

• вложенность групп — до 8 уровней
• условий и групп в фильтре — до 100
• значений во всех списках in фильтра — до 1000

Связанные поля в фильтреСвязанные поля в фильтре

Условие можно задать по полю связанного объекта через точку:

• поле связанного элемента CRM — ["company.title", "=", "Ромашка"], ["myCompany.title", "=", "Моя компания"], ["contact.name", "=", "Иван"]
• значение телефона, почты, сайта или мессенджера — ["phone.value", "=", "+79990000000"], у сделки — ["contact.phone.value", "=", "+79990000000"]. Для этих полей доступны только операторы = и in
• метка UTM — ["utm.source", "=", "google"], поля source, medium, campaign, content, term
• время последней коммуникации — ["lastCommunication.callTime", ">", "2026-11-01T00:00:00+03:00"]

Поля сотрудников, стадий, воронок и других справочников через точку не фильтруются: ["assignedBy.lastName", "=", "Иванова"] вызывает ошибку BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION. Фильтруйте по идентификатору: assignedById, stageId, categoryId.

Пустые значения и множественные поляПустые значения и множественные поля

Значение null можно передать только с операторами = и != и только для полей, которые бывают пустыми, например companyId, contactId, myCompanyId. Для остальных полей null вызывает ошибку валидации типа.

Пустая привязка к элементу CRM хранится по-разному: в ответе companyId равен null, но в базе может лежать 0. Чтобы найти все элементы без компании, проверяйте оба значения:

{
    "filter": [
        {
            "type": "filter",
            "logic": "or",
            "conditions": [
                ["companyId", "=", 0],
                ["companyId", "=", null]
            ]
        }
    ]
}

Для множественных полей contactsId и observersId доступны только операторы =, != и in. Условие ["contactsId", "in", [5, 7]] находит элементы, к которым привязан хотя бы один из контактов. Для полей-идентификаторов связанных элементов, например contactId, оператор between не поддерживается.

Параметр orderПараметр order

Объект, где ключ — имя поля, а значение — направление сортировки. Сортировать можно по полям, у которых в ответе crm.<тип>.field.list признак sortable равен true. Поля связанных объектов через точку и множественные поля, например contactsId, сортировку не поддерживают.

Возможные значения направления:

• ASC — по возрастанию
• DESC — по убыванию

Регистр направления не важен: asc и ASC работают одинаково.

Если передано несколько полей, элементы сортируются по ним в порядке перечисления: {"stageId": "ASC", "opportunity": "DESC"}. Если id нет в order, метод добавляет его последним ключом с направлением ASC. Поэтому порядок элементов с одинаковыми значениями не меняется между страницами.

Строковые поля сортируются по значению. Например, stageId сортируется по коду стадии, а не по ее положению в воронке.

По умолчанию: {"id": "ASC"}

Параметр paginationПараметр pagination

Другие ключи в pagination вызывают ошибку. Параметр start из предыдущей версии REST метод не учитывает.

Отличия типов объектовОтличия типов объектов

• crm.company.list не возвращает компании из списка «Мои компании». Их получают методом crm.mycompany.list
• crm.deal.list не возвращает шаблоны регулярных сделок. Шаблоны регулярных счетов и смарт-процессов с включенной регулярностью метод тоже пропускает
• у смарт-процесса состав полей зависит от настроек типа: например, без стадий нет stageId, без привязки к клиенту — companyId и contactId. Подробнее — на странице полей смарт-процесса

Примеры кодаПримеры кода

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

Примеры получают элементы смарт-процесса с идентификатором типа 1038 из воронки 69 с суммой от 10 000 — первую страницу по два элемента, по убыванию суммы. Для другого типа объекта замените имя метода по таблице выше.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","title","stageId","opportunity","assignedBy.firstName"],"filter":[["categoryId","=",69],["opportunity",">=",10000]],"order":{"opportunity":"DESC"},"pagination":{"limit":2,"page":1}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.smartprocess1038.list

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["id","title","stageId","opportunity","assignedBy.firstName"],"filter":[["categoryId","=",69],["opportunity",">=",10000]],"order":{"opportunity":"DESC"},"pagination":{"limit":2,"page":1},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/crm.smartprocess1038.list

import { ApiVersion, Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

type ItemListResult = {
  items: {
    id: number
    title: string
    stageId: string
    opportunity: number
    assignedBy: {
      firstName: string
    }
  }[]
}

try {
  const response = await $b24.getHttpClient(ApiVersion.v3).call<ItemListResult>(
    'crm.smartprocess1038.list',
    {
      select: ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
      filter: [
        ['categoryId', '=', 69],
        ['opportunity', '>=', 10000],
      ],
      order: {
        opportunity: 'DESC',
      },
      pagination: {
        limit: 2,
        page: 1,
      },
    },
    Text.getUuidRfc4122()
  )

  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Items:', result.items)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function listItems() {
    try {
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.getHttpClient(B24Js.ApiVersion.v3).call(
        'crm.smartprocess1038.list',
        {
          select: ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
          filter: [
            ['categoryId', '=', 69],
            ['opportunity', '>=', 10000],
          ],
          order: {
            opportunity: 'DESC',
          },
          pagination: {
            limit: 2,
            page: 1,
          },
        },
        B24Js.Text.getUuidRfc4122()
      )

      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Items:', result.items)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', listItems)
</script>

from b24pysdk import Config
from b24pysdk.errors import BitrixSDKException
from b24pysdk.errors.v3 import BitrixAPIError

method = "crm.smartprocess1038.list"
Config().configure(api_v3_methods=Config().api_v3_methods | {method})

try:
    response = bitrix_token.call_method(
        api_method=method,
        params={
            "select": ["id", "title", "stageId", "opportunity", "assignedBy.firstName"],
            "filter": [
                ["categoryId", "=", 69],
                ["opportunity", ">=", 10000],
            ],
            "order": {"opportunity": "DESC"},
            "pagination": {"limit": 2, "page": 1},
        },
        prefer_version=3,
    )
    for item in response["result"]["items"]:
        print(item["id"], item["title"], item["opportunity"])
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}")

try {
    $response = $b24Service
        ->core
        ->call(
            'crm.smartprocess1038.list',
            [
                'select' => ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
                'filter' => [
                    ['categoryId', '=', 69],
                    ['opportunity', '>=', 10000],
                ],
                'order' => [
                    'opportunity' => 'DESC',
                ],
                'pagination' => [
                    'limit' => 2,
                    'page' => 1,
                ],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    print_r($result);
} catch (Throwable $e) {
    echo $e->getMessage();
}

BX24.callMethod(
    'crm.smartprocess1038.list',
    {
        select: ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
        filter: [
            ['categoryId', '=', 69],
            ['opportunity', '>=', 10000],
        ],
        order: {
            opportunity: 'DESC',
        },
        pagination: {
            limit: 2,
            page: 1,
        },
    },
    result => {
        if (result.error())
            console.error(result.error());
        else
            console.dir(result.data());
    }
);

require_once('crest.php');

$result = CRest::call(
    'crm.smartprocess1038.list',
    [
        'select' => ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
        'filter' => [
            ['categoryId', '=', 69],
            ['opportunity', '>=', 10000],
        ],
        'order' => [
            'opportunity' => 'DESC',
        ],
        'pagination' => [
            'limit' => 2,
            'page' => 1,
        ],
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.smartprocess1038.list", b24.Params{
	"select": []string{"id", "title", "stageId", "opportunity", "assignedBy.firstName"},
	"filter": []any{
		[]any{"categoryId", "=", 69},
		[]any{"opportunity", ">=", 10000},
	},
	"order": b24.Params{
		"opportunity": "DESC",
	},
	"pagination": b24.Params{
		"limit": 2,
		"page":  1,
	},
}, b24.WithIdempotent())
if err != nil {
	return fmt.Errorf("crm.smartprocess1038.list: %w", err)
}

raw, ok := b24.Unwrap(res.Result, "items")
if !ok {
	return fmt.Errorf("в ответе нет ключа items")
}

var items []struct {
	ID          int     `json:"id"`
	Title       string  `json:"title"`
	StageID     string  `json:"stageId"`
	Opportunity float64 `json:"opportunity"`
	AssignedBy  struct {
		FirstName string `json:"firstName"`
	} `json:"assignedBy"`
}
if err := json.Unmarshal(raw, &items); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
for _, it := range items {
	fmt.Println(it.ID, it.Title, it.Opportunity)
}

Обработка ответаОбработка ответа

HTTP-статус: 200

{
    "result": {
        "items": [
            {
                "id": 21,
                "title": "Ремонт оргтехники",
                "stageId": "DT1038_69:CLIENT",
                "opportunity": 95000,
                "assignedBy": {
                    "firstName": "Мария"
                }
            },
            {
                "id": 19,
                "title": "Поставка картриджей",
                "stageId": "DT1038_69:PREPARATION",
                "opportunity": 48000,
                "assignedBy": {
                    "firstName": "Мария"
                }
            }
        ]
    },
    "time": {
        "start": 1793706441,
        "finish": 1793706441.814752,
        "duration": 0.8147521018981934,
        "processing": 0,
        "date_start": "2026-11-03T14:47:21+03:00",
        "date_finish": "2026-11-03T14:47:21+03:00",
        "operating_reset_at": 1793706780,
        "operating": 0.14652299880981445
    }
}

Возвращаемые данныеВозвращаемые данные

Обработка ошибокОбработка ошибок

HTTP-статус: 400

{
    "error": {
        "code": "BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION",
        "message": "Не удается распознать выражение фильтра `{\"logic\":\"or\",\"conditions\":[[\"id\",17],[\"id\",\"in\",[21,23]]]}`"
    }
}

Возможные коды ошибокВозможные коды ошибок

Ошибки валидации запросаОшибки валидации запроса

Код ошибки: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

Ошибки фильтраОшибки фильтра

Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION

Неизвестный оператор фильтраНеизвестный оператор фильтра

Код ошибки: BITRIX_REST_V3_EXCEPTION_UNKNOWNFILTEROPERATOREXCEPTION

Ошибка неизвестного поляОшибка неизвестного поля

Код ошибки: BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION

Ошибка формата selectОшибка формата select

Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDSELECTEXCEPTION

Ошибка сортировкиОшибка сортировки

Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDORDEREXCEPTION

Ошибка постраничной навигацииОшибка постраничной навигации

Код ошибки: BITRIX_REST_V3_EXCEPTION_INVALIDPAGINATIONEXCEPTION

Метод не найденМетод не найден

Код ошибки: BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION, HTTP-статус 404

Статусы и коды системных ошибокСтатусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

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

• Элементы CRM в REST 3.0: обзор методов
• Создать элемент CRM v 3.0 crm.<тип>.add
• Изменить элемент CRM v 3.0 crm.<тип>.update
• Получить элемент CRM по идентификатору v 3.0 crm.<тип>.get
• Удалить элемент CRM v 3.0 crm.<тип>.delete
• Посчитать элементы CRM v 3.0 crm.<тип>.aggregate
• Получить описание полей v 3.0 crm.<тип>.field.list