Conhecimento · Fatura eletrónica
Validar a fatura eletrónica e ler corretamente o relatório de validação
Quando uma fatura eletrónica emitida pelo seu software é rejeitada, a sua equipa tem de descobrir, com base no relatório de validação, que campo originou a mensagem e quem o pode corrigir.
Mostramos como ler um relatório de validação e em que pontos a validação deve estar presente no seu software.
O que é verificado na validação de uma fatura eletrónica
Um validador verifica uma fatura eletrónica sucessivamente face a três conjuntos de regras e regista cada desvio num relatório de validação.
Esquema XML da sintaxe
Uma fatura eletrónica segundo a EN 16931 existe numa de duas sintaxes, UBL ou UN/CEFACT CII. Todas as especificações de aplicação habituais assentam nestas duas sintaxes, por exemplo XRechnung, ZUGFeRD e Peppol BIS Billing 3.0.
O esquema XML da sintaxe define que elementos são permitidos, em que ordem surgem e que tipo de dados têm.
Os erros de esquema não têm ID de regra. O analisador XML comunica-os com códigos próprios, por exemplo cvc-complex-type.2.4.a para um elemento num local onde o esquema não o espera.
No ZUGFeRD, um ficheiro CII está incorporado num PDF. O validador verifica a parte XML. Em caso de divergência com a parte visual, é esta parte que prevalece, segundo a circular do Ministério Federal das Finanças (BMF-Schreiben) de 15 de outubro de 2025 sobre a introdução da fatura eletrónica obrigatória.
Regras de negócio da EN 16931
As regras de negócio controlam os dados de uma fatura eletrónica quanto a erros lógicos, por exemplo se os campos obrigatórios estão preenchidos e se os totais batem certo entre si. O Comité Europeu de Normalização (CEN) publica estas regras como ficheiros Schematron no GitHub, respetivamente para UBL e para CII.
Pelo prefixo do ID de regra reconhece o tipo de verificação. As regras com BR e um número verificam os campos obrigatórios e a sua quantidade, BR-CO verifica cálculos e dependências entre campos, BR-CL verifica listas de códigos e BR-DEC as casas decimais dos montantes. Regras como BR-S, BR-AE ou BR-IC verificam os dados relativos a categorias de IVA específicas.
Os ficheiros do CEN contêm ainda regras específicas da sintaxe. As regras com o prefixo UBL-CR emitem, por exemplo, um aviso quando um ficheiro UBL contém elementos que não pertencem ao modelo de dados da EN 16931.
Regras da XRechnung e do Peppol BIS Billing 3.0
A XRechnung e o Peppol BIS Billing 3.0 são especificações de aplicação da EN 16931, designadas tecnicamente CIUS (Core Invoice Usage Specification). Tornam obrigatórios campos adicionais e complementam a EN 16931 com regras próprias. Uma CIUS não pode introduzir novos campos de dados.
As regras da XRechnung começam por BR-DE e provêm do Centro de Coordenação de Normas Informáticas (Koordinierungsstelle für IT-Standards, KoSIT). O Peppol BIS Billing 3.0 acrescenta regras com os prefixos PEPPOL-EN16931 e PEPPOL-COMMON, bem como regras específicas de cada país.
O identificador da especificação em BT-24 determina que especificação de aplicação se aplica ao ficheiro. O validador da KoSIT escolhe com base neste identificador o cenário de verificação adequado. Um identificador errado ou desatualizado pode, por isso, fazer com que o ficheiro seja verificado face a outras regras ou rejeitado.
O que uma validação não verifica
Um validador não deteta se a taxa de imposto corresponde ao serviço nem se a descrição do serviço é suficiente.
Segundo o Ministério Federal das Finanças da Alemanha, todos os dados obrigatórios para efeitos de IVA têm de constar da parte estruturada da fatura eletrónica. Uma simples remissão para um anexo com a descrição do serviço não basta. Ainda assim, um nome de artigo como «ver anexo» em BT-153 passa na validação, porque nenhuma regra avalia o conteúdo deste campo.
A KoSIT e o Fórum Alemão da Fatura Eletrónica (Forum elektronische Rechnung Deutschland, FeRD) publicaram uma tabela que associa os dados obrigatórios segundo a lei alemã do IVA aos campos BT correspondentes. Com base nesta tabela, pode definir que dados obrigatórios o seu software deve salvaguardar com verificações de plausibilidade próprias.
Estrutura de um relatório de validação
Cada entrada do relatório de validação contém, em regra, quatro dados.
ID de regra
O ID de regra, como BR-CO-15 ou BR-DE-2, remete para a regra na documentação do respetivo conjunto de regras.
Nível de gravidade
Um validador classifica cada mensagem como erro ou como aviso. Nas regras Peppol, os erros chamam-se fatal. Um aviso, por si só, não leva normalmente à rejeição. Alguns validadores emitem ainda notas, ou seja, recomendações para uma implementação correta sem influência no resultado. No final do seu relatório, o validador da KoSIT recomenda aceitar ou rejeitar o documento.
O Peppol introduz frequentemente novas regras primeiro como aviso e, numa versão posterior, eleva-as a erro. Com a versão 3.0.21, por exemplo, as regras PEPPOL-COMMON-R052 e PEPPOL-COMMON-R053 passaram de avisos a erros, como consta das notas de versão do Peppol BIS Billing 3.0.
Localização
A localização é uma expressão XPath que aponta para o elemento afetado no XML. O mesmo número BT encontra-se em locais diferentes em UBL e em CII. O montante da fatura com IVA (BT-112) está, em UBL, no elemento cbc:TaxInclusiveAmount sob cac:LegalMonetaryTotal e, em CII, no elemento ram:GrandTotalAmount sob ram:SpecifiedTradeSettlementHeaderMonetarySummation.
Nas regras que comparam vários campos, a localização aponta muitas vezes para um elemento de nível superior. O valor que origina a mensagem encontra-se então através do texto da mensagem.
Texto da mensagem
O texto da mensagem descreve a regra e indica, na maioria dos casos, os números BT envolvidos. A mensagem relativa a BR-CO-15 diz, por exemplo, que o montante da fatura com IVA (BT-112) tem de corresponder à soma do montante da fatura sem IVA (BT-109) com o montante do IVA (BT-110).
Desde a versão 3.0.21, os textos das regras Peppol começam pelo ID de regra.
Analisar os relatórios de validação pela ordem certa
Um relatório de validação longo deve-se muitas vezes a poucas causas.
-
Corrigir os erros de esquema
Enquanto o ficheiro não cumprir o esquema, os resultados das regras de negócio são pouco significativos ou nem existem. Por isso, corrija primeiro os erros de esquema na exportação e valide depois o ficheiro novamente.
-
Agrupar as entradas por ID de regra
Um erro no mapeamento pode surgir em cada linha da fatura. Uma fatura com 40 linhas gera então 40 entradas da mesma regra, que se devem a uma única causa. Por isso, analise o relatório por IDs de regra.
-
Identificar erros consequentes
Um elemento em falta pode violar várias regras ao mesmo tempo. Se faltar a discriminação do IVA (BG-23), o validador comunica, por exemplo, BR-CO-18 e, adicionalmente, regras da categoria de IVA afetada, como BR-S-01. Corrija primeiro a causa e valide novamente antes de tratar individualmente as restantes mensagens.
-
Do número BT para o modelo de dados próprio
O número BT liga o relatório de validação ao seu software. Mantenha uma correspondência entre cada número BT e o campo da base de dados, o campo do formulário na sua interface e a responsabilidade. A responsabilidade define se é a sua equipa que corrige um erro ou o seu cliente, por exemplo quando faltam dados mestre.
-
Avaliar e registar os avisos
Decida, para cada aviso, se o corrige ou se o aceita conscientemente, e registe a decisão. Em cada nova versão, verifique se um aviso aceite foi elevado a erro.
Causas de erro típicas por grupo de regras
O grupo de regras indica muitas vezes, desde logo, em que ponto do seu software deve ser feita a correção.
Erros de esquema sem ID de regra
A causa está na ordem dos elementos, no namespace ou num tipo de dados errado na exportação. A correção é feita na função de exportação, uma única vez para todos os clientes.
BR com número
A causa está num campo obrigatório que não está mapeado ou que está vazio nos dados mestre. A correção é feita no mapeamento ou no campo obrigatório na interface.
BR-CO e BR-DEC
A causa está nos totais, nos arredondamentos, nos descontos e nos encargos ao nível do documento. A correção é feita na lógica de cálculo da emissão das faturas.
BR-CL
A causa está num código desatualizado ou próprio, por exemplo para unidades de medida ou países. A correção é feita nas listas de códigos do seu software.
BR-S, BR-AE, BR-IC e outras categorias
A categoria de IVA, a taxa de imposto e o motivo de isenção não são coerentes entre si. A correção é feita na lógica fiscal e nos dados mestre dos artigos.
UBL-CR
A exportação contém elementos UBL fora do modelo de dados da EN 16931. A correção é feita na função de exportação.
BR-DE
Faltam os dados de contacto do vendedor, os dados de pagamento ou a referência do comprador. A correção é feita, na maioria dos casos, nos dados mestre dos seus clientes.
PEPPOL-EN16931 e PEPPOL-COMMON
Falta o endereço eletrónico ou um identificador tem o formato errado. A correção é feita nos dados mestre e na gestão dos IDs Peppol.
Referência do comprador em falta na XRechnung (BR-DE-15)
A regra BR-DE-15 assinala a falta da referência do comprador em BT-10. Nas faturas para a administração pública, este campo contém o Leitweg-ID da entidade. Para faturas B2B, segundo o Ministério Federal das Finanças da Alemanha, basta para efeitos de IVA um marcador como «-», se o destinatário da fatura não indicar um identificador próprio. O seu software pode, por isso, pré-preencher o campo em faturas B2B com um marcador que os seus clientes possam substituir.
Diferenças de arredondamento no IVA (BR-S-09)
A regra BR-S-09 compara o montante do IVA da categoria de taxa normal com o produto da matéria coletável pela taxa de imposto. Se o seu software arredondar o IVA por linha e somar os montantes, o total pode divergir. Com muitas linhas, a divergência pode tornar-se maior do que a tolerância que a regra admite. Por isso, calcule o montante do imposto por categoria a partir da matéria coletável e da taxa de imposto, tal como a regra prevê.
Integrar a validação no seu software
A validação deve estar presente em cinco pontos do seu software e do seu processo de desenvolvimento.
Antes do envio
O seu software deve validar cada fatura eletrónica logo após a sua criação e suspender o envio em caso de erros. Os seus clientes pouco podem fazer com um ID de regra ou uma expressão XPath. Por isso, traduza as regras que os seus clientes podem corrigir eles próprios numa indicação junto do campo de formulário afetado. A indicação relativa a BR-DE-6, o número de telefone do contacto do vendedor em BT-42, pode ser, por exemplo, «Indique um número de telefone para esclarecimentos».
Os erros que se devem ao seu mapeamento ou à sua lógica de cálculo não podem ser corrigidos pelo seu cliente. Esses erros devem ser encaminhados como alerta interno para a sua equipa.
Na receção
O seu software deve validar também as faturas eletrónicas recebidas e mostrar o resultado junto do documento. Guarde o ficheiro original sem alterações e, ao lado, o relatório de validação como documento próprio. O Ministério Federal das Finanças da Alemanha exige que, pelo menos, a parte estruturada de uma fatura eletrónica seja conservada intacta na sua forma original.
Se uma fatura recebida contiver erros, o seu cliente pode pedir ao remetente uma fatura retificada. O seu software pode apoiar este passo, por exemplo com um pedido de esclarecimento preparado para o remetente, que inclua o relatório de validação.
Em testes automatizados
Crie uma coleção de faturas de teste que abranja os seus tipos de fatura com os respetivos códigos, por exemplo 380 para uma fatura e 384 para uma fatura retificativa. Abranja também cada categoria de IVA que os seus clientes utilizam. A isto juntam-se descontos e encargos, bem como cada sintaxe que o seu software gera. Inclua também ficheiros deliberadamente incorretos e verifique se o validador os rejeita.
O validador da KoSIT é um programa open source para a linha de comandos e pode ser integrado num pipeline de build. A KoSIT disponibiliza ainda um conjunto de testes com faturas de exemplo, adequado como ponto de partida para a sua própria coleção.
Após cada atualização dos conjuntos de regras
Os conjuntos de regras mudam mesmo sem novo número de versão. A KoSIT publica regularmente, para a XRechnung 3.0.2, bundles com correções de erros, o mais recente na versão de 31 de agosto de 2026. A XRechnung 3.0 mantém-se em vigor pelo menos até 31 de julho de 2027.
A versão preliminar da especificação XRechnung 4.0 foi publicada a 15 de setembro de 2026. Não se destina expressamente à utilização em produção; dá-lhe antes uma visão antecipada das funcionalidades novas e alteradas. A versão final deverá ser publicada na primavera de 2027, juntamente com os componentes técnicos.
A OpenPeppol publica regularmente novas versões do Peppol BIS Billing 3.0, nos últimos anos sempre em maio e em novembro. A versão 3.0.21 foi publicada a 20 de maio de 2026 e é vinculativa desde 17 de agosto de 2026.
Planeie para cada versão uma data fixa em que valida a sua coleção de testes face às novas regras. Registe em cada relatório de validação com que versão do validador e do conjunto de regras foi gerado. Assim, consegue reconstituir um resultado mesmo que as regras tenham entretanto mudado. Para a transição para a XRechnung 4.0, o seu ambiente de testes deve conseguir verificar ambas as versões em paralelo.
Analisar os relatórios de validação de todos os clientes
Se o seu software gerar faturas eletrónicas para muitos clientes, compensa analisar os relatórios de validação de todos os clientes em conjunto. Se o mesmo ID de regra surgir de repente em muitos clientes, a causa está provavelmente no mapeamento ou num novo conjunto de regras. Se surgir apenas num cliente, a causa está mais provavelmente nos dados mestre desse cliente.
Validação com o InvoiceRails
Os passos deste artigo podem ser implementados integralmente pela sua equipa. O esforço inicial é limitado; o esforço contínuo não: conjuntos de regras, listas de códigos e configurações de verificação mudam várias vezes por ano, e cada alteração tem de entrar nos seus testes, no seu envio e no seu planeamento de versões.
Por isso, a validação, o envio e a manutenção dos conjuntos de regras podem também ser entregues a um Peppol Access Point certificado como o InvoiceRails.
Validador de faturas eletrónicas para verificações individuais
O validador de faturas eletrónicas do InvoiceRails, gratuito, verifica ficheiros XML em UBL e CII, bem como faturas PDF híbridas, sem registo. Deteta automaticamente a sintaxe, a versão e o perfil, entre eles XRechnung, Peppol BIS Billing 3.0, ZUGFeRD, Factur-X e outros perfis da EN 16931. Depois valida o ficheiro face ao esquema XML e às regras Schematron e de negócio do perfil detetado. O relatório de validação pode ser descarregado em PDF ou partilhado por link, por exemplo quando o seu apoio ao cliente analisa uma fatura rejeitada com um cliente.
API do InvoiceRails no seu software
O InvoiceRails é o Peppol Access Point certificado pela OpenPeppol da fino data services. O seu software liga-se ao InvoiceRails através de uma API REST e envia e recebe por esse meio faturas eletrónicas para um número ilimitado de clientes, se desejar em white label.
A API oferece a validação como endpoint próprio, igualmente com deteção automática do perfil. O seu software pode assim verificar as faturas eletrónicas logo após a sua criação. Cada mensagem na resposta contém o ID de regra, o nível de gravidade, o texto da mensagem e a localização em XPath. O seu software pode guardar o ID de validação junto da fatura e voltar a consultar o resultado durante pelo menos 90 dias.
O InvoiceRails valida cada ficheiro que o seu software envia através do Peppol, mesmo sem esta chamada. O seu software tem de verificar previamente que formatos um destinatário suporta.
O InvoiceRails verifica também as faturas eletrónicas recebidas e entrega ao seu software o ficheiro original juntamente com os dados da fatura extraídos. Um webhook comunica ao seu software cada alteração do estado de entrega.
O seu software continua responsável pela correspondência dos campos do seu modelo de dados, pelas indicações compreensíveis na sua interface e pelas verificações de plausibilidade dos dados obrigatórios que nenhuma regra abrange.
