# 🏢 API de Employers (Empregadores)

## 📋 **Visão Geral**

A API de Employers permite gerenciar informações sobre empregadores no sistema de microcrédito. Inclui funcionalidades completas de CRUD, filtros, busca, estatísticas e verificação de empregadores.

## 🔗 **Endpoints Disponíveis**

### **1. Listar Empregadores**
```http
GET /api/employers
```

**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): Termo de busca
- `business_type` (opcional): Tipo de negócio (Government, Private, NGO, Other)
- `is_verified` (opcional): Status de verificação (true/false)
- `format` (opcional): Formato de resposta (original/friendly)

**Resposta:**
```json
{
    "success": true,
    "data": [
        {
            "employer_id": 1,
            "employer_name": "Ministério da Educação",
            "employer_address": "Av. 24 de Julho, 1678, Maputo",
            "contact_phone": "+258 21 300 000",
            "contact_email": "info@minedh.gov.mz",
            "contact_person": "Dr. Carmelita Namashulua",
            "salary_range_min": 15000,
            "salary_range_max": 45000,
            "position": "Ministra",
            "department": "Ministério",
            "employee_count": 2500,
            "business_type": "Government",
            "registration_number": "GOV-MZ-001",
            "tax_id": "TAX-GOV-001",
            "is_verified": true,
            "verification_date": "2024-01-15T00:00:00.000Z",
            "notes": "Ministério responsável pela educação",
            "total_customers": 15,
            "active_loans": 8
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 10,
        "total": 25,
        "pages": 3
    },
    "statistics": {
        "total": 25
    },
    "format": "original"
}
```

### **2. Buscar Empregador por ID**
```http
GET /api/employers/:id
```

**Parâmetros:**
- `id`: ID do empregador
- `format` (opcional): Formato de resposta (original/friendly)

**Resposta:**
```json
{
    "success": true,
    "data": {
        "employer_id": 1,
        "employer_name": "Ministério da Educação",
        // ... outros campos
    },
    "format": "original"
}
```

### **3. Criar Empregador**
```http
POST /api/employers
```

**Body:**
```json
{
    "employer_name": "Empresa Teste API",
    "employer_address": "Rua de Teste, 123, Maputo",
    "contact_phone": "+258 21 123 456",
    "contact_email": "teste@empresa.co.mz",
    "contact_person": "João Teste",
    "salary_range_min": 10000,
    "salary_range_max": 25000,
    "position": "Gerente",
    "department": "Administração",
    "employee_count": 50,
    "business_type": "Private",
    "registration_number": "REG-TEST-001",
    "tax_id": "TAX-TEST-001",
    "is_verified": false,
    "notes": "Empresa criada para teste"
}
```

**Campos Obrigatórios:**
- `employer_name`: Nome da empresa (2-200 caracteres)

**Campos Opcionais:**
- `employer_address`: Endereço (máx. 500 caracteres)
- `contact_phone`: Telefone de contato (máx. 20 caracteres)
- `contact_email`: Email de contato (formato válido)
- `contact_person`: Pessoa de contato (máx. 200 caracteres)
- `salary_range_min`: Salário mínimo (número ≥ 0)
- `salary_range_max`: Salário máximo (número ≥ 0)
- `position`: Cargo (máx. 100 caracteres)
- `department`: Departamento (máx. 100 caracteres)
- `employee_count`: Número de funcionários (inteiro ≥ 0)
- `business_type`: Tipo de negócio (Government, Private, NGO, Other)
- `registration_number`: Número de registro (máx. 100 caracteres)
- `tax_id`: ID fiscal (máx. 100 caracteres)
- `is_verified`: Status de verificação (boolean, padrão: false)
- `verification_date`: Data de verificação (formato ISO)
- `notes`: Observações (máx. 1000 caracteres)

**Resposta:**
```json
{
    "success": true,
    "message": "Empregador criado com sucesso",
    "data": {
        "employer_id": 26,
        "employer_name": "Empresa Teste API",
        // ... outros campos
    }
}
```

### **4. Atualizar Empregador**
```http
PUT /api/employers/:id
```

**Body:** Mesmo formato da criação, mas todos os campos são opcionais.

**Resposta:**
```json
{
    "success": true,
    "message": "Empregador atualizado com sucesso",
    "data": {
        "employer_id": 26,
        "employer_name": "Empresa Teste API",
        // ... campos atualizados
    }
}
```

### **5. Deletar Empregador**
```http
DELETE /api/employers/:id
```

**Restrições:**
- Apenas administradores podem deletar
- Não é possível deletar empregador com clientes vinculados

**Resposta:**
```json
{
    "success": true,
    "message": "Empregador deletado com sucesso",
    "data": {
        "employer_id": 26,
        "employer_name": "Empresa Teste API"
    }
}
```

### **6. Verificar Empregador**
```http
PUT /api/employers/:id/verify
```

**Restrições:**
- Apenas administradores podem verificar

**Resposta:**
```json
{
    "success": true,
    "message": "Empregador verificado com sucesso",
    "data": {
        "employer_id": 26,
        "is_verified": true,
        "verification_date": "2025-01-11T20:30:00.000Z"
    }
}
```

### **7. Estatísticas**
```http
GET /api/employers/stats
```

**Resposta:**
```json
{
    "success": true,
    "data": {
        "total_employers": 25,
        "verified_employers": 20,
        "government_employers": 5,
        "private_employers": 15,
        "ngo_employers": 5,
        "avg_employee_count": 450.5,
        "total_employees": 11263,
        "business_types_breakdown": [
            {
                "business_type": "Private",
                "count": 15
            },
            {
                "business_type": "Government",
                "count": 5
            },
            {
                "business_type": "NGO",
                "count": 5
            }
        ]
    }
}
```

### **8. Buscar Empregadores**
```http
GET /api/employers/search?q=termo
```

**Parâmetros:**
- `q`: Termo de busca (mín. 2 caracteres)
- `page` (opcional): Número da página
- `limit` (opcional): Itens por página

**Resposta:** Mesmo formato da listagem, com `search_term` adicional.

### **9. Empregadores por Tipo de Negócio**
```http
GET /api/employers/business-type/:businessType
```

**Parâmetros:**
- `businessType`: Government, Private, NGO, Other

**Resposta:** Mesmo formato da listagem, com `business_type` adicional.

### **10. Empregadores Verificados**
```http
GET /api/employers/verified
```

**Resposta:** Mesmo formato da listagem, apenas empregadores verificados.

### **11. Tipos de Negócio Disponíveis**
```http
GET /api/employers/business-types
```

**Resposta:**
```json
{
    "success": true,
    "data": [
        {
            "business_type": "Private",
            "count": 15
        },
        {
            "business_type": "Government",
            "count": 5
        },
        {
            "business_type": "NGO",
            "count": 5
        }
    ]
}
```

## 🔐 **Autenticação e Autorização**

### **Autenticação Obrigatória**
Todos os endpoints requerem token JWT no header:
```http
Authorization: Bearer <token>
```

### **Níveis de Acesso**
- **Usuários autenticados**: Visualizar, criar, atualizar
- **Administradores**: Deletar, verificar empregadores

## 📊 **Formato Amigável**

Use `?format=friendly` para obter dados formatados:

```json
{
    "employer_name": "Ministério da Educação",
    "is_verified": "Verificado",
    "business_type": "Government",
    "contact_email": "info@minedh.gov.mz",
    "contact_phone": "+258 21 300 000",
    "employee_count": 2500,
    "total_customers": 15,
    "active_loans": 8
}
```

## 🎯 **Validações**

### **Validações de Negócio**
- `salary_range_max` deve ser maior que `salary_range_min`
- Empregadores com clientes vinculados não podem ser deletados
- Email deve ter formato válido
- Números devem ser positivos

### **Validações de Formato**
- `employer_name`: 2-200 caracteres
- `contact_email`: Formato de email válido
- `business_type`: Valores permitidos (Government, Private, NGO, Other)
- `employee_count`: Número inteiro ≥ 0

## 📝 **Exemplos de Uso**

### **Criar Empregador Governamental**
```bash
curl -X POST http://localhost:8000/api/employers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_name": "Ministério da Saúde",
    "business_type": "Government",
    "contact_email": "info@minsaude.gov.mz",
    "employee_count": 3000,
    "is_verified": true
  }'
```

### **Buscar Empregadores Privados**
```bash
curl -X GET "http://localhost:8000/api/employers/business-type/Private" \
  -H "Authorization: Bearer <token>"
```

### **Verificar Empregador**
```bash
curl -X PUT http://localhost:8000/api/employers/1/verify \
  -H "Authorization: Bearer <token>"
```

## 🚀 **Testes**

Execute o script de teste:
```bash
node test-employers-api.js
```

## 📈 **Campos Calculados**

Cada empregador inclui campos calculados:
- `total_customers`: Número de clientes vinculados
- `active_loans`: Número de empréstimos ativos dos clientes

## 🔄 **Relacionamentos**

- **Customers**: Um empregador pode ter muitos clientes
- **Loans**: Através dos clientes, um empregador pode ter empréstimos associados

---

**📅 Última Atualização**: 2025-01-11  
**👨‍💻 Desenvolvido por**: Sistema de Microcrédito  
**🔧 Versão**: 1.0.0 (CRUD Completo)