sigrhapf/Documents/sigfip/sigefp/ENDPOINTS_API.md

# 📡 Endpoints da API SIGEFP

## Base URL
```
http://localhost:8080
```

---

## 🔐 ADMIN - `/api/admin`

### Users
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/admin/users` | Listar utilizadores | `page`, `size`, `sortBy`, `sortDirection` |
| `GET` | `/api/admin/users/{id}` | Buscar utilizador | `id` (UUID) |
| `POST` | `/api/admin/users` | Criar utilizador | Body: `UserAccountDTO` |
| `PUT` | `/api/admin/users/{id}` | Atualizar utilizador | `id` (UUID), Body: `UserAccountDTO` |
| `POST` | `/api/admin/users/{id}/roles` | Atribuir perfis | `id` (UUID), Body: `AssignRolesDTO` |

### Roles
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/admin/roles` | Listar perfis | `page`, `size`, `sortBy`, `sortDirection` |
| `GET` | `/api/admin/roles/{id}` | Buscar perfil | `id` (UUID) |
| `POST` | `/api/admin/roles` | Criar perfil | Body: `RoleDTO` |
| `PUT` | `/api/admin/roles/{id}` | Atualizar perfil | `id` (UUID), Body: `RoleDTO` |

### Audit Logs
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/admin/audit-logs` | Consultar logs | `userId`, `module`, `startDate`, `endDate`, `page`, `size` |

---

## 🏛️ ORG - `/api/org`

### Ministries
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/org/ministries` | Listar ministérios | `page`, `size`, `sortBy`, `sortDirection` |
| `GET` | `/api/org/ministries/{id}` | Buscar ministério | `id` (UUID) |
| `POST` | `/api/org/ministries` | Criar ministério | Body: `MinistryDTO` |
| `PUT` | `/api/org/ministries/{id}` | Atualizar ministério | `id` (UUID), Body: `MinistryDTO` |

### Org Units
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/org/org-units` | Listar unidades | `ministryId`, `parentUnitId`, `page`, `size` |
| `GET` | `/api/org/org-units/tree/{ministryId}` | Árvore de unidades | `ministryId` (UUID) |
| `GET` | `/api/org/org-units/{id}` | Buscar unidade | `id` (UUID) |
| `POST` | `/api/org/org-units` | Criar unidade | Body: `OrgUnitDTO` |
| `PUT` | `/api/org/org-units/{id}` | Atualizar unidade | `id` (UUID), Body: `OrgUnitDTO` |

### Positions
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/org/positions` | Listar posições | `orgUnitId`, `page`, `size` |
| `GET` | `/api/org/positions/{id}` | Buscar posição | `id` (UUID) |
| `POST` | `/api/org/positions` | Criar posição | Body: `PositionDTO` |
| `PUT` | `/api/org/positions/{id}` | Atualizar posição | `id` (UUID), Body: `PositionDTO` |

---

## 👥 RH - `/api/rh`

### Agents
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/rh/agents` | Listar agentes | `page`, `size`, `sortBy`, `sortDirection` |
| `GET` | `/api/rh/agents/{id}` | Buscar agente | `id` (UUID) |
| `POST` | `/api/rh/agents` | Criar agente | Body: `AgentDTO` |
| `PUT` | `/api/rh/agents/{id}` | Atualizar agente | `id` (UUID), Body: `AgentDTO` |

### Payroll
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/rh/payroll-periods` | Listar períodos | - |
| `POST` | `/api/rh/payroll-periods` | Criar período | Body: `CreatePayrollPeriodDTO` |
| `POST` | `/api/rh/payroll-runs` | Criar execução de folha | Body: `CreatePayrollRunDTO` |
| `GET` | `/api/rh/payroll-runs/{id}` | Buscar execução com itens | `id` (UUID) |

---

## 💰 BUDGET - `/api/budget`

### Fiscal Years
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/budget/fiscal-years` | Listar anos fiscais | `page`, `size`, `sortBy`, `sortDirection` |
| `GET` | `/api/budget/fiscal-years/current` | Obter exercício corrente | - |
| `GET` | `/api/budget/fiscal-years/{id}` | Buscar ano fiscal | `id` (UUID) |
| `POST` | `/api/budget/fiscal-years` | Criar exercício fiscal | Body: `FiscalYearDTO` |
| `POST` | `/api/budget/fiscal-years/{id}/open` | Abrir exercício | `id` (UUID) |
| `POST` | `/api/budget/fiscal-years/{id}/close` | Fechar exercício | `id` (UUID) |

### Budget Lines
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/budget/lines` | Listar linhas | `fiscalYearId`, `ministryId`, `orgUnitId`, `page`, `size` |
| `GET` | `/api/budget/lines/{id}` | Buscar linha (com cálculos) | `id` (UUID) |
| `POST` | `/api/budget/lines` | Criar linha | Body: `BudgetLineDTO` |
| `PUT` | `/api/budget/lines/{id}` | Atualizar linha | `id` (UUID), Body: `BudgetLineDTO` |

### Budget Execution
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/budget/execution` | Listar execuções | `budgetLineId`, `periodId`, `movementType`, `page`, `size` |
| `POST` | `/api/budget/execution` | Registrar movimento | Body: `BudgetExecutionDTO` |

---

## 💳 TREASURY - `/api/treasury`

### Payment Batches
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/treasury/payment-batches` | Listar lotes | `periodId`, `ministryId`, `status`, `page`, `size` |
| `GET` | `/api/treasury/payment-batches/{id}` | Buscar lote | `id` (UUID) |
| `POST` | `/api/treasury/payment-batches` | Criar lote | Body: `CreatePaymentBatchDTO` |
| `POST` | `/api/treasury/payment-batches/{id}/status` | Alterar status | `id` (UUID), Body: `UpdateStatusDTO` |

### Payment Orders
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/treasury/payment-orders` | Listar ordens | `batchId`, `status`, `page`, `size` |
| `GET` | `/api/treasury/payment-orders/{id}` | Buscar ordem | `id` (UUID) |
| `POST` | `/api/treasury/payment-orders` | Criar ordem | Body: `CreatePaymentOrderDTO` |
| `POST` | `/api/treasury/payment-orders/{id}/status` | Atualizar status | `id` (UUID), Body: `UpdateStatusDTO` |

### Treasury Payments
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/treasury/payments` | Consultar pagamentos | `paymentOrderId`, `status`, `page`, `size` |
| `POST` | `/api/treasury/payments` | Registrar pagamento efetivo | Body: `CreateTreasuryPaymentDTO` |

---

## 🏦 COMMON - `/api/common`

### Banks
| Método | Endpoint | Descrição | Parâmetros |
|--------|----------|-----------|------------|
| `GET` | `/api/common/banks` | Listar bancos | `page`, `size`, `sortBy`, `sortDirection` |
| `GET` | `/api/common/banks/{id}` | Buscar banco | `id` (UUID) |
| `POST` | `/api/common/banks` | Criar banco | Body: `BankDTO` |
| `PUT` | `/api/common/banks/{id}` | Atualizar banco | `id` (UUID), Body: `BankDTO` |

---

## 📊 Estatísticas

- **Total de Endpoints:** 50+
- **Módulos:** 6
- **Controllers:** 16
- **Métodos HTTP:** GET, POST, PUT

---

## 🔍 Parâmetros Comuns

### Paginação
- `page` (int, default: 0) - Número da página
- `size` (int, default: 20) - Tamanho da página
- `sortBy` (String, optional) - Campo para ordenação
- `sortDirection` (String, default: ASC) - Direção (ASC/DESC)

### Filtros de Data
- `startDate` (Instant, ISO format) - Data inicial
- `endDate` (Instant, ISO format) - Data final

---

## 📝 Exemplos de Requisição

### Criar Banco
```bash
POST /api/common/banks
Content-Type: application/json

{
  "code": "001",
  "name": "Banco do Brasil",
  "swiftCode": "BRASBRRJ"
}
```

### Criar Utilizador
```bash
POST /api/admin/users
Content-Type: application/json

{
  "username": "joao.silva",
  "fullName": "João Silva",
  "email": "joao.silva@example.com",
  "password": "senha123",
  "isActive": true
}
```

### Criar Período de Folha
```bash
POST /api/rh/payroll-periods
Content-Type: application/json

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

---

**Nota:** Todos os endpoints retornam JSON e esperam `Content-Type: application/json` nas requisições POST/PUT.