Consulta NIF Angola

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

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

Authorization: Bearer SUA_API_KEY

curl https://dev.it.ao/consultar/5400123456 \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Accept: application/json"

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

$ch = curl_init('https://dev.it.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);

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

Cada plano recebe um subconjunto fixo de campos. Campos previstos cujo valor a fonte oficial não forneça são devolvidos vazios (nunca inventados).

▸ CAE — actividades económicas (BASIC e PRO)

cae_principal é um objeto {"codigo","descricao"} (ou null se a empresa não tiver CAE registado). cae_secundarios é uma lista de objetos {"codigo","descricao"} (vazia se não existirem). O codigo é sempre uma string (preserva zeros à esquerda). A descricao vem vazia quando a fonte oficial não a fornece — não inventamos descrições.

{
  "success": true,
  "data": {
    "nif": "5000088927",
    "nome": "ANGOHOST - PRESTAÇAO DE SERVIÇOS, LDA",
    "estado": "Activo",
    "tipo": "TIPO5",
    "telefone": "942090108",
    "morada": "RUA 2, BLOCO 11, PREDIO Nº 3, 7º ANDAR, APTº701",
    "municipio": "",
    "provincia": "",
    "data_constituicao": "",
    "regime_fiscal": "EXCL",
    "cae_principal": { "codigo": "82990", "descricao": "" },
    "cae_secundarios": []
  }
}

Disponível vs inexistente vs indisponível: HTTP 200 com cae_principal: null = a fonte respondeu e a empresa não tem CAE registado (inexistente). HTTP 503 (SOURCE_UNAVAILABLE) = não foi possível consultar (fontes indisponíveis) — repita mais tarde; não assuma ausência de CAE. Cobertura por fonte: o CAE principal e os secundários provêm da fonte oficial completa (GUE); quando esta está indisponível, o serviço devolve, via fonte alternativa (AGT), o cae_principal conhecido e cae_secundarios: [].

morada é sempre uma string. O objeto estruturado opcional morada_detalhada só é incluído no plano Pro e apenas quando a fonte o fornecer. O plano Free é cache-only em /consultar.

Importante para integradores: distinga sempre 404 NIF_NOT_FOUND (o NIF não existe) de 503 SOURCE_UNAVAILABLE (não foi possível confirmar por indisponibilidade das fontes). Em 503 repita a consulta mais tarde; não trate como NIF inexistente. A resposta pública é estável e não revela qual a fonte interna de dados utilizada.

▸ Axios (Node.js / React / Vue)

import axios from 'axios';

async function consultarNIF(nif) {
  try {
    const { data } = await axios.get(
      `https://dev.it.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

import requests

def consultar_nif(nif: str) -> dict:
    r = requests.get(f"https://dev.it.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

function consultarNIF(string $nif): array {
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL            => "https://dev.it.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