Как добавить новые файлы в пользовательское поле сделки Битрикс24, сохранив существующие

При работе с коробочной версией Битрикс24 возникает задача: добавить новые файлы в пользовательское поле сделки, имеющее тип "Файл" с множественным выбором, при этом не удаляя уже загруженные документы.

Стандартный подход через API часто приводит к перезаписи поля, когда новые файлы замещают старые. Для корректного решения необходимо объединить идентификаторы существующих файлов с данными новых.

Алгоритм решения

Процесс состоит из нескольких ключевых шагов:

• Получение текущих данных сделки: Загрузите информацию о сделке, включая массив с идентификаторами уже прикрепленных файлов.
• Подготовка массива для обновления: Создайте новый массив, который будет содержать как старые ID файлов, так и данные новых файлов в специальном формате.
• Формирование данных для новых файлов: Каждый новый файл должен быть представлен в виде массива с ключом fileData, содержащего имя файла и его содержимое в кодировке base64.
• Вызов метода обновления: Передайте сформированный объединенный массив в поле при обновлении сделки.

Пример реализации на PHP

Ниже представлен рабочий код, который решает поставленную задачу. Предполагается, что у вас уже подключена библиотека CRest.

require_once(__DIR__.'/crest.php');

// Пути к новым файлам для добавления
$filePaths = [
    __DIR__ . '/filesForTest/test.docx',
    __DIR__ . '/filesForTest/test2.docx',
];

// Получаем данные сделки
$deal = CRest::call('crm.deal.get', [
    'id' => 159
]);

// Извлекаем массив ID существующих файлов из пользовательского поля
$existingFiles = $deal['result']['UF_CRM_1766393619832'] ?? [];

// Инициализируем массив для итогового обновления
$filesForUpdate = [];

// Добавляем ID старых файлов
foreach ($existingFiles as $fileId) {
    $filesForUpdate[] = $fileId;
}

// Подготавливаем и добавляем новые файлы
foreach ($filePaths as $path) {
    if (!file_exists($path)) {
        continue; // Пропускаем несуществующие файлы
    }
    // Формируем массив в формате, ожидаемом API Битрикс24
    $filesForUpdate[] = [
        'fileData' => [
            basename($path),
            base64_encode(file_get_contents($path))
        ]
    ];
}

// Выполняем обновление сделки с объединенным списком файлов
$result = CRest::call('crm.deal.update', [
    'id' => 159,
    'fields' => [
        'UF_CRM_1766393619832' => $filesForUpdate
    ]
]);

// Для отладки можно вывести сформированный массив
echo '<pre>';
print_r($filesForUpdate);
echo '</pre>';

Ключевые моменты

• Формат данных: API Битрикс24 требует передавать существующие файлы как их числовые ID, а новые - как вложенные массивы fileData.
• Проверка существования файлов: Код включает проверку file_exists для избежания ошибок.
• Идентификатор поля: Замените UF_CRM_1766393619832 на код вашего конкретного пользовательского поля.
• ID сделки: Укажите актуальный ID вашей сделки вместо значения 159.

Этот подход гарантирует, что все ранее загруженные файлы останутся в поле, а новые будут добавлены к ним.