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

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

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

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

Метод HEAD для этого адреса не поддерживается и возвращает 404. Для скачивания используйте GET.

Этот эндпоинт нужен потому, что адрес файла наружу не отдаётся: в нём содержится код авторизации, поэтому запрос по такому адресу из сторонней программы возвращает страницу входа с кодом 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 — берите его, чтобы не собирать адрес по частям
Параметрsource (query) Типstring Обяз. ОписаниеХранилище, в котором искать комментарий: chat или legacy. Приходит в attachments[].downloadUrl каждой строки списка и в поле source ответа по комментарию — путь из ответа уже несёт этот параметр. Без него файл ищется в обоих хранилищах. Другое значение — 400 INVALID_SOURCE

Примеры

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 Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеtaskId, id или fileId не является положительным целым числом. Обращения к Битрикс24 при этом не происходит
HTTP400 КодINVALID_SOURCE ОписаниеПараметр source не равен chat или legacy. Обращения к Битрикс24 при этом не происходит
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа не настроены токены Битрикс24
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа task
HTTP404 КодNOT_FOUND ОписаниеКомментария с таким id нет в названной задаче. Тот же ответ приходит, когда нет самой задачи
HTTP404 КодNOT_FOUND ОписаниеФайл существует, но принадлежит другому комментарию либо у него нет адреса для скачивания
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отказал одному из вызовов, стоящих за этой операцией, и более точного условия не назвал
HTTP429 КодRATE_LIMITED ОписаниеКод отдают два источника. Первый — собственный лимит операции, 30 запросов в минуту на ключ: действующее значение берите из заголовка X-RateLimit-Limit, остаток и время сброса — из X-RateLimit-Remaining и X-RateLimit-Reset, они приходят с каждым ответом операции, включая отказы, а сам отказ несёт ещё Retry-After с секундами до сброса окна. Второй — Битрикс24, отбивший вызов по лимиту частоты: приходит заголовок Retry-After: 2
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 принял вызов, но не ответил в отведённое время. Операция читающая, поэтому повтор безопасен. Заголовок Retry-After: 10
HTTP502 КодDOWNLOAD_FAILED ОписаниеЗапрос за байтами вернулся не-2xx (в том числе когда Битрикс24 временно недоступен именно на выдаче файла), либо Битрикс24 назвал адрес за пределами домена аккаунта — по такому адресу запрос не уходит
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 ответил 5xx на REST-вызов, стоящий за операцией, — чтение комментария или запрос сведений о файле. Статус тот же, что у DOWNLOAD_FAILED, различайте по error.code. Оба исхода временные и допускают повтор

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

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

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

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