> ## Documentation Index
> Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Шаблоны

> Найдите шаблон и прочитайте его variable_schema

Документ создаётся из **шаблона** — или из готового файла, если он у вас уже
есть: см. [Загрузка своего документа](/ru/guides/documents/uploads). Шаблон
задаёт печатную форму и набор
переменных, которые заполняются при создании документа. Эти переменные описаны в
`variable_schema` — JSON-схеме, которой должен соответствовать `template_values` в
теле `POST /documents`.

Порядок работы простой: найдите шаблон → прочитайте его `variable_schema` →
подготовьте `template_values` по этой схеме. Всё чтение шаблонов покрывает область
`documents:read`.

## Поиск шаблонов

`GET /document_templates` возвращает **только активные** шаблоны, постранично.
Сузьте выборку параметром `search` по названию:

```bash theme={null}
curl -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  "https://app.doodocs.kz/api/developer/v1/document_templates?search=%D0%BF%D1%80%D0%B8%D1%91%D0%BC&limit=20"
```

```json theme={null}
{
  "templates": [
    {
      "id": "tpl_7c1a…",
      "name": "Приказ о приёме на работу",
      "version": 3
    }
  ],
  "next_page_token": ""
}
```

<Note>
  Список подчиняется общей [пагинации](/ru/api-reference/pagination): `limit` (по
  умолчанию `100`, максимум `1000`) и непрозрачный `page_token`. Неактивные шаблоны
  через Developer API не отдаются.
</Note>

## Чтение схемы переменных

`GET /document_templates/{template_id}` возвращает шаблон вместе с `variable_schema`:

```bash theme={null}
curl -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  https://app.doodocs.kz/api/developer/v1/document_templates/tpl_7c1a…
```

```json theme={null}
{
  "id": "tpl_7c1a…",
  "name": "Приказ о приёме на работу",
  "version": 3,
  "variable_schema": {
    "type": "object",
    "required": ["employee_full_name", "position", "start_date"],
    "properties": {
      "employee_full_name": { "type": "string", "title": "ФИО сотрудника" },
      "position":           { "type": "string", "title": "Должность" },
      "start_date":         { "type": "string", "format": "date", "title": "Дата приёма" },
      "salary":             { "type": "number", "title": "Оклад" }
    }
  }
}
```

Состав `variable_schema` зависит от конкретного шаблона — читайте его перед
созданием документа, а не полагайтесь на память. Для «Приказа о приёме на работу»
из примера `template_values` собирается по трём обязательным полям:

```json theme={null}
{
  "template_values": {
    "employee_full_name": "Куляш Байсеитова",
    "position": "HR-менеджер",
    "start_date": "2026-02-10",
    "salary": 650000
  }
}
```

<Tip>
  Закрепляйте версию шаблона: передавайте `template_version` в `POST /documents`
  равным `version` из ответа. Так документ создаётся по той схеме, которую вы читали,
  даже если шаблон позже обновят.
</Tip>

<Warning>
  Если `template_values` не соответствует `variable_schema` шаблона (нет
  обязательного поля, неверный тип), `POST /documents` вернёт `400`. Сверяйте
  значения со схемой до отправки.
</Warning>

## Дальше

<Columns cols={2}>
  <Card title="Подписание" icon="pen" href="/ru/guides/documents/signing">
    Создайте документ из шаблона и проведите его по маршруту.
  </Card>

  <Card title="Обзор документов" icon="file-lines" href="/ru/guides/documents/overview">
    Статусы, структура объекта и файлы.
  </Card>
</Columns>