Colaboradores

Colaborador é a entidade central do Pontua — representa cada pessoa cuja jornada é registrada na plataforma. Toda batida de ponto, registro de frequência, banco de horas e relatório de folha está vinculado a um colaborador. Sincronizar o quadro de funcionários é tipicamente a primeira integração que clientes fazem ao adotar a API: manter o cadastro do ERP/RH em paridade com o Pontua para que jornadas sejam atribuídas corretamente.

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

A listagem aceita os filtros padrão de paginação pagina + limite além de query-params específicos da entidade. Veja o schema completo no try-it.

Quando você já tem o identificador, use a busca direta — mais barata que listar e filtrar:

Endpoint	Quando usar
`GET /colaborador/{id}`	Você tem o UUID interno do Pontua
`GET /colaborador/{cpf}/cpf`	Você tem o CPF (sem máscara, 11 dígitos)
`GET /colaborador/codigo/{codigo}`	Você tem o código/matrícula da empresa
`GET /colaborador/me`	Apenas em fluxos com JWT de usuário (não API key)

404 Not Found em qualquer dessas rotas pode significar ID válido em outra UN — cheque Multi-tenant.

Endpoint	Resultado
`GET /colaborador/status-count`	Contagem agrupada por status (ATIVO/INATIVO/DEMITIDO/FERIAS)
`GET /colaborador/export/csv`	CSV com todos os colaboradores da UN
`GET /colaborador/birthday`	Aniversariantes do mês/dia (uso interno típico)
`GET /colaborador/cidade`	Cidades distintas onde há colaboradores cadastrados

Mutações

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}

Padrão unificado. Aceita payload parcial com qualquer combinação de campos: dados cadastrais, alocação (depto/cargo/CC), preferências, foto, definições.

Existem rotas legacy PATCH /colaborador/{id}/dados, PATCH /colaborador/{id}/alocacao, PATCH /colaborador/{id}/acesso, etc. — todas marcadas como deprecated. Sua integração nova deve usar exclusivamente o PATCH /colaborador/{id} unificado.

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

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}

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)

async function syncDiarioColaboradores(token, dadosErp) {
  for (const dadoErp of dadosErp) {
    // 1. Tenta buscar por CPF (chave natural)
    const buscaResp = await fetch(
      `https://api.pontua.com.br/colaborador/${dadoErp.cpf}/cpf`,
      { headers: { Authorization: `Bearer ${token}` } },
    )

    if (buscaResp.ok) {
      // 2a. Já existe — atualiza apenas campos mutáveis
      const { id } = await buscaResp.json()
      await fetch(`https://api.pontua.com.br/colaborador/${id}`, {
        method: 'PATCH',
        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          departamentoId: dadoErp.departamentoId,
          cargoId: dadoErp.cargoId,
          centroCustoId: dadoErp.centroCustoId,
          // demais campos do PATCH unificado...
        }),
      })
    } else if (buscaResp.status === 404) {
      // 2b. Não existe — cria
      await fetch('https://api.pontua.com.br/colaborador', {
        method: 'POST',
        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        body: JSON.stringify(dadoErp),
      })
    }
  }
}

Movimentação de departamento/cargo

// Ex: promoção interna — muda cargo e centro de custo
await fetch(`https://api.pontua.com.br/colaborador/${colaboradorId}`, {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    cargoId: novoCargoId,
    centroCustoId: novoCentroCustoId,
  }),
})

A jornada esperada do colaborador pode mudar se o novo cargo tem turno diferente — verifique Turnos e Calendário.

Demissão com data retroativa

// CUIDADO: demissão retroativa pode invalidar fechamentos do período
await fetch(`https://api.pontua.com.br/colaborador/${colaboradorId}/status`, {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    status: 'DEMITIDO',
    dataDemissao: '2026-04-15',
  }),
})

// Após demissão, gerar relatório de banco de horas residual:
await fetch('https://api.pontua.com.br/relatorio/banco-horas', {
  method: 'POST',
  headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    colaboradorIds: [colaboradorId],
    dataInicio: '2026-04-01',
    dataFim: '2026-04-15',
    formato: 'PDF',
  }),
})

Gotchas conhecidos

Você não consegue cadastrar dois colaboradores com o mesmo CPF na mesma UN — retorna 409 Conflict. Mas o mesmo CPF em UNs diferentes é permitido (cada UN tem sua base isolada). Em integrações multi-tenant (ex.: contador atendendo múltiplas empresas), trate isso no seu modelo de dados.

POST /colaborador rejeita IDs de departamento/cargo que não existem na UN do token. Em sync de quadro completo, faça primeiro:

Sincronizar departamentos e cargos (ver Estrutura Organizacional)
Só depois sincronizar colaboradores

Inverter a ordem causa cascata de 404 nos POSTs e dificulta troubleshoot.

Mudar para INATIVO ou DEMITIDO durante o mês corrente trava cálculos de frequência do colaborador da data em diante. Banco de horas acumulado fica congelado até quitação manual ou via folha.Sempre verifique se o período fechado cobre a data de mudança antes de aplicar — ver Fechamento.

Múltiplas rotas de subperfil legacy (/acesso, /definicoes, /preferencia, /alocacao, /complemento, /dados, /foto) permanecem retornando 200 OK por compatibilidade, mas estão marcadas deprecated: true no spec OpenAPI. Use o PATCH /colaborador/{id} unificado.

Cadastro contém dados sensíveis (CPF, RG, endereço, foto). Sua integração deve:

Trafegar somente o necessário (não puxe export/csv se só precisa de IDs)
Não logar payloads completos em sistemas com retenção longa
Respeitar consentimento — colaborador pode pedir remoção via Art. 18 LGPD

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

Schema completo + try-it interativo em Referência da API.

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

Começando

Conceitos

Guias práticas

Referência por recurso

Contexto de negócio

CPF é a chave natural

Soft-delete reversível

Status afeta jornadas

Vínculo organizacional obrigatório

Endpoints públicos

Consultas

Mutações

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

Veja também

​Contexto de negócio

CPF é a chave natural

Soft-delete reversível

Status afeta jornadas

Vínculo organizacional obrigatório

​Endpoints públicos

​Consultas

​Mutações

​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

​Veja também

Contexto de negócio

Endpoints públicos

Consultas

Mutações

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

Veja também