Contexto de negócio
CPF é a chave natural
Cada colaborador é identificado pelo CPF dentro da unidade de negócio.
O mesmo CPF pode existir em UNs diferentes (multi-tenant), mas é
único por UN.
Soft-delete reversível
Excluir um colaborador via API é soft-delete — histórico de
batidas, ajustes e relatórios é preservado. Reversão pelo endpoint
/colaborador/{id}/recuperar enquanto não houver hard-delete pelo
backoffice.Status afeta jornadas
INATIVO, DEMITIDO e FERIAS desligam o cálculo automático de
jornada e bloqueiam novas batidas. Sua integração precisa propagar
mudanças de status do RH para evitar inconsistências.Vínculo organizacional obrigatório
Departamento e Cargo são obrigatórios na criação. Isso exige
sincronizar a estrutura organizacional antes do quadro de
colaboradores em integrações de onboarding.
Endpoints públicos
Consultas
- Listagem com filtros
- Busca por chave
- Métricas e exports
GET /colaborador — Lista paginada com filtros opcionaisCasos de uso comuns:- Sync diário do ERP (puxar todos ativos)
- Filtro por departamento para BI
- Validação se um colaborador específico existe
pagina + limite
além de query-params específicos da entidade. Veja o schema completo
no try-it.Mutações
Criar — POST /colaborador
Criar — POST /colaborador
Cria um novo colaborador na unidade de negócio do token. Departamento
e Cargo precisam existir antes —
POST /colaborador falha com
404 Not Found se referenciar IDs que não existem na UN.Para cliente que ainda não tem conta no Pontua (típico em RH
terceirizado), use POST /colaborador/externo — cria sem provisionar
login no app.Idempotência: CPF é único por UN. Antes de criar, faça
GET /colaborador/{cpf}/cpf para evitar 409. Veja
Idempotência.Atualizar — PATCH /colaborador/{id}
Atualizar — PATCH /colaborador/{id}
Padrão unificado. Aceita payload parcial com qualquer combinação
de campos: dados cadastrais, alocação (depto/cargo/CC), preferências,
foto, definições.
Mudança de status — PATCH /colaborador/{id}/status
Mudança de status — PATCH /colaborador/{id}/status
Estado válido:
ATIVO → INATIVO → DEMITIDO (caminho típico
rescisão) ou ATIVO → FERIAS → ATIVO.Mudança para DEMITIDO exige dataDemissao. Após demissão, banco
de horas residual deve ser quitado por abono ou abatimento conforme
Art. 59 da CLT — esse cálculo é feito pelo módulo de Banco de Horas,
não por este endpoint.Soft-delete reversível: dentro de prazo configurado pela UN,
PATCH /colaborador/{id}/recuperar reverte exclusão preservando
todo histórico.Importação em massa — POST /colaborador/import
Importação em massa — POST /colaborador/import
Aceita arquivo CSV com cadastros para criar em lote. Top use case
para integradores de RH — onboarding inicial ou migração de outro
sistema.Campos obrigatórios e opcionais do CSV estão documentados no schema
da operação. Linhas com erro retornam no response com identificação
da linha + motivo (CPF duplicado, departamento inexistente, etc.).Para mais de 50 colaboradores, prefira o import a múltiplas chamadas
individuais — reduz round-trips e dá relatório de erro consolidado.
Ver guia Importar em massa via CSV.
Exclusão — DELETE /colaborador/{id}
Exclusão — DELETE /colaborador/{id}
Soft-delete. Colaborador some das listagens mas histórico é
preservado. Para reverter dentro do prazo, use o endpoint
/recuperar. Após o prazo, exclusão é definitiva (necessita backoffice
para hard-delete em casos LGPD).Fluxos típicos
Sync diário com sistema externo (ERP / RH)
Movimentação de departamento/cargo
Demissão com data retroativa
Gotchas conhecidos
Endpoints expostos publicamente
| Método | Rota | Descrição |
|---|---|---|
| GET | /colaborador | Lista com filtros e paginação |
| GET | /colaborador/me | Colaborador do usuário logado (JWT user, não API key) |
| GET | /colaborador/{id} | Busca por UUID |
| GET | /colaborador/{cpf}/cpf | Busca por CPF (11 dígitos) |
| GET | /colaborador/codigo/{codigo} | Busca por código/matrícula |
| GET | /colaborador/status-count | Contagem agrupada por status |
| GET | /colaborador/birthday | Aniversariantes do dia/mês |
| GET | /colaborador/cidade | Cidades onde há colaboradores |
| GET | /colaborador/export/csv | Exportação CSV completa |
| POST | /colaborador | Cria novo colaborador |
| POST | /colaborador/externo | Cria colaborador externo (sem app) |
| POST | /colaborador/import | Importação em massa via CSV |
| PATCH | /colaborador/{id} | Update unificado (campos parciais) |
| PATCH | /colaborador/{id}/status | Ativa/inativa/demite |
| PATCH | /colaborador/{id}/recuperar | Reverte exclusão |
| DELETE | /colaborador/{id} | Soft delete |
Veja também
- Importar em massa via CSV — fluxo bulk completo
- Cadastrar primeiro colaborador — passo a passo
- Estrutura Organizacional — UN, Depto, Cargo, CC
- Multi-tenant — entender o isolamento por UN
- Idempotência — padrão de upsert com CPF