Portal do Cliente

API de Facturação Electrónica

O Fact Flexi Connect é um serviço HTTP que permite a sistemas de terceiros, ERPs, softwares de facturação, plataformas SaaS, comunicarem com a API de Facturação Electrónica da AGT Angola (SIFP).

Porquê usar o Connect?

Integrar directamente com a API da AGT é complexo. É necessário:

  • Implementar assinatura digital JWS RS256 com certificados
  • Gerir múltiplos ambientes (homologação e produção)
  • Manter conexões TLS 1.2 com keep-alive
  • Lidar com erros e validações específicos da AGT

O Connect abstrai toda esta complexidade. O teu sistema envia um JSON simples e recebe a resposta da AGT.

O que o Connect não faz

O Fact Flexi Connect é uma ponte, não uma base de dados. O serviço:

  • Não armazena produtos, clientes, stocks ou qualquer informação de negócio do teu sistema
  • Não guarda os documentos emitidos, apenas regista metadados de utilização para facturação e logs
  • Não retém dados após a comunicação com a AGT estar concluída

Os teus dados permanecem no teu sistema. O Connect apenas autentica, assina e encaminha os documentos para a AGT, garantindo que ficam registados na base de dados oficial da Facturação Electrónica. A chave privada que envias em cada request também nunca é armazenada, é usada exclusivamente para a assinatura JWS desse pedido e descartada de seguida.

Como funciona

A renderizar...

Características

CaracterísticaDescrição
AutenticaçãoAPI Key via header x-api-key ou Authorization: Bearer
Modelo v2Dados da empresa enviados em cada request (NIF + chave privada)
Assinatura digitalJWS RS256 automática
AmbientesHomologação (HML) e Produção (PROD)
Rate limiting60 req/min por API Key
LogsRegisto completo de todas as chamadas
ValidaçãoZod, erros de input apanhados antes de chegar à AGT
Respostas normalizadasConnect traduz respostas da AGT para formato consistente

Endpoints Disponíveis

Séries

MétodoRotaDescriçãoScope
POST/v2/seriesListar séries de numeraçãoseries:listar
POST/v2/series/solicitarSolicitar criação de sériefacturas:emitir

Documentos

MétodoRotaDescriçãoScope
POST/v2/documentos/emitirEmitir documentos fiscaisfacturas:emitir
POST/v2/documentos/statusConsultar estado de validaçãofacturas:consultar

Sistema

MétodoRotaDescrição
GET/healthVerificar estado do serviço

Modelo de Respostas

Todas as respostas seguem o mesmo formato:

{
  "success": true,
  // ... dados específicos do endpoint
}

Em caso de erro:

{
  "success": false,
  "error": "Descricao do erro",
  "code": "CODIGO_DO_ERRO",
  "details": {}  // opcional, detalhes de validação
}

Códigos de Erro Comuns

HTTPcodeSignificado
401UNAUTHORIZEDAPI Key ausente, inválida ou revogada
402LICENSE_EXPIREDLicença expirada ou inexistente (modelo ilimitado)
402NIF_REQUIREDCampo nif obrigatório (modelo por NIF)
402NIF_NOT_LICENSEDNIF não autorizado ou licença expirada (modelo por NIF)
403FORBIDDENScope insuficiente para este endpoint
400INVALID_JSONCorpo do request não é JSON válido
400VALIDATION_ERRORCampos obrigatórios em falta ou inválidos
502AGT_ERRORErro de comunicação com a AGT

Guia de Início Rápido

  1. Autenticação, Obtém a tua API Key
  2. Listar Séries, Vê que séries estão disponíveis
  3. Solicitar Série, Cria séries novas se necessário
  4. Emitir Documento, Submete documentos à AGT
  5. Consultar Estado, Verifica se foram validados

Ajuda e Contactos

Se precisar de assistência durante a integração ou tiver dúvidas comerciais: