# Validação de CPF para limites de compra por cliente em promoções relâmpago > Saiba como usar validação de CPF via API para aplicar limites de compra por cliente em promoções relâmpago e evitar abusos no e-commerce. **Publicado:** 10/03/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/validacao-de-cpf-para-limites-de-compra-por-cliente-em-promocoes-relampago --- 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 ```python 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: ```bash 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](https://www.gov.br/mj/pt-br/assuntos/seus-direitos/consumidor) 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. ### Leia também - [Como evitar chargebacks usando validação de CPF no checkout](https://cpfhub.io/blog/como-evitar-chargebacks-usando-validacao-de-cpf-no-checkout) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) --- ## 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](https://www.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.