> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pontua.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Colaboradores

> Quadro de funcionários da unidade de negócio. Cadastro, consulta, importação em massa, controle de status e ciclo de vida (admissão, férias, demissão, recuperação).

**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

<CardGroup cols={2}>
  <Card title="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**.
  </Card>

  <Card title="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.
  </Card>

  <Card title="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.
  </Card>

  <Card title="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.
  </Card>
</CardGroup>

## Endpoints públicos

### Consultas

<Tabs>
  <Tab title="Listagem com filtros">
    `GET /colaborador` — Lista paginada com filtros opcionais

    **Casos 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.
  </Tab>

  <Tab title="Busca por chave">
    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](/conceitos/multi-tenant).
  </Tab>

  <Tab title="Métricas e exports">
    | 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          |
  </Tab>
</Tabs>

### Mutações

<AccordionGroup>
  <Accordion title="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](/conceitos/idempotencia).
  </Accordion>

  <Accordion title="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.

    <Warning>
      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.
    </Warning>
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/guias-praticas/importar-em-massa-csv).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Fluxos típicos

### Sync diário com sistema externo (ERP / RH)

```javascript theme={null}
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

```javascript theme={null}
// 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](/referencia/turnos-e-calendario).

### Demissão com data retroativa

```javascript theme={null}
// 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

<Warning title="CPF é único POR UN, não global">
  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.
</Warning>

<Warning title="Departamento/Cargo precisam existir antes">
  `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](/referencia/estrutura-organizacional))
  2. Só depois sincronizar **colaboradores**

  Inverter a ordem causa cascata de 404 nos POSTs e dificulta troubleshoot.
</Warning>

<Warning title="Mudança de status impacta cálculos pendentes">
  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](/referencia/fechamento).
</Warning>

<Warning title="Endpoints deprecated com mesma intenção">
  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.
</Warning>

<Warning title="Dados pessoais sob LGPD">
  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
</Warning>

## 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](/api-reference#tag/Colaborador).

## Veja também

* [Importar em massa via CSV](/guias-praticas/importar-em-massa-csv) — fluxo bulk completo
* [Cadastrar primeiro colaborador](/guias-praticas/primeiro-colaborador) — passo a passo
* [Estrutura Organizacional](/referencia/estrutura-organizacional) — UN, Depto, Cargo, CC
* [Multi-tenant](/conceitos/multi-tenant) — entender o isolamento por UN
* [Idempotência](/conceitos/idempotencia) — padrão de upsert com CPF