метод REST scope: crm

crm.address.list

Получить список адресов по фильтру

Кто может выполнять: пользователь с правом на чтение контактов, компаний и лидов

Описание

Метод возвращает список адресов по фильтру.

Адреса перемещены в реквизиты. В карточке CRM они имеют отображение в виде отдельного поля.

К объекту CRM могут быть привязаны несколько реквизитов. Внутри реквизита может быть несколько адресов (каждый своего типа).

Параметры

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

Массив со списком полей, которые необходимо выбрать (смотрите поля адресов).

Если массив не передан или же передан пустой массив, то будут выбраны все доступные поля адресов

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

Объект для фильтрации выбранных адресов в формате {"field_1": "value_1", ... "field_N": "value_N"}.

Возможные значения для field соответствуют полям адреса.

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

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

Объект для сортировки выбранных адресов в формате {"field_1": "order_1", ... "field_N": "order_N"}.

Возможные значения для field соответствуют полям адреса.

Возможные значения для order:
- asc — в порядке возрастания
- desc — в порядке убывания

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

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

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

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

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

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

Описание полей адреса

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

Идентификатор типа адреса. Элемент перечисления «Тип адреса».

Элементы перечисления «Тип адреса» можно получить с помощью метода crm.enum.addresstype

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

Идентификатор типа родительского объекта.

Идентификаторы типов объектов можно получить с помощью метода crm.enum.ownertype.

Адреса могут быть привязаны только к Реквизитам (а реквизиты уже к компаниям либо контактам) или Лидам.

Для обратной совместимости оставлена возможность связывать Адреса с Контактами или Компаниями. Но эта связь возможна только на некоторых старых порталах, где специально техподдержкой был включен старый режим работы с адресами

ENTITY_ID string необязательный

Идентификатор родительского объекта

ADDRESS_1 string необязательный

Улица, дом, корпус, строение

ADDRESS_2 string необязательный

Квартира / офис

CITY string необязательный

Город

POSTAL_CODE string необязательный

Почтовый индекс

REGION string необязательный

Район

PROVINCE string необязательный

Область

COUNTRY string необязательный

Страна

COUNTRY_CODE string необязательный

Код страны.

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

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

Идентификатор адреса местоположения.

Это поле содержит идентификатор объекта адреса в модуле Location, связанного с объектов адреса CRM. Каждому адресу CRM соответствует объект адреса в модуле location. Это можно использовать для копирования существующего адреса в CRM с информацией о местоположении, которой нет в полях адреса CRM.

Если при создании адреса указан идентификатор адреса модуля location, то создается копия адреса location и привязывается к созданному адресу CRM. Если в таком случае не указаны значения для строковых полей адреса, то они будут заполнены из location-адреса.

Если же было указано хоть одно строковое поле, то в адресе CRM будут сохранены только указанные поля, и их значения перезапишут соответствующие значения в объекте location-адреса. Такое же поведение будет и при обновлении адреса

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

Идентификатор типа основного родительского объекта.

Это поле для служебного использования. Значение заполняется автоматически при добавлении адреса.

Идентификаторы типов объектов можно получить с помощью метода crm.enum.ownertype.

В этом поле содержится идентификатор типа родительского объекта реквизита (компания или контакт), если адрес привязан к реквизиту. Если адрес привязан к лиду, то этим значением будет идентификатор типа лид

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

Это поле для служебного использования. Значение заполняется автоматически при добавлении адреса.

В этом поле содержится идентификатор родительского объекта реквизита (компании или контакта), если адрес привязан к реквизиту. Если адрес привязан к лиду, то этим значением будет идентификатор лида

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

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"order":{"TYPE_ID":"asc"},"filter":{"ENTITY_TYPE_ID":8,"ENTITY_ID":7335},"limit":10}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.address.list

Ответ

HTTP-статус: 200

{
    "result": [
        {
            "TYPE_ID": "1",
            "ENTITY_TYPE_ID": "8",
            "ENTITY_ID": "7335",
            "ADDRESS_1": "Ленина 2",
            "ADDRESS_2": "701",
            "CITY": "Тюмень",
            "POSTAL_CODE": "625003",
            "REGION": "Тюменская обл",
            "PROVINCE": "Тюменская обл",
            "COUNTRY": "Россия",
            "COUNTRY_CODE": null,
            "LOC_ADDR_ID": "479",
            "ANCHOR_TYPE_ID": "3",
            "ANCHOR_ID": "17192"
        }
    ],
    "total": 1,
    "time": {
        "start": 1716301758.664873,
        "finish": 1716301759.73158,
        "duration": 1.0667071342468262,
        "processing": 0.028820037841796875,
        "date_start": "2024-05-21T16:29:18+02:00",
        "date_finish": "2024-05-21T16:29:19+02:00",
        "operating": 0
    }
}

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

result array

Массив объектов с информацией о выбранных адресах. Каждый элемент содержит выбранные поля адресов

total integer

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

time time

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

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

{
    "error":0,
    "error_description":"error"
}
Код Описание Значение
Access denied Недостаточно прав доступа для получения списка адресов. Нет доступа на чтение компаний, контактов, лидов

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

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