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

Скачать PDF документа

GET /v1/documents/:id/pdf

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

Документ Маршрут Скоуп
Документ приложения GET /v1/documents/:id/pdf documentgenerator
Документ записи CRM GET /v1/crm-documents/:id/pdf 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/pdf" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o document-2001.pdf

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

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents/2001/pdf', {
  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()

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

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

Заголовок Пример значения Описание
Content-Type application/pdf Тип содержимого, который вернул Битрикс24 для файла документа
Content-Disposition attachment; filename="document-2001.pdf" Имя файла для сохранения в виде document-<id>.pdf. Название документа в него не входит

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

http 
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="document-2001.pdf"
Content-Length: 11733

<двоичное содержимое .pdf, 11733 байта, начинается с %PDF>

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

404 — документ не найден:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Document not found."
  }
}

Ошибки

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 — Ошибки.

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

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

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

Хеш PDF не подходит для сверки документа. Пока PDF документа записи CRM не сформирован заново, повторная выгрузка отдаёт тот же файл байт в байт. Когда Битрикс24 формирует PDF заново, в файле меняются дата создания, даты преобразования в метаданных и идентификатор файла, а страницы и текст остаются прежними. Сверяйте содержимое по файлу DOCX из GET /v1/crm-documents/:id/download: при повторном формировании PDF он не меняется.

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

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