# Документы

Документ — это готовый файл, который Битрикс24 формирует по шаблону с подстановкой значений. Каждый документ создаётся на основе шаблона документов и провайдера данных.

Битрикс24 API: `documentgenerator.document.*`
Скоуп: `documentgenerator`

## Операции

- [Создать документ](./documents/create.md) — `POST /v1/documents`
- [Список документов](./documents/list.md) — `GET /v1/documents`
- [Документы по CRM-сущности](./documents/crm-list.md) — `GET /v1/crm-documents`
- [Получить документ](./documents/get.md) — `GET /v1/documents/:id`
- [Обновить документ](./documents/update.md) — `PATCH /v1/documents/:id`
- [Удалить документ](./documents/delete.md) — `DELETE /v1/documents/:id`
- [Поиск документов](./documents/search.md) — `POST /v1/documents/search`
- [Поля документа](./documents/fields.md) — `GET /v1/documents/fields`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `templateId` | Идентификатор шаблона. Источник: `GET /v1/doc-templates` |
| `providerClassName` | Класс провайдера данных, например `Bitrix\DocumentGenerator\DataProvider\Rest` |
| `value` | Внешний идентификатор объекта-источника, например `ORDER-1024` |
| `values` | Значения полей-меток шаблона |
| `number` | Номер документа |
| `pdfUrl` | Ссылка на готовый PDF |

Полный список полей — [Поля документа](./documents/fields.md).

## Что нужно знать перед работой

1. Документ создаётся по шаблону: обязательны `templateId`, `providerClassName` и `value`.
2. Поля ответа приходят в camelCase.
3. Готовый файл доступен по ссылкам `downloadUrl` и `pdfUrl` (для пользователя) и `downloadUrlMachine` / `pdfUrlMachine` (для приложения).
4. Документы конкретной записи CRM возвращает отдельный эндпоинт [`GET /v1/crm-documents`](./documents/crm-list.md) со скоупом `crm`: отбор идёт по `entityTypeId` и `entityId`, идентификаторы в ответе приходят строками.

## Типичный сценарий

1. Выбрать шаблон: [`GET /v1/doc-templates`](/docs/entities/doc-templates).
2. Создать документ по шаблону: [`POST /v1/documents`](./documents/create.md) с `templateId`, `providerClassName` и `value`.
3. Получить, обновить или удалить документ по `id`: [`GET /v1/documents/:id`](./documents/get.md), [`PATCH /v1/documents/:id`](./documents/update.md), [`DELETE /v1/documents/:id`](./documents/delete.md).
4. Посмотреть все документы, прикреплённые к записи CRM: [`GET /v1/crm-documents`](./documents/crm-list.md) с `entityTypeId` и `entityId`.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Шаблоны документов](/docs/entities/doc-templates)
- [Реквизиты компании для генерации документа](/docs/recipes/document-requisites)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)