API de e-invoice para Factur-X e ZUGFeRD PDF/A-3b
Gere e-invoices Factur-X e ZUGFeRD em PDF/A-3b com EN 16931 CII XML incorporado pelo endpoint público de e-invoice do gPdf.
/api/v1/e-invoice/render Empacotar um PDF de fatura legível por humanos e EN 16931 CII XML fornecido pelo chamador em uma e-invoice Factur-X ou ZUGFeRD PDF/A-3b que possa ser validada por motores externos de referência para PDF/A e e-invoice.
Quando usar esta API
- Você precisa de saída Factur-X ou ZUGFeRD, não apenas de um PDF de fatura comum.
- Seu sistema consegue fornecer EN 16931 CII XML correto para a fatura.
- Você precisa de empacotamento PDF/A-3b, metadados de anexo e ligação XMP de e-invoice.
- Você quer que o endpoint público de capacidades confirme padrões e perfis suportados.
O que ela não substitui
- Você precisa apenas de um PDF comum de fatura para o cliente. Use JSON Render ou Template Render.
- Você precisa de saída nativa XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e ou GST antes que o OpenAPI a liste.
- Você espera que o gPdf crie XML de fatura legalmente correto a partir de dados de negócio incompletos.
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
POST /api/v1/e-invoice/render - requisição mínima Factur-X PDF/A-3b.
{
"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
- Empacotamento Factur-X ou ZUGFeRD PDF/A-3b por POST /api/v1/e-invoice/render.
- Incorporação do EN 16931 CII XML fornecido pelo chamador como arquivo associado.
- Metadados do wrapper PDF/A-3b e ligação XMP específica do padrão de e-invoice.
- Descoberta de capacidades por GET /api/v1/e-invoice/capabilities.
O que seu sistema controla
- Semântica de negócio da fatura, regras fiscais, identificadores de comprador/vendedor e correção do XML EN 16931.
- Escolha entre Factur-X ou ZUGFeRD conforme o fluxo do destinatário.
- Testes externos de aceite com o recebedor, sistema de automação de contas a pagar ou processo local de compliance.
Checklist de produção
- Chame /api/v1/e-invoice/capabilities antes de presumir um padrão ou perfil.
- Valide o EN 16931 CII XML antes de incorporá-lo.
- Passe a saída por /validator/ ou pelo seu próprio pipeline de motor de referência.
- Mantenha geração de PDF de fatura comum e empacotamento legal de e-invoice separados no código.
- Registre IDs de requisição, padrão, perfil, versão da fonte XML e evidência de validação.
Limites da promessa
- A saída pública nativa de e-invoice é Factur-X / ZUGFeRD com EN 16931 CII XML.
- Outros nomes nacionais de e-invoice são contexto de mercado, a menos que o OpenAPI os liste como padrões suportados.
- O gPdf empacota XML fornecido pelo chamador; seu sistema continua responsável pela correção de negócio do XML.
Um endpoint para o pacote de e-invoice
O endpoint de e-invoice existe porque este fluxo não é apenas “renderizar um PDF de fatura”. Ele precisa produzir um wrapper PDF/A-3b com os metadados corretos de arquivo associado e XMP específico do padrão, incorporando o EN 16931 CII XML fornecido pelo chamador.
Chame POST /api/v1/e-invoice/render quando a saída exigida for Factur-X ou
ZUGFeRD. Use GET /api/v1/e-invoice/capabilities quando sua integração quiser
confirmar padrões, perfis, tipos de documento e formatos XML suportados antes de
enviar trabalho.
O que fica fora do gPdf
A semântica do XML continua sendo sua responsabilidade. O gPdf não consegue saber se um número de fatura é legal, se um valor de imposto está correto, se um identificador do comprador corresponde ao parceiro comercial ou se um recebedor específico vai aceitar uma variante do processo de negócio. Gere e valide o XML antes, depois use o gPdf para empacotamento PDF/A-3b e renderização.
Não transforme termos de roadmap em suporte nativo
É válido discutir XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e ou GST como contexto de mercado. Não apresente esses nomes como saída nativa pública do renderizador a menos que o contrato de capacidades OpenAPI os liste.
FAQ
- Quais padrões de e-invoice têm saída pública nativa hoje?
- A saída pública nativa é Factur-X e ZUGFeRD PDF/A-3b com EN 16931 CII XML incorporado. Consulte /api/v1/e-invoice/capabilities para o contrato atual.
- O gPdf gera o EN 16931 XML para mim?
- Não. Seu sistema fornece o conteúdo XML. O gPdf o empacota no wrapper de e-invoice PDF/A-3b com os metadados de anexo exigidos.
- Posso enviar settings.e_invoice para JSON Render?
- Não. O empacotamento de e-invoice pertence ao POST /api/v1/e-invoice/render. A documentação pública informa que settings.e_invoice é específico da rota.
- Como devo validar a saída?
- Use o validador gPdf ou seu próprio fluxo de motor de referência para verificar tanto a camada PDF/A quanto a camada XML de e-invoice incorporada.