Modelo de Dados

Documentação dos campos utilizados nas requisições e respostas da API EloFiel.

Envelope padrão

Todos os endpoints retornam o mesmo envelope ApiResult<T>:

{
  "sucesso": true,
  "dados": { ... },
  "mensagem": "Mensagem descritiva.",
  "erros": []
}

Campo	Tipo	Descrição
sucesso	bool	true se a operação foi bem-sucedida
dados	T (objeto)	Payload da resposta; null em caso de erro
mensagem	string	Mensagem descritiva do resultado; pode ser null
erros	string[]	Lista de erros de validação ou negócio; vazio em sucesso

---

Venda — VendaPdvRequest

Campos do body para POST /api/v1/venda:

Campo	Tipo	Obrigatório	Formato aceito	Descrição
cnpjLoja	string	Sim	"12.345.678/0001-90" ou "12345678000190"	CNPJ do estabelecimento
cpfCliente	string	Sim	"123.456.789-09" ou "12345678909"	CPF do cliente
valorVenda	number	Sim	Decimal positivo	Valor total da venda em R$
documentoExterno	string	Não	Texto livre (máx. 100 chars)	Identificador do PDV/ERP para rastreio
observacao	string	Não	Texto livre	Observação livre; null é aceito
usarCashbackDisponivel	boolean	Não	true / false (padrão false)	Se true e a campanha permitir (permiteCheckoutCashbackNaVenda: true), aplica o saldo de cashback disponível como desconto na própria venda. O novo cashback é calculado sobre o valor líquido. Ignorado se campanha for Diferido.
cliente	ClienteAutoRequest	Não	—	Dados para auto-cadastro (se CPF não existir)

Sub-objeto cliente (opcional):

Campo	Tipo	Obrigatório	Descrição
cliente.nome	string	Sim (se cliente presente)	Nome completo
cliente.email	string	Não	E-mail do cliente
cliente.telefone	string	Não	Telefone do cliente

CPF e CNPJ com ou sem formatação

A API aceita CPF e CNPJ formatados ("123.456.789-09") ou apenas com dígitos ("12345678909"). Ambas as formas são equivalentes em todos os endpoints.

Venda — VendaResponse (campo dados)

Campo	Tipo	Descrição
vendaId	uuid	ID agrupador da venda (issue #3). Compartilhado por todas as movimentações em beneficiosAplicados[]; usado pelo cancelamento bulk
clienteId	uuid	ID do cliente na plataforma
clienteNome	string	Nome do cliente (se cadastrado)
valorVenda	number	Valor bruto da venda registrado
cashbackUsado	number	Cashback do saldo anterior aplicado como desconto nesta venda. 0 quando usarCashbackDisponivel não foi usado ou campanha não permite
valorFinal	number	Valor líquido pago pelo cliente (valorVenda - cashbackUsado)
beneficiosAplicados	BeneficioAplicado[]	1 a 2 benefícios aplicados (máx. 1 Cashback + 1 Pontos por loja — issue #3)
pontosCreditados	number	Agregado — soma dos pontos creditados em todas as campanhas
cashbackCreditado	number	Agregado — soma do cashback creditado em todas as campanhas
saldoAtual	SaldoResponse	Saldo atualizado do cliente após a venda

Elemento de beneficiosAplicados[]:

Campo	Tipo	Descrição
movimentacaoId	uuid	ID único da movimentação gerada por esta campanha
campanhaId	uuid	ID da campanha
campanhaDescricao	string	Nome da campanha
tipoBeneficio	string	"Cashback" ou "Pontos"
pontosCreditados	number	Pontos por esta campanha (0 se Cashback)
cashbackCreditado	number	Cashback em R$ por esta campanha (0 se Pontos)
statusBeneficio	string	"Disponivel" ou "Pendente"
dataLiberacao	date | null	Data de liberação do cashback diferido
dataExpiracao	date | null	Data de expiração do lote

---

Saldo — ConsultaSaldoResponse (campo dados)

Resposta de GET /api/v1/resgate/saldo:

Campo	Tipo	Descrição
clienteId	uuid	ID do cliente
clienteNome	string	Nome do cliente
saldoPontos	number	Total de pontos disponíveis para resgate
saldoCashback	number	Total de cashback em R$ disponível para resgate
saldoPendente	number	Cashback diferido ainda bloqueado (não disponível)
lotesAtivos	LoteResponse[]	Detalhamento dos lotes ativos de crédito

Saldo pendente não pode ser resgatado

saldoPendente representa cashback que ainda não atingiu a data de liberação. Não inclua esse valor na oferta de desconto ao cliente — ele não será aceito em um resgate.

---

Resgate — ResgatePdvRequest

Campos do body para POST /api/v1/resgate:

Campo	Tipo	Obrigatório	Valores aceitos	Descrição
cnpjLoja	string	Sim	CNPJ formatado ou limpo	CNPJ do estabelecimento
cpfCliente	string	Sim	CPF formatado ou limpo	CPF do cliente
tipoBeneficio	string	Sim	"Cashback" ou "Pontos"	Tipo de benefício a resgatar
valorResgate	number | null	Condicional	Decimal positivo	Valor em R$ a resgatar (apenas para Cashback). null = resgatar tudo disponível
pontosResgate	number | null	Condicional	Inteiro positivo	Quantidade de pontos a resgatar (apenas para Pontos). null = resgatar tudo disponível
documentoExterno	string	Não	Texto livre (máx. 100 chars)	Identificador do PDV/ERP
observacao	string	Não	Texto livre (máx. 500 chars)	Observação livre
descricaoTroca	string	Não	Texto livre (máx. 200 chars)	Descrição do brinde/produto entregue. Somente para tipoBeneficio: "Pontos" — exibido no histórico do app clube

Resgate — ResgateResponse (campo dados)

Campo	Tipo	Descrição
movimentacaoId	uuid	ID único da movimentação de resgate
clienteId	uuid	ID do cliente
clienteNome	string	Nome do cliente
tipoBeneficio	string	"Cashback" ou "Pontos"
pontosResgatados	number	Quantidade de pontos resgatados (0 se Cashback)
cashbackResgatado	number	Valor em R$ resgatado (0 se Pontos)
saldoAtual	SaldoResponse	Saldo atualizado após o resgate

---

SaldoResponse (sub-objeto)

Retornado como saldoAtual em VendaResponse e ResgateResponse:

Campo	Tipo	Descrição
saldoPontos	number	Pontos disponíveis
saldoCashback	number	Cashback em R$ disponível
saldoPendente	number	Cashback diferido bloqueado

---

---

Cadastro de Cliente — CadastrarClientePdvRequest

Campos do body para POST /api/v1/cliente:

Campo	Tipo	Obrigatório	Formato aceito	Descrição
cpf	string	Sim	Com ou sem formatação	CPF do cliente (11-14 chars)
nome	string	Sim	Texto livre	Nome completo (mín. 2, máx. 150 chars)
email	string	Sim	E-mail válido	E-mail (máx. 150 chars). Enviar "" quando não disponível
telefone	string	Sim	Texto livre	Telefone (máx. 20 chars). Enviar "" quando não disponível
dataNascimento	string	Não	"YYYY-MM-DD"	Data de nascimento. Omitir quando não disponível
aceiteLgpd	boolean	Sim	true	Consentimento LGPD. Deve ser true

email e telefone são obrigatórios

Mesmo que o cliente não forneça esses dados, os campos devem ser enviados como string vazia "". Eles são usados para notificações de cashback e pontos e não podem ser null.

Cadastro de Cliente — CadastrarClienteResponse (campo dados)

Campo	Tipo	Descrição
clienteId	uuid	ID do cliente no EloFiel
cpf	string	CPF normalizado (apenas dígitos)
nome	string	Nome do cliente
email	string	E-mail do cliente
telefone	string	Telefone normalizado (apenas dígitos)
jaExistia	boolean	true se o CPF já estava cadastrado (dados não foram alterados)

---

Configuração — ConfiguracaoResponse (campo dados)

Resposta de GET /api/v1/configuracao:

Campo	Tipo	Descrição
cnpjLoja	string	CNPJ normalizado (apenas dígitos)
nomeLoja	string	Nome da loja
campanhaAtiva	boolean	true se há campanha ativa para a loja
tipoCampanha	string | null	"Cashback" ou "Pontos". null quando sem campanha
permiteCheckoutCashbackNaVenda	boolean	true = exibir opção de usar cashback como desconto na venda
pontosMinimosParaResgate	number | null	Mínimo de pontos para resgate (apenas campanhas Pontos)
permiteUsoParcialDePontos	boolean | null	true = resgate parcial permitido (apenas campanhas Pontos)

---

Formatos de data

Todas as datas retornadas pela API seguem o formato ISO 8601:

• Data: "2026-09-29" (YYYY-MM-DD)
• Data/hora: "2026-03-30T12:00:00Z" (UTC)