Skip to main content
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

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.

Mutações

Cria um novo colaborador na unidade de negócio do token. Departamento e Cargo precisam existir antesPOST /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.
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.
Estado válido: ATIVOINATIVODEMITIDO (caminho típico rescisão) ou ATIVOFERIASATIVO.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.
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.
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:
  1. Sincronizar departamentos e cargos (ver Estrutura Organizacional)
  2. 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étodoRotaDescrição
GET/colaboradorLista com filtros e paginação
GET/colaborador/meColaborador do usuário logado (JWT user, não API key)
GET/colaborador/{id}Busca por UUID
GET/colaborador/{cpf}/cpfBusca por CPF (11 dígitos)
GET/colaborador/codigo/{codigo}Busca por código/matrícula
GET/colaborador/status-countContagem agrupada por status
GET/colaborador/birthdayAniversariantes do dia/mês
GET/colaborador/cidadeCidades onde há colaboradores
GET/colaborador/export/csvExportação CSV completa
POST/colaboradorCria novo colaborador
POST/colaborador/externoCria colaborador externo (sem app)
POST/colaborador/importImportação em massa via CSV
PATCH/colaborador/{id}Update unificado (campos parciais)
PATCH/colaborador/{id}/statusAtiva/inativa/demite
PATCH/colaborador/{id}/recuperarReverte exclusão
DELETE/colaborador/{id}Soft delete
Schema completo + try-it interativo em Referência da API.

Veja também