Consultar Saldo

A consulta de saldo retorna o saldo atual de cashback e pontos de um cliente, discriminando o saldo disponível para resgate e o saldo ainda pendente (diferido).

Endpoint

GET /api/v1/resgate/saldo?cnpjLoja={cnpj}&cpfCliente={cpf}
X-Api-Key: SUA_API_KEY_AQUI

Quando consultar o saldo

Antes do resgate: sempre consulte o saldo antes de oferecer desconto ao cliente. Isso garante que você exiba apenas o valor disponível (saldoCashback), sem incluir o saldo pendente.

No display do PDV: ao identificar o cliente pelo CPF (ex.: ao inserir no início do atendimento), exiba o saldo disponível para engajar o cliente.

Fluxo recomendado

1. Cliente informa o CPF no início do atendimento
2. PDV consulta o saldo via GET /api/v1/resgate/saldo
3. Operador informa ao cliente o saldo disponível
4. Cliente decide se quer usar o benefício
5. Venda é finalizada (POST /api/v1/venda)
6. Se cliente quis usar o benefício: POST /api/v1/resgate

Exemplo de requisição

cURL

curl -G https://api-sandbox.elofiel.com.br/api/v1/resgate/saldo \
  -H "X-Api-Key: SUA_API_KEY_AQUI" \
  --data-urlencode "cnpjLoja=12.345.678/0001-90" \
  --data-urlencode "cpfCliente=123.456.789-09"

JavaScript

async function consultarSaldo(cnpjLoja, cpfCliente) {
  const params = new URLSearchParams({ cnpjLoja, cpfCliente });

  const response = await fetch(
    `https://api-sandbox.elofiel.com.br/api/v1/resgate/saldo?${params}`,
    {
      method: 'GET',
      headers: {
        'X-Api-Key': process.env.ELOFIEL_API_KEY,
      },
    }
  );

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

  return response.json();
}

const resultado = await consultarSaldo('12.345.678/0001-90', '123.456.789-09');
const { saldoCashback, saldoPendente } = resultado.dados;

console.log(`Disponível para resgate: R$ ${saldoCashback}`);
console.log(`Aguardando liberação: R$ ${saldoPendente}`);

PHP

<?php
function consultarSaldo(string $cnpjLoja, string $cpfCliente): array {
    $params = http_build_query([
        'cnpjLoja'   => $cnpjLoja,
        'cpfCliente' => $cpfCliente,
    ]);

    $ch = curl_init("https://api-sandbox.elofiel.com.br/api/v1/resgate/saldo?{$params}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'X-Api-Key: ' . getenv('ELOFIEL_API_KEY'),
        ],
    ]);
    $resposta = curl_exec($ch);
    curl_close($ch);
    return json_decode($resposta, true);
}

$resultado = consultarSaldo('12.345.678/0001-90', '123.456.789-09');
$dados = $resultado['dados'];

echo "Disponível: R$ {$dados['saldoCashback']}\n";
echo "Pendente: R$ {$dados['saldoPendente']}\n";

Resposta

{
  "sucesso": true,
  "dados": {
    "clienteId": "8e9f1234-abcd-4321-efgh-000000000001",
    "clienteNome": "Maria Silva",
    "saldoPontos": 150,
    "saldoCashback": 22.50,
    "saldoPendente": 5.00
  },
  "mensagem": null,
  "erros": []
}

Diferença entre saldoCashback e saldoPendente

Campo	Descrição	Pode ser resgatado?
saldoCashback	Cashback disponível (liberado)	Sim
saldoPendente	Cashback diferido ainda bloqueado	Não
saldoPontos	Pontos disponíveis para resgate	Sim

Nunca ofereça o saldo pendente como desconto

O campo saldoPendente representa benefícios que ainda não atingiram a data de liberação. Se o operador tentar resgatar esse valor, a API retornará HTTP 422 com "Saldo insuficiente para resgate.".

Exiba ao cliente apenas saldoCashback como desconto disponível.

Como exibir no display do PDV

Sugestão de texto para o display ou cupom:

PROGRAMA ELOFIEL
Olá, Maria Silva!
Cashback disponível: R$ 22,50
(+ R$ 5,00 aguardando liberação)

Tratamento de erros

HTTP	Causa	Ação recomendada
400	Parâmetro ausente	Verificar se cnpjLoja e cpfCliente foram enviados
401	X-Api-Key inválida	Verificar configuração da chave
404	Cliente não encontrado	Informar que o CPF não possui cadastro no programa

if (!resultado.sucesso) {
  // CPF não cadastrado ou outro erro — continuar o atendimento normalmente
  console.warn('Saldo não disponível:', resultado.erros[0]);
}