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. Os resultados são automaticamente cached por 1 hora.

# 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 /consultar/{nif}": "Consultar empresa por NIF"
  }
}

GET /consultar/{nif} Consultar por NIF

Retorna os dados completos do contribuinte ou empresa registada com o NIF indicado.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
nif	string	obrigatório	Número de Identificação Fiscal (NIF) angolano. Ex: `5400123456`

Exemplos de Pedido

cURL

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

JavaScript (fetch)

const res = await fetch(
  'https://api-agt.angohost.ao/consultar/5400123456'
);
const data = await res.json();
console.log(data);

PHP

$response = file_get_contents(
  'https://api-agt.angohost.ao/consultar/5400123456'
);
$data = json_decode($response, true);

Python

import requests
r = requests.get(
  'https://api-agt.angohost.ao/consultar/5400123456'
)
data = r.json()

Respostas

200 OK 404 Not Found 500 Error

200 — Sucesso

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

404 — NIF não encontrado

{
  "error":   "NIF não encontrado",
  "message": "Não foi possível encontrar dados para o NIF informado"
}

# 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
numero_contacto	string	Número de contacto principal
endereco	string	Endereço completo formatado
municipio	string	Município onde está registado
provincia	string	Código da província (ex: LA = Luanda)
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