sigrhapf/Documents/sigfip/sigefp/DOCUMENTACAO_API.md

📚 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

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

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

Resposta:

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

Usar o Token

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.

💰 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

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

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

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:

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