API ZUGFeRD para faturas híbridas PDF/A-3b
Gere faturas ZUGFeRD PDF/A-3b com EN 16931 CII XML incorporado usando o endpoint público E-Invoice Render do gPdf.
/api/v1/e-invoice/render Empacotar a saída PDF de fatura como ZUGFeRD PDF/A-3b com EN 16931 CII XML incorporado depois que seu ERP ou sistema de cobrança preparou os dados corretos da fatura.
Quando usar esta API
- Você precisa de saída ZUGFeRD nativa pelo endpoint público E-Invoice Render.
- Seu sistema já tem EN 16931 CII XML válido para a fatura.
- Você precisa de empacotamento PDF/A-3b com metadados ZUGFeRD e ligação de arquivo associado.
- Você precisa de uma página irmã clara para as páginas mais amplas de e-invoice e Factur-X.
O que ela não substitui
- Você precisa de geração nativa XRechnung ou submissão a portal.
- Você precisa que o gPdf calcule impostos, infira semântica de fatura ou crie XML a partir de registros contábeis.
- Você precisa de padrões não listados no contrato OpenAPI público.
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 - formato mínimo de pacote ZUGFeRD.
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "zugferd",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "ZUGFeRD invoice",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
O que a gPdf faz
- Empacotamento ZUGFeRD por E-Invoice Render.
- Tratamento de perfil PDF/A-3b para saída de fatura híbrida.
- Incorporação do CII XML como arquivo associado com metadados ZUGFeRD.
- Comportamento de entrega inline do PDF ou por objeto conforme documentado.
O que seu sistema controla
- Correção do EN 16931 CII XML, dados da fatura, lógica fiscal e semântica de comprador e vendedor.
- Validação externa, requisitos do destinatário, submissão a portal e interpretação legal.
- Comportamento de retentativa, armazenamento, evidência de auditoria e entrega ao cliente.
Checklist de produção
- Defina settings.e_invoice.standard = zugferd e settings.e_invoice.profile = en16931.
- Use CII XML com format = cii e encoding = utf8.
- Defina settings.profile como pdfa-3b ou omita para aplicar o padrão de e-invoice.
- Valide o PDF retornado com seu fluxo de validação ZUGFeRD.
- Mantenha XRechnung ou submissão a portal fora deste endpoint.
Limites da promessa
- Esta página cobre saída ZUGFeRD por E-Invoice Render.
- Ela não declara geração nativa XRechnung.
- Seu sistema controla os dados de negócio da fatura e a validade do XML.
ZUGFeRD usa o caminho E-Invoice Render
ZUGFeRD não é um endpoint raiz separado. Ele é selecionado pelo campo
settings.e_invoice.standard em POST /api/v1/e-invoice/render. A mesma
fronteira se aplica: o gPdf empacota a fatura híbrida PDF/A-3b; seu sistema
controla os fatos da fatura e a validade do XML.
FAQ
- Qual endpoint renderiza ZUGFeRD?
- Use POST /api/v1/e-invoice/render com settings.e_invoice.standard definido como zugferd.
- Esta página cobre XRechnung?
- Não. Esta página se limita ao contrato público ZUGFeRD. XRechnung não é declarado aqui como saída nativa.
- O gPdf cria o CII XML?
- Seu sistema fornece o EN 16931 CII XML e controla sua correção.
- Posso verificar o resultado?
- Use seu fluxo de validação ZUGFeRD e as páginas do validador gPdf para contexto de validação.