API de geração de PDFs em lote para filas e jobs
Gere muitos PDFs por fluxos JSON Render ou Template Render seguros para filas, enquanto seu sistema assume divisão em blocos, retentativas, idempotência e armazenamento.
/api/v1/template-render Renderizar muitos PDFs a partir de uma fila ou job agendado, dividindo o trabalho em requisições seguras, enviando cada documento ou item de dados de modelo ao gPdf e armazenando ou entregando o PDF retornado no seu próprio sistema.
Quando usar esta API
- Você precisa gerar faturas, extratos, etiquetas ou relatórios em um lote agendado ou orientado a eventos.
- Você tem um modelo estável e pode enviar vários itens de data dentro dos limites do endpoint.
- Você precisa de renderização amigável a filas sem executar workers de navegador.
- Você pode assumir deduplicação, retentativas e armazenamento de saída.
O que ela não substitui
- Você precisa que o gPdf seja seu agendador de lotes, fila, sistema de armazenamento ou ledger de idempotência.
- Você precisa de cabeçalhos publicados de limite de taxa ou de um contrato server-side de idempotency-key.
- Você precisa de uma única requisição sem limite para renderizar todos os documentos de uma campanha.
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 - lote pequeno com dois itens de dados de fatura.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
O que a gPdf faz
- Renderização de PDF para cada requisição JSON Render ou Template Render.
- Arrays data de Template Render dentro dos limites públicos documentados.
- Respostas de renderização rápidas e sem estado, adequadas para workers de fila.
- Comportamento compartilhado de ID de requisição e envelope de erro.
O que seu sistema controla
- Desenho da fila, divisão em blocos, concorrência, retentativas, deduplicação e armazenamento de saída.
- Seleção dos objetos de negócio, escolha do modelo e fluxo de entrega.
- Política de backoff, alertas e recuperação após falha parcial.
Checklist de produção
- Divida o trabalho para que cada requisição fique dentro dos limites documentados de itens e corpo de requisição.
- Gere um X-Request-Id por requisição e mapeie-o para o ID do seu job.
- Repita apenas falhas de rede ou 5xx, com backoff exponencial limitado.
- Não repita falhas de validação 4xx sem alterar o corpo da requisição.
- Armazene PDFs de saída ou dados de origem de acordo com sua política de retenção.
Limites da promessa
- O gPdf é a API de renderização, não a camada de fila ou armazenamento.
- Hoje, a API pública não publica cabeçalhos de limite de taxa nem chaves de idempotência server-side.
- Seu sistema precisa tornar as retentativas seguras.
Geração em lote é um padrão de integração
A geração de PDFs em lote não é um endpoint separado. Ela é a forma como sua fila usa as APIs públicas de renderização. Mantenha os jobs pequenos, observáveis e seguros para retentativas.
Para layouts repetidos, Template Render costuma oferecer o contrato mais limpo. Para documentos programáticos com layouts personalizados, JSON Render continua disponível.
FAQ
- O gPdf oferece uma API de job em lote?
- Não há um agendador de lotes separado exposto. Use JSON Render ou Template Render a partir da sua própria fila ou sistema de workers.
- Template Render pode aceitar vários itens de data?
- Sim, dentro dos limites públicos do endpoint. Divida jobs maiores em várias requisições.
- Quem é responsável pelas retentativas?
- Seu sistema é responsável por retentativas, backoff, deduplicação e idempotência. O gPdf ecoa IDs de requisição para rastreabilidade.
- Posso renderizar muitos layouts diferentes em uma única requisição?
- Use requisições separadas quando layouts ou IDs de modelo forem diferentes. Mantenha cada requisição simples e rastreável.