Visão Geral

Antes de integrar, é útil entender os principais conceitos da plataforma EloFiel e como eles se relacionam.

Entidades principais

Tenant

O Tenant representa a empresa contratante do EloFiel (ex.: uma rede de farmácias, uma loja de roupas). Cada tenant possui:

• Uma ou mais Lojas (identificadas por CNPJ)
• Uma X-Api-Key única para autenticação
• Configurações de campanha próprias

Loja

A Loja é a unidade física ou CNPJ de um ponto de venda do tenant. Uma mesma empresa pode ter múltiplas lojas cadastradas. O cnpjLoja é obrigatório em todas as chamadas de venda e resgate para identificar em qual estabelecimento a transação ocorreu.

Cliente

O Cliente é identificado pelo CPF dentro de um tenant. Pontos e saldos são acumulados por cliente, por tenant — ou seja, o saldo da loja A não é compartilhado com a loja B de outro tenant.

Cadastro automático

Se o CPF não existir no tenant, o cliente é criado automaticamente na primeira venda. Não há endpoint de cadastro de cliente.

Campanha

A Campanha define as regras de benefício aplicáveis às vendas. Cada campanha contém:

• Tipo de benefício: Cashback (em R$) ou Pontos
• Percentual de cashback ou pontos por real gasto
• Compra mínima: valor mínimo da venda para ativar o benefício
• Vigência: datas de início e fim
• Diferimento (opcional): prazo em dias para liberar o benefício

A primeira campanha ativa onde compraMinima <= valorVenda é selecionada (ordem de cadastro).

Lote de Crédito

Cada venda que gera benefício cria um Lote de Crédito para o cliente. O lote registra:

• Valor de cashback ou quantidade de pontos creditados
• Data de expiração
• Status atual

Ciclo de vida de um lote

              [Venda registrada]
                     |
        Itera beneficiosAplicados[]
        (issue #3: 1 ou 2 entries,
         1 Cashback + 1 Pontos máx)
                     |
        Para cada benefício aplicado:
                     |
              statusBeneficio?
              /             \
       "Disponivel"      "Pendente"
            |                 |
        Pode ser           Aguarda
        resgatado       dataLiberacao
        imediatamente         |
                              |
                       [Data liberada]
                              |
                        "Disponivel"
                              |
                       [Resgate feito]
                              |
                        "Resgatado"

  Se dataExpiracao passou sem resgate:
        "Expirado"

Status	Descrição
Pendente	Cashback diferido — aguardando dataLiberacao
Disponivel	Pode ser resgatado pelo cliente
Resgatado	Já foi utilizado como desconto
Expirado	Prazo de validade encerrado sem uso

FIFO no resgate

Quando o cliente resgata, os lotes mais antigos são consumidos primeiro (FIFO — First In, First Out), respeitando a data de expiração de cada lote. Isso é transparente para a integração: o sistema calcula automaticamente quais lotes serão debitados.

Diagrama de fluxo simplificado

PDV/ERP                          API EloFiel
   |                                   |
   |-- POST /api/v1/venda ----------->|
   |   (cpfCliente, valorVenda, ...)   |
   |                                   |-- Identifica/cria cliente
   |                                   |-- Seleciona campanha
   |                                   |-- Cria lote de crédito
   |<-- VendaResponse ----------------|
   |   (cashbackCreditado, saldo...)   |
   |                                   |
   |-- GET /api/v1/resgate/saldo ---->|
   |   (cnpjLoja, cpfCliente)          |
   |<-- ConsultaSaldoResponse ---------|
   |   (saldoCashback, saldoPendente)  |
   |                                   |
   |-- POST /api/v1/resgate ---------->|
   |   (tipoBeneficio, valorResgate)   |
   |                                   |-- Debita lotes (FIFO)
   |<-- ResgateResponse ---------------|
   |   (cashbackResgatado, saldo...)   |