# Папки

Управление папками на диске Битрикс24: список содержимого, создание, переименование и удаление. Папки хранятся внутри хранилищ и образуют дерево вложенности.

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

## Операции

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

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

| Поле | Описание |
|------|---------|
| `id` | Числовой идентификатор папки |
| `name` | Имя папки. Обязательно при создании |
| `parentId` | Идентификатор родительской папки. Обязателен при создании и для листинга. Корневую папку хранилища даёт поле `rootFolderId` в [`GET /v1/storages`](/docs/entities/storages) |
| `storageId` | Идентификатор хранилища, из [`GET /v1/storages`](/docs/entities/storages) |
| `type` | Тип объекта — `"folder"` или `"file"` |
| `detailUrl` | Ссылка на папку в интерфейсе Битрикс24 |
| `createdAt` | Дата и время создания в формате ISO 8601 |

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

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

1. **Имена полей в ответе — camelCase.** Схема приводит исходные UPPER_SNAKE-имена к camelCase.
2. **`parentId` обязателен и для создания, и для листинга.** `GET /v1/folders` возвращает содержимое конкретной папки. Корневую папку хранилища даёт поле `rootFolderId` в [`GET /v1/storages`](/docs/entities/storages).
3. **`GET /v1/folders` возвращает смешанный список.** В ответе одновременно подпапки (`type: "folder"`) и файлы (`type: "file"`). У файлов набор полей отличается — есть `fileId`, `size`, `downloadUrl` и нет `realObjectId`. Для управления файлами используйте раздел [Файлы](/docs/entities/files). Карточка файла доступна через [`GET /v1/files/:id`](/docs/entities/files/get), а не `GET /v1/folders/:id`.
4. **Минимум для создания — `name` и `parentId`.**
5. **Через `PATCH` меняется только имя.** `PATCH /v1/folders/:id` переименовывает папку. Поля `parentId` и `code` в теле `PATCH` неизменяемы. Чтобы переместить папку в другую родительскую, используйте [`POST /v1/folders/:id/moveto`](./folders/moveto.md).
6. **Удаление — мягкое.** `DELETE /v1/folders/:id` помечает папку удалённой и переносит в корзину, физически папка не стирается. Восстановление через API не предусмотрено.

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

1. Получить хранилище: [`GET /v1/storages`](/docs/entities/storages) — нужны `id` и `rootFolderId`.
2. Посмотреть содержимое корня: [`GET /v1/folders?parentId=<rootFolderId>`](./folders/list.md).
3. Создать подпапку: [`POST /v1/folders`](./folders/create.md) с `name` и `parentId`.
4. Переименовать при необходимости: [`PATCH /v1/folders/:id`](./folders/update.md).
5. Удалить: [`DELETE /v1/folders/:id`](./folders/delete.md).

## Лимиты

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

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

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