# Файлы

Управление файлами на диске Битрикс24: получение списка, загрузка, скачивание, переименование, перемещение, копирование и удаление. Файлы хранятся в папках внутри хранилищ.

Битрикс24 API: `disk.file.*`
Скоуп: `disk`

## Операции

- [Список файлов папки](./files/list.md) — `GET /v1/files`
- [Поиск файлов](./files/search.md) — `POST /v1/files/search`
- [Получить файл](./files/get.md) — `GET /v1/files/:id`
- [Переименовать файл](./files/update.md) — `PATCH /v1/files/:id`
- [Удалить файл](./files/delete.md) — `DELETE /v1/files/:id`
- [Поля файла](./files/fields.md) — `GET /v1/files/fields`
- [Загрузить файл](./files/upload.md) — `POST /v1/files/upload`
- [Скачать файл](./files/download.md) — `GET /v1/files/:id/download`
- [Переместить файл](./files/moveto.md) — `POST /v1/files/:id/moveto`
- [Скопировать файл](./files/copyto.md) — `POST /v1/files/:id/copyto`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `id` | Числовой идентификатор файла |
| `name` | Имя файла с расширением |
| `size` | Размер файла в байтах. Приходит у записей-файлов |
| `folderId` | Идентификатор родительской папки (из [`GET /v1/folders`](/docs/entities/folders)) |
| `storageId` | Идентификатор хранилища (из [`GET /v1/storages`](/docs/entities/storages)) |
| `type` | Тип объекта — для файлов всегда `"file"` |
| `downloadUrl` | Временная ссылка для скачивания. Для программного скачивания используйте [`GET /v1/files/:id/download`](./files/download.md) |
| `createdAt` | Дата и время создания в формате ISO 8601 |
| `updatedAt` | Дата и время последнего изменения в формате ISO 8601 |

Полный список полей — [`GET /v1/files/fields`](./files/fields.md).

## Что нужно знать перед работой

1. **Для получения списка файлов требуется `folderId`.** `GET /v1/files` возвращает содержимое конкретной папки. Чтобы получить идентификатор папки, сначала запросите список хранилищ через `GET /v1/storages`, затем список папок через `GET /v1/folders` с нужным `storageId`.
2. **`GET /v1/files` возвращает смешанный список.** В ответе одновременно присутствуют файлы (`type: "file"`) и подпапки (`type: "folder"`). Для фильтрации по типу используйте поле `type`.
3. **Удаление — мягкое.** `DELETE /v1/files/:id` помечает файл как удалённый, физически файл не стирается. Удалённый файл остаётся в Битрикс24 до окончательной очистки.
4. **Изменить можно только имя.** `PATCH /v1/files/:id` принимает только поле `name`. Прочие поля доступны только для чтения.
5. **Перемещение работает только внутри одного хранилища.** `POST /v1/files/:id/moveto` не перемещает файлы между хранилищами. Для переноса между хранилищами используйте `POST /v1/files/:id/copyto`, затем `DELETE /v1/files/:id`.

## Типичный сценарий

1. Получить идентификатор хранилища: [`GET /v1/storages`](/docs/entities/storages).
2. Найти нужную папку: [`GET /v1/folders`](/docs/entities/folders) с параметром `storageId`.
3. Загрузить файл в папку: [`POST /v1/files/upload`](./files/upload.md) с `folderId` — в ответе придёт `id` нового файла.
4. Скачать содержимое файла: [`GET /v1/files/:id/download`](./files/download.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (при `limit > 50` Вайбкод выполняет несколько запросов автоматически, смещение через `offset`) |
| Максимальный размер загружаемого файла | определяется настройками портала Битрикс24 |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

## Смотрите также

- [Папки](/docs/entities/folders)
- [Хранилища](/docs/entities/storages)
- [Синтаксис фильтрации](/docs/filtering)
- [Ключи и авторизация](/docs/keys-auth)
- [Коды ошибок](/docs/errors)