Metadata-Version: 2.4
Name: identify-ao
Version: 0.1.0
Summary: SDK em Python para consulta de NIF pessoal e de empresa via API Identity Lookup
Author-email: Omar Rodrigues <omarscode007@gmail.com>
License: MIT
Keywords: nif,identity,api,sdk,angola,bi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# 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)

```bash
pip install identify-ao
```

### Desenvolvimento local

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

## Uso Básico

### Importar o SDK

```python
from identify_ao import personal_nif, company_nif
```

### Consultar NIF Pessoal

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

**Resposta esperada:**
```json
{
    "fullName": "Morgado Andrade De Melo",

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

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

### Consultar NIF de Empresa

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

**Resposta esperada:**
```json
{
    "companyName": "UNITEL, S.A"
}
```

## Tratamento de Erros

O SDK levanta `IdentityLookupError` em caso de falhas:

```python
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

```python
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 - omarscode007@gmail.com

## 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.
