Gere seu primeiro PDF com o NextPDF Connect

Visão geral

Esta receita mostra o caminho mais curto de uma sessão vazia até um PDF renderizado com o NextPDF Connect. Você cria um documento A4 de uma única página, adiciona um título e um subtítulo e, em seguida, retorna o arquivo em base64. Três ferramentas Core fazem o trabalho: create_pdf, add_text e output_pdf. Você não precisa de fontes, imagens nem de um nível licenciado.

Um transporte do Connect envia cada chamada de ferramenta como uma requisição e retorna o resultado da ferramenta como uma resposta. A camada de transporte é independente do resultado retornado pela ferramenta (PSR-18 §p2).

Instalação

Instale o NextPDF Server e configure um transporte:

composer require nextpdf/server

Execute o servidor com o transporte que o host espera: Model Context Protocol sobre stdio, REST ou gRPC. Veja Disponibilidade de transportes abaixo. As ferramentas desta receita são ferramentas Core. Elas vêm com o servidor, portanto você não precisa de um pacote Pro ou Enterprise.

Visão conceitual

Uma sessão do Connect é um armazenamento de documentos do lado do servidor indexado por um document_id. create_pdf abre uma sessão e retorna o ID. Cada chamada de ferramenta posterior usa esse ID. O documento começa com uma página em branco. A árvore de páginas é a estrutura que um leitor usa para chegar a cada página (ISO 32000-2 §7.7.3). output_pdf renderiza a sessão em um PDF. Por padrão, ele destrói a sessão em seguida para liberar memória.

Quando você chama add_text sem um x ou y explícito, o texto flui para a posição apropriada. Ele começa no cursor atual, e o cursor avança após cada chamada.

Superfície da API

O registro de ferramentas resolve estas ferramentas quando o servidor é iniciado. Os nomes mostrados aqui são os nomes de protocolo do registro. O catálogo oficial é o catálogo de ferramentas consolidado. As ferramentas disponíveis dependem do nível instalado, mas estas três estão sempre presentes no Core.

Ferramenta	Função	Nível de risco
`create_pdf`	Abrir uma sessão de documento	Safe
`add_text`	Escrever texto no documento	Caution
`output_pdf`	Renderizar e retornar o PDF	Approval Required (modo de arquivo) / Review (base64)

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

O host faz três chamadas de ferramenta. Na ordem:

Chame create_pdf com page_size: "A4", orientation: "portrait" e o título e o autor do documento. O servidor retorna um document_id.
Chame add_text com esse document_id, o texto do título, um font_size grande, width: 0 (a largura total do conteúdo) e alignment: "center".
Chame output_pdf com o document_id. Sem nenhum file_path, o servidor retorna o PDF como base64 e destrói a sessão.

Veja um objeto mínimo de argumentos para create_pdf:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

A resposta inclui o document_id, a contagem de páginas e a geometria da página. Trate o ID como um valor opaco e não infira nenhum significado a partir dele.

Exemplo de código — Produção

Em produção, o chamador verifica cada resposta antes de fazer a próxima chamada. Ele nunca reutiliza um document_id depois que output_pdf destrói a sessão.

create_pdf — confirme que a resposta contém um document_id. Se o servidor retornar o erro de limite de sessões, libere as sessões não utilizadas e tente novamente.
add_text (título) — confirme que a resposta inclui uma position.
add_text (subtítulo) — use um font_size menor; o cursor continua abaixo do título.
output_pdf — leia o campo base64 e decodifique-o para bytes. O sinalizador destroyed confirma que a sessão foi removida.

O arquivo é retornado inline (modo base64), portanto não há efeito colateral no sistema de arquivos nem portão de aprovação humana. Veja Nível de risco HITL.

Casos extremos e pegadinhas

Sessão destruída. Depois que output_pdf é executado com o padrão destroy: true, o document_id deixa de ser válido. Qualquer chamada posterior que o use retorna um erro de documento desconhecido. Em vez disso, crie uma nova sessão.
Tamanho de página desconhecido. O servidor rejeita um page_size que não reconhece e retorna um erro claro. Use um tamanho documentado (A3, A4, A5, A6, Letter, Legal, Tabloid).
Texto vazio. Um text vazio produz uma entrada de largura zero, não um erro. Verifique a entrada antes da chamada.
Limite de sessões. O armazenamento em memória limita quantas sessões são executadas ao mesmo tempo. Libere as sessões prontamente com output_pdf.

Desempenho

Uma única página somente de texto renderiza com folga dentro do orçamento da página, e a saída costuma ser de 1–3 KB. Esta receita usa o perfil de reprodutibilidade de renderização dupla structural. O PDF carrega um /ID no trailer e carimbos de data/hora que mudam a cada execução, portanto uma comparação estrutural (normalizada) é a mais precisa.

Notas de segurança

O caminho em base64 não tem efeito colateral no sistema de arquivos. O caminho de saída em arquivo tem esse efeito e é controlado por um portão. Veja a seção HITL. Trate o base64 retornado como conteúdo de documento, não como um canal confiável. São exatamente os bytes que as ferramentas produziram.

Conformidade

Declaração	Especificação	Cláusula	reference_id
Um transporte envia uma requisição e recebe uma resposta independentemente do resultado.	PSR-18	§p2
As páginas são acessadas por meio da árvore de páginas do documento.	ISO 32000-2	§7.7.3

Esta receita descreve como o servidor produz a saída. Ela não declara conformidade com nenhum perfil.

Contexto comercial

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

Disponibilidade de transportes

Transporte	Disponível	Notas
MCP (stdio)	Sim	As chamadas de ferramenta correspondem a `tools/call` do MCP.
REST	Sim	Cada ferramenta é uma operação REST; o resultado é o corpo da resposta.
gRPC	Sim	Cada ferramenta é uma chamada unária.

O resultado da ferramenta é o mesmo em todos os transportes; apenas o enquadramento difere. Um resultado malsucedido ainda é uma resposta normal, não uma falha de transporte (PSR-18 §p2).

Nível de risco HITL

O servidor coloca cada chamada de ferramenta em uma escala de risco com humano no circuito (human-in-the-loop, HITL): Safe (0) → Caution (1) → Review (2) → Approval Required (3). create_pdf é Safe, e add_text é Caution. output_pdf é Approval Required, mas no modo base64 (sem file_path) ele passa para Review e é executado sem uma confirmação humana. Gravar em um arquivo o mantém em Approval Required. Veja output-approval e a referência de níveis de risco HITL.

Envelope JSON do portão de confirmação

Esta receita permanece em modo base64, portanto o portão de confirmação retorna o envelope de permissão:

{ "allowed": true }

O envelope de desafio (allowed: false, com uma string challenge e um token de uso único) está documentado em output-approval.