API de JSON para PDF para geração estruturada de documentos
Transforme corpos de requisição estruturados DocumentRequest em PDFs com páginas, coordenadas, texto, tabelas, códigos de barras, metadados e configurações PDF/A.
/api/v1/pdf/render Converter dados estruturados da aplicação em documentos PDF determinísticos sem executar um navegador, enviar HTML/CSS ou armazenar arquivos de clientes. Seu sistema envia páginas, elementos, coordenadas, configurações e conteúdo de negócio; o gPdf retorna uma resposta application/pdf.
Quando usar esta API
- Seu backend já tem dados estruturados e precisa de uma resposta em PDF.
- Você quer páginas, coordenadas, elementos, códigos de barras e configurações explícitas, em vez de layout em HTML.
- Você precisa de saída repetível para faturas, etiquetas, relatórios, extratos ou pacotes gerados.
- Você quer testar os dados enviados no Playground antes de colocar um token em produção.
O que ela não substitui
- Você precisa converter HTML arbitrário em PDF. O gPdf usa JSON DocumentRequest, não um DOM de navegador.
- Sua equipe quer um contrato template_id estável. Use Template Render depois que o layout for publicado.
- Você precisa de empacotamento de e-invoice Factur-X ou ZUGFeRD. Use o endpoint E-Invoice Render.
Qual endpoint chamar
/api/v1/pdf/render
JSON Render é o caminho padrão para este fluxo.
/api/v1/template-render
Use quando o fluxo precisar da API relacionada, de um contrato de template ou de uma consulta de capacidades.
Request mínimo
POST /api/v1/pdf/render - DocumentRequest JSON de uma página.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
O que a gPdf faz
- Renderização de DocumentRequest a partir de páginas e elementos.
- Texto, tabelas, imagens, códigos de barras vetoriais, linhas, formas, marcas d'água, metadados e configurações PDF/A.
- Incorporação de fontes e fontes substitutas para latim, CJK, fontes compatíveis com emoji e outros scripts suportados.
- Resposta binária em PDF com o envelope compartilhado de códigos de erro do gPdf em caso de falha.
O que seu sistema controla
- Dados de negócio, mapeamento de campos e semântica do documento.
- IDs de requisição, estratégia de retentativa e idempotência, nomes de arquivo e armazenamento após a resposta.
- Qualquer regra fiscal, de fatura, transportadora, compliance ou específica do cliente antes da renderização.
Checklist de produção
- Gere e envie um X-Request-Id para rastreabilidade.
- Valide os corpos de requisição contra o OpenAPI ou a documentação antes de enviar tráfego real.
- Mantenha a URL base da API configurável e armazene o bearer token fora do código-fonte.
- Decida se a saída deve ser exibida inline ou em modo attachment.
- Adicione testes golden-PDF para layouts críticos, para que mudanças de modelo ou dados fiquem visíveis.
Limites da promessa
- Esta não é uma API de HTML para PDF e não executa Chromium.
- A API renderiza o documento que você descreve; ela não infere significado legal ou de negócio a partir dos seus dados.
- Para layouts repetidos, Template Render costuma ser o melhor contrato público.
Como o fluxo JSON Render se encaixa
JSON Render é o caminho público de renderização no nível mais baixo. Sua aplicação envia a estrutura do documento diretamente: tamanho da página, elementos, coordenadas, estilo, metadados, modo de saída e configurações PDF/A opcionais. Essa é a camada certa quando o layout do documento é gerado por código ou quando a equipe quer controle em nível de pixel sobre o PDF.
O contrato da API é explícito. Se o seu sistema envia um elemento de texto, o gPdf renderiza um elemento de texto. Se envia um elemento de código de barras, o gPdf desenha o código de barras como conteúdo vetorial no PDF. O gPdf não lê a intenção de negócio do corpo da requisição e não decide se o número da fatura, o valor de rastreamento da transportadora ou o campo fiscal está correto.
Quando migrar para Template Render
Se o mesmo layout é usado repetidamente em vários sistemas, publique-o como um
modelo e chame POST /api/v1/template-render com template_id mais data[].
Isso tira a responsabilidade pelo layout de cada chamador e dá ao seu ERP, OMS,
WMS ou backend SaaS um contrato de campos estável.
Use JSON Render para criação de layout, documentos pontuais e documentos programáticos. Use Template Render quando o layout estiver fixo e a única coisa que muda em cada requisição forem os dados de negócio.
Formato de produção
Em produção, trate uma requisição de PDF como qualquer outra chamada importante de API: inclua um ID de requisição, defina tempo limite, torne as retentativas idempotentes, registre os metadados da resposta e armazene o PDF retornado somente no seu próprio sistema se a retenção for necessária. O caminho de renderização do gPdf é sem estado depois de uma resposta de renderização padrão.
FAQ
- Esta é uma API de HTML para PDF?
- Não. O gPdf aceita um DocumentRequest JSON estruturado com páginas, elementos, coordenadas e configurações. Ele não executa um navegador nem processa HTML/CSS arbitrário.
- Qual endpoint devo chamar primeiro?
- Comece com POST /api/v1/pdf/render quando quiser controle direto sobre o layout. Migre para POST /api/v1/template-render quando o layout precisar virar um contrato template_id estável.
- A API retorna o PDF diretamente?
- Sim. Uma renderização bem-sucedida retorna application/pdf. Erros usam o envelope JSON compartilhado com um código API-XXX e req_id.
- Posso testar sem criar uma integração?
- Use o gPdf Playground para testar dados JSON interativamente e depois leve o mesmo formato DocumentRequest para o cliente do seu backend.