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

Deixe o cliente gerar Content-Type: multipart/form-data com o boundary. Ao usar curl, basta enviar o arquivo com --form.

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

HTTP 201 Created.

{
  "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.

Linhas inválidas não transformam o upload em erro HTTP: a rota ainda retorna 201 Created, com a quantidade de erros e os detalhes disponíveis para revisão. Quando há até 40 linhas inválidas, detailed_errors identifica cada linha; acima desse volume, error_columns resume os campos que precisam ser corrigidos.

Campos de erro detalhado:

Campo	Descrição
`line`	Número da linha no arquivo
`row_name`	Nome informado na linha
`row_document`	Documento informado na linha
`errors`	Lista dos nomes dos campos inválidos na 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`	Opcional
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 vazio, ilegível ou em formato não aceito	Corrigir o arquivo enviado
`401`	Token ausente, inválido, expirado ou revogado	Conferir token
`403`	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
`422`	Limite operacional de cadastros em lote atingido	Aguardar a renovação do limite ou contatar a ValePix
`429`	Limite de chamadas excedido	Reduzir a frequência e aplicar backoff
`500`, `502`, `503`, `504`	Falha temporária no upload	Tentar novamente com backoff e acionar suporte se persistir

Autenticação​

Path params​

Body​

Exemplo curl​

Response​

Formato dos dados do arquivo​

Erros comuns​