identify-ao 0.1.0

SDK em Python para consulta de NIF pessoal e de empresa via API Identity Lookup

identify-ao

SDK em Python para consulta de identidades pessoais e de empresas via NIF angolano utilizando a API Identity Lookup.

📋 Requisitos

• Python 3.8+
• requests >= 2.31.0

Instalação

Via pip (após publicação)

pip install identify-ao

Desenvolvimento local

git clone https://github.com/omariscode/identify-ao.git
cd identify-ao
pip install -e .

Uso Básico

Importar o SDK

from identify_ao import personal_nif, company_nif

Consultar NIF Pessoal

try:
    resultado = personal_nif("12345678901")
    print(resultado)
except Exception as e:
    print(f"Erro: {e}")

Resposta esperada:

{
    "fullName": "Morgado Andrade De Melo",

    "address": "VIANA, NA, CASA Nº XXXX ZONA YY",

    "dateOfBirth": "2000-01-04"
}

Consultar NIF de Empresa

try:
    resultado = company_nif("123456789")
    print(resultado)
except Exception as e:
    print(f"Erro: {e}")

Resposta esperada:

{
    "companyName": "UNITEL, S.A"
}

Tratamento de Erros

O SDK levanta IdentityLookupError em caso de falhas:

from identify_ao.core import IdentityLookupError, personal_nif

try:
    dados = personal_nif("invalid-nif")
except IdentityLookupError as e:
    print(f"Falha na consulta: {e}")

Tipos de erros:

• Conexão falhou: Problema de rede ou API indisponível
• Resposta inválida: A API retornou um formato não esperado
• NIF inválido: O NIF fornecido não existe ou é inválido

Estrutura do Projeto

identify-ao/
├── identify_ao/
│   ├── __init__.py          # Exports públicos
│   └── core.py              # Lógica principal
├── pyproject.toml           # Configuração do pacote
├── requirements.txt         # Dependências
└── README.md                # Este ficheiro

🔌 API Reference

personal_nif(nif: str) -> dict

Consulta informações de uma pessoa pelo NIF.

Parâmetros:

• nif (str): NIF angolano da pessoa (14 dígitos)

Retorna:

• dict: Dados da pessoa ou informações de erro

Levanta:

• IdentityLookupError: Se a consulta falhar

---

company_nif(nif: str) -> dict

Consulta informações de uma empresa pelo NIF.

Parâmetros:

• nif (str): NIF angolano da empresa (14 dígitos)

Retorna:

• dict: Dados da empresa ou informações de erro

Levanta:

• IdentityLookupError: Se a consulta falhar

Exemplos

Script simples

from identify_ao import personal_nif, company_nif, IdentityLookupError

def consultar_identidade(nif, tipo="pessoal"):
    try:
        if tipo == "pessoal":
            resultado = personal_nif(nif)
        else:
            resultado = company_nif(nif)
        
        print(f"✓ Consulta bem-sucedida:")
        for chave, valor in resultado.items():
            print(f"  {chave}: {valor}")
    
    except IdentityLookupError as e:
        print(f"✗ Erro na consulta: {e}")

# Uso
consultar_identidade("12345678901", "pessoal")
consultar_identidade("123456789", "empresa")

Licença

MIT

Autor

Omar Rodrigues - [e-mail]

Contribuições

Contribuições são bem-vindas! Por favor:

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/TuaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

Suporte

Para reportar bugs ou fazer sugestões, abra uma issue no repositório.