POST /colaborador/import é o caminho recomendado para criar mais de
~50 colaboradores. Reduz round-trips, dá relatório consolidado de erros
e é muito mais rápido que loop de POST individuais.
Pré-requisitos
- Token de API (Quick Start)
- Estrutura organizacional pré-cadastrada — Departamentos e Cargos precisam existir antes (ver Estrutura Organizacional)
- Arquivo CSV no formato esperado (schema na Referência)
Fluxo geral
Implementação
totalLinhas, totalImportados,
erros, etc.) está em Referência da API.
Estratégias de tratamento de erro
Estratégia 1: Re-importar só os erros
Estratégia 2: Criar individuais como fallback
Erros comuns no CSV
| Erro | Causa típica | Como corrigir |
|---|---|---|
CPF já existe na unidade | Colaborador duplicado | Usar PATCH em vez de criar, ou pular |
Departamento não encontrado | ID/nome de departamento inválido na UN | Verifica catálogo, atualiza CSV |
Cargo não encontrado | Idem departamento | Mesma correção |
CPF inválido | Formato errado, dígitos verificadores não batem | Limpar CSV: 11 dígitos sem máscara |
Data de admissão inválida | Formato fora de ISO 8601 | Padronizar yyyy-MM-dd |
Volumetria recomendada
| Volume | Caminho |
|---|---|
| 1-10 colaboradores | POST individual (mais simples) |
| 11-100 | POST /colaborador/import em uma chamada |
| 101-1000 | POST /colaborador/import em lotes de 100 |
| > 1000 | Lotes de 100 + processar à noite com backoff entre lotes |
Veja também
- Colaboradores — schema completo da entidade
- Estrutura Organizacional — pré-requisito de sync
- Cadastrar primeiro colaborador — fluxo unitário
- Idempotência — evitar duplicatas em retry