Preencha um formulário PDF com o NextPDF Connect (Pro)

Visão geral

Preencha campos interativos de formulários PDF no NextPDF Connect usando o XML Forms Data Format (XFDF). A ferramenta para assinatura e formulários é fill_form. O provedor de ferramentas Pro registra new FillFormTool(), cujo nome de protocolo é fill_form. fill_form é uma ferramenta do tier Pro. Na inicialização, o servidor verifica a presença do pacote Pro com class_exists() e registra a ferramenta somente quando o pacote está presente. Em instalações somente com o Core, fill_form fica ausente do registro.

Instalação

composer require nextpdf/server
composer require nextpdf/pro

Vincule um transporte. Em seguida, confirme que a ferramenta existe com diagnostic.capabilities (consulte environment-diagnostics). Não assuma que o conjunto de ferramentas é fixo.

Visão conceitual

O XFDF mapeia nomes de campos para valores usando elementos <field>. Cada nome deve corresponder a um campo AcroForm que já existe no documento de destino. O dicionário de campos do formulário interativo contém cada campo (ISO 32000-2 §12.7), e o valor fornecido passa a ser o valor do campo (ISO 32000-2 §12.7). Se um nome não corresponder a nenhum campo, a ferramenta o ignora em vez de tratá-lo como erro. A ferramenta informa quantos campos foram preenchidos e quantos foram ignorados.

Superfície da API

Ferramenta	Tier	Função	Nível de risco
`create_pdf`	Core	Abrir a sessão	Seguro
`fill_form`	Pro	Aplicar valores XFDF aos campos AcroForm	Cautela
`output_pdf`	Core	Renderizar e retornar o PDF	Aprovação Necessária / Revisão (base64)

Os nomes das ferramentas correspondem aos nomes de protocolo no registro. O catálogo de ferramentas é o catálogo oficial. O tier instalado determina quais ferramentas estão disponíveis. As ferramentas Pro aparecem somente quando o pacote Pro está instalado.

Exemplo de código — Início rápido

create_pdf (ou carregue um modelo que já tenha campos de formulário).
fill_form com xfdf_data mapeando nomes de campos para valores.
output_pdf → base64.

O resultado informa fields_filled, fields_skipped e os nomes dos campos com correspondência.

Exemplo de código — Produção

Use um modelo com nomes de campos AcroForm que você controla. Valide o XFDF contra o schema XFDF antes de enviá-lo. Verifique fields_skipped e a lista de nomes retornada para detectar divergências de nome (os nomes são sensíveis a maiúsculas e minúsculas). Para preenchimentos grandes, mantenha-se abaixo do limite de tamanho do XFDF e divida os dados se necessário.

Casos extremos e armadilhas

XFDF malformado. Um erro de análise identifica o local problemático. Faça escape das entidades XML e inclua o xmlns.
Divergência de nome. Um campo sem correspondência é ignorado silenciosamente, e fields_skipped é incrementado. Os nomes são sensíveis a maiúsculas e minúsculas.
Sem campos de formulário. Um documento sem AcroForm resulta em zero campos preenchidos.
XFDF grande demais. O servidor rejeita dados que excedem o limite de tamanho. Divida-o ou remova os espaços em branco.
Pro ausente. Em instalações somente com o Core, fill_form não é registrado, e chamá-lo retorna um erro de ferramenta desconhecida. Verifique primeiro com diagnostic.capabilities.

Desempenho

O preenchimento é rápido em comparação com a renderização. A saída varia de alguns KB a dezenas de KB, dependendo da quantidade de campos e da incorporação de fontes. O perfil é structural.

Notas de segurança

Os valores dos campos se tornam conteúdo do documento. Não insira segredos em campos de formulário se você for retornar o PDF por um canal não confiável. O caminho base64 não causa efeitos colaterais no sistema de arquivos. A saída em arquivo é restrita por gate.

Conformidade

Declaração	Especificação	Cláusula	reference_id
Um campo de formulário está contido no dicionário de campos do formulário interativo.	ISO 32000-2	§12.7
Os dados fornecidos se tornam o valor do campo.	ISO 32000-2	§12.7

Contexto comercial

fill_form é uma ferramenta do tier Pro. O servidor a registra somente quando o pacote Pro é resolvido na inicialização (com detecção via class_exists()). As implantações Core não a expõem.

Disponibilidade por transporte

Transporte	Disponível	Observações
MCP (stdio)	Sim (Pro)	Presente somente quando o Pro está instalado.
REST	Sim (Pro)	Mesmo comportamento.
gRPC	Sim (Pro)	Mesmo comportamento.

Nível de risco HITL

fill_form é classificada como Cautela porque é uma mutação de conteúdo reversível. output_pdf é Aprovação Necessária, rebaixada para Revisão no modo base64 (níveis de risco HITL).

Envelope JSON do gate de confirmação

Saída base64:

{ "allowed": true }

A saída em arquivo retorna o envelope de desafio descrito em output-approval.