Гайд по добавлению адресов при создании компаний и контактов в Битрикс24 через REST API

К сущности Контакт или Компания в Битрикс24 могут быть прикреплены реквизиты. У одной сущности может быть 0 или несколько реквизитов. Банковские реквизиты при этом являются отдельным разделом и прикрепляются к общим реквизитам. Аналогично реквизитам у сущности банковские реквизиты, привязаны к общим реквизитам сущности. Банковских реквизитов может быть 0 или несколько.

Работа с реквизитами требует некоторых знаний, которыми мы с вами сейчас поделимся. Итак, наша задача - прикрепить к компании/контакту несколько адресов разного типа.

Допустимые типы жестко заданы, добавить свои типы нельзя. В справке метод, возвращающий список типов, размещен по пути CRM > Вспомогательные сущности > Перечисления > crm.enum.addresstype

На данный момент существует четыре типа:

• фактический адрес,

• адрес регистрации,

• юридический адрес,

• адрес бенефициара.

Методы работы с адресами размещаются по пути CRM > Реквизиты > Методы

Смотрим состав полей адреса (CRM > Реквизиты > Структура таблиц) и видим, что адрес привязывается к своему владельцу через два поля: ENTITY_TYPE_ID - ID типа сущности и ENTITY_ID - ID этой самой сущности. Идентификаторы типов мы получаем запросом crm.enum.ownertype.

Переходим к реквизитам. Смотрим поля таблицы реквизита (CRM > Реквизиты > Структура таблиц) и видим, что помимо тех же самых ENTITY_TYPE_ID и ENTITY_ID есть еще обязательное поле - PRESET_ID - идентификатор шаблона, по которому создается реквизит.

Шаблон реквизита создается методом crm.requisite.preset.add (CRM > Реквизиты > Методы). Среди обязательных полей видим ENTITY_TYPE_ID. Поскольку мы создаем шаблон для реквизита, указываем в нем его тип (равен 8). Теперь по данному шаблону можно создавать сам реквизит, но, чтобы в нашем реквизите отображался адрес (в интерфейсе портала), в шаблоне должно присутствовать поле типа адрес.

Казалось бы, поля к шаблону добавлять можно, для этого есть метод crm.requisite.preset.field.add. И для того, чтобы добавить именно адрес надо в поле FIELD_NAME указать код RQ_ADDR. Но нет, API в ответ говорит нам, что мы не можем добавлять такое поле. Получается, что создание своего шаблона теряет всякий смысл. Остается при создании реквизита выбрать подходящий из уже имеющихся на портале шаблонов. Существует отдельный шаблон для компаний и отдельный - для контактов. Вот только различить их можно исключительно по языкозависимому названию шаблона.

Полная схема привязки адресов к компаниям (контактам)

Создаем (если нужно) компанию - crm.company.add - в result возвращается идентификатор компании. (В примерах использована функция отправки rest-запроса, встречающаяся периодически в публикациях разработчиков, есть в примере эхо-бота)

$result = restCommand('crm.company.add', array(
   'TITLE'=>'My new company',
));
$newCompanyId = intval($result['result']);
Получаем идентификаторы: crm.requisite.preset.list, crm.enum.ownertype, crm.enum.addresstype - собственно, кроме шаблона, можно узнать идентификаторы один раз и затем использовать как константы, поскольку на всех порталах они одинаковы.
define('REQUSITE_OWNER_TYPE', 8);
define('CONTACT_OWNER_TYPE', 3);
define('COMPANY_OWNER_TYPE', 4);

define('STREET_ADDR', 1); // фактический
define('REG_ADDR', 4); // регистрации
define('LEG_ADDR', 6); // юридический
define('BEN_ADDR', 9); // бенефициара

$result = restCommand('crm.requisite.preset.list', array(
   'filter'=> array('NAME'=>'Организация'),
));
$organizationPresetId = intval($result[0]['ID']);

Создаем реквизит - crm.requisite.add. При этом в поле ENTITY_TYPE_ID для реквизита компании указываем 4, контакта - 3. PRESET_ID указываем тот, что каким-либо образом определили в списке доступных шаблонов.

$result = restCommand('crm.requisite.add', array(
   'fields'=>array(
         'ENTITY_TYPE_ID'=>COMPANY_OWNER_TYPE, // компания
         'ENTITY_ID'=>$newCompanyId,
         'PRESET_ID'=>$organizationPresetId,
         'NAME'=>'Адреса компании',
         'ACTIVE'=>'Y',
   ),
));
$newRequisiteId = intval($result['result']);

И вот, наконец, добавляем к реквизиту адрес(а) конкретного типа - crm.address.add. При этом в поле ENTITY_TYPE_ID указываем 8 (идентификатор типа "реквизит"), а в поле ENTITY_ID - идентификатор созданного нами реквизита. При выборке через rest api адресов мы видим, что в адресе присутствуют еще два интересных поля: ANCHOR_ID и ANCHOR_TYPE_ID. И они заполнены соответственно идентификатором нашей компании и типом сущности "компания" (когда реквизит относится к компании). Метод crm.address.fields говорит нам, что эти поля необязательные. Может так оно и есть, и все сработает и без указания нашей компании, но мы, на всякий случай, их заполняем.

$result = restCommand('crm.address.add', array(
   'fields'=>array(
         'TYPE_ID'=>STREET_ADDR, // фактический адрес
         'ENTITY_TYPE_ID'=>REQUSITE_OWNER_TYPE, // реквизит
         'ENTITY_ID'=>$newRequisiteId,
         'ADDRESS_1'=>'Цветочная стрит, 16',
         'CITY'=>'Берн',
   ),
));

Проверяем добавление. Идем в карточку нашей компании, прокручиваем страницу и среди табов, размещенных внизу страницы, находим "Реквизиты", открываем. В списке должен быть наш реквизит, кликаем по его названию. В popup-е должны появиться наши адреса. Если этого не случилось, значит шаблон, который мы указали при создании реквизита, не содержит поля типа "адрес". Программно такое поле добавить нельзя, но вручную - можно. Как только вы его добавите, в реквизитах появятся наши адреса.

Функции для работы с реквизитами и ссылки на документацию

Если требуется проверить, есть у сущности реквизит

filter: {"ENTITY_TYPE_ID":___, "ENTITY_ID": ___}

ENTITY_TYPE_ID — тип сущности из справочника 1 — Лид, 2 — Сделка, 3 — Контакт, 4 — Компания.

ENTITY_ID — ид сущности

Результатом будет или список реквизитов привязанных к данной сущности или пустой список.

Добавление реквизита к сущности

crm.requisite.add

"fields":{"ENTITY_TYPE_ID":__, "ENTITY_ID":__, "PRESET_ID":__, "NAME":"Реквизит", "ACTIVE":"Y", "SORT":"100"}

PRESET_ID — id шаблона реквизита, 1 — Организация, 2 — ИП, 3 — Про работу с реквизитами физического лица можно подробнее узнать тут

Если есть реквизиты, то выбрать нужный и по id получить детальные данные о реквизите

"id":__

id реквизита сущности полученный из запроса crm.requisite.list. После выполнения, выводит все поля реквизита.

Для выбора банковского реквизита достаточно ID реквизита прикрепленного к сущности

Проверка, что в реквизите есть банковский реквизит

crm.requisite.bankdetail.list

filter: {"ENTITY_ID":__}

ENTITY_ID — id реквизита, привязанного к сущности

Данный запрос покажет список банковских реквизитов, прикрепленных к реквизиту, прикрепленному к сущности. ID из этого запроса нужен для обновления банковских реквизитов.

Добавление банковского реквизита к реквизиту привязанного к сущности

crm.requisite.bankdetail.add

"fields":{"ENTITY_ID":__,"COUNTRY_ID":1,"NAME":"Реквизит банка","ACTIVE":"Y","SORT":100}

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

Для обновления банковского реквизита надо выполнить этот метод. Надо выбрать id банковского реквизита и передать обновляемые поля.

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

Там есть события изменения банковских реквизитов, удаление реквизитов.