---
title: "HTTP API печати по шаблону"
description: "HTTP API печати по шаблону NocoBase: через action templatePrint можно напечатать выделенные записи, текущий результат фильтрации или все подходящие данные и скачать сгенерированный файл Word, Excel, PowerPoint или PDF."
keywords: "печать по шаблону,HTTP API,templatePrint,PDF,печать выделенных записей,печать всех записей,NocoBase"
---

# HTTP API

Печать по шаблону поддерживает прямой запуск рендеринга и скачивания документа через HTTP API. И блок подробностей, и блок таблицы по сути запускают action `templatePrint` для текущего бизнес-ресурса.

```shell
curl -X POST \
	-H "Authorization: Bearer <JWT>" \
	-H "Content-Type: application/json" \
	"http://localhost:3000/api/<resource_name>:templatePrint" \
	--data-raw '{...}'
```

Пояснения:
- `<resource_name>` — имя ресурса, соответствующее текущей таблице данных.
- Интерфейс возвращает поток двоичного файла, а не данные JSON.
- Вызывающая сторона должна обладать правами на запрос текущего ресурса и правами на использование соответствующей кнопки печати по шаблону.
- При вызове интерфейса в заголовке Authorization необходимо передать JWT-токен, выданный при входе пользователя, иначе доступ будет отклонён.

## Параметры тела запроса

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `templateName` | `string` | Да | Имя шаблона, соответствующее идентификатору шаблона в управлении шаблонами. |
| `blockName` | `string` | Да | Тип блока. Для блока таблицы — `table`, для блока подробностей — `details`. |
| `timezone` | `string` | Нет | Часовой пояс, например `Asia/Shanghai`. Используется для рендеринга дат и времени в шаблоне. |
| `uid` | `string` | Нет | Schema uid кнопки печати по шаблону. Используется для проверки прав. |
| `convertedToPDF` | `boolean` | Нет | Конвертировать ли в PDF. При `true` возвращается файл `.pdf`. |
| `queryParams` | `object` | Нет | Параметры, передаваемые в нижележащий запрос данных. |
| `queryParams.page` | `number \| null` | Нет | Номер страницы. `null` означает отсутствие постраничной выборки. |
| `queryParams.pageSize` | `number \| null` | Нет | Количество записей на странице. `null` означает отсутствие постраничной выборки. |
| `queryParams.filter` | `object` | Нет | Условия фильтрации. Автоматически объединяются с фиксированными условиями ACL. |
| `queryParams.appends` | `string[]` | Нет | Связанные поля, которые нужно подгрузить дополнительно. |
| `queryParams.filterByTk` | `string \| object` | Нет | Часто используется в блоке подробностей, задаёт значение первичного ключа. |
| `queryParams.sort` и другие параметры | `any` | Нет | Прочие параметры запроса передаются в нижележащий запрос ресурса как есть. |

## Блок таблицы

Блок таблицы использует тот же интерфейс и указывает режим печати списка через `blockName: "table"`. Сервер выполняет запрос `find` к ресурсу и передаёт массив результатов в шаблон.

### Печать выделенных записей или результатов текущей страницы

Подходит для случая, когда из блока таблицы нужно напечатать часть отмеченных записей или сохранить контекст текущей страницы. Распространённый подход:

- Установить `queryParams.page` и `queryParams.pageSize` равными текущему номеру страницы и числу записей на странице.
- Собрать первичные ключи отмеченных записей в условие `filter.id.$in`.

```shell
curl 'https://<your-host>/api/<resource_name>:templatePrint' \
	-H 'Authorization: Bearer <JWT>' \
	-H 'Content-Type: application/json' \
	--data-raw '{
		"queryParams": {
			"pageSize": 20,
			"filter": {
				"id": {
					"$in": [1, 2]
				}
			},
			"appends": [],
			"page": 1
		},
		"templateName": "9012hy7ahn4",
		"blockName": "table",
		"timezone": "Asia/Shanghai",
		"uid": "ixs3fx3x6is"
	}'
```

Что означает такой запрос:

- `blockName` равен `table` — шаблон рендерится по данным списка.
- `filter.id.$in` задаёт набор записей, которые нужно напечатать.
- `page` и `pageSize` сохраняют контекст текущей страницы, чтобы поведение совпадало с тем, что видит пользователь.
- `appends` позволяет при необходимости подгрузить связанные поля.

### Печать всех записей, удовлетворяющих условиям

Подходит для случая, когда в блоке таблицы нажимается «Напечатать все записи». В этом случае постраничная выборка не используется — данные тянутся целиком, в соответствии с текущими условиями фильтрации.

Ключевая особенность — явная передача `queryParams.page` и `queryParams.pageSize` со значением `null`.

```shell
curl 'https://<your-host>/api/<resource_name>:templatePrint' \
	-H 'Authorization: Bearer <JWT>' \
	-H 'Content-Type: application/json' \
	--data-raw '{
		"queryParams": {
			"pageSize": null,
			"filter": {},
			"appends": [],
			"page": null
		},
		"templateName": "9012hy7ahn4",
		"blockName": "table",
		"timezone": "Asia/Shanghai",
		"uid": "ixs3fx3x6is"
	}'
```

Что означает такой запрос:

- `page: null` и `pageSize: null` отключают ограничение по страницам.
- `filter: {}` означает отсутствие дополнительных условий фильтрации; если в интерфейсе уже задана фильтрация, её можно так же передать сюда.
- Сервер запрашивает все подходящие записи и пакетно рендерит шаблон.

> Внимание: за один раз блок таблицы печатает не более 300 записей. При превышении лимита интерфейс возвращает ошибку `400`.

## Блок подробностей

Блок подробностей использует тот же action `templatePrint`, но обычно передаёт:

- `blockName: "details"`;
- `queryParams.filterByTk` — первичный ключ текущей записи;
- `queryParams.appends` — связанные поля, которые нужно подгрузить.

Сервер выполняет запрос `findOne` к ресурсу и передаёт объект-результат в шаблон.

## Возвращаемый результат

После успешного вызова интерфейс возвращает поток файла. Типичные заголовки ответа:

```http
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="<template-title>-<suffix>.<ext>"
```

Пояснения:

- При `convertedToPDF`, равном `true`, расширение возвращаемого файла — `.pdf`.
- Иначе возвращается файл оригинального типа шаблона, например `.docx`, `.xlsx` или `.pptx`.
- Фронтенд обычно использует имя файла из `Content-Disposition`, чтобы запустить скачивание в браузере.

## Дополнительные ресурсы
- [Использование API-ключей в NocoBase](../integration/api-keys/usage.md)
