Como validar um SAF-T (PT) antes de submeter à AT

Para quê pré-validar

O portal da AT aceita o seu ficheiro SAF-T. Ou rejeita-o com "ficheiro inválido". Não há meio-termo nem feedback útil. Se submeter no dia 5 às 23h50 e o ficheiro voltar, tem dez minutos para encontrar o bug e voltar a exportar do ERP. É a pior altura para descobrir que a numeração das faturas reiniciou, que o dígito de controlo do NIF está errado ou que a codificação ficou mal.

A pré-validação fecha esse buraco. Submete o ficheiro a um validador que corre o mesmo XSD mais as heurísticas que a AT aplica à entrada — codificação, BOM, NIF Mod-11, formato ATCUD, datas do cabeçalho, totais de documentos, taxas de câmbio, consistência do estado dos documentos — e vê todos os problemas com número de linha antes da AT.

O que validar, por ordem

1. Codificação. A causa de rejeição silenciosa mais comum. A AT exige Windows-1252; a maioria dos ERPs exporta UTF-8. O parser XSD não se importa; o pipeline de entrada da AT importa-se. Veja a regra de codificação.
2. BOM. Se o seu ERP coloca um byte-order-mark UTF-8 antes de <?xml ?>, a AT rejeita. O mesmo para BOMs UTF-16.
3. Esquema. O XSD valida a forma estrutural: elementos obrigatórios, tipos de atributos, valores de enumeração. É o que a AT corre primeiro. schema 1.04_01 é a versão atual do SAF-T (PT) para a faturação mensal.
4. NIF Mod-11. Cada TaxRegistrationNumber e CustomerTaxID / SupplierTaxID precisa de dígito de controlo português válido e prefixo permitido. Veja a regra do NIF.
5. Formato ATCUD. Oito alfanuméricos maiúsculos, hífen, sequência ≥ 1. Obrigatório desde 2023.
6. Datas do cabeçalho. StartDate < EndDate, FiscalYear corresponde ao ano de StartDate, DateCreated >= EndDate, EndDate não no futuro.
7. Intervalo de datas por documento. Cada data de Invoice, Payment, WorkDocument, StockMovement tem de cair dentro da janela de reporte do cabeçalho.
8. Totais de bloco. SalesInvoices.NumberOfEntries coincide com a contagem dos filhos; TotalDebit + TotalCredit coincide com a soma dos GrossTotals, dentro de 0,01 €.
9. Moeda. Documentos em moeda estrangeira precisam de CurrencyCode + CurrencyAmount + ExchangeRate > 0. Taxa em falta é invisível para o XSD; a AT rejeita à entrada.
10. Estado do documento. InvoiceStatus em {N, S, A, R, F}; InvoiceStatusDate >= InvoiceDate.

O que a pré-validação NÃO apanha

Seja honesto consigo: um validador consegue confirmar que o ficheiro está bem formado e consistente. Não consegue garantir que a AT o vai aceitar. Duas coisas que não vê:

• Regras de negócio do lado da AT que mudam sem aviso. A AT, por vezes, aperta regras de entrada sem atualizar o XSD público. Monitores de alterações de esquema e avisos da comunidade ajudam — mas padrões de rejeição novos por vezes só aparecem em submissões reais.
• Restrições ao nível da conta. Janela de submissão já usada, contribuinte em suspensão, registo de software certificado divergente — nenhum destes é um problema do ficheiro; é do contribuinte.

Para a primeira classe, os ciclos pós-rejeição continuam a importar. Para a segunda, o seu contabilista ou o apoio da AT é o canal certo.

Fluxo para o prazo do dia 5

1. Exporte o SAF-T mensal do ERP um dia antes — idealmente no dia 3 do mês seguinte.
2. Passe-o por um pré-validador. Corrija todos os erros reportados. Se a regra de codificação disparar, aplique o auto-fix e revalide.
3. Volte a exportar apenas quando um problema estrutural for reportado. Voltar a correr a pré-validação no mesmo ficheiro partido duas vezes dá a mesma resposta.
4. Submeta à AT assim que o validador devolver limpo. Guarde o relatório PDF como parte da pasta de submissão.

Pronto?

Submeta o seu SAF-T XML e veja o que a AT vai rejeitar — antes de submeter. Validar agora →