Заполнение PDF-формы через NextPDF Connect (Pro)

Кратко

Заполнение полей интерактивных PDF-форм через NextPDF Connect с помощью XML Forms Data Format (XFDF). Инструмент для подписей и форм — fill_form. Поставщик инструментов Pro регистрирует new FillFormTool() с именем протокола fill_form. fill_form — это инструмент уровня Pro. При запуске сервер проверяет наличие пакета Pro с помощью class_exists() и регистрирует инструмент только если пакет найден. При использовании только Core fill_form отсутствует в реестре.

Установка

composer require nextpdf/server
composer require nextpdf/pro

Привяжите транспорт. Затем через diagnostic.capabilities убедитесь, что инструмент доступен (см. environment-diagnostics). Не считайте набор инструментов неизменным.

Концептуальный обзор

В XFDF имена полей сопоставляются со значениями через элементы <field>. Каждое имя должно соответствовать полю AcroForm, которое уже существует в целевом документе. Каждое поле хранится в словаре полей интерактивной формы (ISO 32000-2 §12.7), а переданное значение становится значением поля (ISO 32000-2 §12.7). Если имя не соответствует ни одному полю, инструмент пропускает его и не считает это ошибкой. Инструмент сообщает, сколько полей он заполнил и сколько пропустил.

Состав API

Инструмент	Уровень	Назначение	Уровень риска
`create_pdf`	Core (базовый)	Открыть сессию	Безопасно
`fill_form`	Pro (профессиональный)	Применить значения XFDF к полям AcroForm	Внимание
`output_pdf`	Core (базовый)	Отрисовать и вернуть PDF	Требуется подтверждение / Проверка (base64)

Имена инструментов в реестре совпадают с именами протокола. Каталог инструментов — официальный каталог. Установленный уровень определяет, какие инструменты доступны. Инструменты Pro появляются только при установленном пакете Pro.

Пример кода — быстрый старт

create_pdf (или загрузите шаблон, в котором уже есть поля формы).
fill_form с xfdf_data, где имена полей сопоставлены со значениями.
output_pdf → base64.

Результат содержит fields_filled, fields_skipped и имена совпавших полей.

Пример кода — продакшен

Используйте шаблон с именами полей AcroForm, которые вы контролируете. Проверьте XFDF по схеме XFDF перед отправкой. Проверяйте fields_skipped и возвращённый список имён, чтобы находить несовпадения (имена чувствительны к регистру). При больших объёмах заполнения не превышайте предельный размер XFDF и при необходимости разделяйте данные.

Граничные случаи и подводные камни

Некорректный XFDF. Ошибка разбора укажет на проблемное место. Экранируйте XML-сущности и включите xmlns.
Несовпадение имени. Поле с несовпавшим именем пропускается без ошибки, а счётчик fields_skipped увеличивается. Имена чувствительны к регистру.
Нет полей формы. В документе без AcroForm будет ноль заполненных полей.
XFDF слишком большой. Сервер отклоняет данные, превышающие предельный размер. Разделите данные или удалите лишние пробелы.
Pro отсутствует. При использовании только Core fill_form не регистрируется, и его вызов возвращает ошибку неизвестного инструмента. Сначала проверьте через diagnostic.capabilities.

Производительность

Заполнение обычно выполняется быстрее, чем отрисовка. Размер результата варьируется от нескольких КБ до десятков КБ в зависимости от числа полей и встраивания шрифтов. Профиль — structural.

Замечания по безопасности

Значения полей становятся содержимым документа. Не помещайте секреты в поля формы, если затем возвращаете PDF через недоверенный канал. Вариант с base64 не имеет побочных эффектов для файловой системы. Для вывода в файл действуют ограничения.

Соответствие

Утверждение	Спецификация	Пункт	reference_id (идентификатор ссылки)
Поле формы хранится в словаре полей интерактивной формы.	ISO 32000-2	§12.7
Переданные данные становятся значением поля.	ISO 32000-2	§12.7

Коммерческий контекст

fill_form — это инструмент уровня Pro. Сервер регистрирует его только тогда, когда пакет Pro доступен при запуске (проверка class_exists()). Развёртывания только на Core его не предоставляют.

Доступность по транспортам

Транспорт	Доступно	Примечания
MCP по stdio	Да (Pro)	Доступно только при установленном Pro.
REST	Да (Pro)	То же условие.
gRPC	Да (Pro)	То же условие.

Уровень риска HITL

fill_form относится к уровню “Внимание”, поскольку это обратимое изменение содержимого. output_pdf относится к уровню “Требуется подтверждение”, который в режиме base64 понижается до уровня “Проверка” (уровни риска HITL).

JSON-конверт шлюза подтверждения

Вывод в base64:

{ "allowed": true }

Вывод в файл возвращает конверт запроса на подтверждение, описанный в output-approval.