#HTTP API

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

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-токен, выданный при входе пользователя, иначе доступ будет отклонён.

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

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

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

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

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

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

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.

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 к ресурсу и передаёт объект-результат в шаблон.

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

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

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

Пояснения:

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

#Дополнительные ресурсы

• Использование API-ключей в NocoBase