Validação de CPF para limites de compra por cliente em promoções relâmpago

Validar o CPF no checkout de promoções relâmpago é a única forma eficaz de aplicar limites de compra por pessoa física. Diferente da limitação por conta de e-mail — facilmente contornada com múltiplos cadastros —, o CPF é um identificador único que vincula a transação a um indivíduo real, verificado em tempo real via API da CPFHub.io em cerca de 900ms.

Introdução

Promoções relâmpago são uma ferramenta poderosa para gerar tráfego, aumentar vendas e reduzir estoque. Porém, sem controles adequados, essas campanhas atraem revendedores e oportunistas que compram em massa, esgotando os produtos antes que o público-alvo consiga aproveitá-los. A limitação por conta de usuário é facilmente contornada: basta criar múltiplas contas com e-mails diferentes.

A solução eficaz é limitar as compras por CPF. Ao validar o CPF de cada comprador via API, o sistema garante que cada pessoa física compre apenas a quantidade permitida, independentemente de quantas contas possua.

Por que limitar por conta não funciona

Limitar compras por conta (e-mail ou login) é uma medida frágil porque:

• Criação de múltiplas contas — Um mesmo indivíduo pode criar dezenas de contas com e-mails temporários em minutos.

• Compartilhamento de contas — Grupos de revendedores podem distribuir compras entre várias contas.

• Bots — Scripts automatizados criam contas e completam checkouts em segundos.

• Sem identidade real — O e-mail não vincula a compra a uma pessoa física, tornando impossível rastrear quem está comprando.

A limitação por CPF resolve esses problemas porque o CPF é um identificador único por pessoa física, vinculado a dados reais verificáveis.

Arquitetura da solução

Componentes

• Tabela de controle — Armazena o CPF, o ID da promoção e a quantidade já comprada.

• Validação de CPF via API — Confirma que o CPF informado é real antes de registrar a compra.

• Verificação de limite — Antes de processar o pedido, consulta a tabela de controle para verificar se o CPF já atingiu o limite.

Fluxo

1. O comprador inicia o checkout da promoção relâmpago.
2. O sistema solicita o CPF.
3. O CPF é validado via API da CPFHub.io.
4. O sistema verifica se o CPF já atingiu o limite para aquela promoção.
5. Se dentro do limite, o pedido é processado e o contador é incrementado.
6. Se no limite, o pedido é rejeitado com mensagem informativa.

Implementação com Python e Flask

import requests
from flask import Flask, request, jsonify
from datetime import datetime

app = Flask(__name__)

CPFHUB_API_KEY = 'SUA_CHAVE_DE_API'

# Configuracao de promocoes
promocoes = {
    'FLASH2025': {
    'nome': 'Promocao Relampago 2025',
    'limite_por_cpf': 2,
    'ativa': True,
    'inicio': '2025-03-10T08:00:00',
    'fim': '2025-03-10T23:59:59'
    }
}

# Controle de compras por CPF
controle_compras = {}

def consultar_cpf(cpf: str) -> dict:
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
    response = requests.get(url, headers=headers, timeout=10)
    return response.json()

def verificar_limite(cpf: str, promo_id: str) -> dict:
    promo = promocoes.get(promo_id)
    if not promo:
    return {'permitido': False, 'motivo': 'Promocao nao encontrada'}

    if not promo['ativa']:
    return {'permitido': False, 'motivo': 'Promocao encerrada'}

    chave = f'{cpf}:{promo_id}'
    compras_atuais = controle_compras.get(chave, 0)
    limite = promo['limite_por_cpf']

    if compras_atuais >= limite:
    return {
    'permitido': False,
    'motivo': f'Limite de {limite} unidades por CPF atingido',
    'compras_realizadas': compras_atuais,
    'limite': limite
    }

    return {
    'permitido': True,
    'compras_realizadas': compras_atuais,
    'restante': limite - compras_atuais,
    'limite': limite
    }

def registrar_compra(cpf: str, promo_id: str, quantidade: int):
    chave = f'{cpf}:{promo_id}'
    controle_compras[chave] = controle_compras.get(chave, 0) + quantidade

@app.route('/api/promocao/comprar', methods=['POST'])
def comprar_promocao():
    dados = request.json
    cpf = dados.get('cpf')
    promo_id = dados.get('promo_id')
    quantidade = dados.get('quantidade', 1)

    # 1. Validar CPF
    resultado_cpf = consultar_cpf(cpf)
    if not resultado_cpf.get('success'):
    return jsonify({
    'erro': 'CPF nao encontrado na base de dados'
    }), 400

    # 2. Verificar limite
    verificacao = verificar_limite(cpf, promo_id)
    if not verificacao['permitido']:
    return jsonify({
    'erro': verificacao['motivo'],
    'detalhes': verificacao
    }), 403

    # 3. Verificar se a quantidade solicitada excede o restante
    if quantidade > verificacao['restante']:
    return jsonify({
    'erro': f'Quantidade solicitada ({quantidade}) excede o '
    f'limite restante ({verificacao["restante"]})'
    }), 400

    # 4. Processar compra
    registrar_compra(cpf, promo_id, quantidade)

    return jsonify({
    'sucesso': True,
    'pedido': {
    'cpf': resultado_cpf['data']['cpf'],
    'titular': resultado_cpf['data']['name'],
    'promo_id': promo_id,
    'quantidade': quantidade,
    'compras_totais': controle_compras[f'{cpf}:{promo_id}'],
    'data': datetime.now().isoformat()
    }
    }), 201

if __name__ == '__main__':
    app.run(port=3000)

Cenários de uso

Black Friday

Durante a Black Friday, é comum que lojas ofereçam produtos com descontos agressivos em quantidades limitadas. Sem controle por CPF, revendedores compram todo o estoque promocional e revendem a preço de mercado. Com a validação, cada pessoa física pode comprar apenas a quantidade definida.

Lançamentos de produtos

No lançamento de produtos com demanda alta (eletrônicos, tênis de edição limitada), a limitação por CPF garante distribuição mais justa entre consumidores reais.

Promoções de supermercados online

Ofertas como "limite de 2 unidades por cliente" são facilmente contornadas sem validação de CPF. Com ela, o limite é efetivamente por pessoa física.

Desempenho em cenários de alta concorrência

Promoções relâmpago geram picos de acesso que exigem cuidados técnicos:

• Cache de validações — Armazene o resultado da validação do CPF em cache por um período curto (por exemplo, 5 minutos) para evitar consultas repetidas à API durante a mesma sessão de compra.

• Operações atômicas no controle — Utilize mecanismos de lock ou operações atômicas no banco de dados para evitar condições de corrida no incremento do contador de compras.

• Timeout adequado — Configure timeout de 10 segundos na chamada à API. Em caso de falha, decida se a compra prossegue com validação pendente ou se é bloqueada.

• Fila de processamento — Em cenários de altíssima demanda, considere processar as validações em fila, reservando o item para o comprador por um período enquanto a validação é concluída.

Consulta rápida via cURL

Para testar a validação antes da integração:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json" \
    --max-time 10

Comunicação com o cliente

A forma como o limite é comunicado impacta a experiência do usuário:

• Antes da compra — Informar claramente na página da promoção que há limite por CPF.

• No checkout — Mostrar quantas unidades o CPF ainda pode adquirir.

• Na rejeição — Exibir mensagem clara explicando que o limite foi atingido, sem revelar detalhes técnicos da validação.

• Suporte — Preparar a equipe de atendimento para explicar a política e orientar clientes com dúvidas. A Senacon recomenda que limites de compra sejam comunicados de forma clara antes do início da promoção.

Perguntas frequentes

Por que a limitação por e-mail não é suficiente para promoções relâmpago?

Porque criar múltiplas contas com e-mails temporários é trivial — qualquer pessoa pode gerar dezenas de endereços em minutos sem verificação real de identidade. O CPF, por ser único por pessoa física e vinculado a dados da Receita Federal, é o único identificador que garante o limite por indivíduo real, independentemente de quantas contas ele possua na plataforma.

Como lidar com casos em que dois CPFs diferentes tentam comprar ao mesmo tempo?

Use operações atômicas no banco de dados (como transações SQL com lock de linha ou operações INCR no Redis) para garantir que o contador de compras seja incrementado de forma consistente mesmo com requisições simultâneas. Sem esse cuidado, dois usuários podem ser aprovados ao mesmo tempo para a última unidade disponível.

A validação de CPF atrasa o checkout em promoções de alta concorrência?

A latência média da API CPFHub.io é de cerca de 900ms. Para mitigar o impacto em picos de tráfego, implemente cache de validação por sessão (reutilize o resultado por 5 minutos para o mesmo CPF), pré-valide o CPF durante o cadastro e use filas para processar as validações em paralelo com a reserva do item.

É necessário armazenar o CPF completo para controlar o limite de compras?

Não. Para fins de controle de limite, você pode armazenar um hash do CPF (SHA-256, por exemplo) em vez do número em texto claro. O hash é suficiente para identificar se o mesmo CPF já comprou, sem expor o dado original. Isso reduz o risco em caso de vazamento de banco de dados e está alinhado ao princípio de minimização de dados da LGPD.

Conclusão

A validação de CPF é a forma mais eficaz de implementar limites de compra reais por pessoa física em promoções relâmpago. Ao substituir a limitação por conta pela limitação por CPF validado, o e-commerce garante que cada indivíduo respeite o limite definido, protegendo o estoque promocional para o maior número possível de clientes.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a aplicar limites reais por pessoa física nas suas próximas promoções relâmpago.