## Скачать файл

`GET /v1/files/:id/download`

Скачивает содержимое файла через прокси Вайбкода с автоматической авторизацией. В отличие от поля `downloadUrl` в ответе `GET /v1/files/:id`, этот эндпоинт добавляет авторизацию при каждом вызове — токен не нужно извлекать и подставлять вручную. Ответ — бинарный поток с заголовком `Content-Disposition`, браузеры предлагают сохранить файл автоматически.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `id` | path | number | да | ID файла. Получить: `GET /v1/files` или `GET /v1/files/:id` |

Тело запроса пустое.

## Примеры

### curl — личный ключ

```bash
# Сохранить в файл с исходным именем из заголовка Content-Disposition
curl -OJ -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/files/205/download

# Указать имя файла явно
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/files/205/download \
  -o myfile.pdf
```

### curl — OAuth-приложение

```bash
curl -OJ \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/files/205/download
```

### JavaScript — личный ключ

```javascript
const fileId = 205

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/files/${fileId}/download`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

// Сохранить blob в браузере
const blob = await res.blob()
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = res.headers.get('Content-Disposition')?.match(/filename="(.+?)"/)?.[1] ?? 'file'
a.click()
URL.revokeObjectURL(url)
```

### JavaScript — OAuth-приложение

```javascript
const fileId = 205

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/files/${fileId}/download`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const blob = await res.blob()
```

## Заголовки ответа

При успехе возвращается бинарное содержимое файла (HTTP 200). Секции `## Поля ответа` нет — тело ответа не является JSON.

| Заголовок | Пример значения | Описание |
|-----------|-----------------|----------|
| `Content-Type` | `application/pdf` | Тип содержимого. Зависит от типа файла: `text/plain`, `image/png`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` и т. д. |
| `Content-Disposition` | `attachment; filename="report.pdf"` | Имя файла для сохранения. Браузеры используют его автоматически при скачивании |
| `Content-Length` | `31232` | Размер файла в байтах. Передаётся, если известен из метаданных |

## Пример ответа при ошибке

404 — файл не найден:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Could not find entity with id '99999999'."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный ключ |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `disk` |
| 404 | `ENTITY_NOT_FOUND` | Файла с таким `id` не существует или он недоступен ключу |
| 404 | `DOWNLOAD_URL_NOT_FOUND` | У файла нет адреса для скачивания |
| 502 | `DOWNLOAD_FAILED` | Битрикс24 вернул ошибку при проксировании (например, `403`) |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- **Авторизация добавляется автоматически.** Для ключей OAuth-приложений Вайбкод добавляет токен авторизации к запросу при каждом вызове. Для ключей типа вебхук токен уже встроен в адрес — Вайбкод использует адрес как есть.
- **Поле `downloadUrl` из `GET /v1/files/:id` — временное.** Этот эндпоинт (`/download`) — стабильный способ скачивания: он каждый раз получает актуальный адрес и добавляет авторизацию. Обращение напрямую по сохранённому `downloadUrl` может завершиться ошибкой, когда токен устареет.

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

- [Получить файл](/docs/entities/files/get) — `GET /v1/files/:id`
- [Список файлов](/docs/entities/files/list) — `GET /v1/files`
- [Файлы](/docs/entities/files)