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
coparticipation_percentage	number	Sim	Percentual de coparticipação
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	number	Sim	Valor mensal do item em centavos

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",
    "coparticipation_percentage": 0,
    "items": [
      {
        "product_id": "00000000-0000-4000-8000-000000000201",
        "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
400	Payload inválido, benefício duplicado, item ausente, produto inválido ou item duplicado	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