Pular para o conteúdo principal

Changelog

Histórico de versões da API EloFiel e desta documentação.

v1.6.0 — 2026-05-20 — Categoria de Benefício (issue #3)​

⚠️ Breaking — VendaResponse substituiu campos singulares por beneficiosAplicados[]​

A partir desta versão, cada loja pode operar com até 1 campanha de Cashback + 1 de Pontos simultaneamente. A venda passa a aplicar TODAS as campanhas elegíveis, retornando uma lista de benefícios em vez de um único.

Removidos do VendaResponse (dados):

  • movimentacaoId (singular) → use beneficiosAplicados[].movimentacaoId ou o novo vendaId agregador
  • campanhaDescricao → beneficiosAplicados[].campanhaDescricao
  • tipoBeneficio → beneficiosAplicados[].tipoBeneficio
  • statusBeneficio → beneficiosAplicados[].statusBeneficio
  • dataLiberacao → beneficiosAplicados[].dataLiberacao
  • dataExpiracao → beneficiosAplicados[].dataExpiracao

Adicionados:

  • vendaId — UUID agrupador da venda (compartilhado por todas as movimentações geradas)
  • beneficiosAplicados[] — lista com 1 ou 2 elementos, cada um com os 9 campos do benefício
  • pontosCreditados/cashbackCreditado continuam como agregados (soma da lista)

API — Novas funcionalidades​

  • Validação RF-1/RF-2: criar uma 2ª campanha ativa do mesmo Tipo para a mesma loja retorna 422 com mensagem "Já existe uma campanha de cashback/pontos ativa nesta loja…"
  • Cancelamento bulk forçado: POST /api/v1/venda/cancelar agora cancela TODAS as movimentações da venda (agrupadas por vendaId), em vez de apenas uma. UX previsível
  • Novos eventos de notificação: CashbackEPontosCreditados (imediato) e CashbackPendenteEPontosCreditados (diferido) — venda com 2 benefícios envia 1 única notificação consolidada
  • Métrica OTel elofiel_venda_movimentacoes_count: histograma que indica quantos benefícios cada venda gerou (1 ou 2). Use no Grafana para detectar regressão de stacking

Documentação​

  • Atualizado: Endpoints PDV — novo formato do VendaResponse
  • Atualizado: Registrar Venda — cenários com 1 ou 2 benefícios
  • Atualizado: Fluxo Completo — código JS itera sobre lista
  • Atualizado: Modelo de Dados — tabela do VendaResponse e novo BeneficioAplicado
  • Atualizado: Exemplos de Código — snippets JS, PHP, Python iterando sobre beneficiosAplicados[]
  • Atualizado: Regras de Campanhas — seção 1 reescrita com Categoria de Benefício, RF-1/RF-2 e DP-1
  • Atualizado: Arquitetura de Cancelamento — adendo DP-3 (bulk forçado)
  • SDK Delphi (exemplos-integracoes/delphi/) — TResultadoVenda refatorado para TArray<TBeneficioAplicado>

Como migrar​

  1. Substituir leituras dados.movimentacaoId por dados.vendaId (ou iterar beneficiosAplicados[] se precisar do ID de cada movimentação)
  2. Substituir dados.campanhaDescricao / dados.tipoBeneficio / dados.statusBeneficio / dados.dataLiberacao / dados.dataExpiracao por iteração sobre dados.beneficiosAplicados[]
  3. dados.pontosCreditados e dados.cashbackCreditado continuam funcionando — agora como agregados da lista
  4. Quem usa o SDK Delphi: pull do repo exemplos-integracoes/delphi/ traz a versão nova

v1.5.0 — 2026-04-01​

API — Novas funcionalidades​

  • Modelo 3 — Desconto sobre cashback gerado (usarCashbackGerado): campo boolean opcional em POST /api/v1/venda. Quando true, o cashback que a venda geraria é aplicado como desconto imediato em vez de ser creditado ao saldo. Requer permiteDescontoSobreCashbackGerado: true na campanha (configurado pelo admin)
  • Novo endpoint POST /api/v1/venda/preview: simula o Modelo 3 sem gravar nada. Retorna permiteAplicarDesconto, motivoBloqueio, cashbackGeradoPrevisto, valorComDesconto e cashbackSobreDesconto. Chamar antes de oferecer o desconto ao cliente para exibir os valores exatos
  • Campo descontoGerado na resposta de POST /api/v1/venda: valor do cashback desta venda aplicado como desconto (Modelo 3). Separado de cashbackUsado (Modelo 2)
  • Campo permiteDescontoSobreGerado em GET /api/v1/configuracao: indica se o Modelo 3 está habilitado para a loja. Usar na inicialização do PDV para exibir ou ocultar o botão de desconto imediato
  • Exclusividade mútua entre Modelos 2 e 3: enviar usarCashbackDisponivel: true e usarCashbackGerado: true simultaneamente retorna 422
  • Modelo 3 funciona na primeira compra: ao combinar usarCashbackGerado: true com o objeto cliente no body, o auto-cadastro e o desconto imediato ocorrem na mesma chamada atômica

Documentação​

  • Novo guia: Cenário 6 — Modelo 3 — fluxo completo com preview e venda
  • Atualizado: Registrar Venda — tabela de campos com usarCashbackGerado, aviso de exclusividade mútua, tabela de resposta com descontoGerado
  • Atualizado: Configuração do PDV — campo permiteDescontoSobreGerado na tabela e nos exemplos JSON
  • Atualizado: Fluxo Completo de PDV — tabela comparativa com os 3 modelos, diagrama de sequência do Modelo 3, exemplos de código em JavaScript e PHP
  • Atualizado: Endpoints PDV — seção POST /api/v1/venda/preview completa com request/response; campo permiteDescontoSobreGerado em GET /api/v1/configuracao
  • Atualizado: Regras de Campanhas — nova seção 6.3 documentando permiteDescontoSobreCashbackGerado e o cálculo do Modelo 3
  • Atualizado: Guia de Integração PDV/ERP (docs/integracao-pdv-erp.md) — seção 4.1, preview endpoint, Fluxo 5 e tabela comparativa final

v1.4.0 — 2026-04-01​

API — Novas funcionalidades​

  • Novo endpoint GET /api/v1/configuracao: retorna o resumo da campanha ativa para a loja — tipo (Cashback ou Pontos), permissão de checkout de cashback na venda e configurações de resgate de pontos. Chamar na inicialização do PDV/ERP para adaptar a UI
  • POST /api/v1/resgate — campo descricaoTroca: campo opcional (máx. 200 chars) para registrar o brinde ou produto entregue ao cliente no resgate de pontos. Exibido no histórico do app clube. Ignorado para Cashback
  • POST /api/v1/cliente — email e telefone obrigatórios: os campos passaram de opcionais para obrigatórios (enviar "" quando o cliente não informar). Usados para notificações via WhatsApp e e-mail

Documentação​

  • Novo guia: Configuração do PDV — GET /api/v1/configuracao com exemplos em 4 linguagens
  • Novo guia: Cadastrar Cliente — POST /api/v1/cliente com idempotência e regras LGPD
  • Atualizado: POST /api/v1/resgate — campo descricaoTroca em todos os guias e referências
  • Atualizado: POST /api/v1/cliente — email e telefone marcados como obrigatórios
  • Atualizado: Modelo de Dados — novos tipos CadastrarClientePdvRequest, CadastrarClienteResponse e ConfiguracaoResponse
  • Atualizado: Coleção Postman — templates para GET /configuracao e POST /cliente
  • Documentado: Checkout Integrado (usarCashbackDisponivel) — campo POST /api/v1/venda que permite aplicar o saldo de cashback como desconto na própria venda, em uma única chamada atômica. Campos cashbackUsado e valorFinal adicionados à documentação da resposta. Guia Fluxo Completo atualizado com diagrama e exemplos do Modelo 2

v1.3.0 — 2026-03-31​

API — Novas funcionalidades​

  • Auto-cadastro de cliente na venda (POST /api/v1/venda): campo opcional cliente com nome, email e telefone para registrar o cliente na mesma chamada da primeira venda
  • API Clube (consumidor): endpoints de login por PIN (WhatsApp/e-mail), saldo, histórico, perfil e QR Code — base para apps de fidelidade para o consumidor final
  • QR Code: cliente gera QR via POST /api/v1/clube/cliente/renovar-qr; operador identifica via GET /api/v1/admin/cliente/identificar?qr={token}
  • Lotes ativos detalhados: GET /api/v1/resgate/saldo agora retorna array lotesAtivos com detalhamento por lote (status, validade, valor disponível)

Documentação​

  • Novo guia: Identificar Cliente por QR Code
  • Novo guia: Integração Clube (App do Consumidor)
  • Nova referência: Endpoints Clube (Consumidor)
  • Atualizado: VendaPdvRequest com campo cliente em todos os guias e referências
  • Atualizado: ConsultaSaldoResponse com lotesAtivos

v1.2.0 — 2026-03-31​

API​

  • Integração PDV Delphi XE3: exemplo completo disponível em exemplos-integracoes/delphi/
  • Mini CRM interno: leads do formulário de contato captados automaticamente (backoffice interno, não exposto na API pública)

v1.1.0 — 2026-03-29​

  • OpenAPI spec completa disponível em /openapi/elofiel-v1.yaml
  • Swagger UI interativo disponível em /api

v1.0.0 — 2026-03-29​

Lançamento inicial da API EloFiel e da documentação de integração para desenvolvedores.

API​

  • Endpoint POST /api/v1/venda — registro de venda com crédito automático de cashback ou pontos
  • Endpoint GET /api/v1/resgate/saldo — consulta de saldo do cliente
  • Endpoint POST /api/v1/resgate — resgate de cashback ou pontos como desconto
  • Endpoint POST /api/v1/authadmin/login — autenticação do painel administrativo
  • Suporte a cashback imediato (statusBeneficio: "Disponivel") e diferido ("Pendente")
  • Criação automática de cliente na primeira venda por CPF
  • Aceitação de CPF e CNPJ com ou sem formatação
  • Resgate FIFO (lotes mais antigos consumidos primeiro)
  • Envelope de resposta padronizado ApiResult<T> em todos os endpoints
  • Rate limiting no login admin: 5 tentativas por minuto por IP

Documentação​

  • Quick Start com exemplos em cURL, JavaScript e PHP
  • Guias de integração: registrar venda, consultar saldo, realizar resgate, fluxo completo
  • Referência completa dos endpoints PDV/ERP e admin
  • Documentação de códigos de erro e rate limiting
  • Exemplos de código em cURL, JavaScript/Node.js, PHP e Python
  • Instruções de configuração no Postman