O problema
Com o Decreto Executivo 683/25, em vigor desde Setembro de 2025, as facturas passam a ser assinadas e submetidas à AGT em tempo real, em JSON, em vez de um ficheiro enviado de tempos a tempos. Escolas, clínicas e empresas que já têm o seu sistema precisam de cumprir sem o refazer.
O objectivo é um serviço que esses sistemas chamam por API para emitir a factura, e que trata da assinatura, da submissão, do prazo e do SAF-T. O AutoPropina é o primeiro a integrar.
A abordagem
- 01
Duas fontes, comparadas campo a campo
A documentação técnica da AGT (schemaVersion 2.0) diverge do decreto em pontos estruturais: o identificador da submissão, a série passar a ser atribuída pela AGT, o estabelecimento, a natureza fiscal de cada linha. Comparei as duas fontes campo a campo e registei as contradições da própria documentação, para confirmar em homologação.
- 02
Assinatura RS256 do documento inteiro
Cada documento é assinado em JWS compacto, RS256, sobre o objecto JSON completo e canónico. Concatenar campos e assinar o resultado, o erro mais fácil de cometer, é precisamente o que a documentação avisa para não fazer.
- 03
Submissão por filas, sem perder a resposta
O sistema que pede a factura recebe-a logo assinada; a submissão corre por filas: registar, perguntar o estado com intervalos crescentes, avisar por webhook. O aviso é gravado na mesma transacção que aplica a resposta da AGT, e um erro que não é passageiro não se repete, porque só gastaria o prazo.
- 04
Avisar antes do prazo de 24 horas
A AGT dá 24 horas para submeter um documento assinado e, depois disso, valida-o com penalização. Uma tarefa corre de 15 em 15 minutos e avisa 4 horas antes, uma vez por documento, na consola e por webhook.
- 05
SAF-T (AO) que passa no validador
Cada empresa gera o seu SAF-T (AO) 1.01, e o ficheiro é validado contra o esquema oficial. O validador apanhou restrições que a leitura do esquema não revelava, como o limite de 172 caracteres da Hash, que obriga a uma segunda chave. Ou sai um ficheiro válido, ou sai um erro: nunca um ficheiro com documentos a menos.