Introdução à API

Bem-vindo à documentação oficial de integração do Fiscal AGT Gateway.

O Gateway é uma API intermediária que abstrai toda a complexidade de integrar directamente com a Autoridade Geral Tributária (AGT) de Angola. O seu ERP, CRM ou sistema de facturação envia documentos em JSON simples — nós tratamos da assinatura digital, do envio à AGT e da notificação do resultado.

Porquê usar o Gateway?

Integrar directamente com a AGT significa lidar com certificados RSA, geração de assinaturas JWS e indisponibilidade do serviço central. O Gateway resolve isto:

Payload simples — envias os dados estruturados da factura; nós geramos a assinatura digital.
Processamento assíncrono — a resposta da API é imediata (requestId); o envio real à AGT acontece em segundo plano, com resiliência a falhas temporárias.
Notificação via webhook — o teu sistema é avisado automaticamente quando um documento é validado ou rejeitado, sem precisares de fazer polling constante.

Base URL

https://<host-do-gateway>/v1

Ambiente	Base URL
Produção	`https://api.cipherpath.tech/v1`
Testes (homologação)	`https://fiscal-test.cipherpath.tech/v1`

Cada instância do Gateway está ligada a um ambiente da AGT (homologação ou produção), configurado do lado do servidor. Usa sempre a base URL e a API Key que te foram fornecidas para o ambiente em que estás a trabalhar.

Antes de começar

No dashboard, garante que já tens:

Uma conta criada e uma API Key gerada (ver Autenticação).
A chave RSA do contribuinte carregada.
Pelo menos uma série activa para o tipo de documento que vais emitir (ex.: FT).

Sem isto, a submissão de documentos falha.

Primeiro pedido

curl -X POST https://<host>/v1/client/factura/ft \
  -H "X-API-Key: agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "FT",
    "documentDate": "2026-07-27",
    "systemEntryDate": "2026-07-27T10:00:00Z",
    "customerTaxID": "999999999",
    "companyName": "Cliente Final",
    "documentTotals": { "netTotal": 500.0, "taxPayable": 70.0, "grossTotal": 570.0 },
    "lines": [
      {
        "lineNumber": 1,
        "productCode": "SERV001",
        "productDescription": "Serviço de consultoria",
        "quantity": 1,
        "unitOfMeasure": "UN",
        "unitPriceBase": 500.0,
        "unitPrice": 500.0,
        "creditAmount": 500.0,
        "taxes": [{ "taxType": "IVA", "taxPercentage": 14, "taxAmount": 70.0, "taxContribution": 70.0 }]
      }
    ]
  }'

const response = await fetch('https://<host>/v1/client/factura/ft', {
  method: 'POST',
  headers: {
    'X-API-Key': 'agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentType: 'FT',
    documentDate: '2026-07-27',
    systemEntryDate: '2026-07-27T10:00:00Z',
    customerTaxID: '999999999',
    companyName: 'Cliente Final',
    documentTotals: { netTotal: 500.0, taxPayable: 70.0, grossTotal: 570.0 },
    lines: [
      {
        lineNumber: 1,
        productCode: 'SERV001',
        productDescription: 'Serviço de consultoria',
        quantity: 1,
        unitOfMeasure: 'UN',
        unitPriceBase: 500.0,
        unitPrice: 500.0,
        creditAmount: 500.0,
        taxes: [{ taxType: 'IVA', taxPercentage: 14, taxAmount: 70.0, taxContribution: 70.0 }]
      }
    ]
  })
})
 
const data = await response.json()
console.log(data.requestId)

import requests
 
response = requests.post(
    "https://<host>/v1/client/factura/ft",
    headers={"X-API-Key": "agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "documentType": "FT",
        "documentDate": "2026-07-27",
        "systemEntryDate": "2026-07-27T10:00:00Z",
        "customerTaxID": "999999999",
        "companyName": "Cliente Final",
        "documentTotals": {"netTotal": 500.0, "taxPayable": 70.0, "grossTotal": 570.0},
        "lines": [
            {
                "lineNumber": 1,
                "productCode": "SERV001",
                "productDescription": "Serviço de consultoria",
                "quantity": 1,
                "unitOfMeasure": "UN",
                "unitPriceBase": 500.0,
                "unitPrice": 500.0,
                "creditAmount": 500.0,
                "taxes": [{"taxType": "IVA", "taxPercentage": 14, "taxAmount": 70.0, "taxContribution": 70.0}],
            }
        ],
    },
)
 
print(response.json()["requestId"])

<?php
 
$ch = curl_init('https://<host>/v1/client/factura/ft');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'documentType' => 'FT',
    'documentDate' => '2026-07-27',
    'systemEntryDate' => '2026-07-27T10:00:00Z',
    'customerTaxID' => '999999999',
    'companyName' => 'Cliente Final',
    'documentTotals' => ['netTotal' => 500.0, 'taxPayable' => 70.0, 'grossTotal' => 570.0],
    'lines' => [[
        'lineNumber' => 1,
        'productCode' => 'SERV001',
        'productDescription' => 'Serviço de consultoria',
        'quantity' => 1,
        'unitOfMeasure' => 'UN',
        'unitPriceBase' => 500.0,
        'unitPrice' => 500.0,
        'creditAmount' => 500.0,
        'taxes' => [['taxType' => 'IVA', 'taxPercentage' => 14, 'taxAmount' => 70.0, 'taxContribution' => 70.0]],
    ]],
]));
 
$response = json_decode(curl_exec($ch), true);
echo $response['requestId'];

Resposta:

{ "requestId": "d3f1...", "message": "Documento FT enfileirado com sucesso" }

A submissão é assíncrona — guarda o requestId e consulta o resultado em Consultar Estado, ou recebe-o automaticamente via Webhook.

Autenticação