метод REST scope: crm

crm.item.list

Получить список элементов

Кто может выполнять: любой пользователь с правом «чтения» элементов объекта CRM

Описание

Метод получает список элементов определенного типа объекта CRM.

Элементы объекта CRM не попадут в итоговую выборку, если у пользователя нет прав на «чтение» этих элементов.

Параметры

entityTypeId integer обязательный

Идентификатор системного или пользовательского типа, чьи элементы нужно получить.

Числовые значения для системных типов (Лид — 1, Сделка — 2, Контакт — 3, Компания — 4, Счет — 31 и др.) приведены в справочнике типов объектов CRM. Идентификатор смарт-процесса можно узнать методом crm.type.list

select array необязательный

Список полей, которые должны быть заполнены у элементов в выборке.

Может содержать в себе только названия полей элемента или '*'.

Список всех доступных полей для выборки можно узнать методом crm.item.fields. Перечень стандартных полей доступен в статье Поля объектов CRM

Поле fm (множественные поля: телефоны, e-mail, мессенджеры) не является полем объекта CRM и не может быть запрошено через select явно. Чтобы получить fm в ответе, передайте select: ['*']

filter object необязательный

Объект формата:

{
    field_1: value_1,
    field_2: value_2,
    ...,
    field_n: value_n,
}

где
- field_n — название поля по которому будет отфильтрована выборка элементов
- value_n — значение фильтра

Фильтр может иметь неограниченную вложенность и количество условий.
По умолчанию все условия соединяются друг с другом как AND (логическое И). Если нужно использовать OR (Логическое ИЛИ), то можно передать специальный ключ logic со значением OR.

К ключам field_n можно добавить префикс, уточняющий работу фильтра.
Возможные значения префикса:
- >= — больше либо равно
- > — больше
- <= — меньше либо равно
- < — меньше
- @ — IN, в качестве значения передается массив
- !@ — NOT IN, в качестве значения передается массив
- % — LIKE, поиск по подстроке. Символ % в значении фильтра передавать не нужно. Поиск ищет подстроку в любой позиции строки
- =% — LIKE, поиск по подстроке. Символ % нужно передавать в значении. Примеры:
- "мол%" — ищет значения, начинающиеся с «мол»
- "%мол" — ищет значения, заканчивающиеся на «мол»
- "%мол%" — ищет значения, где «мол» может быть в любой позиции
- %= — LIKE (аналогично =%)
- !% — NOT LIKE, поиск по подстроке. Символ % в значении фильтра передавать не нужно. Поиск идет с обеих сторон
- !=% — NOT LIKE, поиск по подстроке. Символ % нужно передавать в значении. Примеры:
- "мол%" — ищет значения, не начинающиеся с «мол»
- "%мол" — ищет значения, не заканчивающиеся на «мол»
- "%мол%" — ищет значения, где подстроки «мол» нет в любой позиции
- !%= — NOT LIKE (аналогично !=%)
- = — равно, точное совпадение (используется по умолчанию)
- != — не равно
- ! — не равно

Список всех доступных полей для фильтрации можно узнать методом crm.item.fields. Перечень стандартных полей доступен в статье Поля объектов CRM

Для фильтрации по пользовательским полям типа boolean передавайте в filter значения 1 или 0, даже если при получении или изменении элемента значение такого поля передается в формате Y или N. Например, для поля ufCrm2_1234567890 используйте фильтр {"ufCrm2_1234567890": 1}. Формат Y или N в фильтре для пользовательских полей типа boolean не поддерживается.

order object необязательный

Объект формата:

{
    field_1: value_1,
    field_2: value_2,
    ...,
    field_n: value_n,
}

где
- field_n — название поля по которому будет произведена сортировка выборки элементов
- value_n — значение типа string равное:
- ASC — сортировка по возрастанию
- DESC — сортировка по убыванию

Список всех доступных полей для сортировки можно узнать методом crm.item.fields. Перечень стандартных полей доступен в статье Поля объектов CRM

start integer необязательный

Параметр используется для управления постраничной навигацией.

Размер страницы результатов всегда статичный — 50 записей.

Чтобы выбрать вторую страницу результатов, передайте значение 50. Чтобы выбрать третью страницу результатов — значение 100 и так далее.

Формула расчета значения параметра start:

start = (N-1) * 50, где N — номер нужной страницы

useOriginalUfNames boolean необязательный

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

  • Y — оригинальные имена пользовательских полей, например UF_CRM_2_1639669411830
  • N — имена пользовательских полей в camelCase, например ufCrm2_1639669411830

По умолчанию — N

Примеры запроса

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"entityTypeId":1,"select":["id","title","lastName","name","stageId","sourceId","assignedById","opportunity","isManualOpportunity"],"filter":{"0":{"logic":"OR","0":{"!=name":""},"1":{"!=lastName":""}},"@stageId":["NEW","IN_PROCESS"],"@sourceId":["WEB","ADVERTISING"],"@assignedById":[1,6],">=opportunity":5000,"<=opportunity":20000,"isManualOpportunity":"Y"},"order":{"lastName":"ASC","name":"ASC"}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.item.list

Ответ

HTTP-статус: 200

{
    "result": {
        "items": [
            {
                "id": 253,
                "assignedById": 6,
                "stageId": "NEW",
                "opportunity": 19000,
                "sourceId": "WEB",
                "title": "Лид #253",
                "name": "Админ",
                "lastName": null,
                "isManualOpportunity": "Y"
            },
            {
                "id": 255,
                "assignedById": 1,
                "stageId": "NEW",
                "opportunity": 19600,
                "sourceId": "WEB",
                "title": "Лид #255",
                "name": "Иван",
                "lastName": "Иванов",
                "isManualOpportunity": "Y"
            },
            {
                "id": 252,
                "assignedById": 1,
                "stageId": "NEW",
                "opportunity": 12000,
                "sourceId": "ADVERTISING",
                "title": "Лид #252",
                "name": "Иван",
                "lastName": "Котов",
                "isManualOpportunity": "Y"
            },
            {
                "id": 254,
                "assignedById": 6,
                "stageId": "IN_PROCESS",
                "opportunity": 19000,
                "sourceId": "ADVERTISING",
                "title": "Лид #254",
                "name": "Кот",
                "lastName": "Котов",
                "isManualOpportunity": "Y"
            }
        ]
    },
    "total": 4,
    "time": {
        "start": 1721724354.214286,
        "finish": 1721724354.805263,
        "duration": 0.5909769535064697,
        "processing": 0.24513697624206543,
        "date_start": "2024-07-23T10:45:54+02:00",
        "date_finish": "2024-07-23T10:45:54+02:00",
        "operating": 0
    }
}

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

result object

Корневой элемент ответа. Содержит единственный ключ items

items item[]

Массив c информацией о найденных элементах.

Возвращаемые поля зависят от параметра select, описание полей

total integer

Общее количество найденных элементов

next integer

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

Параметр next появляется в ответе, если количество элементов, соответствующих вашему запросу, превышает значение 50.

time time

Информация о времени выполнения запроса

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

HTTP-статус: 400

{
    "error": "INVALID_ARG_VALUE",
    "error_description": "Invalid filter: field 'FIELD' is not allowed in filter"
}
Код Описание Значение
403 allowed_only_intranet_user Действие разрешено только интранет-пользователям
400 NOT_FOUND Смарт-процесс не найден
400 INVALID_ARG_VALUE Invalid filter: field 'field' is not allowed in filter
400 INVALID_ARG_VALUE Invalid filter: field 'field' has invalid value
400 INVALID_ARG_VALUE Invalid order: field 'field' is not allowed in order
400 INVALID_ARG_VALUE Invalid order: allowed sort directions are ASC, DESC. But got 'orderValue' for field 'field'

Что будем искать? Например,Продвижение

Этот сайт использует куки-файлы. Оставаясь на сайте, Вы соглашаетесь на их использование. Для получения дополнительной информации, пожалуйста, ознакомьтесь с политикой в отношении персональных данных.