Адреса реквизитов

Где хранятся адреса

Для работы с адресами в коробочном PHP используется \Bitrix\Crm\EntityAddress. Через него можно получить адреса, сохранить адрес нужного типа или удалить адрес.

Адрес привязывается к родительскому объекту через поля ENTITY_TYPE_ID и ENTITY_ID. Для адресов реквизитов родительский объект — это реквизит, а не компания.

Связь с компанией

Чтобы получить адреса компании, обычно нужно сделать два шага: сначала получить реквизиты компании, потом получить адреса этих реквизитов.

Получить адреса компании

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

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\EntityAddress;
use Bitrix\Crm\EntityRequisite;

const CRM_COMPANY_TYPE_ID = \CCrmOwnerType::Company;
const CRM_REQUISITE_TYPE_ID = \CCrmOwnerType::Requisite;

Loader::includeModule('crm');

/**
 * Получает ID реквизитов компании.
 */
function fetchCompanyRequisiteIds(int $company_id): array
{
    $requisite_ids = [];
    $entity_requisite = new EntityRequisite();

    $requisite_result = $entity_requisite->getList([
        'select' => [
            'ID',
        ],
        'filter' => [
            '=ENTITY_TYPE_ID' => CRM_COMPANY_TYPE_ID,
            '=ENTITY_ID' => $company_id,
        ],
        'order' => [
            'SORT' => 'ASC',
            'ID' => 'ASC',
        ],
    ]);

    while ($requisite = $requisite_result->fetch()) {
        $requisite_ids[] = (int) $requisite['ID'];
    }

    return $requisite_ids;
}

/**
 * Получает адреса по ID реквизитов.
 */
function fetchAddressesByRequisiteIds(array $requisite_ids): array
{
    if (empty($requisite_ids)) {
        return [];
    }

    $addresses = [];
    $entity_address = new EntityAddress();

    $address_result = $entity_address->getList([
        'select' => [
            'TYPE_ID',
            'ENTITY_TYPE_ID',
            'ENTITY_ID',
            'ADDRESS_1',
            'ADDRESS_2',
            'CITY',
            'POSTAL_CODE',
            'REGION',
            'PROVINCE',
            'COUNTRY',
            'COUNTRY_CODE',
            'ANCHOR_TYPE_ID',
            'ANCHOR_ID',
        ],
        'filter' => [
            '=ENTITY_TYPE_ID' => CRM_REQUISITE_TYPE_ID,
            '@ENTITY_ID' => $requisite_ids,
        ],
        'order' => [
            'ENTITY_ID' => 'ASC',
            'TYPE_ID' => 'ASC',
        ],
    ]);

    while ($address = $address_result->fetch()) {
        $addresses[] = $address;
    }

    return $addresses;
}

$requisite_ids = fetchCompanyRequisiteIds($company_id);
$addresses = fetchAddressesByRequisiteIds($requisite_ids);

print_r($addresses);

Если нужно получить адреса одного конкретного реквизита, можно сразу фильтровать по ENTITY_TYPE_ID = CCrmOwnerType::Requisite и ENTITY_ID нужного реквизита.

Добавить или изменить адрес

Для сохранения адреса используется EntityAddress::register(). Если адрес такого типа уже был у реквизита, он будет обновлён. Если не был — будет создан.

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\EntityAddress;
use Bitrix\Crm\EntityAddressType;

const CRM_COMPANY_TYPE_ID = \CCrmOwnerType::Company;
const CRM_REQUISITE_TYPE_ID = \CCrmOwnerType::Requisite;

Loader::includeModule('crm');

/**
 * Подготавливает поля адреса реквизита.
 */
function buildRequisiteAddressFields(int $company_id): array
{
    return [
        'ANCHOR_TYPE_ID' => CRM_COMPANY_TYPE_ID,
        'ANCHOR_ID' => $company_id,
        'ADDRESS_1' => 'ул. Ленина, д. 10',
        'ADDRESS_2' => 'офис 15',
        'CITY' => 'Москва',
        'POSTAL_CODE' => '101000',
        'REGION' => '',
        'PROVINCE' => 'Москва',
        'COUNTRY' => 'Россия',
        'COUNTRY_CODE' => 'RU',
    ];
}

/**
 * Сохраняет адрес реквизита.
 */
function saveRequisiteAddress(int $requisite_id, int $address_type_id, array $address_fields): void
{
    if (EntityAddress::isEmpty($address_fields)) {
        return;
    }

    EntityAddress::register(
        CRM_REQUISITE_TYPE_ID,
        $requisite_id,
        $address_type_id,
        $address_fields
    );
}

$address_fields = buildRequisiteAddressFields($company_id);

saveRequisiteAddress(
    $requisite_id,
    EntityAddressType::Registered,
    $address_fields
);

В примере используется тип EntityAddressType::Registered — юридический адрес. Для фактического, почтового или адреса доставки нужно выбрать другой тип.

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

Удаление адреса идёт по комбинации: тип родительской сущности, ID родительской сущности и тип адреса. Для адреса реквизита родительская сущность — реквизит.

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\EntityAddress;
use Bitrix\Crm\EntityAddressType;

const CRM_REQUISITE_TYPE_ID = \CCrmOwnerType::Requisite;

Loader::includeModule('crm');

/**
 * Удаляет адрес реквизита нужного типа.
 */
function deleteRequisiteAddress(int $requisite_id, int $address_type_id): void
{
    EntityAddress::unregister(
        CRM_REQUISITE_TYPE_ID,
        $requisite_id,
        $address_type_id
    );
}

deleteRequisiteAddress($requisite_id, EntityAddressType::Registered);

Перед удалением лучше сначала получить адрес и проверить, что удаляется именно нужный тип адреса.

Основные поля адреса

Типы адресов

Для типов адресов лучше использовать константы \Bitrix\Crm\EntityAddressType, а не числа напрямую.

ANCHOR_TYPE_ID и ANCHOR_ID

У адреса есть родительская сущность и основной родитель. Для адреса реквизита ENTITY_ID указывает на реквизит, а ANCHOR_ID помогает понять, к какой основной CRM-карточке относится этот адрес.

• Bitrix API: Bitrix\Crm\EntityAddress
• Официальная документация D7: EntityAddress
• REST: About Addresses
• REST: crm.address.fields
• REST: crm.enum.addresstype