Files Service API — `/api/v1/files`

Auth: JWT access token или X-API-Key

Response envelope: формат ответа C (legacy JSON)

---

Аутентификация

Метод	Header	Permissions (API Key)
JWT	`Authorization: Bearer <access_token>`	access token (не refresh)
API Key	`X-API-Key: <key>`	`files:upload`, `files:download`, `files:` или ``

Query param api_key поддерживается как fallback для API Key.

---

POST /api/v1/files/upload

Загрузка одного или нескольких файлов.

Content-Type: загрузка файлов (multipart)

Form fields:

Поле	Тип	Обяз.	Описание
`file`	file	да*	Один файл
`files`	file[]	да*	Несколько файлов
`category`	string	нет	Категория
`is_public`	string	нет	`"true"` / `"false"`, default false
`metadata`	string	нет	JSON object as string

*Один из: file или files. Max files per request — из конфига (files.max_files_per_request, default 10).

Response 200:

{
  "success": true,
  "files": [
    {
      "id": "uuid",
      "filename": "doc.pdf",
      "storage_path": "...",
      "mime_type": "application/pdf",
      "size": 1024,
      "hash_md5": "...",
      "hash_sha256": "...",
      "uploaded_at": "2026-08-21T08:00:00Z",
      "metadata": {}
    }
  ],
  "count": 1,
  "errors": null
}

Errors: 400 (нет файла, превышен лимит), 401 (нет auth)

---

GET /api/v1/files/{file_id}/download

Скачивание файла (binary response).

Auth: JWT или X-API-Key с files:download

Access control:

is_public=true — доступен любому авторизованному клиенту
is_public=false — JWT: только владелец (uploaded_by); API Key: нужен files:download

Response 200: binary file (Content-Disposition: attachment)

Errors: 403 (private file), 404 (not found)

---

GET /api/v1/files/{file_id}

Метаданные файла (без binary content).