# 📚 Documentação da API SIGEFP

## 🌐 Acesso ao Swagger UI

Após iniciar a aplicação, acesse a documentação interativa do Swagger:

- **Swagger UI**: http://localhost:8081/swagger-ui.html
- **OpenAPI JSON**: http://localhost:8081/api-docs
- **OpenAPI YAML**: http://localhost:8081/api-docs.yaml

## 🔐 Autenticação

A API utiliza autenticação JWT (JSON Web Token). Para acessar os endpoints protegidos:

1. **Fazer login** em `/api/auth/login` para obter o token
2. **Incluir o token** no header `Authorization: Bearer {token}` em todas as requisições

### Exemplo de Login

```bash
POST /api/auth/login
Content-Type: application/json

{
  "username": "usuario",
  "password": "senha"
}
```

**Resposta:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "type": "Bearer",
  "username": "usuario",
  "fullName": "Nome Completo",
  "email": "usuario@example.com",
  "roles": ["ADMIN", "USER"]
}
```

### Usar o Token

```bash
GET /api/admin/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## 📋 Endpoints Principais

### 🔑 Autenticação (`/api/auth`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| POST | `/api/auth/login` | Autenticar usuário | Não |
| POST | `/api/auth/refresh` | Renovar tokens | Não |
| POST | `/api/auth/logout` | Logout | Não |

### 👥 Administração (`/api/admin`)

#### Usuários (`/api/admin/users`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/admin/users` | Listar usuários (paginado) | Sim |
| GET | `/api/admin/users/{id}` | Buscar usuário por ID | Sim |
| POST | `/api/admin/users` | Criar usuário | Sim |
| PUT | `/api/admin/users/{id}` | Atualizar usuário | Sim |
| POST | `/api/admin/users/{id}/roles` | Associar roles ao usuário | Sim |

#### Roles (`/api/admin/roles`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/admin/roles` | Listar roles | Sim |
| GET | `/api/admin/roles/{id}` | Buscar role por ID | Sim |
| POST | `/api/admin/roles` | Criar role | Sim |
| PUT | `/api/admin/roles/{id}` | Atualizar role | Sim |

#### Auditoria (`/api/admin/audit-logs`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/admin/audit-logs` | Listar logs de auditoria (com filtros) | Sim |

### 🏛️ Organização (`/api/org`)

#### Ministérios (`/api/org/ministries`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/org/ministries` | Listar ministérios | Sim |
| GET | `/api/org/ministries/{id}` | Buscar ministério por ID | Sim |
| POST | `/api/org/ministries` | Criar ministério | Sim |
| PUT | `/api/org/ministries/{id}` | Atualizar ministério | Sim |

#### Unidades Organizacionais (`/api/org/org-units`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/org/org-units` | Listar unidades (com filtros) | Sim |
| GET | `/api/org/org-units/{id}` | Buscar unidade por ID | Sim |
| GET | `/api/org/org-units/tree/{ministryId}` | Árvore de unidades por ministério | Sim |
| POST | `/api/org/org-units` | Criar unidade | Sim |
| PUT | `/api/org/org-units/{id}` | Atualizar unidade | Sim |

#### Posições (`/api/org/positions`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/org/positions` | Listar posições (com filtros) | Sim |
| GET | `/api/org/positions/{id}` | Buscar posição por ID | Sim |
| POST | `/api/org/positions` | Criar posição | Sim |
| PUT | `/api/org/positions/{id}` | Atualizar posição | Sim |

### 👨‍💼 Recursos Humanos (`/api/rh`)

#### Agentes (`/api/rh/agents`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/rh/agents` | Listar agentes (paginado) | Sim |
| GET | `/api/rh/agents/{id}` | Buscar agente por ID | Sim |
| POST | `/api/rh/agents` | Criar agente | Sim |
| PUT | `/api/rh/agents/{id}` | Atualizar agente | Sim |

#### Folha de Pagamento (`/api/rh`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/rh/payroll-periods` | Listar períodos de folha | Sim |
| POST | `/api/rh/payroll-periods` | Criar período de folha | Sim |
| POST | `/api/rh/payroll-runs` | Criar execução de folha | Sim |
| GET | `/api/rh/payroll-runs/{id}` | Buscar execução de folha | Sim |

#### Transparência e Vida Laboral

A partir da versão de Dezembro/2024, o histórico de agentes foi substituído por uma **Linha do Tempo de Carreira** estruturada, conforme o Decreto 12-A/94.

| Método | Endpoint | Descrição | DTO de Resposta |
|--------|----------|-----------|-----------------|
| GET | `/api/rh/agents/{id}/history` | Linha do tempo profissional | `List<CareerTimelineDTO>` |

> [!NOTE]
> Para detalhes sobre a lógica de snapshots salariais (5/6 e 1/6) e regras de promoção, consulte a [Documentação Técnica da Vida Laboral](./DOCUMENTACAO_VIDA_LABORAL.md).

### 💰 Orçamento (`/api/budget`)

#### Exercícios Fiscais (`/api/budget/fiscal-years`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/budget/fiscal-years` | Listar exercícios fiscais | Sim |
| GET | `/api/budget/fiscal-years/{id}` | Buscar exercício por ID | Sim |
| GET | `/api/budget/fiscal-years/current` | Buscar exercício atual | Sim |
| POST | `/api/budget/fiscal-years` | Criar exercício fiscal | Sim |
| POST | `/api/budget/fiscal-years/{id}/open` | Abrir exercício fiscal | Sim |
| POST | `/api/budget/fiscal-years/{id}/close` | Fechar exercício fiscal | Sim |

#### Linhas Orçamentárias (`/api/budget/lines`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/budget/lines` | Listar linhas (com filtros) | Sim |
| GET | `/api/budget/lines/{id}` | Buscar linha por ID | Sim |
| POST | `/api/budget/lines` | Criar linha orçamentária | Sim |
| PUT | `/api/budget/lines/{id}` | Atualizar linha | Sim |

#### Execução Orçamentária (`/api/budget/execution`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/budget/execution` | Listar execuções (com filtros) | Sim |
| POST | `/api/budget/execution` | Registrar execução orçamentária | Sim |

### 💳 Tesouraria (`/api/treasury`)

#### Lotes de Pagamento (`/api/treasury/payment-batches`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/treasury/payment-batches` | Listar lotes (com filtros) | Sim |
| GET | `/api/treasury/payment-batches/{id}` | Buscar lote por ID | Sim |
| POST | `/api/treasury/payment-batches` | Criar lote | Sim |
| POST | `/api/treasury/payment-batches/{id}/status` | Atualizar status do lote | Sim |

#### Ordens de Pagamento (`/api/treasury/payment-orders`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/treasury/payment-orders` | Listar ordens (com filtros) | Sim |
| GET | `/api/treasury/payment-orders/{id}` | Buscar ordem por ID | Sim |
| POST | `/api/treasury/payment-orders` | Criar ordem de pagamento | Sim |
| POST | `/api/treasury/payment-orders/{id}/status` | Atualizar status da ordem | Sim |

#### Pagamentos (`/api/treasury/payments`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/treasury/payments` | Listar pagamentos (com filtros) | Sim |
| POST | `/api/treasury/payments` | Registrar pagamento | Sim |

### 🏦 Comum (`/api/common`)

#### Bancos (`/api/common/banks`)

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| GET | `/api/common/banks` | Listar bancos (paginado) | Sim |
| GET | `/api/common/banks/{id}` | Buscar banco por ID | Sim |
| POST | `/api/common/banks` | Criar banco | Sim |
| PUT | `/api/common/banks/{id}` | Atualizar banco | Sim |

## 📦 Exemplos de Requisições

### Criar Usuário

```bash
POST /api/admin/users
Authorization: Bearer {token}
Content-Type: application/json

{
  "username": "novousuario",
  "fullName": "Novo Usuário",
  "email": "novo@example.com",
  "password": "senha123",
  "isActive": true,
  "roleIds": ["role-uuid-1", "role-uuid-2"]
}
```

### Criar Agente

```bash
POST /api/rh/agents
Authorization: Bearer {token}
Content-Type: application/json

{
  "nationalId": "12345678901",
  "fullName": "João Silva",
  "email": "joao@example.com",
  "hireDate": "2024-01-15",
  "status": "ACTIVE",
  "orgUnitId": "org-unit-uuid",
  "positionId": "position-uuid"
}
```

### Criar Período de Folha

```bash
POST /api/rh/payroll-periods
Authorization: Bearer {token}
Content-Type: application/json

{
  "year": 2024,
  "month": 12,
  "startDate": "2024-12-01",
  "endDate": "2024-12-31"
}
```

## 🔄 Refresh Token

Quando o token de acesso expirar, use o refresh token para obter novos tokens:

```bash
POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

## 📥 Exportar Coleção Postman

1. Acesse o Swagger UI: http://localhost:8081/swagger-ui.html
2. Clique em "Download" no topo da página
3. Selecione "OpenAPI 3.0 (JSON)"
4. Importe o arquivo no Postman ou Insomnia

## ⚠️ Códigos de Status HTTP

| Código | Descrição |
|--------|-----------|
| 200 | Sucesso |
| 201 | Criado com sucesso |
| 400 | Requisição inválida (validação falhou) |
| 401 | Não autenticado (token inválido ou ausente) |
| 403 | Não autorizado (sem permissão) |
| 404 | Recurso não encontrado |
| 500 | Erro interno do servidor |

## 🔒 Segurança

- Todos os endpoints (exceto `/api/auth/**` e `/actuator/**`) requerem autenticação JWT
- Tokens expiram em 24 horas
- Refresh tokens expiram em 7 dias
- Use HTTPS em produção
- Mantenha a chave secreta JWT segura

## 📝 Notas

- A paginação usa parâmetros `page` (padrão: 0) e `size` (padrão: 20)
- Ordenação usa `sortBy` e `sortDirection` (ASC/DESC)
- Datas devem estar no formato ISO 8601: `YYYY-MM-DD` ou `YYYY-MM-DDTHH:mm:ss`
- UUIDs devem estar no formato padrão UUID