API do Elo Forte

Como começar

1. A loja precisa ser parceira ativa do Elo Forte. Cadastro de lojas.
2. Peça a chave de API pelo sac@eloforteclube.com.br, informando a loja e o sistema. A chave é gerada por loja, começa com efk_ e é mostrada uma única vez.
3. Use o endereço base abaixo e envie e receba JSON.

https://app.eloforteclube.com.br/api

Valores em dinheiro vão sempre em centavos (inteiro). Datas no fuso de Brasília.

Autenticação

Envie a chave no cabeçalho Authorization em todas as chamadas de /parceiro:

Authorization: Bearer efk_sua_chave_aqui
Accept: application/json
Content-Type: application/json

A chave não expira. Ela para de funcionar quando o Elo Forte a revoga ou quando a loja é suspensa ou inativada. Guarde-a só no servidor, nunca no navegador ou no app do cliente.

Fluxo no caixa

1. Validar o código lido (QR, cartão ou digitado) com POST /parceiro/validar. A resposta diz se o membro tem direito e qual o desconto da loja.
2. Se valid for true, aplique o desconto na venda.
3. Registrar o valor com POST /parceiro/validacoes/{validation_id}/desconto em até 24 horas. Isso vira a economia que o membro vê no app.

Códigos aceitos

GET /parceiro/eu

Confere a chave e devolve a loja dona dela.

{
  "integration": { "name": "ERP Varejo Forte - loja centro", "key_prefix": "efk_a1B2c3" },
  "partner": {
    "name": "Ótica Visão Clara",
    "benefit": "Armação grátis na compra da lente",
    "discount_percent": 10,
    "discount_label": "10%",
    "logo": "https://app.eloforteclube.com.br/uploads/partners/otica.png",
    "initials": "OV"
  }
}

POST /parceiro/validar

Lê a carteirinha e registra a leitura. Campos:

• code (texto): o conteúdo do QR, do cartão ou o código #M-.
• source (opcional): "nfc" quando vier de um cartão por aproximação.
• serial (opcional): número do chip NFC, para cartões vinculados pelo número.

curl -X POST https://app.eloforteclube.com.br/api/parceiro/validar \
  -H "Authorization: Bearer efk_sua_chave_aqui" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"code": "#M-123"}'

{
  "valid": true,
  "reason": null,
  "validation_id": 9876,
  "method": "code",
  "method_label": "Código digitado",
  "member": {
    "code": "#M-123",
    "name": "Maria Souza",
    "city": "Maringá/PR",
    "plan": "Anual",
    "valid_until": "30/10/2027"
  },
  "benefit": "Armação grátis na compra da lente",
  "discount_percent": 10,
  "discount_label": "10%"
}

Quando o membro está sem plano ou suspenso, vem "valid": false e o motivo em reason (Sem assinatura ativa ou Conta suspensa). Código desconhecido ou QR vencido responde 404 com message.

POST /parceiro/validacoes/{validation_id}/desconto

Registra a compra e o desconto concedido. Envie um dos dois: o outro é calculado pela porcentagem da loja. Prazo: 24 horas após a validação. Pode ser enviado de novo para corrigir.

• purchase_cents: valor da compra, em centavos.
• discount_cents: valor do desconto, em centavos.

{ "purchase_cents": 15000 }

{
  "ok": true,
  "discount": "R$ 15,00",
  "message": "Desconto de R$ 15,00 na compra de R$ 150,00 registrado."
}

GET /parceiro/validacoes

Leituras de hoje da loja (todas as origens: app do caixa e integrações).

{
  "count": 12,
  "discount_total": "R$ 184,00",
  "items": [
    { "id": 9876, "time": "14:32", "member": "#M-123 · Maria", "valid": true,
      "reason": null, "method": "Código digitado", "discount": "R$ 15,00" }
  ]
}

Erros e limites

Toda resposta de erro tem o campo message, em português, que pode ser mostrado ao operador do caixa.

API pública (sem chave)

Para sites e apps que queiram mostrar a rede credenciada. Limite de 120 chamadas por minuto por IP.

• GET /publico/lojas: lojas ativas. Filtros: uf, cidade, categoria, canal (fisica ou online), q, page, por_pagina (até 48).
• GET /publico/resumo: planos, números da rede, estados/cidades e categorias com loja ativa.