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

Скачать вложение комментария задачи

GET /v1/tasks/:taskId/comments/:id/files/:fileId/download

Скачивает файл, приложенный к комментарию задачи. Ответ — содержимое файла байтами, а не JSON, с именем файла в заголовке ответа.

Этот эндпоинт нужен потому, что адрес файла наружу не отдаётся: в нём содержится код авторизации, поэтому запрос по такому адресу из сторонней программы возвращает страницу входа с кодом 200, а не файл. Эндпоинт добавляет авторизацию сам. Скоупа task достаточно — расширять права ключа до всего Диска не требуется, и отдаёт он только файл того комментария, который этому ключу и так доступен на чтение.

Параметры

Параметр Тип Обяз. Описание
taskId (path) number да ID задачи. Получить: GET /v1/tasks
id (path) number да ID комментария. Получить: GET /v1/tasks/:taskId/comments или ответ POST /v1/tasks/:taskId/comments
fileId (path) number да Значение attachments[].fileId из ответа по комментарию — GET /v1/tasks/:taskId/comments/:id. Тот же путь целиком лежит в attachments[].downloadUrl — берите его, чтобы не собирать адрес по частям

Примеры

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

Terminal 
# Сохранить с исходным именем из заголовка ответа
curl -OJ -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/tasks/3711/comments/9393/files/6687/download

# Указать имя файла явно
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/tasks/3711/comments/9393/files/6687/download \
  -o attachment.jpg

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

Terminal 
curl -OJ \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/tasks/3711/comments/9393/files/6687/download

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/tasks/3711/comments/9393/files/6687/download',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
)

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

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

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/tasks/3711/comments/9393/files/6687/download',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  },
)

const bytes = await res.arrayBuffer()

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

При успехе приходит содержимое файла с кодом 200. Тело ответа — байты файла, а не JSON, поэтому вместо полей ответа описаны заголовки.

Заголовок Пример значения Описание
Content-Type image/jpeg Тип содержимого, как его отдал Битрикс24
Content-Disposition attachment; filename="ava555.jpg" Имя файла для сохранения
Content-Length 405559 Размер в байтах, если Битрикс24 его сообщил

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "File 6687 does not belong to comment 9395"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS taskId, id или fileId не является положительным целым числом. Обращения к Битрикс24 при этом не происходит
401 TOKEN_MISSING У ключа не настроены токены Битрикс24
403 SCOPE_DENIED Ключу не хватает скоупа task
404 NOT_FOUND Комментария с таким id нет в названной задаче. Тот же ответ приходит, когда нет самой задачи
404 NOT_FOUND Файл существует, но принадлежит другому комментарию либо у него нет адреса для скачивания
422 BITRIX_ERROR Битрикс24 отказал одному из вызовов, стоящих за этой операцией, и более точного условия не назвал
429 RATE_LIMITED Код отдают два источника. Первый — собственный лимит операции, 30 запросов в минуту на ключ: действующее значение берите из заголовка X-RateLimit-Limit, остаток и время сброса — из X-RateLimit-Remaining и X-RateLimit-Reset, они приходят с каждым ответом операции, включая отказы, а сам отказ несёт ещё Retry-After с секундами до сброса окна. Второй — Битрикс24, отбивший вызов по лимиту частоты: приходит заголовок Retry-After: 2
503 BITRIX_TIMEOUT Битрикс24 принял вызов, но не ответил в отведённое время. Операция читающая, поэтому повтор безопасен. Заголовок Retry-After: 10
502 DOWNLOAD_FAILED Запрос за байтами вернулся не-2xx (в том числе когда Битрикс24 временно недоступен именно на выдаче файла), либо Битрикс24 назвал адрес за пределами домена аккаунта — по такому адресу запрос не уходит
502 BITRIX_UNAVAILABLE Битрикс24 ответил 5xx на REST-вызов, стоящий за операцией, — чтение комментария или запрос сведений о файле. Статус тот же, что у DOWNLOAD_FAILED, различайте по error.code. Оба исхода временные и допускают повтор

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

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

  • Файл обязан принадлежать названному комментарию. Иначе приходит 404, даже когда файл существует и доступен в другом комментарии. Проверка нужна не для строгости: без неё совпадение идентификатора по числу отдало бы чужой файл.
  • Совпадение номера ничего не значит. У комментариев чата и у записей блока комментариев старой карточки идентификаторы живут в разных пространствах и пересекаются по числу. Поэтому надёжный источник fileId — ответ по тому же комментарию, а не число, взятое из другого места.
  • Путь в downloadUrl приходит без домена. Поле указывает на эту операцию, а не на файл в Битрикс24. Склейте путь с тем же базовым адресом API, к которому обращались, — домен в ответе не дублируется.

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