Работа с файлами через REST

Файлы в REST Битрикс24 передаются двумя способами: инлайн через base64 в параметрах метода и через механизм Диска с временным uploadUrl. Первый прост, но упирается в размер запроса; второй сложнее, зато подходит для крупных файлов.

Инлайн-загрузка через base64

Самый простой способ — передать содержимое файла закодированным в base64 прямо в параметрах метода. Многие сущности принимают файловое поле в виде массива из двух элементов: [имя_файла, base64-содержимое].

Например, добавление комментария к делу CRM с вложением или запись в пользовательское файловое поле выглядит так:

crm.deal.update?id=42&fields[UF_CRM_FILE][0]=scan.pdf&fields[UF_CRM_FILE][1]=JVBERi0xLjQK...

Клиент кодирует файл функцией уровня base64_encode() и подставляет результат вторым элементом. Способ хорош для небольших вложений: сканов, изображений, документов в пределах допустимого размера запроса.

Загрузка на Диск через uploadUrl

Для больших файлов используется двухшаговая схема Диска Битрикс24. Она разделяет получение адреса загрузки и саму передачу байтов, что снимает ограничение на размер тела REST-запроса.

1. Вызываете метод загрузки папки Диска — например, disk.folder.uploadfile — и получаете в ответе временный uploadUrl.
2. Отправляете файл обычным multipart/form-data POST-запросом на этот uploadUrl.
3. В ответ приходит объект файла Диска с его ID, который затем можно привязать к задаче, сделке или сообщению.

Чтобы получить хранилище приложения, используют disk.storage.getforapp, а список папок — disk.storage.getchildren. Файл, загруженный на Диск, живёт как полноценный объект и переиспользуется по ID.

Какой способ выбрать

Правило простое: мелкие вложения (сканы, аватары, короткие документы) — через base64; всё, что рискует превысить лимит тела запроса, — через Диск.

Вложения в задачах и CRM

Разные модули принимают файлы по-своему, и важно знать конкретное поле:

• Задачи. Файлы задачи хранятся на Диске и привязываются через поле UF_TASK_WEBDAV_FILES. В tasks.task.add передают массив ID файлов Диска в формате n[id].
• CRM. Пользовательские файловые поля (UF_CRM_*) принимают массив [имя, base64]. Файлы дел и таймлайна прикрепляют через соответствующие методы активности.
• Мессенджер и Открытые линии. Файлы отправляют как объекты Диска, ссылаясь на их ID.

Перед привязкой файла к задаче убедитесь, что у пользователя есть права на папку Диска, иначе привязка завершится ошибкой доступа.

Получение и скачивание файлов

На чтение файловые поля возвращают либо ссылку для скачивания, либо объект с URL. Списочные методы CRM отдают файловые поля свёрнутыми — часто нужен отдельный вызов, чтобы получить прямой адрес.

Для Диска применяют disk.file.get, который возвращает объект с полем DOWNLOAD_URL. Ссылка временная и уже содержит авторизацию, поэтому качать по ней нужно относительно быстро.

Частые ошибки при работе с файлами

Наиболее распространённые проблемы и их причины:

• Слишком большой файл через base64. Запрос упирается в лимит тела — переходите на Диск.
• Битая кодировка. Забытый или неверный base64_encode, лишние переносы строк в строке — файл не распознаётся.
• Нет прав на папку Диска. Привязка файла к задаче/сделке падает по доступу.
• Просроченный uploadUrl. Временный адрес загрузки имеет короткий срок жизни — получайте его непосредственно перед отправкой.
• Тайм-аут на крупном файле. Длинная загрузка прерывается по времени — дробите или используйте Диск.

Итог

Работа с файлами в REST Битрикс24 сводится к выбору между простым инлайн-base64 для небольших вложений и двухшаговой загрузкой на Диск через uploadUrl для крупных. Помните про раздувание base64 на треть, ограничение тела запроса, права на папки Диска и короткий срок жизни ссылок скачивания.

Мы в B2Bsite настраиваем обмен документами и файлами между Битрикс24, сайтом и учётными системами так, чтобы вложения надёжно доходили и не упирались в лимиты. Если у вас теряются сканы, договоры или изображения при синхронизации — разберём и починим файловый обмен.