Saltar para o conteúdo
Henrique Vieira
Todos os projectos

Software para a AGT, multi-tenant

Facturação electrónica

Um software de facturação electrónica que outros sistemas integram por API para emitir facturas segundo o Decreto Executivo 683/25 da AGT, com a submissão em tempo real e o SAF-T gerado por cada empresa.

Papel
Autor único: desenho, API, consola e integração com a AGT
Período
Nov 2026 - presente
Estado
Em fase final, a caminho da submissão à certificação da AGT
Tecnologias
TypeScriptNestJSPrismaPostgreSQLBullMQNext.jsJWS RS256SAF-T (AO)

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

Os resultados

18
tipos de documento do Anexo I: facturas, facturas/recibo, notas de crédito, recibos, avisos de cobrança
56
códigos de erro da AGT tratados, cada um marcado para repetir, corrigir ou contactar o suporte
33
operações na API pública, com o contrato OpenAPI verificado em cada alteração
10
emissões em simultâneo no teste de concorrência da cadeia de chaves dos documentos
4 h
de antecedência no aviso do prazo de submissão de 24 horas

O que aprendi

O decreto e a documentação técnica nem sempre dizem o mesmo, e a documentação contradiz-se em alguns campos. Registo cada divergência com a decisão tomada e o motivo, para a homologação a confirmar ou corrigir sem ninguém ter de adivinhar.

Caso seguinte

MediaSync

Sinalética digital sincronizada para Smart TVs

Ler o caso