Endpoints Clube (Consumidor)

API destinada ao desenvolvimento de aplicativos e portais para o consumidor final (portador do cartão fidelidade). Utiliza autenticação JWT Bearer — sem X-Api-Key.

URL base: https://api.elofiel.com.br

Público-alvo

Estes endpoints são para quem está construindo o app ou portal do cliente (mobile, web). Para integração PDV/ERP, consulte os Endpoints PDV/ERP.

---

Autenticação

POST /api/v1/clube/auth/solicitar-pin

Envia um PIN de 6 dígitos ao cliente por WhatsApp ou e-mail para iniciar o login.

Rate limit: 3 tentativas por minuto por IP.

Auth: Nenhuma (público).

Request

{
  "cpf": "123.456.789-09",
  "canal": "whatsapp"
}

Campo	Tipo	Obrigatório	Valores	Descrição
cpf	string	Sim	CPF com ou sem formatação	CPF do cliente
canal	string	Sim	"whatsapp" ou "email"	Canal de entrega do PIN

Response

HTTP 200 — ApiResult<ClubeSolicitarPinResponse>

{
  "sucesso": true,
  "dados": {
    "destinoMascarado": "(**) *****-5566",
    "whatsappIndisponivel": false
  },
  "mensagem": null,
  "erros": []
}

Campo	Tipo	Descrição
destinoMascarado	string	Telefone ou e-mail mascarado para exibição ao usuário
whatsappIndisponivel	bool	true se o número não está no WhatsApp — ofereça canal e-mail como alternativa

Segurança anti-enumeração

A API sempre retorna HTTP 200 mesmo que o CPF não exista, para não revelar se o CPF está cadastrado.

---

POST /api/v1/clube/auth/login

Autentica o cliente com PIN (recebido via WhatsApp/e-mail) ou com senha definida.

Rate limit: 5 tentativas por minuto por IP.

Auth: Nenhuma (público).

Request

Login com PIN

{
  "cpf": "123.456.789-09",
  "pin": "847291"
}

Login com senha

{
  "cpf": "123.456.789-09",
  "senha": "MinhaS3nha!"
}

Response

HTTP 200 — ApiResult<ClubeLoginResponse>

{
  "sucesso": true,
  "dados": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiraEm": "2026-04-30T04:00:00Z",
    "nome": "Maria Silva",
    "cpf": "123.456.789-09",
    "qrToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "mensagem": null,
  "erros": []
}

Campo	Tipo	Descrição
token	string	JWT Bearer válido por 30 dias
expiraEm	datetime	Data/hora de expiração do token (UTC)
nome	string	Nome do cliente
cpf	string	CPF do cliente
qrToken	uuid	Token do QR Code para identificação no PDV

Erros:

HTTP	Causa
400	cpf ausente ou formato inválido
401	PIN expirado, PIN inválido ou senha incorreta
422	Senha não definida (use PIN)

---

POST /api/v1/clube/auth/renovar

Renova o token JWT do cliente (janela deslizante de 30 dias).

Auth: Bearer JWT (ClubeCliente).

Request

Nenhum body. Apenas o header Authorization: Bearer {token}.

Response

HTTP 200 — ApiResult<ClubeLoginResponse> (mesma estrutura do login)

Renovação automática

Chame este endpoint quando o token estiver próximo de expirar (ex.: menos de 7 dias) para renovar a sessão sem exigir novo PIN.

---

Perfil

GET /api/v1/clube/perfil

Retorna os dados de perfil do cliente autenticado.

Auth: Bearer JWT (ClubeCliente).

Response

{
  "sucesso": true,
  "dados": {
    "clienteId": "uuid",
    "nome": "Maria Silva",
    "email": "maria@email.com",
    "telefone": "(44) 99999-0000",
    "dataUltimoLogin": "2026-03-31T00:00:00Z",
    "dataCriacao": "2026-01-15T00:00:00Z"
  }
}

---

PUT /api/v1/clube/perfil

Atualiza e-mail e/ou telefone do cliente.

Auth: Bearer JWT (ClubeCliente).

Request

{
  "email": "novo@email.com",
  "telefone": "(44) 98888-7777"
}

Ambos os campos são opcionais — envie apenas o que deseja alterar.

Response

HTTP 200 — ApiResult sem dados ("Perfil atualizado com sucesso.")

---

POST /api/v1/clube/auth/definir-senha

Define ou altera a senha do cliente.

Auth: Bearer JWT (ClubeCliente).

Request

{
  "senhaAtual": "SenhaAntiga1!",
  "novaSenha": "NovaSenha2@",
  "confirmacaoSenha": "NovaSenha2@"
}

Campo	Tipo	Obrigatório	Descrição
senhaAtual	string	Condicional	Obrigatório se já houver senha definida; omita na primeira definição
novaSenha	string	Sim	Nova senha
confirmacaoSenha	string	Sim	Deve ser igual a novaSenha

Response

HTTP 200 — ApiResult sem dados ("Senha definida com sucesso.")

---

Saldo e Histórico

GET /api/v1/clube/saldo

Retorna o saldo consolidado do cliente em todos os estabelecimentos.

Auth: Bearer JWT (ClubeCliente).

Response

{
  "sucesso": true,
  "dados": [
    {
      "lojaId": "uuid-loja",
      "lojaNome": "Farmácia Central",
      "saldoPontos": 150,
      "saldoCashback": 22.50,
      "saldoPendente": 5.00,
      "lotesAtivos": [
        {
          "id": "uuid-lote",
          "tipoBeneficio": "Cashback",
          "valorOriginal": 10.00,
          "valorDisponivel": 10.00,
          "status": "Disponivel",
          "dataLiberacao": null,
          "dataExpiracao": "2026-09-29"
        }
      ]
    }
  ]
}

O array retorna um item por loja onde o cliente tem saldo, ordenado por maior saldo disponível.

---

GET /api/v1/clube/historico

Retorna o histórico paginado de transações do cliente.

Auth: Bearer JWT (ClubeCliente).

Query parameters

Parâmetro	Tipo	Padrão	Descrição
pagina	number	1	Número da página
tamanho	number	20	Itens por página

Exemplo:

GET /api/v1/clube/historico?pagina=1&tamanho=20

Response

{
  "sucesso": true,
  "dados": {
    "paginacao": {
      "pagina": 1,
      "tamanho": 20,
      "totalRegistros": 45
    },
    "data": [
      {
        "movimentacaoId": "uuid",
        "tipo": "Credito",
        "descricao": "Cashback 5% Verão — Farmácia Central",
        "valor": 7.50,
        "data": "2026-03-31T10:30:00Z"
      }
    ]
  }
}

---

QR Code

POST /api/v1/clube/cliente/renovar-qr

Gera um novo QR Token para o cliente (invalida o anterior).

Auth: Bearer JWT (ClubeCliente).

Response

{
  "sucesso": true,
  "dados": {
    "qrToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "dataGerada": "2026-03-31T12:00:00Z"
  }
}

Campo	Tipo	Descrição
qrToken	uuid	Token único para geração do QR Code
dataGerada	datetime	Data/hora de geração

Como usar o QR Token

Gere um QR Code contendo o qrToken no app do cliente. O operador do PDV escaneia o QR para identificar o cliente sem precisar digitar o CPF. Veja o guia Identificar Cliente por QR Code para o fluxo completo.