Atualizar benefício

PUT /api/v1/valepix/benefits/{benefit_id}

Atualiza uma configuração de benefício da 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

Parâmetro	Tipo	Obrigatório	Descrição
benefit_id	string	Sim	Identificador do benefício retornado pela API

Body

Envie os campos escalares que devem permanecer na configuração. Uma lista items não vazia substitui integralmente os itens anteriores.

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do benefício; envie em toda atualização
description	string	Não	Descrição do benefício; se omitida, a descrição atual é removida
items	array	Não	Se omitido ou enviado como [], preserva os itens atuais; uma lista não vazia substitui integralmente os itens anteriores

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

Para substituir a configuração de forma previsível, envie name e todos os campos escalares que devem permanecer, além de uma lista items não vazia quando quiser substituir os itens. O benefit_id vem da URL.

Exemplo curl

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

Response

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

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	benefit_id em formato inválido	Conferir o identificador usado na URL
401	Token ausente, inválido, expirado ou revogado	Conferir token
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
404	Benefício ou product_id não encontrado	Conferir os IDs enviados
422	Item 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 atualização	Tentar novamente com backoff