Colaboradores

As rotas de colaboradores permitem cadastrar, consultar, atualizar, remover ou processar colaboradores em lote na integração autorizada. Para preencher benefit_id, use as rotas de Benefícios. Para criar um benefício antes do cadastro, obtenha o product_id em Listar produtos.

Base path:

/api/v1/valepix/employees

Modelo de colaborador

Um colaborador retornado pela API pode conter:

Campo	Tipo	Descrição
id	string	Identificador do colaborador
name	string	Nome do colaborador
document	string	CPF do colaborador
email	string	E-mail do colaborador
phone	string	Telefone do colaborador
birth_date	string	Timestamp ISO retornado pela API, quando cadastrado
benefit	object	Benefício vinculado ao colaborador
cbo	string	Código CBO
situation	string	Situação cadastral
admission_date	string	Timestamp ISO retornado pela API, quando cadastrado
status	string	Status operacional retornado pela API
has_account	boolean	Indica se o colaborador já possui conta ativada

Objeto benefit:

Campo	Tipo	Descrição
id	string	Identificador do benefício
name	string	Nome do benefício
description	string	Descrição do benefício

Benefício e situação

• benefit_id deve ser obtido pela API de benefícios. Use o benefit_id retornado em Criar benefício ou o id retornado em Listar benefícios.
• situation deve usar o campo value retornado por Situações de colaboradores.

Valores de situação atualmente retornados pela API:

Value	Label
active	Ativo
blocked	Bloqueado
vacation	Férias
sick_leave	Afastado
maternity_leave	Licença Maternidade
dismissed	Desligado

Rotas disponíveis

Operação	Método	Rota
Listar situações	GET	/api/v1/valepix/employees/situations
Listar	GET	/api/v1/valepix/employees
Contar	GET	/api/v1/valepix/employees/count
Criar	POST	/api/v1/valepix/employees
Buscar por ID	GET	/api/v1/valepix/employees/{employee_id}
Atualizar	PUT	/api/v1/valepix/employees/{employee_id}
Remover ou desativar	DELETE	/api/v1/valepix/employees/{employee_id}
Enviar lote	POST	/api/v1/valepix/employees/batch/upload
Consultar lote	GET	/api/v1/valepix/employees/batch/{batch_id}
Remover itens de lote	DELETE	/api/v1/valepix/employees/batch/{batch_id}
Confirmar lote	POST	/api/v1/valepix/employees/batch/{batch_id}/commit

Todas as rotas exigem um API token ativo.

Datas

Envie datas de colaborador somente no formato:

YYYY-MM-DD

Exemplos válidos:

{
  "birth_date": "1990-05-20",
  "admission_date": "2024-02-01"
}

Não envie timestamp ISO completo, como 1990-05-20T00:00:00.000Z.

Paginação

Rotas de listagem aceitam page e limit.

curl --request GET \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json" \
  --url "https://routes.valepix.com.br/api/v1/valepix/employees?page=1&limit=10"

Metadados de paginação:

{
  "meta": {
    "total": 25,
    "current_page": 1,
    "last_page": 3,
    "limit": 10
  }
}

Envelope de resposta

Em caso de sucesso, as respostas seguem o padrão:

{
  "success": "success",
  "data": {}
}

Em erros de validação, autenticação ou autorização, consulte Erros.