Cupons - Detalhe, Geração em Lote e Histórico de Usos

O que é

A página de detalhes do cupom mostra tudo sobre um código promocional em um só lugar: o valor do desconto, as regras (limite de usos, valor mínimo do pedido, período de validade), as estatísticas de uso e os últimos clientes que aplicaram o código. É para onde você vai depois de clicar em Ver Detalhes em qualquer cupom da listagem, ou automaticamente depois de criar um cupom novo.

A partir dela você chega em duas telas complementares. A tela Gerar Cupons em Lote serve para criar de uma vez vários códigos de uso único com as mesmas regras de desconto - o cenário típico é distribuir um código diferente para cada influenciador, vendedor externo ou parceiro de uma campanha, sem ter que cadastrar cupom por cupom. Já o Histórico de Usos lista, com paginação, todos os pedidos que já aplicaram aquele código específico, com nome do cliente, e-mail, data e valor descontado.

Como usar

Ver os detalhes de um cupom

1. Vá em Marketing > Cupons no sidebar.
2. Clique em Ver Detalhes em qualquer cupom da lista (ou abra o dropdown de três pontinhos do cartão e escolha Visualizar).
3. No topo, o código aparece em destaque com um botão Copiar ao lado (copia para a área de transferência e mostra a confirmação "Copiado!" por 1,5 segundo) e um selo de status: Ativo, Inativo, Expirado, Agendado ou Esgotado.
4. No bloco Desconto, veja o valor e, se houver, o teto máximo de desconto. No bloco Detalhes, confira tipo do cupom, limites de uso, valor mínimo do pedido e datas de início/expiração.
5. Se o cupom já teve algum uso, o bloco Últimos Usos mostra até 20 aplicações recentes, com nome do cliente e valor descontado. Clique em Ver todos para abrir o histórico completo.
6. Na lateral direita, o bloco Estatísticas mostra o total de usos, a barra de progresso em relação ao limite (quando houver) e quantos usos ainda estão disponíveis.
7. No bloco Ações Rápidas, você encontra Duplicar Cupom, Ativar/Desativar Cupom e, quando já houve uso, Ver Histórico de Usos.

Gerar cupons em lote

1. Na listagem de cupons, clique no botão Gerar Lote (ao lado de Novo Cupom, no cabeçalho).
2. Preencha o Nome do Lote (identificação interna, ex: "Influenciadores Janeiro 2026") e a Quantidade de Cupons (de 1 até 1000).
3. Opcionalmente, informe um Prefixo de até 10 caracteres (ex: INF gera códigos como INF-XXXX-XXXX). O cartão Preview, na lateral direita, mostra 5 exemplos de código - clique em Atualizar para gerar novos exemplos.
4. Configure o Tipo de Desconto (Percentual, Valor Fixo, Por Passageiro ou Taxa Grátis), o Valor do Desconto, o teto de desconto (quando percentual) e o Valor Mínimo do Pedido. Essas regras valem igualmente para todos os códigos do lote.
5. Defina, se quiser, Data de Início e Data de Expiração, e restrinja o uso a viagens/excursões específicas em Restrições (vazio libera todas).
6. Confira o cartão Resumo e clique em Gerar N Cupons (botão verde, rodapé da lateral direita). O sistema cria todos os códigos e te leva direto para a página de detalhes do cupom-pai do lote recém-criado.

Consultar o histórico de usos

1. Na página de detalhes de um cupom que já foi usado, clique em Ver Histórico de Usos (Ações Rápidas) ou em Ver todos (bloco Últimos Usos).
2. Confira os cartões de resumo no topo: Total de Usos, Total Descontos, Desconto Médio e Disponível.
3. Use o campo Buscar por nome ou email... e o botão Filtrar para localizar um cliente específico dentro do histórico.
4. Cada linha da lista mostra o cliente, o e-mail, a data da aplicação, o pedido vinculado (quando existe, com link direto para a reserva), o valor descontado e o valor original do pedido. O ícone de olho abre o cadastro do cliente, quando ele existe na sua base.

O que você precisa saber antes

• Cupom acumula com o desconto do Clube de Assinatura. Os dois não são exclusivos: se o passageiro já tem desconto de clube aplicado, o cupom incide sobre o valor que sobrou depois do clube, não sobre o valor cheio. Ou seja, um cliente do clube pode economizar duas vezes na mesma reserva.
• Excluir o cupom-pai de um lote apaga todos os códigos filhos de uma só vez - mesmo os que já foram usados por algum cliente. A trava que impede excluir um cupom "já utilizado" só olha para o próprio contador de usos do cupom-pai (que normalmente é zero, porque quem é usado são os filhos, não ele). Antes de excluir um lote, exporte o CSV e confirme que nenhum código relevante já foi resgatado; se já foi, prefira Desativar o lote em vez de excluir.
• O código do próprio cupom-pai também é um cupom válido, resgatável por qualquer cliente, além de ser o "recipiente" que agrupa os filhos - ele nasce com limite de 1 uso, assim como cada filho. Se você repassar esse código por engano (por exemplo, copiando ele da tela de detalhes achando que é só um identificador do lote), ele funciona igual aos demais e some do total de usos disponíveis do lote. Ele também não aparece na lista de códigos exportada pelo Exportar CSV, que traz só os filhos - então ele fica fácil de perder de vista.
• Todo código gerado em lote nasce como uso único, com limite de 1 uso no total e 1 uso por cliente, independente do tipo de desconto escolhido. Não existe opção de gerar lote com cupons reutilizáveis por várias pessoas.
• Ativar ou desativar o cupom-pai replica o novo status para todos os filhos automaticamente - útil para pausar a campanha inteira de uma vez. O caminho inverso não vale: ativar ou desativar um código filho individual (abrindo a página de detalhes dele) afeta só aquele código, não o lote inteiro nem os irmãos dele.
• A quantidade máxima por lote é 1000 cupons por geração. Para mais que isso, gere mais de um lote.
• Os cupons filhos ficam ocultos da listagem principal - só o cupom-pai aparece lá, com a contagem de filhos. Para ver, buscar ou copiar um código filho específico, exporte o CSV do lote ou abra o cupom-pai e use a busca dentro do histórico de usos.

Casos especiais

Geração de código pode falhar em lotes muito grandes com prefixo raro

Cada código é sorteado aleatoriamente e checado contra os já existentes no banco; o sistema tenta até 10 vezes a quantidade pedida antes de desistir. Na prática isso praticamente nunca acontece (o espaço de combinações possíveis é enorme), mas se acontecer você recebe uma mensagem genérica de erro do sistema, sem o lote ser criado. Se isso ocorrer, tente novamente com um prefixo mais curto ou peça uma quantidade menor.

Cupom sem histórico de usos ainda soma no contador

O bloco Estatísticas mostra "Total de Usos" a partir do próprio contador do cupom, não a partir da lista real de aplicações. Em uso normal os dois sempre batem, porque o contador só sobe quando um uso de verdade é registrado no checkout.

Restringir por viagens/excursões

Tanto na criação de um cupom único quanto no lote, deixar o campo de restrição por viagens vazio libera o cupom para qualquer viagem ativa. Ao marcar uma ou mais viagens, o cupom passa a valer somente nelas - isso vale igualmente para todos os filhos do lote, já que compartilham as mesmas regras do cupom-pai.

Erros comuns

• Página de detalhes não abre / redireciona - Causa: o código do cupom na URL não existe mais (foi excluído) ou pertence a outra empresa. Solução: volte para Marketing > Cupons e localize o cupom pela busca.
• Botão Ver Histórico de Usos não aparece - Causa: o cupom ainda não tem nenhum uso registrado. Solução: não há o que consultar ainda; o link só aparece depois da primeira aplicação bem-sucedida.
• "Não foi possível gerar N códigos únicos após M tentativas" - Causa: quantidade muito alta combinada com um prefixo que reduz demais as combinações disponíveis. Solução: use um prefixo mais curto (ou remova) e gere o lote novamente.
• O máximo é 1000 cupons por lote - Causa: você digitou uma quantidade maior que 1000 no campo Quantidade de Cupons. Solução: gere em lotes separados de até 1000 códigos cada.
• Exportar CSV não aparece na página de detalhes - Causa: o cupom aberto não é um cupom-pai de lote (é um cupom comum ou um filho individual). Solução: a exportação só existe na página de detalhes do cupom-pai, que mostra o cartão Cupons do Lote.

Onde encontrar

• URL do detalhe: /admin/marketing/cupons/{id}
• URL da geração em lote: /admin/marketing/cupons/lote/create
• URL do histórico de usos: /admin/marketing/cupons/{id}/usos
• Caminho no menu: Marketing > Cupons > clique em um cupom (detalhe) ou em Gerar Lote (geração em massa)
• Permissão necessária: ver os cupons (para o detalhe e o histórico) e criar os cupons (para gerar lote)
• Módulo necessário: nenhum

Veja também

• Cupons - Listagem
• Cupons - Criar Cupom
• Cupons - Editar Cupom