> ## 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.

# Cadastrar primeiro colaborador via API

> Como cadastrar 1 colaborador novo na sua unidade de negócio via POST /colaborador. Use a referência interativa para ver o schema exato do body.

Este guia mostra o **fluxo geral** de cadastro de um colaborador via API.
Para o **schema exato** do payload (quais campos são obrigatórios, tipos,
formatos), consulte a [Referência da API](/api-reference#tag/Colaborador/operation/POST-colaborador)
com try-it interativo.

## Pré-requisitos

* ✅ Token de API gerado (ver [Quick Start](/quick-start))
* ✅ Pelo menos **um departamento** e **um cargo** já cadastrados na sua UN
* ✅ CPF do colaborador
* ✅ Data de admissão

## Passo 1 — Descobrir IDs de departamento e cargo

Para cadastrar colaborador você precisa do **UUID** do departamento e do
cargo. Liste e escolha:

```bash theme={null}
# Lista departamentos
curl -s https://api.pontua.com.br/departamentos \
  -H "Authorization: Bearer $TOKEN"

# Lista cargos
curl -s https://api.pontua.com.br/cargos \
  -H "Authorization: Bearer $TOKEN"
```

Anote os IDs dos que vai usar.

## Passo 2 — Verificar se o CPF já existe (idempotência)

Antes de criar, confirme que **não há colaborador com esse CPF**. Se há,
você quer **atualizar** em vez de criar:

```bash theme={null}
curl -s -o /dev/null -w "%{http_code}\n" \
  https://api.pontua.com.br/colaborador/98765432100/cpf \
  -H "Authorization: Bearer $TOKEN"
```

* `200` → já existe, use `PATCH /colaborador/{id}` para atualizar
* `404` → não existe, prossiga com criação

## Passo 3 — Cadastrar via POST

Faça o `POST /colaborador` com o body conforme schema da Referência. Os
campos exatos podem mudar com o tempo — sempre confira a versão atual no
try-it.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pontua.com.br/colaborador \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @colaborador.json
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.pontua.com.br/colaborador', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PONTUA_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(novoColaborador),
  })

  if (!response.ok) {
    const erro = await response.json()
    throw new Error(`${erro.service}.${erro.method}: ${erro.message}`)
  }

  const colaboradorCriado = await response.json()
  console.log(`Criado:`, colaboradorCriado)
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.post(
      'https://api.pontua.com.br/colaborador',
      json=novo_colaborador,
      headers={'Authorization': f"Bearer {os.environ['PONTUA_API_TOKEN']}"},
      timeout=30,
  )
  resp.raise_for_status()
  print(f"Criado: {resp.json()}")
  ```
</CodeGroup>

A resposta `201 Created` traz o objeto colaborador completo, incluindo
o `id` UUID gerado. Guarde esse `id` — você vai precisar dele para
qualquer atualização ou referência futura.

## Passo 4 — Validar no dashboard

Abra o [dashboard Pontua](https://oi.pontua.com.br) → **Gestão de Pessoas
→ Colaboradores** e procure pelo CPF. A nova pessoa deve aparecer.

## Troubleshooting comum

### `400 Bad Request` — validação de schema

```json theme={null}
{
  "service": "ValidationPipe",
  "method": "transform",
  "message": ["nome should not be empty", "..."]
}
```

→ Revise os campos contra a [Referência](/api-reference#tag/Colaborador/operation/POST-colaborador).
Cheque tipos (string vs number), formato de data (ISO 8601), e que
campos obrigatórios estão preenchidos.

### `401 Token inválido` ou `Token expirado`

→ Cheque que o header `Authorization: Bearer <token>` está sendo enviado
corretamente. Se o token expirou, gere um novo no dashboard. Detalhes em
[Autenticação](/conceitos/autenticacao).

### `404 Not Found` — departamento/cargo não encontrado

→ O ID que você usou pode estar em **outra unidade de negócio**
(lembre [multi-tenant](/conceitos/multi-tenant)). Liste novamente do
endpoint correto e use os IDs daquela UN.

### `500 Internal Server Error`

→ Geralmente transitório. Retente com [backoff](/conceitos/idempotencia#backoff-exponencial-em-retries).
Se persistir, abra chamado em `tecnologia@pontua.com.br` com:

* `service` + `method` + `message`
* Timestamp da primeira ocorrência
* Payload exato que estava sendo enviado

## Próximos passos

<CardGroup cols={2}>
  <Card title="Sync em massa via CSV" icon="file-csv" href="/api-reference#tag/Colaborador">
    `POST /colaborador/import` para mais de 50 colaboradores de uma vez
  </Card>

  <Card title="Atualizar colaborador" icon="user-pen" href="/referencia/colaboradores">
    `PATCH /colaborador/{id}` para mudanças unitárias (padrão unificado)
  </Card>
</CardGroup>