API de PDF de fatura para sistemas de cobrança e finanças
Gere PDFs de faturas comuns a partir de dados de cobrança com JSON Render ou Template Render, mantendo lógica fiscal e contábil no seu sistema.
/api/v1/pdf/render Transformar dados de fatura de um sistema de cobrança, ERP ou SaaS em uma fatura PDF legível, mantendo numeração, impostos, estado de pagamento e semântica contábil dentro do sistema chamador.
Quando usar esta API
- Você precisa de PDFs de faturas comuns para clientes, recibos, extratos ou exportações contábeis.
- Seu sistema já controla números de fatura, cálculo de impostos, itens de linha e estado de pagamento.
- Você quer tabelas, totais, metadados e configurações PDF/A opcionais sem executar um navegador.
- Você quer um contrato template_id para layouts de fatura repetidos.
O que ela não substitui
- Você precisa de um pacote legal de e-invoice, como Factur-X ou ZUGFeRD. Use E-Invoice Render.
- Você espera que o gPdf calcule impostos, valide regras contábeis ou reconcilie pagamentos.
- Você quer converter uma fatura HTML arbitrária em vez de usar JSON estruturado ou modelos.
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.
/api/v1/e-invoice/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 - cabeçalho e total mínimos de uma fatura.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
O que a gPdf faz
- Renderização de PDF de fatura a partir de páginas JSON ou dados de modelo.
- Texto, tabelas, blocos de totais, paginação, metadados e saída PDF/A opcional.
- Template Render para layouts de fatura estáveis usados por vários sistemas.
- Resposta binária em PDF e envelope de erro consistente da API.
O que seu sistema controla
- Números de fatura, estado de pagamento, cálculo de impostos, descontos, créditos e significado no ledger.
- Dados do cliente e do emissor, mapeamento de itens de linha, moedas e regras de arredondamento.
- Retenção, entrega, e-mail, links de pagamento e reconciliação com o sistema contábil.
Checklist de produção
- Confirme que cada campo visível da fatura mapeia para dados de cobrança de origem.
- Teste estouro de itens de linha, nomes longos de clientes, faturas com várias páginas e totais.
- Decida se o layout pertence ao JSON Render ou a um modelo publicado.
- Mantenha a geração de PDF de fatura comum separada do empacotamento legal de e-invoice.
- Armazene IDs de requisição e nomes de arquivo de saída junto aos registros de fatura.
Limites da promessa
- PDFs de fatura comuns não são a mesma coisa que mandatos legais de e-invoice.
- O gPdf renderiza o documento de fatura; ele não calcula impostos nem estado contábil.
- Saída Factur-X / ZUGFeRD pertence ao POST /api/v1/e-invoice/render.
Faturas comuns versus e-invoices
Um PDF de fatura comum é o documento que seu cliente lê. Ele pode ser gerado com JSON Render ou Template Render. Seu sistema decide o número da fatura, impostos, itens de linha, moeda e estado de pagamento; depois o gPdf renderiza o PDF visível.
Uma e-invoice legal é diferente. Factur-X e ZUGFeRD combinam uma fatura
PDF/A-3b legível com EN 16931 CII XML incorporado. Use
POST /api/v1/e-invoice/render para esse pacote.
Template Render costuma ser o endpoint de produção
Equipes financeiras raramente querem que cada serviço reconstrua coordenadas de
fatura. O caminho comum é desenhar a fatura uma vez, publicá-la como modelo e
dar aos chamadores um template_id estável mais um schema de dados. JSON Render
continua útil para layouts personalizados, ferramentas internas e prototipagem
de modelos.
Mantenha a lógica contábil antes da renderização
O gPdf deve receber valores finais de exibição, não decisões contábeis ainda em aberto. Calcule impostos, descontos, arredondamento, status de pagamento e elegibilidade da fatura antes de chamar a API de renderização. Isso torna a saída em PDF determinística e mantém o sistema financeiro como fonte de referência.
FAQ
- Um PDF de fatura é o mesmo que uma e-invoice?
- Não. Um PDF de fatura comum é uma saída legível por humanos. Uma e-invoice Factur-X ou ZUGFeRD também incorpora EN 16931 CII XML dentro de um wrapper PDF/A-3b.
- Qual endpoint deve ser usado para faturas repetidas?
- Use Template Render quando o layout da fatura estiver estável e os chamadores precisarem enviar apenas template_id mais data. Use JSON Render quando o código for responsável pelo layout.
- O gPdf calcula impostos?
- Não. Seu sistema de cobrança ou contabilidade calcula impostos, totais, descontos e estado de pagamento antes de enviar os dados de renderização.
- PDFs de fatura podem usar PDF/A?
- Sim, JSON Render oferece suporte a configurações PDF/A. Use E-Invoice Render especificamente quando a fatura precisar ser empacotada como Factur-X ou ZUGFeRD.