Как привязать новый контакт к сделке в Битрикс24 через REST API

Привет! Меня зовут Артём, я бэкенд-разработчик. Кажется, что может быть проще, чем связать контакт и сделку в CRM? В Битрикс24 это сплошные грабли, если делать это динамически через REST API.

Стандартный подход, который предлагают в простых статьях:

// 1. Создаем контакт
$contact = $this->call('crm.contact.add', ['fields' => ['NAME' => 'Иван', 'PHONE' => [['VALUE' => '123']]]]);
$contactId = $contact['result'];

// 2. Создаем сделку и сразу привязываем контакт
$deal = $this->call('crm.deal.add', [
    'fields' => [
        'TITLE' => 'Сделка Ивана',
        'CONTACT_ID' => $contactId // Передаем ID только что созданного контакта
    ]
]);

Сделка создается. Но если вы зайдете в нее в браузере, вы увидите, что контакт Ивана там не отображается в верхнем блоке привязок! Хотя в ответе API поле CONTACT_ID вернулось с правильным числом. Почему?

Разница между полем и сущностью-связкой

В старых версиях Битрикса сделка и контакт были жестко связаны через поле CONTACT_ID в одной таблице. Сейчас сделка может иметь множество контактов. Связь живет в отдельной таблице биндингов.

Когда вы передаете CONTACT_ID при создании сделки, ядро Битрикса пытается создать биндинг «на лету». Но если вы создали контакт только что (микросекунду назад), кэши прав доступа или внутренние триггеры могут не успеть отработать, и биндинг молча не создастся. Поле в базе запишется, но интерфейс его проигнорирует, так как в таблице связей записи нет.

Надежный метод: Явное создание связи

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

$dealId = 123;
$contactId = 456;

$this->call('crm.deal.contact.add', [
    'id' => $dealId,
    'fields' => [
        'CONTACT_ID' => $contactId,
        'IS_PRIMARY' => 'Y' // Указываем, что это основной контакт сделки
    ]
]);

Метод crm.deal.contact.add напрямую пишет в таблицу связей. Он 100% надежен. Да, это лишний запрос к API. Но это единственный способ быть уверенным, что менеджер увидит контакты в карточке сделки.

Бонус: если вам нужно привязать несколько контактов к уже существующей сделке, вместо цикла с add используйте метод crm.deal.contact.items.set. Он принимает массив всех контактов и полностью перезаписывает связи за один вызов.