Criar benefício

POST /api/v1/valepix/benefits

Cria uma configuração de benefício para a 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
name	string	Sim	Nome do benefício
description	string	Não	Descrição do benefício
items	array	Sim	Lista de produtos e valores mensais do benefício

Objeto de items:

Campo	Tipo	Obrigatório	Descrição
product_id	string	Sim	Campo id retornado por Listar produtos
monthly_amount	integer	Não	Valor mensal do item em centavos. Se omitido, o item é criado com valor 0

Use o payload completo acima para criar benefícios de forma previsível.

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/benefits" \
  --data "{
    \"name\": \"Benefício Flexível\",
    \"description\": \"Configuração padrão para colaboradores elegíveis\",
    \"items\": [
      {
        \"product_id\": \"$PRODUCT_ID\",
        \"monthly_amount\": 50000
      }
    ]
  }"

Response

HTTP 201 Created.

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

Use o benefit_id retornado para cadastrar colaboradores, atualizar colaboradores ou confirmar lotes.

Validações importantes

• name deve ser único na integração.
• items deve conter pelo menos um item.
• Cada product_id deve aparecer apenas uma vez em items.
• Cada product_id deve existir e estar disponível em Listar produtos.
• monthly_amount deve ser enviado como número inteiro em centavos.

Erros comuns

HTTP	Quando acontece	Ação recomendada
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
404	product_id não encontrado	Usar um ID retornado por Listar produtos
422	Item ausente ou duplicado, nome já usado ou produto indisponível para a empresa	Corrigir a configuração enviada
429	Limite de chamadas excedido	Reduzir a frequência e aplicar backoff
500, 502, 503, 504	Falha temporária na criação	Tentar novamente com backoff e consultar antes de repetir