Для AI-агентов: markdown этой страницы — /docs-content/entities/activities/file-download.md индекс документации — /llms.txt

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

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

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

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

Параметры

Параметр В Тип Обяз. Описание
activityId path number да ID дела. Получить: GET /v1/activities
fileId path number да ID файла из массива files дела. Получить: GET /v1/activities/:id с select, включающим files

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

Примеры

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

Terminal 
# Сохранить с исходным именем из заголовка 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-приложение

Terminal 
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 — Ошибки.

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

  • Файл обязан принадлежать названному делу. Иначе — 404, даже если файл существует. Проверка нужна не для строгости: Битрикс24 на чужой файл отвечает 200 со страницей входа, и без проверки вы получили бы HTML под видом файла.
  • Права не обходятся. Чтение дела — это и есть проверка доступа: если у ключа нет прав на дело, запрос завершится отказом. Битрикс24 дополнительно сверяет доступ пользователя к делу на своей стороне.
  • Адрес наружу не отдаётся. В адресе для скачивания содержится код авторизации, поэтому эндпоинт отдаёт только поток байтов.
  • Файлы приходят в ответе дела не всегда. В списке дел поле files возвращается только при явном указании в select. У одного дела оно приходит без дополнительных условий.

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