Crie um documento de várias páginas com o NextPDF Connect

Visão geral

Crie um documento com várias páginas usando o NextPDF Connect. add_page anexa uma página que herda a geometria padrão do documento ou usa a própria orientação. Após cada add_page, o cursor volta para a margem superior esquerda da nova página. Nesse fluxo, você usa quatro ferramentas do Core: create_pdf, add_text, add_page e output_pdf.

Instalação

composer require nextpdf/server

Vincule um transporte: Model Context Protocol (MCP) stdio, REST ou gRPC. Você não precisa de um nível licenciado.

Visão conceitual

Um documento usa uma árvore de páginas. Você acessa cada página por meio dessa árvore (ISO 32000-2 §7.7.3). Uma página tem seus próprios atributos de geometria, incluindo a media box que define a área visível (ISO 32000-2 §7.7.3.3). create_pdf cria a primeira página automaticamente, e add_page anexa cada página adicional. Omita page_size/orientation para herdar o padrão do documento. Defina orientation: "landscape" para que uma página A4 fique com 297×210 mm.

Superfície da API

Ferramenta	Função	Nível de risco
`create_pdf`	Abre a sessão; a primeira página é criada	Seguro
`add_text`	Escreve texto na posição do cursor	Cuidado
`add_page`	Anexa uma página (herda ou substitui)	Cuidado
`output_pdf`	Renderiza e retorna o PDF	Aprovação obrigatória / Revisão (base64)

Os nomes das ferramentas são nomes de protocolo definidos pelo registro. O catálogo de ferramentas é a fonte de referência do registro. As ferramentas disponíveis dependem do nível instalado.

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

Em texto corrido:

create_pdf (A4 retrato, título, autor) → document_id.
add_text (título, fonte grande, centralizado) e, em seguida, add_text (parágrafo de introdução, fonte de corpo).
add_page apenas com o document_id → herda A4 retrato. O novo page_number é retornado e o cursor é reposicionado.
add_text para o título e o corpo da seção na página 2.
add_page com orientation: "landscape" → uma página A4 larga.
add_text para o conteúdo largo.
output_pdf → base64.

Exemplo de código — Produção

Valide cada resposta. Após add_page, o conteúdo começa no topo da nova página. A reposição do cursor é um comportamento intencional, não um bug. Acompanhe position.page nas respostas de add_text para detectar quando o conteúdo avançou para uma página posterior. Chame output_pdf exatamente uma vez e, em seguida, descarte o document_id.

Casos extremos e armadilhas

Reposição do cursor. Após add_page, o cursor fica na margem superior esquerda da nova página. Um erro comum é esperar que ele continue a partir do ponto anterior na página anterior.
document_id obrigatório. Toda ferramenta, exceto create_pdf, exige o document_id. Omiti-lo é um erro.
Orientação inválida. Apenas "portrait" e "landscape" são válidos.
Edição após a saída. O conteúdo adicionado após output_pdf com destroy: true falha, porque a sessão não existe mais.

Desempenho

Um documento de texto com várias páginas permanece dentro do orçamento de páginas, e a saída tem alguns KB. O perfil é structural: o /ID do trailer e os carimbos de data e hora não são estáveis entre execuções.

Notas de segurança

O modo base64 não tem efeitos colaterais. A saída para arquivo é controlada; consulte a seção human-in-the-loop (HITL). O document_id é um identificador opaco. Não o compartilhe entre requisições concorrentes.

Conformidade

Afirmação	Especificação	Cláusula	reference_id
As páginas são acessadas por meio da árvore de páginas.	ISO 32000-2	§7.7.3
Um objeto de página define seus próprios atributos de geometria.	ISO 32000-2	§7.7.3.3

Contexto comercial

Não se aplica — todas as ferramentas são do Core.

Disponibilidade de transporte

Transporte	Disponível	Notas
MCP (stdio)	Sim	`tools/call` por ferramenta.
REST	Sim	Uma operação por ferramenta.
gRPC	Sim	Chamada unária por ferramenta.

Nível de risco HITL

create_pdf é Seguro; add_text e add_page são Cuidado; output_pdf é Aprovação obrigatória, rebaixado para Revisão no modo base64. A saída para arquivo permanece como Aprovação obrigatória. Consulte output-approval e níveis de risco HITL.

Envelope JSON do controle de confirmação

Saída em base64 aqui:

{ "allowed": true }

O formulário de desafio é mostrado em output-approval.