Validação XML financeiro: Os 10 erros mais comuns e como os evitar
Guia técnico sobre os 10 erros mais frequentes na validação de ficheiros XML financeiros (SEPA, UBL, Camt) e como os corrigir.
Por que a validação XML é crítica em finanças
Os ficheiros XML financeiros — SEPA pain.001, UBL/Peppol, Camt.053 — são processados automaticamente por sistemas bancários e fiscais sem intervenção humana. Um erro no XML pode resultar em rejeição do pagamento, fatura inválida ou extrato não importável.
A validação XML financeiro opera em múltiplos níveis: validação de estrutura (XSD Schema), validação de regras de negócio (Schematron), e validação semântica (IBAN mod-97, NIF, etc.). Cada nível deteta diferentes tipos de erros.
Os 10 erros mais frequentes
Baseado na análise de milhares de ficheiros XML financeiros validados:
IBAN inválido (mod-97)
O IBAN não passa a verificação mod-97. Erro frequente em migrações de dados ou sistemas que não validam o checksum.
Namespace XML incorreto
O namespace XML não corresponde à versão do formato esperada. Ex: usar o namespace pain.001.003.03 quando o banco espera pain.001.001.09.
Totais de controlo incorretos
O total de transações declarado no header não corresponde à soma das transações individuais. Erro típico de geração automática.
Espaços não removidos para transmissão eletrónica
O IBAN é apresentado com espaços para legibilidade (DE89 3704 0044 0532 0130 00) mas deve ser transmitido sem espaços em XML SEPA e e-faturas (DE89370400440532013000). Espaços em campos XML causam falhas de validação de esquema.
Dígitos de controlo substituídos por zeros (erro de modelo)
Alguns modelos ERP utilizam IBANs de marcador de posição como DE00XXXXXXXXXXXXXXXXXXX onde os dígitos de controlo são 00. Estes passam a validação de comprimento mas falham a soma de verificação mod-97. Calcule sempre os dígitos de controlo corretos ao criar ou testar modelos IBAN.
Conta encerrada ou número de conta bancária alterado
O formato IBAN é válido mas a conta já não existe. Isto causa o código de retorno AC04 (Conta encerrada) depois do pagamento chegar ao banco do devedor. São necessárias atualizações regulares da base de dados IBAN de fornecedores para evitar devoluções AC04.
IBAN não-SEPA num ficheiro de pagamento SEPA
Alguns países têm formatos semelhantes ao IBAN (ex. Líbano LB, Qatar QA) mas não pertencem à zona SEPA. Os ficheiros de pagamento SEPA apenas aceitam IBANs dos 36 países membros SEPA. A inclusão de um IBAN não-SEPA causa uma falha de validação de esquema.
BIC em falta ou errado associado ao IBAN
Desde 2016, BIC não é obrigatório para transações intra-SEPA (é derivado do IBAN). No entanto, alguns sistemas bancários ainda validam a consistência BIC/IBAN. Um BIC não correspondente (IBAN correto mas BIC do banco errado) pode causar falhas de encaminhamento em alguns sistemas bancários mais antigos.
Erros de dados de referência
Erros 4-6: BIC inválido (código bancário não reconhecido), data em formato incorreto (YYYY-MM-DD obrigatório, não DD/MM/YYYY), valor monetário com formato incorreto (usar '.' como separador decimal, não ',').
Erros 7-8: Número de IVA inválido (formato nacional não respeitado), referência duplicada (EndToEndId já usada numa transação anterior no mesmo lote).
Como implementar validação preventiva
Valide sempre antes de submeter: use ferramentas de validação antes de enviar ao banco ou plataforma. O nosso validador permite detetar erros em segundos, antes de qualquer rejeição.
Validar IBAN agoraPerguntas frequentes
O que é a validação XSD vs Schematron?
XSD (XML Schema Definition) valida a estrutura do XML: elementos obrigatórios, tipos de dados, ordem dos elementos. Schematron valida as regras de negócio: totais coerentes, referências cruzadas, etc.
Por que o meu ficheiro SEPA é rejeitado pelo banco?
As causas mais comuns: IBAN inválido, namespace incorreto, totais de controlo errados, data de valor no passado, referência duplicada. Use o nosso validador para diagnóstico.
Como verificar um IBAN manualmente?
Mova os 4 primeiros caracteres para o fim, converta letras em números (A=10, B=11, etc.), calcule o resto da divisão por 97. Se o resultado for 1, o IBAN é válido.
O que é o EndToEndId e por que é importante?
O EndToEndId é a referência de ponta a ponta num pagamento ISO 20022. Deve ser único por transação e é transportado por todos os sistemas até ao beneficiário, facilitando a reconciliação.
Como evitar erros de encoding UTF-8 nos ficheiros XML?
Declare sempre <?xml version="1.0" encoding="UTF-8"?> e certifique-se de que o ficheiro é efetivamente guardado em UTF-8 sem BOM. Use editores que mostrem o encoding do ficheiro.
Que caracteres são permitidos nos campos de texto SEPA?
SEPA restringe a um subconjunto de caracteres Latin: a-z, A-Z, 0-9, e alguns especiais (/-?:().,'+). Acentos e caracteres especiais nacionais não são permitidos em muitos campos.
Como validar os totais de controlo num ficheiro pain.001?
O CtrlSum no header deve ser igual à soma de todos os InstdAmt das transações. O NbOfTxs deve ser igual ao número total de transações no ficheiro.
O que significa um erro 'namespace mismatch'?
O namespace XML declarado no ficheiro não corresponde ao formato esperado pelo sistema receptor. Cada versão de formato tem um namespace unique (ex: urn:iso:std:iso:20022:tech:xsd:pain.001.001.09).
Como testar ficheiros SEPA antes de enviar ao banco?
Use o nosso validador gratuito para verificação estrutural e de regras de negócio. Muitos bancos também oferecem ambientes de teste (sandbox) para teste end-to-end.
Existe um formato XML financeiro universal para todos os países?
O ISO 20022 é a norma universal, mas cada país e cada tipo de transação tem variantes específicas. O Peppol BIS Billing 3.0 é o formato mais harmonizado para faturas na Europa.