Skip to main content
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 com try-it interativo.

​
Pré-requisitos

  • ✅ Token de API gerado (ver 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: 
# 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: 
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. 
curl -X POST https://api.pontua.com.br/colaborador \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @colaborador.json
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 → Gestão de Pessoas → Colaboradores e procure pelo CPF. A nova pessoa deve aparecer.

​
Troubleshooting comum

​
400 Bad Request — validação de schema

{
  "service": "ValidationPipe",
  "method": "transform",
  "message": ["nome should not be empty", "..."]
}
→ Revise os campos contra a Referência. 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.

​
404 Not Found — departamento/cargo não encontrado

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

​
500 Internal Server Error

→ Geralmente transitório. Retente com backoff. 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

Sync em massa via CSV

POST /colaborador/import para mais de 50 colaboradores de uma vez

Atualizar colaborador

PATCH /colaborador/{id} para mudanças unitárias (padrão unificado)