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

GET /v1/files/:id/download

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

#Параметры

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

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

#Примеры

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

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

Terminal 
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_MISSING Ключу не хватает скоупа disk
404 ENTITY_NOT_FOUND Файла с таким id не существует или он недоступен ключу
404 DOWNLOAD_URL_NOT_FOUND У файла нет адреса для скачивания
502 DOWNLOAD_FAILED Битрикс24 вернул ошибку при проксировании (например, 403)

Полный список общих ошибок API — Ошибки.

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

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

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