Validação XML: 5 erros comuns e como corrigi-los
Os erros de validação XML podem bloquear os seus pagamentos ou facturas. Aqui estão os 5 problemas mais comuns que encontramos e como resolvê-los rapidamente.
Porquê validar os seus ficheiros XML?
Um ficheiro XML mal formado ou não conforme será sistematicamente rejeitado pelo seu banco ou parceiro comercial. A validação preventiva poupa-lhe trocas dispendiosas e atrasos nos pagamentos.
Os 5 erros mais comuns
Codificação incorrecta
O ficheiro não está em UTF-8, ou contém caracteres especiais mal codificados (acentos, símbolo €). Isto provoca erros de análise imediatos.
Espaço de nomes XML em falta ou incorrecto
O espaço de nomes XML (xmlns) não corresponde à versão do esquema esperada. Versões diferentes de pain.001 ou UBL têm espaços de nomes diferentes.
Soma de controlo incorrecta (CtrlSum)
Para ficheiros SEPA, o CtrlSum deve corresponder exactamente à soma de todos os montantes individuais. Arredondar para 3 casas decimais em vez de 2 é suficiente para invalidar o ficheiro.
Campos obrigatórios em falta
Alguns campos parecem opcionais no esquema mas são obrigatórios segundo as regras de negócio do Peppol ou EPC (ex. BIC do devedor em determinados contextos).
Formato de data inválido
As datas devem seguir o formato ISO 8601. Uma data como "10/02/2026" será rejeitada; deve ser "2026-02-10".
Validação XSD vs validação de regras de negócio
A validação XML ocorre em dois níveis distintos. O primeiro nível é a validação XSD (XML Schema Definition), que verifica as regras estruturais: nomes de elementos, tipos de dados, cardinalidade (obrigatório vs opcional) e aninhamento. Um ficheiro XML que passa a validação XSD está estruturalmente correcto — mas isso não significa que seja semanticamente válido.
O segundo nível é a validação de regras de negócio. São regras específicas do domínio que vão além do que o esquema pode expressar. Para ficheiros SEPA, o EPC (European Payments Council) publica guias de implementação com regras como: o CtrlSum deve ser igual à soma de todos os montantes individuais, a RequestedExecutionDate deve ser um dia útil futuro e o IBAN do devedor deve estar na zona SEPA. Para facturas UBL, a norma EN 16931 define regras de negócio como: os montantes totais das linhas devem ser iguais ao total da factura, o código de categoria IVA deve ser consistente com a taxa de imposto, e o Peppol acrescenta regras adicionais específicas por país.
Um fluxo de validação robusto verifica ambos os níveis: primeiro a conformidade XSD (para detectar erros estruturais precocemente), depois as regras de negócio (para detectar erros lógicos). O ValidateFin implementa ambos: o validador SEPA verifica contra os esquemas XSD EPC oficiais e aplica as regras de negócio SEPA, enquanto o validador UBL verifica contra o esquema UBL 2.1 e as regras de negócio EN 16931.
Segurança XML: prevenção de ataques XXE e injecção
Os ficheiros XML podem comportar riscos de segurança se não forem tratados com cuidado. O mais perigoso é o ataque XXE (XML External Entity), em que um ficheiro XML malicioso inclui uma declaração DOCTYPE que referencia recursos externos — podendo ler ficheiros do servidor, efectuar pedidos de rede ou causar negação de serviço através da expansão de entidades (o ataque dos «mil milhões de risos»).
A análise segura de XML requer: bloquear completamente as declarações DOCTYPE (qualquer ficheiro XML financeiro com um DOCTYPE é suspeito), limitar a profundidade de expansão de entidades, limitar o tamanho máximo do ficheiro (o ValidateFin limita a 10 MB) e limitar a profundidade de aninhamento (o ValidateFin limita a 64 níveis). Estas protecções são especialmente importantes para validadores baseados na web onde os utilizadores carregam ficheiros arbitrários.
A validação do lado do cliente acrescenta uma camada adicional de segurança: como o XML é analisado no browser do utilizador, mesmo um ficheiro malicioso não pode aceder a recursos do servidor. Esta é uma das vantagens principais da arquitectura do ValidateFin — toda a análise ocorre num sandbox isolado do browser, eliminando completamente os riscos XXE do lado do servidor.
Boas práticas de fluxo de validação
Construir um fluxo de validação XML fiável envolve várias boas práticas. Em primeiro lugar, valide cedo: verifique os ficheiros XML o mais próximo possível do ponto de geração, não apenas antes da submissão. Detectar erros na geração significa que podem ser corrigidos automaticamente, enquanto os erros detectados na submissão requerem intervenção manual.
Em segundo lugar, use a versão de esquema correcta. O SEPA pain.001 tem múltiplas versões (.003, .009, .011) e cada banco pode aceitar versões diferentes. O UBL 2.1 é a norma para o Peppol, mas algumas redes nacionais ainda utilizam versões mais antigas. Verifique sempre com o seu banco ou destinatário qual a versão que esperam e valide contra esse esquema específico.
Em terceiro lugar, implemente um pipeline de validação: (1) verificação de boa formação (o XML é analisável?), (2) validação do esquema XSD (corresponde à estrutura?), (3) validação de regras de negócio (os montantes estão correctos, as datas são válidas?), (4) validação de conteúdo (os IBANs são válidos, os BICs existem?). Cada etapa detecta diferentes classes de erros e executá-las por ordem produz as mensagens de erro mais claras.
Em quarto lugar, registe e monitorize os resultados da validação. Acompanhe os padrões de erro comuns para melhorar o seu processo de geração. Se 30% dos seus ficheiros falharem por discrepâncias no CtrlSum, isso aponta para um erro de arredondamento no seu código de geração de pagamentos. Se aparecerem erros de namespace após uma actualização, o seu modelo pode estar desactualizado.
Automatize a sua validação
Integre a validação XML no seu processo de geração de ficheiros. O ValidateFin permite-lhe validar ficheiros SEPA, UBL e camt.053 directamente no browser — sem carregamento para servidor, sem chave de API necessária. Para pipelines automatizados, pode incorporar a mesma lógica de validação utilizada pelo ValidateFin no seu próprio fluxo de trabalho.
Experimentar as ferramentas de validaçãoPerguntas frequentes
O que é a validação de esquema XSD e porque é importante?
A validação XSD (XML Schema Definition) verifica que um documento XML está em conformidade com o seu esquema definido — verificando nomes de elementos, tipos de dados, campos obrigatórios e estrutura do documento. Para ficheiros XML financeiros como SEPA e UBL, a validação XSD é a primeira linha de defesa contra erros de formatação que causariam rejeição.
Quais são os erros de validação XML mais comuns em ficheiros financeiros?
Os erros mais comuns incluem: elementos obrigatórios em falta, declarações de namespace incorretas, formatos de data ou montante inválidos, elementos em ordem errada, exceder os comprimentos máximos de campo (ex. MsgId limitado a 35 caracteres em SEPA) e problemas de codificação com caracteres especiais.
Devo validar ficheiros XML do lado do cliente ou do servidor?
Para dados financeiros sensíveis, a validação do lado do cliente é fortemente recomendada. Garante que nenhum dado de pagamento confidencial nem detalhes de factura são transmitidos para servidores externos. O ValidateFin processa toda a validação XML inteiramente no browser, tornando-o seguro para ficheiros de produção reais.
Qual é a diferença entre boa formação e validade em XML?
Um documento XML bem formado segue as regras básicas de sintaxe XML: etiquetas correctamente aninhadas, atributos entre aspas, um único elemento raiz e codificação correcta. Um documento XML válido vai mais longe — está em conformidade com um esquema específico (XSD ou DTD) que define quais os elementos permitidos, os seus tipos de dados e a sua estrutura. Um ficheiro XML pode ser bem formado mas não válido: por exemplo, um ficheiro SEPA com sintaxe XML correcta mas com um elemento MsgId em falta.
O que é um namespace XML e porque causa erros de validação?
Um namespace XML (xmlns) é um URI que identifica de forma única a versão do esquema de um documento. Para o SEPA pain.001, o namespace determina a versão utilizada: urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 para a versão 3, ou pain.001.001.09 para a versão 9. Uma incompatibilidade de namespace — usar a versão errada — faz com que o validador verifique contra o esquema errado, resultando em erros difíceis de interpretar mesmo que o conteúdo do ficheiro esteja correcto para uma versão diferente.
Como valido ficheiros SEPA contra as regras de negócio EPC?
As regras de negócio EPC vão além do XSD: verificam que o CtrlSum corresponde à soma de todos os montantes, que a RequestedExecutionDate é um dia útil futuro válido, que os IBANs são sintaticamente correctos e pertencem à zona SEPA, e que os BICs (quando fornecidos) correspondem a bancos reais. O validador SEPA do ValidateFin implementa estas regras EPC automaticamente — basta carregar o seu ficheiro pain.001 ou pain.008 e a ferramenta verifica tanto o XSD como as regras de negócio.
O que é a vulnerabilidade XXE e como se relaciona com a validação XML?
XXE (XML External Entity) é uma vulnerabilidade de segurança em que um analisador XML processa declarações DOCTYPE maliciosas que referenciam recursos externos. Isto pode conduzir à divulgação de ficheiros, falsificação de pedidos do lado do servidor ou negação de serviço. Os validadores XML seguros devem desactivar completamente o processamento de entidades externas. O ValidateFin bloqueia todas as declarações DOCTYPE e processa os ficheiros no sandbox do browser, eliminando os riscos XXE.
Posso validar múltiplos ficheiros XML de uma só vez?
O ValidateFin suporta a validação de ficheiros individuais através da sua interface web. Para validação em lote de múltiplos ficheiros, pode processá-los sequencialmente. Cada validação é efectuada inteiramente no seu browser, pelo que mesmo o processamento de dezenas de ficheiros não envia quaisquer dados para um servidor. Os resultados incluem mensagens de erro detalhadas com números de linha para depuração rápida.
Que limites de tamanho de ficheiro se aplicam à validação XML?
O ValidateFin limita o tamanho dos ficheiros XML a 10 MB e a profundidade de aninhamento a 64 níveis. Estes limites protegem contra negação de serviço através de ficheiros extremamente grandes ou profundamente aninhados. Na prática, a maioria dos ficheiros de pagamento SEPA tem menos de 1 MB (mesmo com milhares de transacções) e as facturas UBL têm normalmente menos de 100 KB. Se o seu ficheiro exceder 10 MB, considere dividi-lo em múltiplos ficheiros mais pequenos.
Como depuro erros de validação XML difíceis de interpretar?
Comece por verificar: (1) O XML está bem formado? Procure etiquetas não fechadas, aspas em falta ou caracteres inválidos. (2) O namespace está correcto? Um namespace errado faz tudo falhar. (3) Os elementos estão na ordem certa? Os esquemas XML impõem frequentemente uma ordem estrita dos elementos. (4) Os tipos de dados estão correctos? Os montantes devem ser decimais, as datas devem estar em formato AAAA-MM-DD. O ValidateFin fornece mensagens de erro claras com caminhos de elementos e números de linha para o ajudar a localizar os problemas rapidamente.