REST: disk.folder.uploadfile

Метод disk.folder.uploadfile загружает файл в конкретную папку Битрикс24.Диска. Он поддерживает два режима: передачу содержимого сразу в base64 и двухшаговую загрузку через временный uploadUrl — второй незаменим для больших файлов. Разбираем оба сценария.

Структура Диска и папки

Битрикс24.Диск устроен иерархически: есть хранилища (storage) — личные, групповые, общий диск компании, — а внутри них папки и файлы. Чтобы загрузить файл, нужен идентификатор целевой папки.

• disk.storage.getlist — список доступных хранилищ;
• disk.storage.getchildren — содержимое хранилища (папки и файлы верхнего уровня);
• disk.folder.getchildren — содержимое папки;
• disk.folder.addsubfolder — создать подпапку.

Метод disk.folder.uploadfile принимает id папки, куда кладётся файл. Именно у папки, а не у хранилища.

Способ 1: передача base64

Простой вариант — передать содержимое файла прямо в запросе через параметр fileContent (массив из имени файла и base64):

POST https://portal.bitrix24.ru/rest/1/xxxxx/disk.folder.uploadfile.json

Параметр id — идентификатор папки, data[NAME] — итоговое имя файла на Диске, fileContent — имя и содержимое в base64. В ответ приходит объект файла с полями ID, NAME, DOWNLOAD_URL и другими.

Способ 2: двухшаговая загрузка

Для больших файлов сначала запрашивают адрес загрузки, а затем отправляют туда сам файл обычным multipart-запросом:

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

Этот путь не гоняет base64 через основной REST-эндпоинт и обходит ограничение на размер тела. Он аналогичен загрузке версий (disk.file.uploadversion) и другим файловым операциям Диска.

Что возвращает метод

Успешный ответ содержит объект файла Диска. Основные поля:

По полученному ID файл можно получить через disk.file.get, переименовать, переместить или удалить, а также прикрепить к сущностям через механизм присоединённых объектов.

Связанные методы Диска

Загрузка редко существует изолированно. Рядом обычно используются:

• disk.file.get — получить метаданные файла;
• disk.file.uploadversion — загрузить новую версию существующего файла;
• disk.file.markdeleted / disk.file.restore — удаление в корзину и восстановление;
• disk.folder.addsubfolder — создать целевую папку перед загрузкой;
• disk.attachedObject.get — работа с прикреплёнными к задачам и записям файлами.

Типовой сценарий интеграции: создать папку под сделку → загрузить туда документы → отдать пользователю DETAIL_URL или прикрепить файл к задаче.

Практика и ошибки

1. Права disk. Методам Диска нужно разрешение disk у вебхука или приложения.
2. Права на папку. Даже с общим правом disk загрузка в чужую папку требует прав доступа к ней у пользователя, от имени которого работает вебхук.
3. Имя файла. Задавайте data[NAME] с расширением — от него зависит определение типа и предпросмотр.
4. Дубли имён. При совпадении имён Диск может создать копию с суффиксом; для обновления содержимого используйте disk.file.uploadversion.
5. Срок жизни uploadUrl. Временный адрес действует ограниченное время — отправляйте файл сразу после получения ссылки.

Итог

Метод disk.folder.uploadfile кладёт файл в папку Битрикс24.Диска двумя способами: быстрым base64 для небольших файлов и двухшаговым через uploadUrl для крупных. Целевую папку и её идентификатор находят через disk.storage и disk.folder, а в ответе получают объект файла с ID и ссылками.

Когда документы, акты и выгрузки должны автоматически попадать на Диск, привязываться к сделкам и версионироваться, нужна аккуратная работа с правами, дублями и лимитами. Мы проектируем и реализуем такие интеграции с Битрикс24 и сопровождаем их под SLA.