# 📋 API de Customers - Documentação Completa

## 🎯 Visão Geral

A API de Customers fornece funcionalidades completas para gerenciar clientes do sistema de microcrédito, incluindo CRUD completo, filtros avançados, estatísticas e exportação de dados.

## 🔐 Autenticação

Todas as rotas requerem autenticação via JWT token no header:
```
Authorization: Bearer <token>
```

## 📊 Endpoints Disponíveis

### 1. **Listar Todos os Customers**
```http
GET /api/customers
```

**Parâmetros de Query:**
- `page` (opcional): Número da página (padrão: 1)
- `limit` (opcional): Itens por página (padrão: 10)
- `search` (opcional): Busca por nome, sobrenome ou ID
- `marital_status` (opcional): Filtro por status marital
- `geotag` (opcional): Filtro por geotag
- `employer_id` (opcional): Filtro por empregador
- `sort_by` (opcional): Campo para ordenação (padrão: created_at)
- `sort_order` (opcional): Ordem (asc/desc, padrão: desc)

**Exemplo de Resposta:**
```json
{
  "success": true,
  "data": [
    {
      "customer_id": 1,
      "surname": "Silva",
      "firstname": "João",
      "title": "Mr.",
      "date_of_birth": "1990-05-15",
      "id_number": "123456789",
      "tax_number": null,
      "home_address": "Maputo, Moçambique",
      "geotag": "Confirmed",
      "mobile": "+258 84 123 4567",
      "home_phone": null,
      "marital_status": "Single",
      "spouse_name": null,
      "next_kin_name": null,
      "employer_id": 1,
      "employer_name": "Empresa ABC",
      "created_by": 1,
      "created_at": "2025-10-11T15:00:00.000Z",
      "updated_at": "2025-10-11T15:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  },
  "statistics": {
    "total": 1
  }
}
```

### 2. **Buscar Customer por ID**
```http
GET /api/customers/:id
```

**Parâmetros:**
- `id`: ID do customer

**Exemplo de Resposta:**
```json
{
  "success": true,
  "data": {
    "customer_id": 1,
    "surname": "Silva",
    "firstname": "João",
    "title": "Mr.",
    "date_of_birth": "1990-05-15",
    "id_number": "123456789",
    "tax_number": null,
    "home_address": "Maputo, Moçambique",
    "geotag": "Confirmed",
    "mobile": "+258 84 123 4567",
    "home_phone": null,
    "marital_status": "Single",
    "spouse_name": null,
    "next_kin_name": null,
    "employer_id": 1,
    "employer_name": "Empresa ABC",
    "created_by": 1,
    "created_at": "2025-10-11T15:00:00.000Z",
    "updated_at": "2025-10-11T15:00:00.000Z"
  }
}
```

### 3. **Criar Novo Customer**
```http
POST /api/customers
```

**Body (JSON):**
```json
{
  "surname": "Silva",
  "firstname": "João",
  "title": "Mr.",
  "date_of_birth": "1990-05-15",
  "id_number": "123456789",
  "tax_number": "TAX123",
  "home_address": "Maputo, Moçambique",
  "geotag": "Confirmed",
  "mobile": "+258 84 123 4567",
  "home_phone": "+258 21 123 456",
  "marital_status": "Single",
  "spouse_name": null,
  "next_kin_name": "Maria Silva",
  "employer_id": 1
}
```

**Campos Obrigatórios:**
- `surname`: Sobrenome (2-100 caracteres)
- `firstname`: Nome (2-100 caracteres)

**Campos Opcionais:**
- `title`: Título (Mr., Mrs., Ms., Dr., Prof.)
- `date_of_birth`: Data de nascimento (formato ISO)
- `id_number`: Número de identificação (único)
- `tax_number`: Número de contribuinte
- `home_address`: Endereço residencial
- `geotag`: Status de geolocalização
- `mobile`: Telefone móvel
- `home_phone`: Telefone fixo
- `marital_status`: Status marital (Single, Married, Divorced, Widowed, Other)
- `spouse_name`: Nome do cônjuge
- `next_kin_name`: Nome do próximo parente
- `employer_id`: ID do empregador

**Exemplo de Resposta:**
```json
{
  "success": true,
  "message": "Cliente cadastrado com sucesso",
  "data": {
    "customer_id": 1,
    "surname": "Silva",
    "firstname": "João",
    "title": "Mr.",
    "date_of_birth": "1990-05-15",
    "id_number": "123456789",
    "tax_number": "TAX123",
    "home_address": "Maputo, Moçambique",
    "geotag": "Confirmed",
    "mobile": "+258 84 123 4567",
    "home_phone": "+258 21 123 456",
    "marital_status": "Single",
    "spouse_name": null,
    "next_kin_name": "Maria Silva",
    "employer_id": 1,
    "created_by": 1,
    "created_at": "2025-10-11T15:00:00.000Z",
    "updated_at": "2025-10-11T15:00:00.000Z"
  }
}
```

### 4. **Atualizar Customer**
```http
PUT /api/customers/:id
```

**Parâmetros:**
- `id`: ID do customer

**Body (JSON):** Mesmos campos da criação, todos opcionais

**Exemplo de Resposta:**
```json
{
  "success": true,
  "message": "Cliente atualizado com sucesso",
  "data": {
    "customer_id": 1,
    "surname": "Silva",
    "firstname": "João",
    "title": "Mr.",
    "date_of_birth": "1990-05-15",
    "id_number": "123456789",
    "tax_number": "TAX123",
    "home_address": "Maputo, Moçambique",
    "geotag": "Confirmed",
    "mobile": "+258 84 999 8888",
    "home_phone": "+258 21 123 456",
    "marital_status": "Married",
    "spouse_name": "Maria Silva",
    "next_kin_name": "Pedro Silva",
    "employer_id": 1,
    "created_by": 1,
    "created_at": "2025-10-11T15:00:00.000Z",
    "updated_at": "2025-10-11T15:30:00.000Z"
  }
}
```

### 5. **Deletar Customer** (Apenas Admin)
```http
DELETE /api/customers/:id
```

**Parâmetros:**
- `id`: ID do customer

**Exemplo de Resposta:**
```json
{
  "success": true,
  "message": "Cliente deletado com sucesso"
}
```

### 6. **Estatísticas dos Customers**
```http
GET /api/customers/stats
```

**Exemplo de Resposta:**
```json
{
  "success": true,
  "statistics": {
    "total_customers": "150",
    "single_count": "45",
    "married_count": "80",
    "divorced_count": "15",
    "widowed_count": "8",
    "other_count": "2",
    "unconfirmed_geotag": "25",
    "with_employer": "120",
    "without_employer": "30",
    "new_last_30_days": "12",
    "new_last_7_days": "3"
  }
}
```

### 7. **Pesquisar Customers**
```http
GET /api/customers/search
```

**Parâmetros de Query:**
- `q`: Termo de busca
- `marital_status`: Filtro por status marital
- `geotag`: Filtro por geotag
- `employer_id`: Filtro por empregador
- `page`: Número da página
- `limit`: Itens por página

**Exemplo de Resposta:**
```json
{
  "success": true,
  "data": [...],
  "pagination": {...},
  "search": {
    "query": "João",
    "marital_status": "Single",
    "geotag": "Confirmed",
    "employer_id": "1"
  }
}
```

### 8. **Customers por Empregador**
```http
GET /api/customers/employer/:employerId
```

**Parâmetros:**
- `employerId`: ID do empregador

**Parâmetros de Query:**
- `page`: Número da página
- `limit`: Itens por página

**Exemplo de Resposta:**
```json
{
  "success": true,
  "data": [...],
  "pagination": {...},
  "employer": {
    "employer_id": 1,
    "employer_name": "Empresa ABC"
  }
}
```

### 9. **Customers por Status Marital**
```http
GET /api/customers/marital-status/:status
```

**Parâmetros:**
- `status`: Status marital (Single, Married, Divorced, Widowed, Other)

**Exemplo de Resposta:**
```json
{
  "success": true,
  "data": [...],
  "pagination": {...},
  "marital_status": "Single"
}
```

### 10. **Customers por Geotag**
```http
GET /api/customers/geotag/:geotag
```

**Parâmetros:**
- `geotag`: Status do geotag

**Exemplo de Resposta:**
```json
{
  "success": true,
  "data": [...],
  "pagination": {...},
  "geotag": "Confirmed"
}
```

### 11. **Histórico de Empréstimos do Customer**
```http
GET /api/customers/:id/loans
```

**Parâmetros:**
- `id`: ID do customer

**Parâmetros de Query:**
- `page`: Número da página
- `limit`: Itens por página

**Exemplo de Resposta:**
```json
{
  "success": true,
  "data": [
    {
      "loan_id": 1,
      "loan_app_id": "LOAN001",
      "product": "Personal Loan",
      "loan_amount": 5000.00,
      "loan_term_months": 12,
      "interest_rate": 15.00,
      "type_of_payment": "Installments",
      "loan_installment": 450.00,
      "net_payable": 5400.00,
      "net_payout": 5000.00,
      "amortized_amount": 0.00,
      "balance": 5400.00,
      "status": "Active",
      "created_on": "2025-10-11T15:00:00.000Z",
      "activated_on": "2025-10-11T15:00:00.000Z",
      "last_modified_on": "2025-10-11T15:00:00.000Z",
      "agent_name": "João Agente",
      "agent_code": "AG001"
    }
  ],
  "pagination": {...},
  "customer": {
    "customer_id": 1,
    "firstname": "João",
    "surname": "Silva"
  }
}
```

### 12. **Exportar Customers (CSV)**
```http
GET /api/customers/export
```

**Parâmetros de Query:**
- `format`: Formato de exportação (apenas 'csv' suportado)
- `marital_status`: Filtro por status marital
- `geotag`: Filtro por geotag
- `employer_id`: Filtro por empregador

**Exemplo de Resposta:**
```
ID,Nome,Sobrenome,Título,Data Nascimento,ID Number,Tax Number,Endereço,Geotag,Mobile,Telefone,Status Marital,Cônjuge,Próximo Parente,Empregador,Criado em,Atualizado em
1,João,Silva,Mr.,1990-05-15,123456789,TAX123,Maputo; Moçambique,Confirmed,+258 84 123 4567,+258 21 123 456,Single,,Maria Silva,Empresa ABC,2025-10-11T15:00:00.000Z,2025-10-11T15:30:00.000Z
```

## 🔒 Permissões

- **Leitura**: Todos os usuários autenticados
- **Criação**: Todos os usuários autenticados
- **Atualização**: Todos os usuários autenticados
- **Exclusão**: Apenas administradores

## 📝 Validações

### Campos Obrigatórios
- `surname`: 2-100 caracteres
- `firstname`: 2-100 caracteres

### Campos com Validação
- `title`: Deve ser um dos valores: Mr., Mrs., Ms., Dr., Prof.
- `date_of_birth`: Data válida, não pode ser futura
- `id_number`: Máximo 50 caracteres, deve ser único
- `tax_number`: Máximo 50 caracteres
- `home_address`: Máximo 500 caracteres
- `geotag`: Máximo 20 caracteres
- `mobile`: Máximo 20 caracteres
- `home_phone`: Máximo 20 caracteres
- `marital_status`: Deve ser um dos valores: Single, Married, Divorced, Widowed, Other
- `spouse_name`: Máximo 200 caracteres
- `next_kin_name`: Máximo 200 caracteres
- `employer_id`: Deve ser um ID válido de empregador existente

## 🚨 Códigos de Erro

- **400**: Dados inválidos ou violação de regras de negócio
- **401**: Não autenticado
- **403**: Sem permissão (apenas para exclusão)
- **404**: Customer não encontrado
- **409**: Conflito (ex: ID number duplicado)
- **500**: Erro interno do servidor

## 📊 Auditoria

Todas as operações são registradas no sistema de auditoria:
- Criação de customers
- Atualização de customers
- Exclusão de customers
- Acesso a dados sensíveis

## 🔄 Rate Limiting

- **Limite**: 1000 requisições por 5 minutos por usuário
- **Headers de resposta**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## 📈 Exemplos de Uso

### Buscar customers com filtros
```bash
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8000/api/customers?page=1&limit=20&marital_status=Married&geotag=Confirmed"
```

### Criar novo customer
```bash
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "surname": "Silva",
    "firstname": "João",
    "title": "Mr.",
    "mobile": "+258 84 123 4567",
    "marital_status": "Single"
  }' \
  "http://localhost:8000/api/customers"
```

### Exportar customers para CSV
```bash
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8000/api/customers/export?format=csv" \
  -o customers.csv
```

## 🎯 Funcionalidades Implementadas

✅ **CRUD Completo**
- ✅ Criar customer
- ✅ Listar customers com paginação
- ✅ Buscar customer por ID
- ✅ Atualizar customer
- ✅ Deletar customer (apenas admin)

✅ **Filtros e Pesquisa**
- ✅ Busca por texto (nome, sobrenome, ID)
- ✅ Filtro por status marital
- ✅ Filtro por geotag
- ✅ Filtro por empregador
- ✅ Ordenação personalizada

✅ **Estatísticas**
- ✅ Estatísticas gerais dos customers
- ✅ Contadores por categoria
- ✅ Métricas de crescimento

✅ **Funcionalidades Avançadas**
- ✅ Histórico de empréstimos do customer
- ✅ Exportação para CSV
- ✅ Validação robusta de dados
- ✅ Auditoria completa
- ✅ Rate limiting
- ✅ Tratamento de erros

✅ **Integração**
- ✅ Sistema de autenticação
- ✅ Sistema de auditoria
- ✅ Banco de dados PostgreSQL
- ✅ Validação com Joi
- ✅ Logging estruturado