Criar colaborador

POST /api/v1/valepix/employees

Cria um colaborador na integração autorizada.

Autenticação

Envie um API token ativo no header Authorization.

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

Path params

Esta rota não possui path params.

Body

Campo	Tipo	Obrigatório	Descrição
benefit_id	string	Sim	Identificador retornado pela rota de benefícios
name	string	Sim	Nome do colaborador
document	string	Sim	CPF válido, preferencialmente somente números
email	string	Sim	E-mail do colaborador
phone	string	Sim	Telefone brasileiro válido, preferencialmente somente números
birth_date	string	Sim	Data de nascimento em YYYY-MM-DD
cbo	string	Sim	Código CBO
situation	string	Sim	Valor retornado no campo value da rota de situações, como active
admission_date	string	Sim	Data de admissão em YYYY-MM-DD

Antes de criar colaboradores, obtenha o benefit_id em Listar benefícios ou Criar benefício. Para criar um benefício, obtenha antes o product_id em Listar produtos. Para situation, use Situações de colaboradores.

Exemplo curl

curl --request POST \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --url "https://routes.valepix.com.br/api/v1/valepix/employees" \
  --data '{
    "benefit_id": "<benefit_id_retornado_pela_rota_de_beneficios>",
    "name": "Maria Exemplo Santos",
    "document": "<cpf_valido>",
    "email": "maria.exemplo@empresa.test",
    "phone": "<telefone_valido>",
    "birth_date": "1990-05-20",
    "cbo": "4110-05",
    "situation": "active",
    "admission_date": "2024-02-01"
  }'

Response

HTTP 201 Created.

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

Use o employee_id retornado para consultar, atualizar ou remover o colaborador.

Validações importantes

• document deve ser um CPF válido e autorizado para cadastro.
• phone deve ser um telefone brasileiro válido.
• birth_date e admission_date devem usar YYYY-MM-DD.
• benefit_id deve ser obtido pela API de benefícios.
• situation deve ser um value retornado por GET /api/v1/valepix/employees/situations.
• O token deve estar ativo e autorizado.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	Payload inválido, CPF/telefone inválido, data incorreta ou benefício inexistente	Corrigir os dados enviados
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
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