Cadastrar colaboradores

Este guia reúne a sequência recomendada para cadastrar colaboradores pela API ValePix sem precisar navegar por todas as páginas de referência.

Siga os passos na ordem. Ao final, você terá os identificadores necessários para criar colaboradores individualmente ou enviar um arquivo em lote.

Resultado esperado

Ao concluir o fluxo, você terá:

Dado	Origem	Uso
`product_id`	Listagem de produtos	Criar ou atualizar benefícios
`benefit_id`	Criação ou listagem de benefícios	Criar colaborador ou confirmar lote
`situation`	Listagem de situações	Informar a situação cadastral do colaborador
`employee_id`	Criação ou listagem de colaboradores	Consultar, atualizar ou remover colaborador
`batch_id`	Upload de lote	Consultar, ajustar e confirmar lote

Antes de começar

Configure a base URL e o API token entregue pela ValePix.

export VALEPIX_BASE_URL="https://routes.valepix.com.br"
export VALEPIX_API_TOKEN="<api_token>"

Todas as chamadas JSON usam estes headers:

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

Para upload de arquivo, use multipart/form-data conforme indicado no passo de lote.

Fluxo recomendado

Ordem	Objetivo	Chamada	Guarde	Documentação completa
1	Validar autenticação e listar produtos	`GET /valepix/products`	`product_id`	Listar produtos
2	Criar configuração de benefício	`POST /valepix/benefits`	`benefit_id`	Criar benefício
3	Obter situações válidas	`GET /valepix/employees/situations`	`situation`	Situações
4A	Cadastrar um colaborador	`POST /valepix/employees`	`employee_id`	Criar colaborador
4B	Enviar arquivo de colaboradores	`POST /valepix/employees/batch/upload`	`batch_id`	Enviar lote
5B	Conferir lote	`GET /valepix/employees/batch/{batch_id}`	Itens válidos ou com erro	Consultar lote
6B	Confirmar lote válido	`POST /valepix/employees/batch/{batch_id}/commit`	Quantidade processada	Confirmar lote
7	Conferir cadastro	`GET /valepix/employees`	Dados cadastrados	Listar colaboradores

Use o caminho 4A para cadastro individual e o caminho 4B a 6B para cadastro em lote.

1. Liste produtos

Guias completos deste passo: Listar produtos.

O produto define o tipo de benefício que será usado na configuração. Use o campo id retornado como product_id.

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/products?page=1&limit=10" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Resposta resumida:

{
  "success": "success",
  "data": {
    "products": [
      {
        "id": "00000000-0000-4000-8000-000000000201",
        "name": "Alimentação",
        "is_active": true
      }
    ],
    "meta": {
      "total": 1
    }
  }
}

Guarde o identificador do produto escolhido:

export PRODUCT_ID="00000000-0000-4000-8000-000000000201"

2. Crie um benefício

Guias completos deste passo: Criar benefício, Listar benefícios e Atualizar benefício.

O benefício agrupa um ou mais produtos e define os valores mensais em centavos.

Exemplo: 50000 representa R$ 500,00.

curl --request POST \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/benefits" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"Benefício Flexível\",
    \"description\": \"Configuração padrão para colaboradores elegíveis\",
    \"items\": [
      {
        \"product_id\": \"$PRODUCT_ID\",
        \"monthly_amount\": 50000
      }
    ]
  }"

Resposta esperada:

{
  "success": "success",
  "data": {
    "benefit_id": "00000000-0000-4000-8000-000000000030"
  }
}

Guarde o identificador retornado:

export BENEFIT_ID="00000000-0000-4000-8000-000000000030"

Se o benefício já existir, liste benefícios e use o campo id do item desejado.

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/benefits?search=flex" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

3. Obtenha uma situação válida

Guias completos deste passo: Situações de colaboradores.

O campo situation deve receber o valor retornado pela API. Valores aceitos: active, blocked, vacation, sick_leave, maternity_leave, dismissed.

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees/situations" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Resposta resumida:

{
  "success": "success",
  "data": {
    "situations": [
      { "label": "Ativo", "value": "active" },
      { "label": "Bloqueado", "value": "blocked" },
      { "label": "Férias", "value": "vacation" },
      { "label": "Afastado", "value": "sick_leave" },
      { "label": "Licença Maternidade", "value": "maternity_leave" },
      { "label": "Desligado", "value": "dismissed" }
    ]
  }
}

Guarde o valor escolhido:

export EMPLOYEE_SITUATION="active"

4A. Cadastre um colaborador individual

Guias completos deste passo: Criar colaborador, Buscar colaborador, Atualizar colaborador e Remover colaborador.

Use birth_date e admission_date no formato YYYY-MM-DD.

curl --request POST \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"benefit_id\": \"$BENEFIT_ID\",
    \"name\": \"Maria Exemplo Santos\",
    \"document\": \"12345678909\",
    \"email\": \"maria.exemplo@empresa.test\",
    \"phone\": \"11999999999\",
    \"birth_date\": \"1990-05-20\",
    \"cbo\": \"4110-05\",
    \"situation\": \"$EMPLOYEE_SITUATION\",
    \"admission_date\": \"2024-02-01\"
  }"

Resposta esperada:

{
  "success": "success",
  "data": {
    "employee_id": "00000000-0000-4000-8000-000000000001"
  }
}

Guarde o identificador:

export EMPLOYEE_ID="00000000-0000-4000-8000-000000000001"

Depois disso, valide o ciclo completo:

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees/$EMPLOYEE_ID" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Para alterar dados cadastrais, envie o payload completo em PUT /valepix/employees/{employee_id}. Para remover ou desativar, use DELETE /valepix/employees/{employee_id}.

4B. Cadastre colaboradores em lote

Guias completos deste passo: Enviar lote de colaboradores.

Use este caminho quando houver muitos colaboradores.

O arquivo CSV ou XLSX deve conter dados equivalentes ao cadastro individual. 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.

Envie o arquivo para validação:

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

Resposta esperada:

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

Guarde o identificador do lote:

export BATCH_ID="00000000-0000-4000-8000-000000000100"

5B. Consulte o lote antes de confirmar

Guias completos deste passo: Consultar lote e Remover itens de lote.

Confira os itens processados e corrija qualquer erro antes do commit.

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees/batch/$BATCH_ID?page=1&limit=50" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Se precisar remover itens inválidos antes de confirmar:

curl --request DELETE \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees/batch/$BATCH_ID" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "item_ids": [
      "00000000-0000-4000-8000-000000000501"
    ]
  }'

6B. Confirme o lote

Guias completos deste passo: Confirmar lote.

O commit cria os colaboradores válidos usando o benefit_id informado.

curl --request POST \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees/batch/$BATCH_ID/commit" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"benefit_id\": \"$BENEFIT_ID\"
  }"

Resposta esperada:

{
  "success": "success",
  "data": {
    "success": true,
    "processed_count": 120
  }
}

7. Confira os colaboradores cadastrados

Guias completos deste passo: Listar colaboradores.

Use a listagem para conferir os dados cadastrados e o total retornado na paginação.

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees?page=1&limit=10&situation=active" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Erros mais comuns neste fluxo

Situação	Possível causa	Como resolver
`401 Unauthorized`	Token ausente, inválido, expirado ou revogado	Conferir o header `Authorization` e solicitar novo token se necessário
`403 Forbidden`	Token sem acesso ao recurso solicitado	Confirmar a liberação com a ValePix
Produto não encontrado ao criar benefício	`product_id` incorreto	Refazer a listagem de produtos e usar o campo `id` retornado
Benefício não encontrado ao criar colaborador	`benefit_id` incorreto	Criar ou listar benefícios e usar o identificador retornado pela API
Situação inválida	Valor diferente do campo `value` retornado pela API	Refazer a consulta de situações e reenviar o valor correto
Erros no lote	CPF, telefone, data, e-mail ou cabeçalho inválidos no arquivo	Corrigir o arquivo e reenviar, ou remover itens inválidos antes do commit

Resultado esperado​

Antes de começar​

Fluxo recomendado​

1. Liste produtos​

2. Crie um benefício​

3. Obtenha uma situação válida​

4A. Cadastre um colaborador individual​

4B. Cadastre colaboradores em lote​

5B. Consulte o lote antes de confirmar​

6B. Confirme o lote​

7. Confira os colaboradores cadastrados​

Erros mais comuns neste fluxo​

Próximas referências​

Resultado esperado

Antes de começar

Fluxo recomendado

1. Liste produtos

2. Crie um benefício

3. Obtenha uma situação válida

4A. Cadastre um colaborador individual

4B. Cadastre colaboradores em lote

5B. Consulte o lote antes de confirmar

6B. Confirme o lote

7. Confira os colaboradores cadastrados

Erros mais comuns neste fluxo

Próximas referências