Для 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 — личный ключ
# Сохранить с исходным именем из заголовка ответа
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-приложение
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 — личный ключ
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-приложение
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 — файл не принадлежит этому комментарию:
{
"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, к которому обращались, — домен в ответе не дублируется.