API de PDF por modelo para contratos de documento estáveis
Renderize PDFs a partir de um template_id estável e um array data quando layouts repetidos devem ser mantidos uma vez e reutilizados por chamadores ERP, OMS, WMS ou SaaS.
/api/v1/template-render Renderizar PDFs repetidos enviando um template_id estável e um array de dados de negócio, em vez de exigir que cada chamador descreva páginas, coordenadas e elementos de layout a cada requisição.
Quando usar esta API
- O layout do documento já foi aprovado e é reutilizado por vários chamadores ou jobs.
- Os chamadores devem enviar dados de negócio, não JSON de layout em nível de coordenadas.
- Você precisa gerar faturas, listas de embalagem, etiquetas de envio ou modelos personalizados.
- Você quer controlar revisões ativas de modelo fora do chamador.
O que ela não substitui
- Você ainda está desenhando o layout. Use JSON Render até que coordenadas e campos estejam estáveis.
- Você precisa converter HTML arbitrário em PDF.
- Você precisa de empacotamento de e-invoice PDF/A-3b com CII XML incorporado.
Qual endpoint chamar
/api/v1/template-render
Template Render é o caminho padrão para este fluxo.
/api/v1/pdf/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/template-render - renderizar uma fatura a partir de um modelo.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-001",
"date_of_issue": "2026-05-29",
"date_due": "2026-06-28",
"issuer_name": "Acme Cloud Inc.",
"issuer_address": "88 Harbor Rd, Long Beach, CA",
"bill_to_name": "Receiver Inc.",
"bill_to_address": "123 Main St, Los Angeles, CA",
"subtotal": "$100.00",
"total": "$100.00",
"amount_due": "$100.00",
"items": [
{
"description": "Service A",
"qty": 1,
"unit_price": "$100.00",
"amount": "$100.00"
}
]
}
]
}
O que a gPdf faz
- Busca de modelo por template_id estável.
- Renderização de cada item de data contra o modelo ativo.
- Concatenação das páginas renderizadas em um único PDF dentro dos limites públicos do endpoint.
- Comportamento compartilhado de autenticação, ID de requisição e envelope de erro.
O que seu sistema controla
- Seleção do modelo, mapeamento de campos, dados de negócio e autorização do chamador.
- Fluxo de publicação do modelo, comunicação de mudanças e cobertura de testes.
- Divisão em blocos, enfileiramento e retentativas ao renderizar muitos documentos.
Checklist de produção
- Trate template_id como um contrato opaco e estável.
- Valide os campos de data antes de chamar Template Render.
- Mantenha testes golden-PDF para o modelo ativo e dados representativos.
- Divida lotes grandes de acordo com os limites públicos de Template Render.
- Registre template_id, ID de requisição e IDs dos objetos de negócio para rastreabilidade.
Limites da promessa
- Template Render não é, por si só, uma ferramenta de design; os modelos já precisam estar publicados.
- O gPdf não infere dados de negócio ausentes a partir do modelo.
- Template Render não substitui o endpoint E-Invoice Render.
Template Render é a camada de contrato em produção
JSON Render é ideal enquanto o layout está sendo desenhado. Template Render é a
camada a usar depois que o layout vira um contrato. Os chamadores enviam
template_id e data; o modelo ativo fica responsável pela estrutura do
documento.
Isso mantém os chamadores menores e torna as mudanças de modelo mais fáceis de revisar, testar e publicar.
FAQ
- Quando devo usar Template Render em vez de JSON Render?
- Use Template Render depois que o layout estiver aprovado e os chamadores precisarem enviar apenas dados de negócio.
- O template_id é estável?
- Sim. A documentação da Template API descreve template_id como o identificador estável voltado ao chamador.
- Uma requisição pode renderizar vários itens de data?
- Sim, Template Render aceita um array data dentro dos limites públicos do endpoint.
- Template Render pode criar e-invoices?
- Não. O empacotamento Factur-X e ZUGFeRD em PDF/A-3b usa o endpoint E-Invoice Render.