Validador de Código Promocional

Anatomia do código promocional: como Stripe, Shopify e Magento pensam em cupons

Um código promocional é uma string curta e legível que mapeia para desconto, frete grátis, brinde ou desbloqueio de feature. A implementação varia por plataforma, mas a estrutura converge: alfanumérico maiúsculo, 6 a 20 caracteres, hífens opcionais para legibilidade. Exemplos de produção: BLACKFRIDAY30 (Stripe Coupons API), SAVE10 (Shopify Discount API), WINTER24-VIP (Magento Cart Rules), ALICE-2024-X8M (WooCommerce personalizado).

Validação no input deve ser permissiva: aceite maiúscula e minúscula (normalize no servidor), retire whitespace, permita hífens. Rejeitar caracteres inválidos no campo é OK; uma mensagem amigável é melhor que falha silenciosa de regex. Esta ferramenta faz a checagem de formato de primeira linha antes do seu backend bater no banco para checar unicidade, expiração e quota por usuário.

Padrões de geração em produção

• Campanha genérica: strings curtas e brandáveis — BLACKFRIDAY, SAVE20, FREESHIP. Compartilhadas por todos, fáceis de brute-force, dependem de quota e expiração.
• Limitada no tempo: WINTER24, SPRING24, Q1-LAUNCH. Mesmo risco, mas com data de expiração.
• Por tier: VIP10, GOLD20, STUDENT15. Validadas contra o segmento do usuário no backend.
• Únicas por usuário: ALICE-2024-X8M, USR-A1B2C3. Geradas no servidor, salvas em tabela de cupons, uso único, anti-share.
• Afiliado / influencer: NOMEDOINFLUENCER10. Prefixo + porcentagem. Atribuição via UTM.

Técnicas antifraude que toda engine de cupom precisa

• Rate limit: limite tentativas por IP e por usuário — 5 códigos errados em 60 segundos é sinal vermelho.
• Data de expiração: corte rígido em UTC, não em horário local. expires_at <= NOW() -> 410 Gone.
• Usos máximos: used_count >= max_uses -> 410 Gone. Use lock de linha ou UPDATE ... WHERE used_count < max_uses atômico.
• Quota por usuário: uses_per_user = 1 evita farming de bônus de cadastro via emails fake.
• Pedido mínimo: min_subtotal_cents evita compras de R$ 0,01 que abusam frete grátis.
• Regras de empilhamento: marque explicitamente quais cupons combinam entre si; default "não empilha" para evitar fraude de desconto combinado.

Vetores comuns de ataque

• Brute force: códigos de 4 chars têm espaço de busca de 36^4 ~ 1,6 milhão e são triviais de quebrar. Use no mínimo 8 chars de entropia e rate limit.
• Coupon stacking: combinar vários descontos que nunca foram pensados para coexistir. Defenda com regras explícitas e validação no carrinho inteiro.
• Farming de cadastros: bots criam contas fake para resgatar bônus de signup. Defenda com verificação de email, fingerprint de device e CAPTCHA no resgate.
• Vazamento via agregadores: Honey, Capital One Shopping, Cuponomia, Méliuz e RetailMeNot fazem scraping e espalham códigos em horas. Mitigue com códigos personalizados, expirações curtas e quotas por usuário.
• Encadeamento de reembolso: resgata, estorna, resgata de novo. Marque uso de cupom como não reversível por padrão.

Ferramentas e bibliotecas

APIs de plataforma que abstraem boa parte do trabalho: Stripe Coupons (POST /v1/coupons), Shopify DiscountCode (Admin GraphQL), Magento Cart Rules, WooCommerce Coupons (REST). Para geração self-hosted, os pacotes npm voucher-code-generator e couponcodes emitem códigos aleatórios com pattern, charset e contagem configuráveis. Ambos suportam export CSV para campanhas de email em massa. E-commerce brasileiro — Magazine Luiza, Americanas, Mercado Livre — tem cultura de cupom pesada e usa esses geradores (ou equivalentes in-house) em escala.

Checklist de design de um cupom saudável

• 8-12 chars para códigos compartilháveis; 16-20 para códigos únicos de uso único.
• Charset A-Z 0-9; evite 0/O e 1/I/L para reduzir erro de transcrição.
• Comparação case-insensitive no servidor; usuário digita em minúscula.
• Hífens a cada 4-6 chars quando o comprimento >= 12: melhora a precisão de digitação.
• Sempre logue code_attempted e code_redeemed separados, para analytics e revisão de abuso.

FAQ

Qual o tamanho ideal de um código promocional?

8-12 caracteres para códigos de marketing compartilhados com muitos usuários (memorável), 16-20 para códigos únicos personalizados (alta entropia). Menos de 6 chars é brute-forceável; mais de 20 prejudica a precisão da digitação.

Case sensitive ou não?

Prefira case-insensitive. Usuários digitam em minúscula mesmo quando a campanha impressa está em maiúscula. Normalize para maiúscula antes de comparar com o banco.

Posso reutilizar um código já expirado?

Tecnicamente sim, mas raramente vale a pena. Códigos expirados podem ter vazado para agregadores (Honey, RetailMeNot, Méliuz). Se for reutilizar, mude pelo menos 2 caracteres para não bater nas assinaturas em cache deles.

Devo permitir hífens ou caracteres especiais?

Hífens, sim — melhoram legibilidade em material impresso. Outros especiais (!, @, %) introduzem ambiguidade de teclado entre locales e quebram paste em shell; evite.

Como me proteger contra agregadores de cupom?

Use códigos personalizados ligados ao usuário, expirações curtas (24-72 horas), quotas por usuário e monitore velocidade de resgate. Se um código é resgatado 1000+ vezes em minutos, ele foi compartilhado em massa.