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.
Como funciona
A renderizar...
Características
| Característica | Descrição |
|---|---|
| Autenticação | API Key via header x-api-key ou Authorization: Bearer |
| Modelo v2 | Dados da empresa enviados em cada request (NIF + chave privada) |
| Assinatura digital | JWS RS256 automática |
| Ambientes | Homologação (HML) e Produção (PROD) |
| Rate limiting | 60 req/min por API Key |
| Logs | Registo completo de todas as chamadas |
| Validação | Zod — erros de input apanhados antes de chegar à AGT |
| Respostas normalizadas | Connect traduz respostas da AGT para formato consistente |
Endpoints Disponíveis
Séries
| Método | Rota | Descrição | Scope |
|---|---|---|---|
POST | /v2/series | Listar séries de numeração | series:listar |
POST | /v2/series/solicitar | Solicitar criação de série | facturas:emitir |
Documentos
| Método | Rota | Descrição | Scope |
|---|---|---|---|
POST | /v2/documentos/emitir | Emitir documentos fiscais | facturas:emitir |
POST | /v2/documentos/status | Consultar estado de validação | facturas:consultar |
Sistema
| Método | Rota | Descrição |
|---|---|---|
GET | /health | Verificar 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
| HTTP | code | Significado |
|---|---|---|
| 401 | UNAUTHORIZED | API Key ausente, inválida ou revogada |
| 403 | FORBIDDEN | Scope insuficiente para este endpoint |
| 400 | INVALID_JSON | Corpo do request não é JSON válido |
| 400 | VALIDATION_ERROR | Campos obrigatórios em falta ou inválidos |
| 502 | AGT_ERROR | Erro de comunicação com a AGT |
Guia de Início Rápido
- Autenticação — Obtém a tua API Key
- Listar Séries — Vê que séries estão disponíveis
- Solicitar Série — Cria séries novas se necessário
- Emitir Documento — Submete documentos à AGT
- Consultar Estado — Verifica se foram validados