# 🏦 API de Empréstimos (Loans) - Documentação Completa

## 📋 Visão Geral

A API de Empréstimos é o núcleo do sistema de microcrédito, gerenciando todo o ciclo de vida dos empréstimos desde a criação até a conclusão.

## 🔗 Base URL
```
http://localhost:8000/api/loans
```

## 🔐 Autenticação

Todas as rotas requerem autenticação via JWT Bearer Token:
```http
Authorization: Bearer <seu_token_jwt>
```

## 📊 Estrutura de Dados

### Empréstimo (Loan)
```json
{
  "loan_id": 1,
  "loan_app_id": "LOAN001",
  "customer_id": 1,
  "product": "Microcrédito Básico",
  "loan_amount": 5000.00,
  "loan_term_months": 6,
  "interest_rate": 15.0,
  "type_of_payment": "Installments",
  "loan_installment": 958.33,
  "net_payable": 5750.00,
  "net_payout": 5000.00,
  "balance": 5750.00,
  "status": "Active",
  "previous_status": "Pending",
  "created_on": "2024-01-15T10:30:00Z",
  "activated_on": "2024-01-16T09:00:00Z",
  "last_modified_on": "2024-01-16T09:00:00Z",
  "agent_id": 1,
  "created_by": 1,
  "approved_by": 1,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-16T09:00:00Z"
}
```

## 🛠️ Endpoints Disponíveis

### 1. 📋 Listar Todos os Empréstimos
```http
GET /api/loans
```

**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 App ID, nome do cliente ou ID
- `status` (opcional): Filtrar por status
- `customer_id` (opcional): Filtrar por cliente
- `agent_id` (opcional): Filtrar por agente
- `product` (opcional): Filtrar por produto
- `sort_by` (opcional): Campo para ordenação (padrão: created_on)
- `sort_order` (opcional): ASC ou DESC (padrão: DESC)
- `format` (opcional): 'original' ou 'friendly' (padrão: original)

**Resposta:**
```json
{
  "success": true,
  "data": [
    {
      "loan_id": 1,
      "loan_app_id": "LOAN001",
      "customer_id": 1,
      "product": "Microcrédito Básico",
      "loan_amount": 5000.00,
      "loan_term_months": 6,
      "interest_rate": 15.0,
      "type_of_payment": "Installments",
      "loan_installment": 958.33,
      "net_payable": 5750.00,
      "net_payout": 5000.00,
      "balance": 5750.00,
      "status": "Active",
      "surname": "Silva",
      "firstname": "João",
      "agent_name": "Carlos Santos",
      "employer_name": "Empresa ABC",
      "total_paid": 0,
      "remaining_balance": 5750.00
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  },
  "statistics": {
    "total": 1,
    "active": 1,
    "pending": 0,
    "completed": 0,
    "overdue": 0
  },
  "format": "original"
}
```

### 2. 🔍 Buscar Empréstimo por ID
```http
GET /api/loans/:id
```

**Parâmetros:**
- `id`: ID do empréstimo
- `format` (opcional): 'original' ou 'friendly'

**Resposta:**
```json
{
  "success": true,
  "data": {
    "loan_id": 1,
    "loan_app_id": "LOAN001",
    "customer_id": 1,
    "product": "Microcrédito Básico",
    "loan_amount": 5000.00,
    "loan_term_months": 6,
    "interest_rate": 15.0,
    "type_of_payment": "Installments",
    "loan_installment": 958.33,
    "net_payable": 5750.00,
    "net_payout": 5000.00,
    "balance": 5750.00,
    "status": "Active",
    "surname": "Silva",
    "firstname": "João",
    "agent_name": "Carlos Santos",
    "employer_name": "Empresa ABC",
    "payments": [],
    "vetting": null,
    "balance_info": {
      "net_payable": 5750.00,
      "total_paid": 0,
      "current_balance": 5750.00
    },
    "overdue_info": {
      "due_date": "2024-07-15T10:30:00Z",
      "is_overdue": false,
      "days_overdue": 0
    }
  },
  "format": "original"
}
```

### 3. 🔍 Buscar Empréstimo por App ID
```http
GET /api/loans/app/:appId
```

**Parâmetros:**
- `appId`: ID da aplicação do empréstimo
- `format` (opcional): 'original' ou 'friendly'

### 4. ➕ Criar Novo Empréstimo
```http
POST /api/loans
```

**Permissões:** Agent, Manager, Admin

**Corpo da Requisição:**
```json
{
  "loan_app_id": "LOAN002",
  "customer_id": 1,
  "product": "Microcrédito Empresarial",
  "loan_amount": 15000.00,
  "loan_term_months": 12,
  "interest_rate": 12.5,
  "type_of_payment": "Installments",
  "agent_id": 1,
  "org_submitted_on": "2024-01-15",
  "approved_by": 1
}
```

**Campos Obrigatórios:**
- `loan_app_id`: ID único da aplicação (string, máximo 50 caracteres)
- `customer_id`: ID do cliente (integer, deve existir)
- `product`: Nome do produto (string, máximo 100 caracteres)
- `loan_amount`: Valor do empréstimo (decimal, positivo)
- `loan_term_months`: Prazo em meses (integer, 1-60)
- `interest_rate`: Taxa de juros (decimal, 0-100%)

**Campos Opcionais:**
- `type_of_payment`: "Single" ou "Installments" (padrão: "Installments")
- `agent_id`: ID do agente (integer, deve existir)
- `org_submitted_on`: Data de submissão (date)
- `approved_by`: ID do aprovador (integer, deve existir)

**Resposta:**
```json
{
  "success": true,
  "message": "Empréstimo criado com sucesso",
  "data": {
    "loan_id": 2,
    "loan_app_id": "LOAN002",
    "customer_id": 1,
    "product": "Microcrédito Empresarial",
    "loan_amount": 15000.00,
    "loan_term_months": 12,
    "interest_rate": 12.5,
    "type_of_payment": "Installments",
    "loan_installment": 1406.25,
    "net_payable": 16875.00,
    "net_payout": 15000.00,
    "balance": 16875.00,
    "status": "Pending",
    "created_by": 1,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5. ✏️ Atualizar Empréstimo
```http
PUT /api/loans/:id
```

**Permissões:** Manager, Admin

**Corpo da Requisição:**
```json
{
  "product": "Microcrédito Atualizado",
  "loan_amount": 20000.00,
  "interest_rate": 10.0
}
```

### 6. 🔄 Atualizar Status do Empréstimo
```http
PATCH /api/loans/:id/status
```

**Permissões:** Manager, Admin

**Corpo da Requisição:**
```json
{
  "status": "Active"
}
```

**Status Válidos:**
- `Pending`: Pendente de aprovação
- `Active`: Ativo (aprovado e em andamento)
- `Completed`: Concluído (pago integralmente)
- `Cancelled`: Cancelado
- `Overdue`: Em atraso

### 7. ✅ Ativar Empréstimo
```http
PATCH /api/loans/:id/activate
```

**Permissões:** Manager, Admin

**Resposta:**
```json
{
  "success": true,
  "message": "Empréstimo ativado com sucesso",
  "data": {
    "loan_id": 1,
    "status": "Active",
    "activated_on": "2024-01-16T09:00:00Z",
    "previous_status": "Pending"
  }
}
```

### 8. 👤 Buscar Empréstimos por Cliente
```http
GET /api/loans/customer/:customerId
```

**Parâmetros:**
- `customerId`: ID do cliente
- `format` (opcional): 'original' ou 'friendly'

### 9. 👨‍💼 Buscar Empréstimos por Agente
```http
GET /api/loans/agent/:agentId
```

**Parâmetros:**
- `agentId`: ID do agente
- `format` (opcional): 'original' ou 'friendly'

### 10. 📊 Buscar Empréstimos por Status
```http
GET /api/loans/status/:status
```

**Parâmetros:**
- `status`: Status do empréstimo
- `format` (opcional): 'original' ou 'friendly'

### 11. ⏰ Buscar Empréstimos em Atraso
```http
GET /api/loans/overdue/all
```

**Parâmetros:**
- `format` (opcional): 'original' ou 'friendly'

**Resposta:**
```json
{
  "success": true,
  "data": [
    {
      "loan_id": 1,
      "loan_app_id": "LOAN001",
      "customer_id": 1,
      "product": "Microcrédito Básico",
      "loan_amount": 5000.00,
      "net_payable": 5750.00,
      "remaining_balance": 5750.00,
      "due_date": "2024-01-15T10:30:00Z",
      "days_overdue": 15,
      "surname": "Silva",
      "firstname": "João",
      "agent_name": "Carlos Santos"
    }
  ],
  "statistics": {
    "total_overdue": 1,
    "total_amount_overdue": 5750.00
  },
  "format": "original"
}
```

### 12. 📈 Estatísticas de Empréstimos
```http
GET /api/loans/stats/overview
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "overview": {
      "total_loans": 100,
      "active_loans": 75,
      "pending_loans": 10,
      "completed_loans": 12,
      "cancelled_loans": 2,
      "overdue_loans": 1,
      "total_loan_amount": 500000.00,
      "active_loan_amount": 375000.00,
      "total_payable": 575000.00,
      "total_outstanding": 400000.00,
      "avg_loan_amount": 5000.00,
      "avg_interest_rate": 15.5
    },
    "by_product": [
      {
        "product": "Microcrédito Básico",
        "count": 50,
        "total_amount": 250000.00,
        "avg_amount": 5000.00
      },
      {
        "product": "Microcrédito Empresarial",
        "count": 30,
        "total_amount": 300000.00,
        "avg_amount": 10000.00
      }
    ],
    "monthly_trend": [
      {
        "month": "2024-01-01T00:00:00Z",
        "loans_created": 15,
        "amount_created": 75000.00
      }
    ]
  }
}
```

### 13. 🔍 Buscar Empréstimos
```http
GET /api/loans/search/query?q=termo
```

**Parâmetros:**
- `q`: Termo de busca (obrigatório)
- `format` (opcional): 'original' ou 'friendly'

### 14. 🧮 Calcular Saldo do Empréstimo
```http
GET /api/loans/:id/balance
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "loan_id": 1,
    "loan_app_id": "LOAN001",
    "net_payable": 5750.00,
    "total_paid": 1000.00,
    "current_balance": 4750.00,
    "last_calculated": "2024-01-20T10:30:00Z"
  }
}
```

### 15. ⏰ Verificar Atraso do Empréstimo
```http
GET /api/loans/:id/overdue
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "loan_id": 1,
    "loan_app_id": "LOAN001",
    "due_date": "2024-01-15T10:30:00Z",
    "is_overdue": true,
    "days_overdue": 5
  }
}
```

### 16. 📊 Estatísticas do Empréstimo
```http
GET /api/loans/:id/statistics
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "loan_id": 1,
    "loan_app_id": "LOAN001",
    "total_payments": 3,
    "total_paid": 2874.99,
    "remaining_balance": 2875.01,
    "avg_payment": 958.33,
    "last_payment_date": "2024-01-20T10:30:00Z"
  }
}
```

## 🎨 Formato Friendly

Quando `format=friendly` é usado, os dados são formatados de forma mais amigável:

```json
{
  "loan_id": 1,
  "loan_app_id": "LOAN001",
  "customer_name": "João Silva",
  "agent_name": "Carlos Santos",
  "employer_name": "Empresa ABC",
  "product": "Microcrédito Básico",
  "loan_amount_display": "MZN 5,000.00",
  "net_payable_display": "MZN 5,750.00",
  "loan_installment_display": "MZN 958.33",
  "balance_display": "MZN 5,750.00",
  "interest_rate_display": "15.0%",
  "loan_term_display": "6 meses",
  "status_display": "Ativo",
  "payment_type_display": "Parcelado",
  "created_on_display": "15/01/2024",
  "activated_on_display": "16/01/2024"
}
```

## 🧮 Cálculos Automáticos

O sistema calcula automaticamente:

### Valores Financeiros
- **net_payable** = loan_amount × (1 + interest_rate / 100)
- **loan_installment** = type_of_payment === 'Single' ? net_payable : net_payable / loan_term_months
- **net_payout** = loan_amount
- **balance** = net_payable (inicialmente)

### Exemplo de Cálculo
```javascript
// Dados de entrada
loan_amount: 5000.00
interest_rate: 15.0%
loan_term_months: 6
type_of_payment: "Installments"

// Resultado
net_payable = 5000 * (1 + 15/100) = 5750.00
loan_installment = 5750 / 6 = 958.33
net_payout = 5000.00
balance = 5750.00
```

## 📦 Produtos de Empréstimo

### Produtos Disponíveis
- **Microcrédito Básico**: Para necessidades imediatas (MZN 1,000 - 10,000)
- **Microcrédito Empresarial**: Para desenvolvimento empresarial (MZN 5,000 - 50,000)
- **Empréstimo Emergencial**: Para emergências (MZN 500 - 5,000)
- **Microcrédito Habitação**: Para melhorias habitacionais (MZN 20,000 - 100,000)
- **Microcrédito Agrícola**: Para atividades agrícolas (MZN 2,000 - 20,000)
- **Microcrédito Comercial**: Para atividades comerciais (MZN 3,000 - 30,000)
- **Microcrédito Educativo**: Para fins educacionais (MZN 1,000 - 15,000)
- **Microcrédito Tecnológico**: Para aquisição de tecnologia (MZN 5,000 - 25,000)
- **Microcrédito Sazonal**: Para atividades sazonais (MZN 1,000 - 8,000)
- **Microcrédito Expansão**: Para expansão de negócios (MZN 10,000 - 100,000)

## 🔒 Códigos de Status HTTP

- **200**: Sucesso
- **201**: Criado com sucesso
- **400**: Dados inválidos
- **401**: Não autenticado
- **403**: Acesso negado
- **404**: Empréstimo não encontrado
- **409**: Conflito (ex: App ID já existe)
- **500**: Erro interno do servidor

## 🚨 Códigos de Erro Personalizados

- **DUPLICATE_ENTRY**: Entrada duplicada
- **VALIDATION_ERROR**: Erro de validação
- **NOT_FOUND**: Recurso não encontrado
- **UNAUTHORIZED**: Não autorizado
- **FORBIDDEN**: Acesso negado

## 📝 Exemplos de Uso

### PowerShell
```powershell
$token = "seu_token_jwt"
$headers = @{"Authorization" = "Bearer $token"}

# Criar empréstimo
$loanData = @{
    loan_app_id = "LOAN001"
    customer_id = 1
    product = "Microcrédito Básico"
    loan_amount = 5000.00
    loan_term_months = 6
    interest_rate = 15.0
    type_of_payment = "Installments"
    agent_id = 1
}

Invoke-RestMethod -Uri "http://localhost:8000/api/loans" -Method POST -Headers $headers -Body ($loanData | ConvertTo-Json) -ContentType "application/json"

# Listar empréstimos
Invoke-RestMethod -Uri "http://localhost:8000/api/loans" -Method GET -Headers $headers

# Buscar por ID
Invoke-RestMethod -Uri "http://localhost:8000/api/loans/1" -Method GET -Headers $headers

# Atualizar status
$statusData = @{ status = "Active" }
Invoke-RestMethod -Uri "http://localhost:8000/api/loans/1/status" -Method PATCH -Headers $headers -Body ($statusData | ConvertTo-Json) -ContentType "application/json"
```

### JavaScript/Node.js
```javascript
const token = "seu_token_jwt";

// Criar empréstimo
const loanData = {
    loan_app_id: "LOAN001",
    customer_id: 1,
    product: "Microcrédito Básico",
    loan_amount: 5000.00,
    loan_term_months: 6,
    interest_rate: 15.0,
    type_of_payment: "Installments",
    agent_id: 1
};

const response = await fetch('http://localhost:8000/api/loans', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(loanData)
});

const result = await response.json();
console.log(result);
```

### cURL
```bash
# Criar empréstimo
curl -X POST http://localhost:8000/api/loans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer seu_token_jwt" \
  -d '{
    "loan_app_id": "LOAN001",
    "customer_id": 1,
    "product": "Microcrédito Básico",
    "loan_amount": 5000.00,
    "loan_term_months": 6,
    "interest_rate": 15.0,
    "type_of_payment": "Installments",
    "agent_id": 1
  }'

# Listar empréstimos
curl -X GET http://localhost:8000/api/loans \
  -H "Authorization: Bearer seu_token_jwt"

# Buscar por ID
curl -X GET http://localhost:8000/api/loans/1 \
  -H "Authorization: Bearer seu_token_jwt"

# Atualizar status
curl -X PATCH http://localhost:8000/api/loans/1/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer seu_token_jwt" \
  -d '{"status": "Active"}'
```

## 🔄 Fluxo de Status

```
Pending → Active → Completed
   ↓         ↓
Cancelled  Overdue
```

1. **Pending**: Empréstimo criado, aguardando aprovação
2. **Active**: Empréstimo aprovado e ativo
3. **Completed**: Empréstimo pago integralmente
4. **Cancelled**: Empréstimo cancelado
5. **Overdue**: Empréstimo em atraso

## 📊 Relacionamentos

### Tabelas Relacionadas
- **customers**: Cliente do empréstimo
- **agents**: Agente responsável
- **users**: Usuário que criou/aprovou
- **payments**: Pagamentos do empréstimo
- **vetting**: Processo de aprovação

### Foreign Keys
- `customer_id` → `customers.customer_id`
- `agent_id` → `agents.agent_id`
- `created_by` → `users.user_id`
- `approved_by` → `users.user_id`

## 🚀 Funcionalidades Avançadas

### 1. Cálculo Automático de Saldo
O sistema recalcula automaticamente o saldo baseado nos pagamentos realizados.

### 2. Verificação de Atraso
Verifica automaticamente se o empréstimo está em atraso baseado na data de vencimento.

### 3. Estatísticas em Tempo Real
Fornece estatísticas detalhadas sobre empréstimos, pagamentos e performance.

### 4. Busca Avançada
Permite busca por múltiplos critérios e ordenação personalizada.

### 5. Formato Amigável
Oferece formatação de dados para exibição mais amigável ao usuário.

## 🔧 Manutenção

### Limpeza de Dados
- Empréstimos cancelados podem ser arquivados após 1 ano
- Empréstimos concluídos podem ser movidos para arquivo após 2 anos

### Backup
- Backup diário da tabela `loans`
- Backup semanal das tabelas relacionadas

### Monitoramento
- Logs de todas as operações de empréstimo
- Alertas para empréstimos em atraso
- Relatórios de performance mensais

---

## 📞 Suporte

Para dúvidas ou problemas com a API de Empréstimos, entre em contato com a equipe de desenvolvimento.

**Versão da API:** 1.0.0  
**Última atualização:** 2024-01-15