Os 10 erros mais comuns no ficheiro SAF-T PT (e como corrigi-los)

Se já submeteu um ficheiro SAF-T PT no Portal das Finanças e recebeu uma mensagem críptica a dizer apenas que o ficheiro é inválido, sabe como é frustrante. Na prática, a esmagadora maioria das rejeições cabe num punhado de causas que se repetem em todos os programas de faturação. Este artigo reúne os dez erros que mais vezes aparecem, com a mensagem típica que a AT (ou um validador) devolve, a explicação em português simples e a forma de os corrigir na origem.

Todos os pontos abaixo correspondem a verificações que o Validador de SAF-T PT gratuito faz no seu browser, sem enviar o ficheiro para lado nenhum.

1. Versão do ficheiro errada

Mensagem típica: "AuditFileVersion inválida" ou rejeição imediata sem detalhe.

O elemento <AuditFileVersion> tem de conter exatamente 1.04_01. Programas antigos, ou exportações guardadas há anos, ainda saem em 1.03_01 — e o Portal das Finanças rejeita sem margem para discussão.

Como corrigir: atualize o software de faturação e reexporte. Não altere o valor à mão: a estrutura do ficheiro mudou entre versões e mudar só o número torna o XML incoerente com o esquema.

2. Encoding diferente de UTF-8

Mensagem típica: "Erro ao processar o ficheiro", ou nomes de clientes com caracteres estranhos.

A AT exige UTF-8. Muitos programas mais antigos exportam em Windows-1252 ou ISO-8859-1, o que corrompe acentos, cedilhas e o símbolo do euro. Às vezes o ficheiro até é aceite, mas os nomes ficam errados nos registos da AT.

Como corrigir: procure a opção de codificação na exportação do seu programa. Se não existir, peça ao fornecedor: gerar SAF-T fora de UTF-8 é um defeito. Não converta o ficheiro num editor de texto sem alterar também a declaração de encoding no topo do XML.

3. ATCUD em falta ou mal formado

Mensagem típica: "ATCUD inválido no documento FT A/123".

Desde 2023 todos os documentos têm de incluir o ATCUD no formato CódigoValidação-Número (por exemplo JFHT-1425). O código de validação é atribuído pela AT quando a série é registada no Portal das Finanças. Se a série nunca foi registada, o programa não tem código e exporta o campo vazio, com 0, ou omite-o.

Como corrigir: registe as séries no Portal das Finanças, guarde o código de validação no programa e reexporte. Documentos já emitidos sem ATCUD não podem ser corrigidos retroativamente — o correto é regularizar a série e garantir que os documentos seguintes saem certos.

4. Sequência de numeração com saltos

Mensagem típica: "Falha na sequência de documentos na série A: falta o número 4".

Dentro da mesma série e tipo de documento, a numeração tem de ser contínua. Um salto significa quase sempre uma de três coisas: exportou apenas parte do período, documentos anulados não foram exportados com o estado A, ou está a misturar séries diferentes na mesma exportação.

Como corrigir: confirme o intervalo de datas da exportação. Documentos anulados têm de constar do SAF-T, com InvoiceStatus igual a A e a respetiva data e motivo. Um programa certificado nunca apaga documentos; se faltam números sem anulação registada, há um problema sério no programa que deve reportar ao fornecedor.

5. Totais que não batem certo

Mensagem típica: "GrossTotal diferente de NetTotal + TaxPayable no documento FT A/57".

A aritmética do documento tem de fechar ao cêntimo: a soma dos valores das linhas dá o NetTotal, o imposto calculado dá o TaxPayable e a soma dos dois dá o GrossTotal. As diferenças de um ou dois cêntimos vêm quase sempre de arredondamento — arredondar linha a linha versus arredondar apenas no total — ou de descontos aplicados sobre o total do documento sem serem redistribuídos pelas linhas.

Como corrigir: é um erro de cálculo do programa, não do ficheiro. Registe os documentos afetados e reporte ao fornecedor. Se o desvio for sistemático em documentos com desconto global, é praticamente certo que a causa é essa.

6. NIF inválido

Mensagem típica: "CustomerTaxID inválido".

O NIF português tem nove dígitos e um dígito de controlo calculado por módulo 11. Erros de digitação passam despercebidos na ficha do cliente e só rebentam no SAF-T. Para consumidor final usa-se 999999990. Clientes estrangeiros devem ter o país correto no campo Country e, aí sim, o número de identificação estrangeiro.

Como corrigir: valide os NIF na ficha do cliente antes de faturar. A ferramenta gratuita de validação de NIF e IBAN faz essa verificação em segundos.

7. CustomerID usado mas ausente dos MasterFiles

Mensagem típica: "CustomerID referido no documento não existe na tabela de clientes".

Cada documento aponta para um cliente através do CustomerID. Se o gerador filtra os clientes por data de criação ou de última alteração, clientes antigos ficam de fora — mas os documentos deles continuam no ficheiro. O CustomerID tem também um limite: entre 1 e 30 caracteres. IDs vazios ou demasiado longos dão erro de esquema.

Como corrigir: a tabela de clientes tem de conter todos os clientes referidos por documentos do período, independentemente de quando foram criados. É um defeito clássico do exportador.

8. Códigos e motivos de isenção de IVA em falta

Mensagem típica: "TaxExemptionReason em falta na linha 2 do documento FT A/12".

Sempre que a taxa aplicada é 0%, o SAF-T exige o motivo de isenção por extenso (TaxExemptionReason) e o código normalizado (TaxExemptionCode, por exemplo M07 para o artigo 9.º do CIVA). Faltando um dos dois, o documento é rejeitado ou marcado para verificação.

Como corrigir: configure na tabela de taxas de IVA do seu programa o código e o texto de isenção para cada situação que use (exportações, artigo 9.º, autoliquidação, regime de isenção do artigo 53.º).

9. InvoiceNo mal formatado

Mensagem típica: "InvoiceNo não respeita o formato exigido".

O número do documento no SAF-T tem um formato obrigatório: TIPO SÉRIE/NÚMERO — por exemplo FT A/125. Um espaço a mais, uma barra invertida em vez de barra, ou o tipo em minúsculas, e o esquema recusa. É frequente em programas que concatenam o número à mão.

Como corrigir: confirme o formato numa amostra de documentos. Se estiver errado, é o gerador que tem de ser corrigido — nunca edite o XML.

10. Datas incoerentes com o período

Mensagem típica: "Data do documento fora do período declarado no cabeçalho" ou "SystemEntryDate anterior à data do documento".

O cabeçalho declara StartDate e EndDate. Todos os documentos têm de cair dentro desse intervalo. Além disso, a SystemEntryDate (o momento em que o documento foi gravado no sistema) nunca pode ser anterior à data do documento nem ser alterada depois — é um dos elementos que a AT usa para verificar a integridade do registo.

Como corrigir: exporte por períodos completos (mês a mês é o mais seguro) e nunca manipule datas de sistema. Se o seu programa permite alterar a data de gravação de um documento emitido, isso é por si só um problema de conformidade.

Como despistar tudo isto de uma vez

Ler o XML à mão não é razoável em ficheiros com milhares de documentos. O caminho prático é passar o ficheiro por um validador que faça os três níveis de verificação — XML bem formado, conformidade com o esquema oficial 1.04_01 e regras de negócio como as acima — e que lhe diga em português o que está errado e onde.

É exatamente isso que o Validador de SAF-T PT da Livegest faz, gratuitamente e sem registo. A validação corre inteiramente no seu browser: o ficheiro nunca é enviado para nenhum servidor, o que resolve também a questão da confidencialidade dos dados dos seus clientes.

Depois de corrigir, vale a pena rever os prazos e obrigações do SAF-T PT e seguir o processo de validação passo a passo antes de submeter.

---

A Livegest é um software de faturação online preparado para os requisitos da AT: séries com ATCUD, QR code, assinatura dos documentos e exportação de SAF-T PT validada automaticamente. Pode experimentar gratuitamente, sem cartão.