Padrão das rotas

Quase todo recurso da API — /colaborador, /cargo, /setor, /tarefa, /vaga e centenas de outros — oferece o mesmo conjunto de operações. Aprenda uma vez e use em todos.

Método	Rota	O que faz
GET	/{recurso}	Lista tudo (aceita search e active)
GET	/{recurso}/page	Lista paginada
GET	/{recurso}/count	Conta registros
GET	/{recurso}/{id}	Busca um registro
POST	/{recurso}	Cria
POST	/{recurso}/batch	Cria vários (corpo é uma lista)
PUT	/{recurso}	Atualiza (o id vai no corpo)
PUT	/{recurso}/batch	Atualiza vários
PATCH	/{recurso}	Atualiza só os campos enviados (o id vai no corpo)
DELETE	/{recurso}/{id}	Exclui (exclusão lógica)
PATCH	/{recurso}/{id}/activate	Ativa
PATCH	/{recurso}/{id}/deactivate	Desativa

Além delas, cada recurso tem as rotas próprias do seu domínio (aprovar, calcular, exportar…), todas na referência.

Paginação, busca e ordenação

GET /colaborador/page?page=0&size=50&sort=nome,asc&search=ana&active=true

Parâmetro	Significado
page	Página, começando em 0
size	Itens por página (padrão 20)
sort	campo,asc ou campo,desc; pode repetir para ordenar por mais de um campo. Campo inexistente responde 400
search	Texto livre, procurado nos campos indexados do recurso
active	true só ativos, false só inativos; ausente traz os dois

A resposta paginada:

{
  "content": [ { "id": 1043, "nome": "Ana Ribeiro" } ],
  "totalElements": 128,
  "totalPages": 3,
  "number": 0,
  "size": 50,
  "numberOfElements": 50,
  "first": true,
  "last": false,
  "empty": false
}

Para varrer um recurso inteiro, avance page até last ser true.

Criar e atualizar

• Criar e atualizar respondem 200 com o registro gravado, já com o id.

• Referências a outros registros são objetos com id, não ids soltos:

  { "nome": "Analista de RH", "departamento": { "id": 12 } }

• PUT substitui o registro; campo omitido pode ser apagado. Para mudar um ou dois campos, use PATCH, que ignora o que vier nulo.

• Campos desconhecidos são ignorados na entrada, e campos nulos são omitidos na saída. Um nome de campo escrito errado não dá erro — o valor só não é gravado. Confira o nome na referência.

Campos comuns

Todo registro traz:

Campo	Significado
id	Identificador numérico, único dentro do recurso
active	Se o registro está ativo
createdAt	Data de criação

Objetos aninhados

Para manter as respostas leves, objetos aninhados vêm até o segundo nível. Em GET /colaborador/{id}, o cargo vem completo, mas o departamento dentro do cargo pode vir só com os campos simples. Quando precisar do objeto inteiro, busque-o pela rota dele.

Exclusão

DELETE faz exclusão lógica: o registro some das listagens e das buscas, mas o histórico continua consistente (folhas, marcações e documentos que apontam para ele não quebram). Um registro com dependências que impedem a exclusão responde 409.