Consulta NIF Angola — API Docs | api-agt.angohost.ao

# Base URL

Base URL https://api-agt.angohost.ao

Todos os endpoints são relativos a esta URL base. A API responde exclusivamente em JSON.

# Autenticação

🔑

Bearer Token obrigatório. Todos os endpoints de consulta requerem uma API key. Para obter acesso, contacte-nos — ser-lhe-á atribuída uma chave pessoal e intransmissível.

Inclua a sua API key em cada pedido usando o header Authorization:

Formato

Authorization: Bearer SUA_API_KEY

cURL

curl https://api-agt.angohost.ao/consultar/5400123456 \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Accept: application/json"

JavaScript (fetch)

const res = await fetch(
  'https://api-agt.angohost.ao/consultar/5400123456',
  { headers: { 'Authorization': 'Bearer SUA_API_KEY' } }
);
const data = await res.json();

PHP

$ch = curl_init('https://api-agt.angohost.ao/consultar/5400123456');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer SUA_API_KEY',
    'Accept: application/json',
  ],
]);
$data = json_decode(curl_exec($ch), true);

Python

import requests
r = requests.get(
  'https://api-agt.angohost.ao/consultar/5400123456',
  headers={'Authorization': 'Bearer SUA_API_KEY'}
)
data = r.json()

Erros de Autenticação

Código	Significado	Solução
401	Token em falta ou inválido	Verifique o header `Authorization: Bearer ...`
403	Token desactivado	Contacte o suporte para reactivar o acesso

# Rate Limit

⚠

Use com responsabilidade. Esta API funciona como proxy da fonte oficial. Não faça mais de 10 pedidos por minuto para o mesmo NIF.

# Endpoints

GET / Estado da API

Retorna informações gerais sobre a API e confirma que está online.

Resposta

JSON

{
  "api_name":    "Consulta NIF API",
  "version":     "1.0.0",
  "description": "API para consulta de dados empresariais por NIF",
  "status":      "online",
  "timestamp":   "2026-03-05 14:00:00",
  "endpoints": {
    "GET /":                    "Informações da API",
    "GET /api/nif-lookup/{nif}": "Consultar por NIF (oficial)",
    "GET /consultar/{nif}":      "Consultar por NIF (legacy)"
  }
}

GET /api/nif-lookup/{nif} Consultar por NIF (oficial)

Endpoint oficial da API. Retorna dados do contribuinte ou empresa.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
nif	string	obrigatório	NIF angolano. Ex: `5400123456` ou `006887386BE049`

Exemplos de Pedido

cURL

curl -X GET \
  https://api-agt.angohost.ao/api/nif-lookup/5400123456 \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Accept: application/json"

JavaScript

const res = await fetch(
  'https://api-agt.angohost.ao/api/nif-lookup/5400123456',
  { headers: { 'Authorization': 'Bearer SUA_API_KEY' } }
);
const data = await res.json();

Respostas

200 OK 404 Not Found

200 — Sucesso

{
  "success": true,
  "data": {
    "nif":              "5400123456",
    "nome":             "ANGOHOST - PRESTAÇÃO DE SERVIÇOS, LDA",
    "telefone":         "923592652",
    "morada":           "CACUACO, CENTRALIDADE DO SEQUELE, RUA 2...",
    "municipio":        "CACUACO",
    "provincia":        "LA",
    "bairro":           "CENTRALIDADE DO SEQUELE",
    "estado":           "Activo",
    "tipo":             "COLLECTIVE",
    "data_constituicao": "2020-11-17",
    "original":         { /* dados completos do contribuinte */ }
  }
}

404 — NIF não encontrado

{
  "success": false,
  "message": "NIF não encontrado"
}

GET /consultar/{nif} Legacy (compatibilidade)

⚠

Endpoint legacy. Mantido por compatibilidade com clientes existentes. Para novas integrações, utilize /api/nif-lookup/{nif}.

Funciona de forma idêntica ao endpoint oficial. Requer Bearer Token.

cURL

curl -X GET \
  https://api-agt.angohost.ao/consultar/5400123456 \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Accept: application/json"

# Campos da Resposta

Campo	Tipo	Descrição
success	boolean	Indica se a consulta foi bem sucedida
nif	string	Número de Identificação Fiscal
nome	string	Nome completo ou denominação social
telefone	string	Número de contacto principal
morada	string	Endereço completo formatado
municipio	string	Município onde está registado
provincia	string	Código da província (ex: LA = Luanda)
bairro	string	Bairro da morada principal
estado	string	`Activo` ou código de estado
tipo	string	`COLLECTIVE` (empresa) ou `SINGULAR` (pessoa)
data_constituicao	string	Data de constituição (formato YYYY-MM-DD)
original	object	Objecto completo com todos os dados do contribuinte

# Erros

HTTP	Código	Descrição
200	—	Sucesso
404	NIF não encontrado	O NIF não existe ou não foi encontrado
500	Erro na consulta	Falha de rede ou serviço temporariamente indisponível

# Exemplos Completos

▸ Axios (Node.js / React / Vue)

JavaScript — Axios

import axios from 'axios';

async function consultarNIF(nif) {
  try {
    const { data } = await axios.get(
      `https://api-agt.angohost.ao/consultar/${nif}`
    );
    return data.data; // objecto com nome, endereço, etc.
  } catch (e) {
    if (e.response?.status === 404) {
      throw new Error('NIF não encontrado');
    }
    throw e;
  }
}

// Uso:
const empresa = await consultarNIF('5400123456');
console.log(empresa.nome); // "ANGOHOST - PRESTAÇÃO DE SERVIÇOS, LDA"

▸ Python — requests

Python

import requests

def consultar_nif(nif: str) -> dict:
    r = requests.get(f"https://api-agt.angohost.ao/consultar/{nif}")
    r.raise_for_status()
    return r.json()["data"]

empresa = consultar_nif("5400123456")
print(empresa["nome"])       # ANGOHOST - PRESTAÇÃO DE SERVIÇOS, LDA
print(empresa["municipio"])  # CACUACO

▸ PHP — cURL

PHP

function consultarNIF(string $nif): array {
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL            => "https://api-agt.angohost.ao/consultar/$nif",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Accept: application/json'],
    ]);
    $json = curl_exec($ch);
    curl_close($ch);
    return json_decode($json, true)['data'];
}

$empresa = consultarNIF('5400123456');
echo $empresa['nome']; // ANGOHOST - PRESTAÇÃO DE SERVIÇOS, LDA