Introdução

Bem-vindo à documentação oficial do NIF Check!

Nossa API permite validar NIFs angolanos em tempo real, consultando directamente a base de dados da AGT (Administração Geral Tributária). Siga os passos abaixo para integrar no seu projeto em minutos.

JavaScript / Fetch

// 1. Definir o NIF e a chave de API
const nif = '020512295LA058';
const endpoint = 'https://nifcheck.mimuu.ao/api/v1/validar';

// 2. Realizar o pedido (suporta GET e POST)
const response = await fetch(`${endpoint}?nif=${nif}`, {
    method: 'GET',
    headers: {
        'X-API-Key': 'SUA_CHAVE_AQUI'
    }
});

// 3. Processar a resposta
const data = await response.json();
console.log(data);

Autenticação

Todas as requisições à API devem incluir a sua chave de acesso no cabeçalho HTTP X-API-Key.

Headers Necessários

X-API-Key: nif-live_xxxxxxxxxxxxxxxxxxxxxxxx

As suas chaves de API podem ser geridas no painel de utilizador em /painel/api-keys.

SEGURANÇA: Nunca exponha a sua chave de API em código front-end público ou repositórios abertos. Utilize sempre variáveis de ambiente (.env).

Consultar NIF

Endpoint para validação em tempo real de um contribuinte individual ou empresa diretamente nas bases de dados da AGT.

GET https://nifcheck.mimuu.ao/api/v1/validar?nif=NIF_AQUI

Parâmetros

Query String / Body JSON

nif            (obrigatório) — NIF ou B.I. a validar
force_refresh  (opcional)    — true para ignorar cache e consultar a AGT novamente

Formatos Aceites

NIF Empresa: 9 dígitos (ex: 5417111260)
NIF Singulares: 9 dígitos + 2 letras + 3 dígitos (ex: 020512295LA058)
B.I. Angolano: 9 dígitos + 2 letras + 3 dígitos (ex: 004006289LA046)

CACHE: Os resultados são armazenados em cache local por 60 minutos. Use force_refresh=true para forçar uma consulta actualizada à AGT.

Estrutura de Resposta

A API retorna um objecto JSON com os dados fiscais do contribuinte consultado.

Resposta de Sucesso (200 OK)

Resposta JSON

{
    "NIF": "020512295LA058",
    "Nome": "JOSE IZATA QUINVULA",
    "Tipo": "SINGULAR",
    "Estado": "Activo",
    "Inadimplente": "Não",
    "Regime de IVA": "Sem actividade em IVA (Não factura IVA)",
    "Residente Fiscal": "SIM",
    "nif": "020512295LA058",
    "fonte": "Cache Local (Fresh)",
    "cache": true
}

Campos da Resposta

Referência

NIF                Número de Identificação Fiscal
Nome               Nome completo do titular
Tipo               "SINGULAR" (pessoa física) ou "COLECTIVO" (empresa)
Estado             "Activo", "Suspenso" ou "Inexistente"
Inadimplente       "Sim" ou "Não"
Regime de IVA      Regime fiscal do contribuinte
Residente Fiscal   "SIM" ou "NÃO"
nif                NIF consultado (echo)
fonte              Origem do dado: "Cache Local (Fresh)", "AGT Live", etc.
cache              true se veio da cache, false se consulta live

Códigos de Erro

A API utiliza códigos HTTP padrão para indicar o estado da requisição.

Códigos HTTP

200  Sucesso — Dados do contribuinte retornados
400  Requisição Inválida — NIF não fornecido ou formato inválido
401  Não Autorizado — Chave de API não fornecida
403  Acesso Negado — Chave inválida, inativa ou pendente
404  Não Encontrado — NIF não existe na base da AGT
429  Limite Atingido — Saldo de créditos esgotado
500  Erro Interno — Problema no servidor
503  Indisponível — Serviço da AGT fora do ar ou em manutenção

Exemplo de Resposta de Erro

404 Not Found

{
    "status": "Não encontrado",
    "erro": "NIF não encontrado na base de dados ativa da AGT.",
    "nif": "999999999",
    "sucesso": false
}

429 Limite Atingido

{
    "erro": "Saldo de consultas esgotado",
    "dica": "Aguarde até amanhã para receber mais 100 créditos ou contacte o administrador."
}

Integração Universal

Selecione a sua linguagem preferida para ver o código de integração pronto a usar:

JavaScript / Fetch

Limites e Quotas

Nossa API opera com um sistema de créditos. Cada consulta consome 1 crédito do seu saldo disponível.

Planos Disponíveis

Planos

Gratuito   — 10 consultas/dia (recarga automática diária)
Pago       — Consultas ilimitadas (contacte o administrador)

Rate Limiting

A API aplica limites de velocidade para garantir estabilidade:

Máximo 30 pedidos/minuto por chave de API
Máximo 5 consultas simultâneas à AGT
Cache local de 60 minutos por NIF

NOTA: Para necessidades de alto volume, contacte-nos para activar o plano pago com quota ilimitada.