Skip to content

Vale-compra

Consulta das definições de vale-compra configuradas na conta (regras), e não dos vales já emitidos. É a partir delas que o front calcula e exibe frases como "receba 110% do valor em vale-compra".

Operations

Obtém as definições de vale-compra da conta

Request

Retorna as regras de vale-compra configuradas na conta — até duas, identificadas pela ordem (ValeCompra1 e ValeCompra2).

⚠️ Este endpoint não lista vales já emitidos para consumidores. Ele devolve a configuração usada para calcular o vale que seria gerado.

Como interpretar

  • valorPorcentagem: percentual aplicado sobre o valor devolvido. Ex.: 110 significa que o consumidor recebe 110% do valor em vale-compra (bônus de 10% para incentivar a retenção da venda).
  • tipo: 0 = retenção (vale oferecido no lugar do estorno em dinheiro); 1 = composição da diferença a pagar pelo consumidor numa troca por item de maior valor.
  • expirarEmDias: validade do vale a partir da emissão.
  • ordem: 1 é a definição principal; 2 costuma ser a variação com bônus.

Como o front Genius usa

Na tela de escolha da forma de reembolso, o front usa valorPorcentagem para montar a comparação que o consumidor vê:

"Receber R$ 199,90 de volta no cartão" × "Receber R$ 219,89 em vale-compra (110%), válido por 90 dias"

Também alimenta o cálculo de calcular-valores-estorno-por-item, que usa essas definições para compor os valores finais.

Observações

  • Retorna 404 quando a conta não possui nenhuma definição ativa de vale-compra — nesse caso simplesmente não ofereça a opção de vale ao consumidor.
Security
BearerAuth
Query
lojaVirtualIdinteger or null, (int64)

Id da loja virtual (subconta), quando a conta opera múltiplas lojas.

curl -i -X GET \
  'https://apidocs.geniusreturns.com.br/_mock/openapi/v1/pvt/vale-compra/obter-vale-compras-do-cliente?lojaVirtualId=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Definições de vale-compra localizadas.

Bodyapplication/json
dataHoraRespostastring, (date-time)

Data e hora da resposta, em UTC.

registrosinteger, (int32)

Quantidade de registros retornados em entidade.

httpStatusstring

Código HTTP da resposta, em texto.

erroCodigostring or null

Código do erro, quando houver.

erroDescricaostring or null

Mensagem do erro, quando houver.

erroDetalhadostring or null

Detalhamento técnico do erro, quando houver.

erroTipostring or null

Classificação do erro. Útil para distinguir falha de integração com a plataforma de e-commerce (04) de erro de domínio ou erro comum (00).

entidadeobject(ValeComprasClienteModel)

Definições de vale-compra da conta. valeCompra1 é a definição principal; valeCompra2 costuma ser a variação com bônus. Qualquer uma pode vir null.

Response
{
  "dataHoraResposta": "2026-09-18T13:25:02.771Z",
  "registros": 2,
  "httpStatus": "200",
  "entidade": {
    "valeCompra1": { … },
    "valeCompra2": { … }
  }
}