REST: Диск и файлы (disk)

Группа disk.* в REST API Битрикс24 управляет Диском: хранилищами, папками и файлами, загрузкой и версионированием, правами доступа. Через неё приложение хранит документы, вложения и сгенерированные файлы прямо в портале, а не на внешнем сервере.

Хранилища, папки и файлы

Диск устроен иерархически: хранилище (storage) содержит папки (folder), папки содержат файлы (file). У каждой сущности своя группа методов:

• disk.storage.* — хранилища (общий диск, диски групп, личные диски);
• disk.folder.* — папки и их содержимое;
• disk.file.* — файлы, версии, перемещение;
• disk.attachedObject.* — файлы, прикреплённые к сущностям (задачам, сообщениям).

Список хранилищ даёт disk.storage.getlist, содержимое хранилища — disk.storage.getchildren, содержимое папки — disk.folder.getchildren. Идентификаторы папок и файлов сквозные в пределах Диска: зная id папки, вы работаете с ней независимо от того, в каком хранилище она лежит. Методы перечисления поддерживают filter, поэтому найти нужный элемент по имени или типу можно без обхода всего дерева.

Тип хранилища определяет ENTITY_TYPE: common — общий диск компании, user — личный диск сотрудника, group — диск рабочей группы или проекта. Это важно при выборе места хранения: документы отдела логично держать в общем диске, а личные черновики — на диске пользователя.

Хранилище приложения

Чтобы не засорять пользовательские диски, приложение может получить собственное хранилище методом disk.storage.getforapp. Оно создаётся автоматически и изолировано под нужды интеграции:

POST /rest/1/xxxx/disk.storage.getforapp

Загрузка файлов

Загрузка выполняется методом disk.folder.uploadfile и поддерживает два способа. Первый — передать содержимое в base64 прямо в запросе через fileContent (массив «имя файла» и base64-строка):

disk.folder.uploadfile { "id": 143, "data": { "NAME": "act.pdf" }, "fileContent": [ "act.pdf", "JVBERi0xLjQK..." ] }

Второй способ — двухшаговый: сначала вызывается метод генерации ссылки, который возвращает поле uploadUrl, затем файл заливается на него обычным multipart POST. Двухшаговый способ обязателен для крупных файлов, которые нельзя закодировать в base64 в теле REST-запроса.

Версии и обновление файлов

Диск хранит версии файлов. Чтобы обновить содержимое, не создавая новый объект, используйте disk.file.uploadversion — она добавляет новую версию к существующему id файла. Историю версий возвращает disk.file.getversions.

Операции с папками и файлами

Стандартный набор действий покрывает организацию хранилища:

• создать подпапку — disk.folder.addsubfolder;
• переименовать папку — disk.folder.rename;
• переместить или скопировать — disk.folder.moveto / disk.folder.copyto;
• удалить в корзину — disk.file.markdeleted / disk.folder.markdeleted;
• удалить безвозвратно вместе с содержимым — disk.folder.deletetree.

Метаданные файла (имя, размер, ссылки на скачивание и предпросмотр) возвращает disk.file.get. Ссылка DOWNLOAD_URL требует авторизации, поэтому для внешней раздачи публикуйте файл отдельно или проксируйте скачивание через приложение. Удаление в корзину (markdeleted) обратимо через disk.file.restore, а deletetree стирает папку со всем содержимым без возможности восстановления — применяйте его осознанно и только к служебным каталогам приложения.

Права доступа

Диск наследует модель прав Битрикс24. Через disk.rights.getTasks получают доступные роли (чтение, редактирование, полный доступ), а назначают права параметром rights при создании папки или отдельными вызовами. Права можно выдавать пользователям, отделам и группам.

Права задаются массивом записей, где каждая связывает субъекта доступа (пользователь, отдел, роль) с уровнем прав из disk.rights.getTasks. Уровни наследуются вниз по дереву: права, выданные на папку, распространяются на вложенные папки и файлы, пока не переопределены. Это удобно для организации разделов с разным доступом — например, папка бухгалтерии закрыта для остальных отделов на уровне корня.

Итог

Группа disk.* даёт полноценное файловое хранилище внутри Битрикс24: иерархия хранилищ, папок и файлов, загрузка через base64 или uploadUrl, версионирование, перемещение и права доступа. Для служебных файлов приложения используйте изолированное хранилище disk.storage.getforapp, а крупные файлы всегда грузите двухшаговым способом.

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