Documents

A document is a ready-to-use file that Bitrix24 generates from a template by substituting values. Each document is created from a document template and a data provider.

Bitrix24 API: documentgenerator.document.* Scope: documentgenerator

For CRM documents, select a template in the CRM template section; app templates live in /v1/doc-templates. The /v1/crm-documents routes use crm.documentgenerator.document.* and the crm scope.

The PDF and the image are generated asynchronously. If a download returns 409 DOCUMENT_NOT_READY, retry later. Public sharing is a separate action: an enabled public URL works without authentication.

Download document DOCX

GET /v1/documents/:id/download

Downloads the DOCX file of a generated document through Vibecode: the platform adds Bitrix24 authorization to the request automatically. A CRM record document is downloaded the same way through its own route.

Parameters

No request body is sent. The examples below are for an app document. For a CRM record document, replace documents with crm-documents in the URL.

Examples

curl — personal key

curl --fail-with-body "https://vibecode.bitrix24.com/v1/documents/2001/download" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o document-2001.docx

curl — OAuth application

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

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/documents/2001/download', {
  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 application

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

Response fields

On success the HTTP status is 200 OK and the response body contains the bytes of the DOCX file. File details come in the headers.

Response example

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="document-2001.docx"
Content-Length: 914

<binary .docx content, 914 bytes, starts with PK>

Error response example

404 — document not found:

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

Errors

Full list of common API errors — Errors.

Known specifics

A read-only key works. Downloading does not count as a write, so a key without write permission gets the file just like a full-access key.

DOCX is ready before PDF and image. In the first seconds after a document is created, the PDF and image routes respond with 409 DOCUMENT_NOT_READY, while this route already returns the file.

The downloadUrlMachine field points to this route. In the responses of GET /v1/documents/:id and GET /v1/crm-documents/:id, the field contains the route URL for the same document. API responses contain no Bitrix24 access secrets.

See also

• Download document PDF
• Download document image
• Get document
• Get CRM document
• Documents