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

`GET /v1/activities/:activityId/files/:fileId/download`

Скачивает файл, прикреплённый к делу CRM — в том числе запись звонка. Ответ — бинарный поток с заголовком `Content-Disposition`.

Этот эндпоинт нужен потому, что файл дела **не является файлом Диска**. `GET /v1/activities/:id` отдаёт каждый файл как `{ id, url }`, где `id` живёт в отдельном пространстве идентификаторов, пересекающемся с идентификаторами объектов Диска. Передать такой `id` в [скачивание файла Диска](/docs/entities/files/download) нельзя: с некоторой вероятностью придёт другой файл. А адрес из поля `url` приходит с пустым параметром авторизации, поэтому запрос по нему возвращает страницу входа с кодом `200` — не файл. Этот эндпоинт добавляет авторизацию сам и отдаёт содержимое.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `activityId` | path | number | да | ID дела. Получить: [`GET /v1/activities`](/docs/entities/activities/list) |
| `fileId` | path | number | да | ID файла из массива `files` дела. Получить: [`GET /v1/activities/:id`](/docs/entities/activities/get) с `select`, включающим `files` |

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

## Примеры

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

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

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

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

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

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

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

if (!res.ok) {
  const { error } = await res.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const audio = await res.arrayBuffer()
console.log('получено байт:', audio.byteLength)
```

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

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

const audio = await res.arrayBuffer()
```

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

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

| Заголовок | Пример значения | Описание |
|-----------|-----------------|----------|
| `Content-Type` | `audio/mpeg` | Тип содержимого, как его отдал Битрикс24 |
| `Content-Disposition` | `attachment; filename="call-record.mp3"` | Имя файла для сохранения |
| `Content-Length` | `22509` | Размер в байтах, если Битрикс24 его сообщил |

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

404 — файл не принадлежит этому делу:

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "File 999999 does not belong to activity 4257"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `activityId` или `fileId` не является положительным целым числом |
| 401 | `TOKEN_MISSING` | У ключа не настроены токены Битрикс24 |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `crm` |
| 404 | `NOT_FOUND` | Дела не существует, файл не принадлежит этому делу, либо у файла нет адреса для скачивания |
| 502 | `DOWNLOAD_FAILED` | Битрикс24 назвал адрес за пределами домена аккаунта (по такому адресу запрос не уходит) либо не отдал файл. В том числе когда он ответил страницей вместо содержимого — значит ключ не удалось авторизовать для этого файла |

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

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

- **Файл обязан принадлежать названному делу.** Иначе — `404`, даже если файл существует. Проверка нужна не для строгости: Битрикс24 на чужой файл отвечает `200` со страницей входа, и без проверки вы получили бы HTML под видом файла.
- **Права не обходятся.** Чтение дела — это и есть проверка доступа: если у ключа нет прав на дело, запрос завершится отказом. Битрикс24 дополнительно сверяет доступ пользователя к делу на своей стороне.
- **Адрес наружу не отдаётся.** В адресе для скачивания содержится код авторизации, поэтому эндпоинт отдаёт только поток байтов.
- **Файлы приходят в ответе дела не всегда.** В [списке дел](/docs/entities/activities/list) поле `files` возвращается только при явном указании в `select`. У [одного дела](/docs/entities/activities/get) оно приходит без дополнительных условий.

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

- [Получить дело](/docs/entities/activities/get)
- [Скачать вложение комментария таймлайна](/docs/entities/timelines/file-download)
- [Скачать файл Диска](/docs/entities/files/download)
- [Дела](/docs/entities/activities)