# Documents

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

Bitrix24 API: `documentgenerator.document.*`
Scope: `documentgenerator`

## Operations

- [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 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` | External identifier of the source object, for example `ORDER-1024` |
| `values` | Values for the template's label fields |
| `number` | Document number |
| `pdfUrl` | Link to the ready 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. `providerClassName` sets the data provider class, `value` is the external identifier of the source object that label-field values are pulled from.
3. Values for the template's label fields are passed in `values`.
4. Response fields come back in camelCase.
5. The ready file is available via `downloadUrl` and `pdfUrl` (for the user) and `downloadUrlMachine` / `pdfUrlMachine` (for the application).
6. Documents of a specific CRM record are returned by a separate endpoint [`GET /v1/crm-documents`](./documents/crm-list.md) with the `crm` scope: the selection is by `entityTypeId` and `entityId`, and identifiers in the response come back as strings.

## Typical scenario

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 selections | `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)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)