Cadastrar Cliente

O EloFiel oferece duas formas de cadastrar um cliente: cadastro direto antes de qualquer venda e auto-cadastro embutido na primeira venda. Este guia cobre o cadastro direto.

Quando usar cada forma

Situação	Recomendação
Atendimento no balcão ou totem antes da compra	Cadastro direto — POST /api/v1/cliente
Registro na primeira venda (fluxo integrado)	Auto-cadastro — campo cliente no POST /api/v1/venda

Endpoint

POST /api/v1/cliente
X-Api-Key: SUA_API_KEY_AQUI

Idempotente

Se o CPF já estiver cadastrado no tenant, o endpoint retorna os dados existentes sem modificá-los e sinaliza com jaExistia: true. É seguro chamar múltiplas vezes com o mesmo CPF.

Request

Campo	Tipo	Obrigatório	Descrição
cpf	string	Sim	CPF do cliente (com ou sem formatação, 11-14 chars)
nome	string	Sim	Nome completo (mín. 2, máx. 150 chars)
email	string	Sim	E-mail válido (máx. 150 chars). Enviar "" quando o cliente não informar
telefone	string	Sim	Telefone (máx. 20 chars). Enviar "" quando o cliente não informar
dataNascimento	string	Não	Data no formato YYYY-MM-DD. Omitir quando não disponível
aceiteLgpd	boolean	Sim	Deve ser true. Recusa resulta em erro 422

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 obrigatórios no banco de dados e utilizados para envio de notificações de cashback e pontos via WhatsApp/e-mail.

LGPD

aceiteLgpd: true é obrigatório. O PDV/ERP é responsável por obter o consentimento explícito do cliente antes de chamar este endpoint. Nunca envie dados de clientes sem consentimento.

Exemplos de requisição

cURL

# Cliente com todos os dados
curl -X POST "$ELOFIEL_BASE_URL/api/v1/cliente" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ELOFIEL_API_KEY" \
  -d '{
    "cpf": "123.456.789-09",
    "nome": "Maria Silva",
    "email": "maria@email.com",
    "telefone": "(44) 99999-0000",
    "dataNascimento": "1990-05-20",
    "aceiteLgpd": true
  }'

# Cliente sem e-mail ou telefone (enviar string vazia)
curl -X POST "$ELOFIEL_BASE_URL/api/v1/cliente" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ELOFIEL_API_KEY" \
  -d '{
    "cpf": "987.654.321-00",
    "nome": "João Souza",
    "email": "",
    "telefone": "",
    "aceiteLgpd": true
  }'

JavaScript / Node.js

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

async function cadastrarCliente({ cpf, nome, email = '', telefone = '', dataNascimento = null, aceiteLgpd = true }) {
  const body = { cpf, nome, email, telefone, aceiteLgpd };
  if (dataNascimento) body.dataNascimento = dataNascimento;

  return eloFielFetch('POST', '/api/v1/cliente', body);
}

// Cliente completo:
const resultado = await cadastrarCliente({
  cpf: '123.456.789-09',
  nome: 'Maria Silva',
  email: 'maria@email.com',
  telefone: '(44) 99999-0000',
  dataNascimento: '1990-05-20',
});

if (resultado.jaExistia) {
  console.log(`Cliente já cadastrado: ${resultado.nome} (${resultado.clienteId})`);
} else {
  console.log(`Novo cliente cadastrado: ${resultado.nome} (${resultado.clienteId})`);
}

PHP

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

function cadastrarCliente(
    string $cpf,
    string $nome,
    string $email = '',
    string $telefone = '',
    ?string $dataNascimento = null,
    bool $aceiteLgpd = true
): array {
    $body = [
        'cpf'        => $cpf,
        'nome'       => $nome,
        'email'      => $email,
        'telefone'   => $telefone,
        'aceiteLgpd' => $aceiteLgpd,
    ];

    if ($dataNascimento !== null) {
        $body['dataNascimento'] = $dataNascimento;
    }

    return eloFielRequest('POST', '/api/v1/cliente', $body);
}

$resultado = cadastrarCliente('123.456.789-09', 'Maria Silva', 'maria@email.com', '44999990000');

if ($resultado['jaExistia']) {
    echo "Cliente já existia: {$resultado['nome']}\n";
} else {
    echo "Cliente cadastrado: {$resultado['clienteId']}\n";
}

Python

from config.elofiel import elofiel_request

def cadastrar_cliente(
    cpf: str,
    nome: str,
    email: str = '',
    telefone: str = '',
    data_nascimento: str = None,
    aceite_lgpd: bool = True,
) -> dict:
    body = {
        'cpf': cpf,
        'nome': nome,
        'email': email,
        'telefone': telefone,
        'aceiteLgpd': aceite_lgpd,
    }
    if data_nascimento:
        body['dataNascimento'] = data_nascimento

    return elofiel_request('POST', '/api/v1/cliente', body)

resultado = cadastrar_cliente('123.456.789-09', 'Maria Silva', email='maria@email.com')

if resultado['jaExistia']:
    print(f"Já cadastrado: {resultado['nome']}")
else:
    print(f"Novo cliente: {resultado['clienteId']}")

Respostas

HTTP 201 — Cliente novo cadastrado

{
  "sucesso": true,
  "mensagem": "Cliente cadastrado com sucesso.",
  "dados": {
    "clienteId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "cpf": "12345678909",
    "nome": "Maria Silva",
    "email": "maria@email.com",
    "telefone": "44999990000",
    "jaExistia": false
  },
  "erros": []
}

HTTP 200 — CPF já cadastrado (idempotente)

{
  "sucesso": true,
  "mensagem": "Cliente já cadastrado.",
  "dados": {
    "clienteId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "cpf": "12345678909",
    "nome": "Maria Silva",
    "email": "maria@email.com",
    "telefone": "44999990000",
    "jaExistia": true
  },
  "erros": []
}

Campos da resposta (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)

Erros específicos

HTTP	Mensagem	Causa
422	"Aceite de LGPD é obrigatório para cadastro."	aceiteLgpd: false
422	"CPF inválido. Informe 11 dígitos."	CPF com número incorreto de dígitos
400	"O campo Nome é obrigatório."	Nome vazio ou ausente