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/api/v1"
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
1	Validar autenticação e listar produtos	GET /valepix/products	product_id
2	Criar configuração de benefício	POST /valepix/benefits	benefit_id
3	Obter situações válidas	GET /valepix/employees/situations	situation
4A	Cadastrar um colaborador	POST /valepix/employees	employee_id
4B	Enviar arquivo de colaboradores	POST /valepix/employees/batch/upload	batch_id
5B	Conferir lote	GET /valepix/employees/batch/{batch_id}	Itens válidos ou com erro
6B	Confirmar lote válido	POST /valepix/employees/batch/{batch_id}/commit	Quantidade processada
7	Conferir cadastro	GET /valepix/employees	Dados cadastrados

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

1. Liste 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/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,
      "current_page": 1,
      "last_page": 1
    }
  }
}

Guarde o identificador do produto escolhido:

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

2. Crie um 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/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\",
    \"coparticipation_percentage\": 0,
    \"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/valepix/benefits?search=flex" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

3. Obtenha uma situação válida

O campo situation deve receber o valor retornado pela API, como active.

curl --request GET \
  --url "$VALEPIX_BASE_URL/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

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

curl --request POST \
  --url "$VALEPIX_BASE_URL/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/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

Use este caminho quando houver muitos colaboradores.

O arquivo CSV ou XLSX deve conter dados equivalentes ao cadastro individual:

Campo	Formato esperado
name	Nome do colaborador
document	CPF válido
birth_date	YYYY-MM-DD
phone	Telefone brasileiro válido
email	E-mail do colaborador
cbo	Código CBO
situation	Valor retornado pela rota de situações, como active
admission_date	YYYY-MM-DD

Envie o arquivo para validação:

curl --request POST \
  --url "$VALEPIX_BASE_URL/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",
    "total_records": 120,
    "status": "processed",
    "errors_count": 0,
    "detailed_errors": [],
    "error_columns": []
  }
}

Guarde o identificador do lote:

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

5B. Consulte o lote antes de confirmar

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

curl --request GET \
  --url "$VALEPIX_BASE_URL/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/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

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

curl --request POST \
  --url "$VALEPIX_BASE_URL/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,
    "errors_count": 0
  }
}

7. Confira os colaboradores cadastrados

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

curl --request GET \
  --url "$VALEPIX_BASE_URL/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 situação inválidos no arquivo	Corrigir o arquivo e reenviar, ou remover itens inválidos antes do commit

Próximas referências

• Listar produtos
• Benefícios
• Situações de colaboradores
• Criar colaborador
• Enviar lote de colaboradores