Realizar Resgate

O resgate permite que o cliente utilize o saldo acumulado (cashback ou pontos) como desconto em uma compra.

Endpoint

POST /api/v1/resgate
X-Api-Key: SUA_API_KEY_AQUI

Fluxo recomendado

Siga sempre este fluxo para garantir uma experiência consistente:

1. Consultar saldo    GET /api/v1/resgate/saldo
        |
        v
2. Exibir saldo disponível ao cliente
        |
        v
3. Cliente confirma resgate (e valor/tipo)
        |
        v
4. Aplicar desconto no total da venda no PDV
        |
        v
5. Registrar o resgate   POST /api/v1/resgate
        |
        v
6. Confirmar desconto com saldo atualizado

Registre o resgate APÓS finalizar o pagamento

O resgate debita o saldo imediatamente. Só chame POST /api/v1/resgate após o pagamento ser confirmado no caixa para evitar inconsistências em caso de cancelamento.

Exemplo de requisição

cURL

curl -X POST https://api-sandbox.elofiel.com.br/api/v1/resgate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SUA_API_KEY_AQUI" \
  -d '{
    "cnpjLoja": "12.345.678/0001-90",
    "cpfCliente": "123.456.789-09",
    "tipoBeneficio": "Cashback",
    "valorResgate": 10.00,
    "pontosResgate": null,
    "documentoExterno": "PDV-001235",
    "observacao": null
  }'

JavaScript

async function realizarResgate(dadosResgate) {
  const response = await fetch('https://api-sandbox.elofiel.com.br/api/v1/resgate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': process.env.ELOFIEL_API_KEY,
    },
    body: JSON.stringify(dadosResgate),
  });

  const resultado = await response.json();

  if (response.status === 422) {
    // Regra de negócio violada — tratar especificamente
    throw new Error(resultado.erros[0] ?? 'Resgate não permitido.');
  }

  if (!response.ok) {
    throw new Error(`Erro HTTP: ${response.status}`);
  }

  return resultado;
}

const resultado = await realizarResgate({
  cnpjLoja: '12.345.678/0001-90',
  cpfCliente: '123.456.789-09',
  tipoBeneficio: 'Cashback',
  valorResgate: 10.00,
  pontosResgate: null,
  documentoExterno: 'PDV-001235',
  observacao: null,
});

PHP

<?php
function realizarResgate(array $dados): array {
    $ch = curl_init('https://api-sandbox.elofiel.com.br/api/v1/resgate');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($dados),
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-Api-Key: ' . getenv('ELOFIEL_API_KEY'),
        ],
    ]);
    $resposta = curl_exec($ch);
    curl_close($ch);
    return json_decode($resposta, true);
}

$resultado = realizarResgate([
    'cnpjLoja'         => '12.345.678/0001-90',
    'cpfCliente'       => '123.456.789-09',
    'tipoBeneficio'    => 'Cashback',
    'valorResgate'     => 10.00,
    'pontosResgate'    => null,
    'documentoExterno' => 'PDV-001235',
    'observacao'       => null,
]);

Resposta

{
  "sucesso": true,
  "mensagem": "Resgate realizado com sucesso.",
  "dados": {
    "movimentacaoId": "7ab12345-1234-5678-9012-abcdef000001",
    "clienteId": "8e9f1234-abcd-4321-efgh-000000000001",
    "clienteNome": "Maria Silva",
    "tipoBeneficio": "Cashback",
    "pontosResgatados": 0,
    "cashbackResgatado": 10.00,
    "saldoAtual": {
      "saldoPontos": 0,
      "saldoCashback": 12.50,
      "saldoPendente": 5.00
    }
  },
  "erros": []
}

Cenários de resgate

Resgate parcial de cashback

Resgatar um valor específico (ex.: R$ 10,00 de um saldo de R$ 22,50):

{
  "tipoBeneficio": "Cashback",
  "valorResgate": 10.00,
  "pontosResgate": null
}

Resgate total de cashback

Resgatar todo o saldo disponível usando null:

{
  "tipoBeneficio": "Cashback",
  "valorResgate": null,
  "pontosResgate": null
}

Resgate parcial de pontos

Resgatar uma quantidade específica de pontos (ex.: 100 de 150):

{
  "tipoBeneficio": "Pontos",
  "valorResgate": null,
  "pontosResgate": 100
}

Resgate total de pontos

{
  "tipoBeneficio": "Pontos",
  "valorResgate": null,
  "pontosResgate": null
}

Resgate de pontos com descrição da troca

Use descricaoTroca para registrar o que foi entregue ao cliente (brinde, produto, serviço). O texto aparece no histórico do app clube.

{
  "tipoBeneficio": "Pontos",
  "valorResgate": null,
  "pontosResgate": 500,
  "descricaoTroca": "Camiseta tamanho M"
}

descricaoTroca é exclusivo de Pontos

O campo descricaoTroca é ignorado quando tipoBeneficio: "Cashback". Enviar o campo em resgates de cashback não gera erro — o valor é simplesmente descartado.

Tratamento de erros de negócio (HTTP 422)

Os erros mais comuns em resgate são violações de regra de negócio, retornados com HTTP 422:

erros[0]	Causa	Como tratar
"Saldo insuficiente para resgate."	valorResgate maior que saldoCashback	Consultar saldo atualizado e ajustar
"Cashback mínimo não atingido."	Campanha exige valor mínimo de resgate	Informar ao cliente o valor mínimo

try {
  const resultado = await realizarResgate(dados);
  // Aplicar desconto confirmado
  aplicarDesconto(resultado.dados.cashbackResgatado);
} catch (erro) {
  if (erro.message === 'Saldo insuficiente para resgate.') {
    // Atualizar saldo exibido e oferecer o valor correto
    const saldo = await consultarSaldo(cnpjLoja, cpfCliente);
    exibirSaldoAtualizado(saldo.dados.saldoCashback);
  } else {
    // Erro genérico — registrar e notificar operador
    console.error('Erro no resgate:', erro.message);
  }
}

Ordem de consumo dos lotes (FIFO)

O sistema consome os lotes mais antigos primeiro, respeitando as datas de expiração. Isso é automático e transparente — você não precisa gerenciar quais lotes serão usados.