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

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

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

Scope: crm

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

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

Адреса перемещены в реквизиты. В карточке 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 (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

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

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,"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.address.list

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

// Shape of each AddressItem returned in result[]
type AddressItem = {
  TYPE_ID: string
  ENTITY_TYPE_ID: string
  ENTITY_ID: string
  ADDRESS_1: string
  ADDRESS_2: string
  CITY: string
  POSTAL_CODE: string
  REGION: string
  PROVINCE: string
  COUNTRY: string
  COUNTRY_CODE: string | null
  LOC_ADDR_ID: string
  ANCHOR_TYPE_ID: string
  ANCHOR_ID: string
}

try {
  // crm.address.list returns a single page (max 50 records). For the whole result set
  // use a list helper: $b24.actions.v2.callList.make() returns every record as one
  // array, $b24.actions.v2.fetchList.make() yields them in chunks (async generator).
  // NOTE: the list helpers do not accept `order` (it is excluded from their params, so
  // passing it is a TS error) — keep this call.make + `start` variant when sort matters.
  const response = await $b24.actions.v2.call.make<AddressItem[]>({
    method: 'crm.address.list',
    params: {
      order: { TYPE_ID: 'asc' },
      filter: { ENTITY_TYPE_ID: 8, ENTITY_ID: 7335 },
      start: 0,
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Addresses found:', result.length, result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function fetchAddressList() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      // crm.address.list returns a single page (max 50 records). For the whole result set
      // use a list helper: $b24.actions.v2.callList.make() returns every record as one
      // array, $b24.actions.v2.fetchList.make() yields them in chunks (async generator).
      // NOTE: the list helpers do not accept `order` (it is excluded from their params, so
      // passing it is a TS error) — keep this call.make + `start` variant when sort matters.
      const response = await $b24.actions.v2.call.make({
        method: 'crm.address.list',
        params: {
          order: { TYPE_ID: 'asc' },
          filter: { ENTITY_TYPE_ID: 8, ENTITY_ID: 7335 },
          start: 0,
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

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

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

Пример

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.address.list(
        select=[
            "TYPE_ID",
            "ENTITY_TYPE_ID",
            "ENTITY_ID",
            "ADDRESS_1",
            "ADDRESS_2",
            "CITY",
            "POSTAL_CODE",
            "COUNTRY",
        ],
        filter={
            "ENTITY_TYPE_ID": 8,
            "ENTITY_ID": 7335,
        },
        order={
            "TYPE_ID": "ASC",
        },
        start=0,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

Пример as_list

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.address.list(
        select=[
            "TYPE_ID",
            "ENTITY_TYPE_ID",
            "ENTITY_ID",
            "ADDRESS_1",
            "CITY",
            "COUNTRY",
        ],
        filter={
            "ENTITY_TYPE_ID": 8,
            "ENTITY_ID": 7335,
        },
        order={
            "TYPE_ID": "ASC",
        },
    ).as_list().response
    result = bitrix_response.result
    for item in result:
        print(item)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        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.address.list',
            [
                'order' => ['TYPE_ID' => 'asc'],
                'filter' => ['ENTITY_TYPE_ID' => 8, 'ENTITY_ID' => 7335],
                'limit' => 10,
            ]
        );

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

    echo 'Success: ' . print_r($result, true);

    if ($result->more()) {
        $result->next();
    }

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error fetching address list: ' . $e->getMessage();
}

BX24.callMethod(
    "crm.address.list",
    {
        order: { "TYPE_ID": "asc"},
        filter: { "ENTITY_TYPE_ID": 8, "ENTITY_ID": 7335},
        limit: 10
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
        {
            console.dir(result.data());
            if(result.more())
                result.next();
        }
    }
);

require_once('crest.php');

$result = CRest::call(
    'crm.address.list',
    [
        'order' => ['TYPE_ID' => 'asc'],
        'filter' => ['ENTITY_TYPE_ID' => 8, 'ENTITY_ID' => 7335],
        'limit' => 10
    ]
);

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

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

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
    }
}

Если у контакта 2 разных реквизита, к которым привязаны адреса:

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"
        },
        {
            "TYPE_ID": "1",
            "ENTITY_TYPE_ID": "8",
            "ENTITY_ID": "7335",
            "ADDRESS_1": "Ленина",
            "ADDRESS_2": "2",
            "CITY": "Тюмень",
            "POSTAL_CODE": "666000",
            "REGION": "Тюменская область рег",
            "PROVINCE": "Тюменская область",
            "COUNTRY": "Россия",
            "COUNTRY_CODE": null,
            "LOC_ADDR_ID": "129",
            "ANCHOR_TYPE_ID": "3",
            "ANCHOR_ID": "17192"
        }
    ],
    "total": 2,
    "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
    }
}

Дополнительная информация о результате

Поле ANCHOR_TYPE_ID заполнено значением из crm.enum.ownertype (в примере это Контакты), а поле ANCHOR_ID содержит ID объекта (в данном случае Контакта).

Поля ANCHOR_TYPE_ID и ANCHOR_ID в двух вышеуказанных примерах одинаковы, следовательно, оба адреса относятся к одному Контакту.

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

Название `тип`	Описание
result `array`	Массив объектов с информацией о выбранных адресах. Каждый элемент содержит выбранные поля адресов
total `integer`	Общее количество найденных записей
time `time`	Информация о времени выполнения запроса

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

HTTP-статус: 40x, 50x

{
    "error":0,
    "error_description":"error"
}

Название `тип`	Описание
error `string`	Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только `error_description`
error_description `string`	Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

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

Код	Описание
`Access denied`	Недостаточно прав доступа для получения списка адресов. Нет доступа на чтение компаний, контактов, лидов

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

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

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

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит
`401`	`NO_AUTH_FOUND` Wrong authorization data	В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука
`401`	`INVALID_REQUEST` Https required	Методы вызываются только по протоколу HTTPS
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на `provided by the access token`
`401`	`expired_token` The access token provided has expired	Срок действия access-токена истек
`401`	`user_access_error` The user does not have access to the application	Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям
`403`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Была ли статья полезна?

Изменить адрес реквизита

Удалить адрес

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

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

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

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

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

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

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

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

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

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