API de e-invoice para sistemas de produção
Gere e-invoice a partir de dados estruturados do backend, sem navegador, com fronteira clara entre o PDF renderizado pela gPdf e as regras do seu sistema.
/api/v1/e-invoice/render Gerar e-invoice como PDF reproduzível a partir de dados estruturados. Seu sistema mantém a lógica de negócio; a gPdf cuida do rendering PDF.
Quando usar esta API
- Seu backend já possui os dados de e-invoice e precisa de uma resposta PDF estável.
- Você quer evitar Chromium ou HTML-to-PDF em documentos operacionais.
- Você precisa de saída repetível para reimpressão, auditoria ou lotes.
O que ela não substitui
- Você precisa que a gPdf compre frete, liquide impostos, crie pedidos externos ou atue como sistema fiscal.
- Você precisa substituir validação de dados, regras de negócio ou integrações com marketplaces.
Qual endpoint chamar
/api/v1/e-invoice/render
E-Invoice Render é o caminho padrão para este fluxo.
/api/v1/e-invoice/capabilities
Use quando o fluxo precisar da API relacionada, de um contrato de template ou de uma consulta de capacidades.
Request mínimo
/api/v1/e-invoice/render - e-invoice
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
O que a gPdf faz
- Rendering PDF de e-invoice a partir de requests estruturados.
- Texto, tabelas, linhas, códigos de barras, páginas, metadados e opções de saída conforme o request.
- Saída determinística para retries, reimpressões e auditoria.
O que seu sistema controla
- Dados corretos de e-invoice, regras de negócio e estado operacional.
- Autenticação, persistência, integrações externas e validação com receptores finais.
Checklist de produção
- Teste com dados reais e com os sistemas que receberão o PDF.
- Armazene request IDs e evidências para suporte, auditoria e reimpressão.
- Promova o layout aprovado para template quando vários sistemas forem reutilizá-lo.
Limites da promessa
- A gPdf usa o endpoint público de e-invoice para Factur-X / ZUGFeRD PDF/A-3b.
- Portais fiscais, PDP, SDI, KSeF, ZATCA, IRP, Peppol e obrigações legais ficam fora do escopo.
- Seu sistema mantém dados do comprador, lógica fiscal, roteamento e interpretação legal local.
Formato da API
API de e-invoice é um workflow de produção sobre as APIs públicas da gPdf. O request descreve dados, layout, settings e partes do PDF que devem ser renderizadas. A gPdf renderiza o PDF; seu sistema mantém a semântica do evento de negócio.
Escolha do endpoint
Para este fluxo, o endpoint padrão é /api/v1/e-invoice/render. Use Template Render quando o layout estiver aprovado e reutilizado entre sistemas. Use E-Invoice Render apenas quando precisar do pacote Factur-X / ZUGFeRD PDF/A-3b com EN 16931 CII XML incorporado.
Validação antes da produção
Valide e-invoice com dados reais e com os sistemas que vão consumi-lo. Guarde request IDs, saída renderizada e evidências de validação para suporte, auditoria e reimpressão.
FAQ
- É um endpoint separado?
- API de e-invoice usa o endpoint público de e-invoice quando o fluxo precisa de Factur-X / ZUGFeRD PDF/A-3b. Não é uma superfície separada.
- Cobre redes locais de clearance?
- Não. A gPdf renderiza e empacota o PDF/e-invoice; portais fiscais e roteamento legal ficam no seu sistema.
- Posso continuar usando JSON Render?
- Sim para PDFs comuns. Use E-Invoice Render quando o resultado precisar incluir o pacote estruturado da API pública.