Configuração do PDV

Ao iniciar o PDV ou ERP, consulte o endpoint de configuração para adaptar a interface ao tipo de campanha ativa na loja — antes de qualquer atendimento.

Endpoint

GET /api/v1/configuracao?cnpjLoja={cnpj}
X-Api-Key: SUA_API_KEY_AQUI

Cache local recomendado

Este endpoint retorna dados que raramente mudam. Chame-o uma única vez na inicialização e armazene o resultado em memória ou em um arquivo de configuração local. Recarregue apenas quando o PDV for reiniciado ou após alterar a campanha no painel.

Por que chamar este endpoint?

A resposta determina como o PDV deve se comportar:

Campo	O que habilitar no PDV
campanhaAtiva: false	Ocultar todo o módulo de fidelidade
tipoCampanha: "Cashback"	Exibir campo de saldo e botões de desconto
tipoCampanha: "Pontos"	Exibir pontuação acumulada e fluxo de resgate por brinde

Lojas com Cashback + Pontos simultâneos

Após a Issue #3 (deploy 2026-05-20), uma loja pode ter uma campanha Cashback e uma de Pontos ativas ao mesmo tempo. O tipoCampanha retorna apenas a de maior prioridade — habilite a UI dos dois programas quando a venda devolver beneficiosAplicados[] com duas entries. Acompanhamento em #479.

| permiteCheckoutCashbackNaVenda: true | Modelo 2 — habilitar botão "Usar cashback acumulado como desconto" | | permiteDescontoSobreGerado: true | Modelo 3 — habilitar botão "Usar desconto desta compra" (chamar /venda/preview para mostrar o valor ao cliente antes de confirmar) | | pontosMinimosParaResgate | Mostrar alerta quando cliente não atingiu o mínimo |

Exemplo de requisição

cURL

curl "$ELOFIEL_BASE_URL/api/v1/configuracao?cnpjLoja=$CNPJ_LOJA" \
  -H "X-Api-Key: $ELOFIEL_API_KEY"

JavaScript / Node.js

const { eloFielFetch, ELOFIEL_CONFIG } = require('./config/elofiel');

async function obterConfiguracao() {
  const params = new URLSearchParams({ cnpjLoja: ELOFIEL_CONFIG.cnpjLoja });
  return eloFielFetch('GET', `/api/v1/configuracao?${params}`);
}

// Uso na inicialização:
const config = await obterConfiguracao();

if (!config.campanhaAtiva) {
  console.log('Nenhuma campanha ativa. Módulo de fidelidade desabilitado.');
} else {
  console.log(`Campanha: ${config.tipoCampanha}`);
  console.log(`Checkout de cashback: ${config.permiteCheckoutCashbackNaVenda}`);
}

PHP

<?php
require_once 'config/elofiel.php';

function obterConfiguracao(): array {
    $params = http_build_query(['cnpjLoja' => CNPJ_LOJA]);
    return eloFielRequest('GET', '/api/v1/configuracao?' . $params);
}

$config = obterConfiguracao();

if (!$config['campanhaAtiva']) {
    echo "Nenhuma campanha ativa.\n";
} else {
    echo "Campanha: {$config['tipoCampanha']}\n";
    echo "Checkout cashback: " . ($config['permiteCheckoutCashbackNaVenda'] ? 'sim' : 'não') . "\n";
}

Python

from urllib.parse import urlencode
from config.elofiel import elofiel_request, CNPJ_LOJA

def obter_configuracao() -> dict:
    params = urlencode({'cnpjLoja': CNPJ_LOJA})
    return elofiel_request('GET', f'/api/v1/configuracao?{params}')

config = obter_configuracao()

if not config['campanhaAtiva']:
    print('Nenhuma campanha ativa.')
else:
    print(f"Campanha: {config['tipoCampanha']}")
    print(f"Checkout cashback: {config['permiteCheckoutCashbackNaVenda']}")

Resposta

Com campanha ativa

{
  "sucesso": true,
  "dados": {
    "cnpjLoja": "12345678000190",
    "nomeLoja": "Loja Central",
    "campanhaAtiva": true,
    "tipoCampanha": "Cashback",
    "permiteCheckoutCashbackNaVenda": true,
    "permiteDescontoSobreGerado": true,
    "pontosMinimosParaResgate": null,
    "permiteUsoParcialDePontos": null
  }
}

Sem campanha ativa

{
  "sucesso": true,
  "dados": {
    "cnpjLoja": "12345678000190",
    "nomeLoja": "Loja Central",
    "campanhaAtiva": false,
    "tipoCampanha": null,
    "permiteCheckoutCashbackNaVenda": false,
    "permiteDescontoSobreGerado": false,
    "pontosMinimosParaResgate": null,
    "permiteUsoParcialDePontos": null
  }
}

Campos da resposta (dados):

Campo	Tipo	Descrição
cnpjLoja	string	CNPJ normalizado (apenas dígitos)
nomeLoja	string	Nome da loja cadastrado no sistema
campanhaAtiva	boolean	true se há campanha configurada e ativa para a loja
tipoCampanha	string | null	"Cashback" ou "Pontos". null quando não há campanha ativa. Limitação atual (#479): retorna apenas a campanha de maior prioridade — após a Issue #3, a loja pode ter Cashback e Pontos ativos simultaneamente. Sempre itere beneficiosAplicados[] no response de POST /venda para detectar a segunda campanha.
permiteCheckoutCashbackNaVenda	boolean	Modelo 2 — true = exibir opção de usar cashback acumulado como desconto na venda. Requer campanha Cashback com regra de resgate configurada
permiteDescontoSobreGerado	boolean	Modelo 3 — true = exibir opção de usar o cashback desta venda como desconto imediato. Requer ModoCashback=Imediato e campanha tipo Cashback
pontosMinimosParaResgate	number | null	Quantidade mínima de pontos para habilitar resgate. null para campanhas Cashback
permiteUsoParcialDePontos	boolean | null	true = cliente pode resgatar quantidade parcial de pontos. null para campanhas Cashback

Erros possíveis

HTTP	Mensagem	Causa
401	—	X-Api-Key ausente ou inválida
422	"CNPJ inválido. Informe 14 dígitos."	CNPJ com quantidade incorreta de caracteres
422	"Loja não encontrada ou inativa."	CNPJ não pertence ao tenant ou loja está desativada

Exemplo de inicialização completa

O padrão recomendado para PDVs é carregar a configuração na inicialização e usar o resultado para controlar a UI:

// pdv-init.js
let pdvConfig = null;

async function inicializarPDV() {
  try {
    pdvConfig = await obterConfiguracao();
  } catch (erro) {
    console.error('Falha ao carregar configuração EloFiel:', erro.message);
    // Continuar sem módulo de fidelidade
    pdvConfig = { campanhaAtiva: false };
  }

  if (!pdvConfig.campanhaAtiva) {
    ocultarModuloFidelidade();
    return;
  }

  if (pdvConfig.tipoCampanha === 'Pontos') {
    configurarModuloPontos(pdvConfig.pontosMinimosParaResgate);
  } else {
    // Modelo 2: usar cashback acumulado como desconto
    configurarModuloCashback(pdvConfig.permiteCheckoutCashbackNaVenda);
    // Modelo 3: usar cashback desta venda como desconto imediato
    // Chamar POST /api/v1/venda/preview na tela de venda para calcular o valor
    if (pdvConfig.permiteDescontoSobreGerado) {
      habilitarBotaoDescontoGerado();
    }
  }
}