Сложности с разделами каталога в Битрикс24 через REST API: игра с деревом

Привет! Меня зовут Артём, я бэкенд-разработчик. Перейдем от сделок к каталогу. Если вы интегрируете интернет-магазин (например, на той же 1С-Битрикс) с облаком Битрикс24 CRM, вам предстоит столкнуться с деревом разделов (папок).

Задача кажется тривиальной: есть папка «Смартфоны» (ID 15). При создании товара через crm.product.add мы передаем:

'fields' => [
    'NAME' => 'iPhone 15',
    'SECTION_ID' => 15
]

Иногда это работает. А иногда товар просто пропадает из каталога — он создается, но ни в одной папке не отображается. Почему?

Проблема левел-аффилиации (IBLOCK_SECTION_ID)

Модуль «Товары» в облаке Битрикс24 — это легаси от классических инфоблоков 1С-Битрикс. В инфоблоках разделы образуют дерево. У раздела может быть родитель.

Поле SECTION_ID в REST API на самом деле ожидает не просто ID, а специфическую логику принадлежности к уровню дерева. Если вы попытаетесь положить товар в подраздел, не привязав его к корневому разделу, или если вы передадите ID раздела из другого каталога (в Битриксе может быть несколько товарных каталогов, например для разных юрлиц), API молча проигнорирует привязку, чтобы не сломать SQL-структуру.

Как безопасно привязать товар к разделу

Никогда не слепо верьте ID папок, которые вам дают менеджеры или которые лежат в вашей CMS. Перед обновлением товара сделайте валидацию:

$targetSectionId = 15;

// Проверяем, существует ли этот раздел в текущем каталоге
$sections = $this->call('crm.catalog.section.list', [
    'filter' => ['ID' => $targetSectionId],
    'select' => ['ID', 'NAME']
]);

if (empty($sections['data'])) {
    $this->writeLog("Ошибка: Раздел $targetSectionId не найден в каталоге!");
    // Создаем раздел на лету? Или кидаем товар в корень (SECTION_ID = 0 или null)
    $targetSectionId = 0; 
}

// Только теперь обновляем товар
$this->call('crm.product.update', [
    'id' => $productId,
    'fields' => [
        'SECTION_ID' => $targetSectionId
    ]
]);

Если вы передадите SECTION_ID равным 0 или null, товар будет лежать в корне каталога. Это гораздо лучше, чем потерять товар в черной дыре несовпадения ID разделов.

И еще одна боль: REST API Битрикс24 не имеет метода создания разделов каталога (crm.catalog.section.add существует только в коробочной версии и недоступен в облаке). Если вам нужно создать новую папку из PHP, вам придется писать костыль через универсальный crm.item.add к Smart-процессу каталога, что превращается в ад. Поэтому всегда заставляйте менеджеров создавать структуру папок руками в Битриксе, а ваш код пусть только валидирует и раскладывает товары по существующим ячейкам.