Início Rápido

Bem-vindo à documentação de integração do EloFiel — a plataforma de cashback e pontos de fidelidade para PDVs e ERPs.

O que é o EloFiel?

O EloFiel é uma plataforma de fidelização que permite ao seu estabelecimento:

• Creditar cashback ou pontos automaticamente a cada venda
• Permitir que clientes resgatem o saldo acumulado como desconto
• Identificar clientes pelo CPF — sem necessidade de cadastro prévio
• Gerenciar campanhas com regras flexíveis de benefício

A integração é feita via API REST com autenticação por chave de API (X-Api-Key), compatível com qualquer linguagem ou plataforma.

Pré-requisitos

Antes de começar, você precisa de:

Item	Descrição
X-Api-Key	Chave de integração fornecida pelo EloFiel ao ativar sua conta
CNPJ da loja	CNPJ do estabelecimento cadastrado na plataforma
Ambiente de teste	URL base: https://api-sandbox.elofiel.com.br

Obtendo sua chave de API

Entre em contato com a equipe EloFiel para receber sua X-Api-Key de sandbox. Ela é vinculada ao seu tenant (empresa) e identifica todas as requisições.

Exemplo completo em 5 minutos

Vamos registrar uma venda de R$ 150,00 para a cliente Maria Silva (CPF: 123.456.789-09) e ver o cashback sendo creditado.

Passo 1 — Registrar a venda

cURL

curl -X POST https://api-sandbox.elofiel.com.br/api/v1/venda \
  -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",
    "valorVenda": 150.00,
    "documentoExterno": "PDV-001234",
    "observacao": null
  }'

JavaScript (fetch)

const response = await fetch('https://api-sandbox.elofiel.com.br/api/v1/venda', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'SUA_API_KEY_AQUI',
  },
  body: JSON.stringify({
    cnpjLoja: '12.345.678/0001-90',
    cpfCliente: '123.456.789-09',
    valorVenda: 150.00,
    documentoExterno: 'PDV-001234',
    observacao: null,
  }),
});

const resultado = await response.json();
console.log(resultado);

PHP (curl)

<?php
$dados = [
    'cnpjLoja'         => '12.345.678/0001-90',
    'cpfCliente'       => '123.456.789-09',
    'valorVenda'       => 150.00,
    'documentoExterno' => 'PDV-001234',
    'observacao'       => null,
];

$ch = curl_init('https://api-sandbox.elofiel.com.br/api/v1/venda');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($dados));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Api-Key: SUA_API_KEY_AQUI',
]);

$resposta = curl_exec($ch);
curl_close($ch);

$resultado = json_decode($resposta, true);
print_r($resultado);

Passo 2 — Interpretar a resposta

{
  "sucesso": true,
  "mensagem": "Venda registrada com sucesso.",
  "dados": {
    "vendaId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "clienteId": "8e9f1234-abcd-4321-efgh-000000000001",
    "clienteNome": "Maria Silva",
    "valorVenda": 150.00,
    "beneficiosAplicados": [
      {
        "movimentacaoId": "aaaaaaaa-1111-2222-3333-444444444444",
        "campanhaDescricao": "Cashback 5% Verão",
        "tipoBeneficio": "Cashback",
        "pontosCreditados": 0,
        "cashbackCreditado": 7.50,
        "statusBeneficio": "Disponivel",
        "dataLiberacao": null,
        "dataExpiracao": "2026-09-29"
      }
    ],
    "pontosCreditados": 0,
    "cashbackCreditado": 7.50,
    "saldoAtual": {
      "saldoPontos": 0,
      "saldoCashback": 22.50,
      "saldoPendente": 0.00
    }
  },
  "erros": []
}

Os campos mais importantes para exibir ao operador do PDV:

• cashbackCreditado (raiz): total creditado nesta venda — agregado da lista (R$ 7,50)
• beneficiosAplicados[]: 1 ou 2 itens, dependendo de quantas campanhas se aplicaram (máx. 1 Cashback + 1 Pontos por loja — issue #3)
• beneficiosAplicados[].statusBeneficio: "Disponivel" significa que já pode ser resgatado
• saldoAtual.saldoCashback: saldo total disponível da cliente (R$ 22,50)

Cliente novo cadastrado automaticamente

Se o CPF informado não existir na plataforma, o cliente é criado automaticamente. Não é necessário nenhum cadastro prévio.

Próximos passos

• Entender os Conceitos — Tenant, Loja, Campanha, ciclo de vida dos lotes
• Guia: Consultar Saldo — Como verificar o saldo antes do resgate
• Guia: Realizar Resgate — Aplicar desconto com cashback ou pontos
• Fluxo Completo de PDV — Integração de ponta a ponta