Enviar lote de colaboradores

POST /api/v1/valepix/employees/batch/upload

Envia um arquivo CSV ou XLSX com colaboradores para validação antes do commit do lote.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json
Content-Type: multipart/form-data

Ao usar curl -F, deixe o curl definir o boundary do multipart/form-data.

Path params

Esta rota não possui path params.

Body

Campo	Tipo	Obrigatório	Descrição
`file`	file	Sim	Arquivo CSV ou XLSX com os colaboradores

Exemplo curl

curl --request POST \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json" \
  --form "file=@colaboradores.xlsx" \
  --url "https://routes.valepix.com.br/api/v1/valepix/employees/batch/upload"

Response

{
  "success": "success",
  "data": {
    "batch_id": "00000000-0000-4000-8000-000000000100",
    "status": "pending_review",
    "total_records": 120
  }
}

Campos como errors_count, detailed_errors e error_columns podem aparecer quando houver erros de validação.

Campos de erro detalhado:

Campo	Descrição
`row_document`	Documento informado na linha
`errors`	Lista de mensagens de validação da linha

Formato dos dados do arquivo

O arquivo deve conter dados equivalentes ao cadastro individual de colaboradores. Use datas em YYYY-MM-DD e documentos/telefones válidos. Para arquivos com datas, prefira XLSX para evitar conversão automática de datas por planilhas.

Campo lógico	Cabeçalho recomendado	Alternativas aceitas	Observação
Nome	`name`	`Nome`, `Nome Completo`	Obrigatório
CPF	`document`	`CPF`, `cpf`	Obrigatório
Data de nascimento	`birthDate`	`Data de nascimento`, `Data de nascimento (Opcional)`, `Nascimento`	Opcional, em `YYYY-MM-DD`
Telefone	`phone`	`Telefone`, `Celular`	Obrigatório
E-mail	`email`	`E-mail`, `Email`	Obrigatório
CBO	`cbo`	`CBO`, `CBO (Opcional)`	Opcional; prefira somente números no arquivo
Data de admissão	`admissionDate`	`Data de admissão`, `Data de admissão (Opcional)`, `Admissão`	Opcional, em `YYYY-MM-DD`

No cadastro em lote, os colaboradores são processados como active. Para aplicar outra situação, atualize o colaborador após o commit.

Erros comuns

HTTP	Quando acontece	Ação recomendada
`400`	Arquivo ausente, formato inválido ou dados inválidos	Corrigir arquivo enviado
`401`	Token ausente, inválido, expirado ou revogado	Conferir token
`403`	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
`500`	Erro interno temporário	Tentar novamente com backoff e acionar suporte se persistir

Autenticação​

Path params​

Body​

Exemplo curl​

Response​

Formato dos dados do arquivo​

Erros comuns​