# 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](/docs/entities/crm-document-templates); 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.

## Operations

- [Download document DOCX](./documents/download.md) — `GET /v1/documents/:id/download`
- [Download document PDF](./documents/pdf.md) — `GET /v1/documents/:id/pdf`
- [Download document image](./documents/image.md) — `GET /v1/documents/:id/image`
- [Enable or disable a document public link](./documents/public-url.md) — `POST /v1/documents/:id/public-url`
- [Create document](./documents/create.md) — `POST /v1/documents`
- [List documents](./documents/list.md) — `GET /v1/documents`
- [Documents by CRM record](./documents/crm-list.md) — `GET /v1/crm-documents`
- [Get CRM document](./documents/crm-get.md) — `GET /v1/crm-documents/:id`
- [Create CRM document](./documents/crm-create.md) — `POST /v1/crm-documents`
- [Update CRM document](./documents/crm-update.md) — `PATCH /v1/crm-documents/:id`
- [Delete CRM document](./documents/crm-delete.md) — `DELETE /v1/crm-documents/:id`
- [Enable or disable a CRM document public link](./documents/crm-public-url.md) — `POST /v1/crm-documents/:id/public-url`
- [Upload CRM document](./documents/crm-upload.md) — `POST /v1/crm-documents/upload`
- [Get document](./documents/get.md) — `GET /v1/documents/:id`
- [Update document](./documents/update.md) — `PATCH /v1/documents/:id`
- [Delete document](./documents/delete.md) — `DELETE /v1/documents/:id`
- [Search documents](./documents/search.md) — `POST /v1/documents/search`
- [Document fields](./documents/fields.md) — `GET /v1/documents/fields`

## Key fields

| Field | Description |
|------|---------|
| `templateId` | Template identifier. Source: `GET /v1/doc-templates` |
| `providerClassName` | Data provider class, for example `Bitrix\DocumentGenerator\DataProvider\Rest` |
| `value` | Source-object key for the provider, for example `ORDER-1024` |
| `values` | Values for the template's label fields |
| `number` | Document number |
| `pdfUrl` | Link to the generated PDF |

Full field list — [Document fields](./documents/fields.md).

## What to know before you start

1. A document is created from a template: `templateId`, `providerClassName`, and `value` are required.
2. With the `Rest` provider, `value` is an arbitrary key rather than a reference to a CRM record: the label values come from `values`. An empty string and `"0"` are rejected.
3. Response fields come back in camelCase.
4. A user opens the generated file through `downloadUrl` and `pdfUrl`. The Vibecode API download URLs `downloadUrlMachine`, `pdfUrlMachine`, and `imageUrlMachine` point to routes with the `documentgenerator` scope for an app document and the `crm` scope for a CRM document. Download: [DOCX](./documents/download.md), [PDF](./documents/pdf.md), [image](./documents/image.md).
5. Documents for a specific CRM record are returned by a separate endpoint [`GET /v1/crm-documents`](./documents/crm-list.md) with the `crm` scope: documents are filtered by `entityTypeId` and `entityId`, and identifiers in the response come back as strings.

## Typical scenario

To create an invoice for a deal, select a [CRM template](/docs/entities/crm-document-templates) with `GET /v1/crm-document-templates`, then pass its `templateId`, `entityTypeId: 2`, and the deal ID to [create a CRM document](./documents/crm-create.md). [Read the document](./documents/crm-get.md), then download the [PDF](./documents/pdf.md). The PDF may still be generating immediately after creation.

1. Pick a template: [`GET /v1/doc-templates`](/docs/entities/doc-templates).
2. Create a document from the template: [`POST /v1/documents`](./documents/create.md) with `templateId`, `providerClassName`, and `value`.
3. Get, update, or delete the document by `id`: [`GET /v1/documents/:id`](./documents/get.md), [`PATCH /v1/documents/:id`](./documents/update.md), [`DELETE /v1/documents/:id`](./documents/delete.md).
4. View all documents attached to a CRM record: [`GET /v1/crm-documents`](./documents/crm-list.md) with `entityTypeId` and `entityId`.

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Document templates](/docs/entities/doc-templates)
- [Company requisites for document generation](/docs/recipes/document-requisites)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)