Idrissa Banora
314 lines
10 KiB
Markdown
314 lines
10 KiB
Markdown
# 📚 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
|
|
|