# Шаблоны документов

Шаблон документов — это файл `.docx` с подстановочными метками, по которому Битрикс24 формирует готовые документы с подставленными значениями.

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

## Операции

- [Создать шаблон](./doc-templates/create.md) — `POST /v1/doc-templates`
- [Список шаблонов](./doc-templates/list.md) — `GET /v1/doc-templates`
- [Получить шаблон](./doc-templates/get.md) — `GET /v1/doc-templates/:id`
- [Обновить шаблон](./doc-templates/update.md) — `PATCH /v1/doc-templates/:id`
- [Удалить шаблон](./doc-templates/delete.md) — `DELETE /v1/doc-templates/:id`
- [Поиск шаблонов](./doc-templates/search.md) — `POST /v1/doc-templates/search`
- [Поля шаблона](./doc-templates/fields.md) — `GET /v1/doc-templates/fields`
- [Агрегация шаблонов](./doc-templates/aggregate.md) — `POST /v1/doc-templates/aggregate`

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

| Поле | Описание |
|------|---------|
| `name` | Название шаблона |
| `numeratorId` | Идентификатор нумератора |
| `region` | Регион, например `ru` |
| `file` | Содержимое `.docx` в виде строки base64 |
| `fileId` | Идентификатор файла на Диске. Источник: загрузка через `POST /v1/files/upload` |

Полный список полей — [Поля шаблона](./doc-templates/fields.md).

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

1. При создании нужен файл — либо содержимое в виде base64 в поле `file`, либо `fileId` уже загруженного на Диск файла. Передаётся ровно одно из двух.
2. Обязательные поля при создании: `name`, `numeratorId`, `region`.
3. Поля ответа приходят в camelCase.
4. Эндпоинты `/v1` принимают только JSON. Формат `multipart/form-data` не поддерживается.

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

1. Загрузить файл `.docx` через `POST /v1/files/upload` — поле `id` из ответа становится значением `fileId`.
2. Создать шаблон с этим `fileId` через [`POST /v1/doc-templates`](./doc-templates/create.md).
3. Получить, обновить или удалить шаблон по `id`: [`GET /v1/doc-templates/:id`](./doc-templates/get.md), [`PATCH /v1/doc-templates/:id`](./doc-templates/update.md), [`DELETE /v1/doc-templates/:id`](./doc-templates/delete.md).

## Лимиты

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

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

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