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

Скачать изображение документа

GET /v1/documents/:id/image

Скачивает изображение готового документа через Вайбкод: авторизацию в Битрикс24 платформа добавляет к запросу сама. Документ записи CRM скачивается так же по своему маршруту.

Документ Маршрут Скоуп
Документ приложения GET /v1/documents/:id/image documentgenerator
Документ записи CRM GET /v1/crm-documents/:id/image crm

Параметры

Параметр Тип Обяз. Описание
id (path) number да Идентификатор документа, положительное целое число. Документы приложения: GET /v1/documents, документы записи CRM: GET /v1/crm-documents

Тело запроса не передаётся. Примеры ниже — для документа приложения. Для документа записи CRM замените в адресе documents на crm-documents.

Примеры

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

Terminal 
curl --fail-with-body "https://vibecode.bitrix24.tech/v1/documents/2001/image" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o document-2001.jpg

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

Terminal 
curl --fail-with-body "https://vibecode.bitrix24.tech/v1/documents/2001/image" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -o document-2001.jpg

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents/2001/image', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const blob = await res.blob()
console.log('Тип изображения:', res.headers.get('Content-Type'))

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents/2001/image', {
  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 OK, тело ответа — байты изображения документа. Сведения о файле приходят в заголовках.

Заголовок Пример значения Описание
Content-Type image/jpeg Тип изображения, который вернул Битрикс24. Формат файла определяйте по этому заголовку
Content-Disposition attachment; filename="document-2001.png" Имя файла для сохранения. Для документа приложения — document-<id>.png, для документа записи CRM — document-<id> без расширения. Расширение в имени не совпадает с форматом изображения

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: attachment; filename="document-2001.png"
Content-Length: 5899

<двоичное содержимое JPEG, 5899 байт>

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

409 — изображение ещё не сформировано:

JSON 
{
  "success": false,
  "error": {
    "code": "DOCUMENT_NOT_READY",
    "message": "Document file is not ready; retry later."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS id не положительное целое число. Сообщение: Document ID must be a positive integer.
404 ENTITY_NOT_FOUND Документа с таким id нет. Сообщение: Document not found.
409 DOCUMENT_NOT_READY Изображение ещё не сформировано. Повторите запрос через несколько секунд
502 DOWNLOAD_FAILED Битрикс24 не отдал файл: ответил кодом ошибки, прислал JSON вместо файла, указал адрес вне портала или ответ не удалось дочитать. Для документа приложения — также если файл больше 10 МиБ
422 BITRIX_ERROR Битрикс24 отклонил запрос. Текст причины — в error.message
403 BITRIX_ACCESS_DENIED Битрикс24 отказал в доступе к документу. Для документа записи CRM — также если записи, к которой он прикреплён, нет
403 SCOPE_DENIED Ключу не хватает скоупа маршрута: documentgenerator для документа приложения, crm для документа записи CRM
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING Ключу не сопоставлены токены — ключ OAuth-приложения вызван без пользовательской сессии

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

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

Ключ только для чтения подходит. Скачивание не считается записью, поэтому ключ без права записи получает файл так же, как ключ с полным доступом.

Изображение формируется после создания или изменения документа. В первые секунды после этого маршрут отвечает 409 DOCUMENT_NOT_READY, а DOCX уже скачивается.

Поле imageUrlMachine указывает на этот маршрут. В ответах GET /v1/documents/:id и GET /v1/crm-documents/:id поле содержит адрес маршрута для того же документа. Секретов доступа к Битрикс24 в ответах API нет.

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