Passeios - Gift Cards

O que é

A área de Gift Cards do módulo de Experiências reúne todos os vale-presentes emitidos pela empresa, tanto os criados manualmente pelo admin quanto os vendidos no site público. Cada gift card tem um código único no formato GIFT-XXXX-XXXX-XXXX, um valor nominal, um saldo atual (que vai sendo consumido conforme o destinatário usa) e um status: Ativo, Utilizado, Expirado ou Cancelado.

O usuário normalmente chega aqui em três momentos: para emitir um vale como cortesia ou campanha promocional, para conferir o saldo restante de um código informado por um cliente, ou para reenviar/cancelar um gift card já emitido. Os quatro cartões no topo da listagem (Total Emitidos, Ativos, Saldo Ativo e Valor Emitido) dão um panorama imediato do quanto a empresa tem em vales circulando no mercado.

Como usar

1. Vá em Experiências > Gift Cards no sidebar (URL /admin/gift-cards).
2. Para emitir um novo vale, clique em Novo Gift Card (botão verde-azulado no canto superior direito).
3. Na tela de criação, defina o Valor do Gift Card:
   • Use os botões de atalho R$ 50, R$ 100, R$ 200 ou R$ 500 para os valores mais comuns, ou
   • Digite um valor livre no campo Valor personalizado (use vírgula como separador decimal: 350,00).
4. Preencha o bloco Destinatário (opcional - pode emitir gift card sem dono ainda):
   • Nome - nome de quem vai receber o presente.
   • Email - obrigatório se quiser enviar o vale por email no momento da criação.
   • Telefone - formato (00) 00000-0000 (máscara aplicada automaticamente).
   • Mensagem personalizada - texto livre que aparece junto ao código no email do destinatário.
5. No bloco Configurações (coluna lateral):
   • Data de vencimento - deixe vazio para vale sem prazo, ou escolha uma data futura (datas passadas são recusadas).
   • Enviar por email ao destinatário - ative para que o sistema dispare o email com o código assim que o gift card for criado. Exige email preenchido acima.
6. Confirme em Criar Gift Card. Se preferir cadastrar vários em sequência, use Criar e criar outro, que recarrega o formulário limpo.
7. Após a criação você cai na tela de detalhes, com o cartão visual mostrando o código e o valor. Anote ou compartilhe o código com o destinatário caso não tenha enviado por email.

Consultar e filtrar gift cards existentes

• Use a busca (placeholder Buscar por código, nome ou email...) para encontrar um vale específico - a pesquisa procura em código, nome do destinatário e email do destinatário.
• O select de status ao lado filtra a listagem por situação atual e recarrega ao mudar a opção.
• Cada item da lista mostra o código, o status colorido, o destinatário (se houver), a validade, o valor nominal e - quando há uso parcial - o saldo ainda disponível.

Casos especiais

Reenviar o email para o destinatário

Acontece quando o cliente perdeu o email original ou foi para spam. Na tela de detalhes do gift card, clique em Reenviar Email (botão azul-petróleo no cabeçalho). O botão só aparece quando o vale tem email cadastrado e está com status Ativo. O sistema dispara novamente o template emails.gift-card com código, valor, validade e mensagem personalizada.

Cancelar um gift card emitido

Use quando o vale foi criado por engano, perdeu validade comercial ou o destinatário pediu o estorno. Na tela de detalhes, clique no botão vermelho Cancelar (cabeçalho) e confirme no modal Cancelar gift card. O status muda para Cancelado e o vale fica bloqueado para qualquer resgate futuro. A ação não devolve dinheiro automaticamente - o reembolso é um processo à parte. Cancelar exige a permissão gift_cards.cancel.

Gift card vendido pelo site

Quando o vale vem da loja pública (tipo vendido no site), os campos de Comprador e o histórico de orderOrigem ficam preenchidos automaticamente. A tela de detalhes mostra Tipo: Vendido no site na seção Informações da coluna lateral, e o nome do comprador aparece logo abaixo.

Acompanhar o saldo após resgates

A coluna lateral da tela de detalhes traz um bloco Saldo com Valor nominal, Utilizado, Saldo restante e uma barra de progresso com o percentual já consumido. Abaixo, o Histórico de Uso lista cada pedido em que o gift card foi aplicado, com data, valor descontado e saldo posterior. Quando o saldo zera, o status muda automaticamente para Utilizado.

Vale com vencimento no passado

Se a data de vencimento já passou, qualquer tentativa de validar o código no checkout marca automaticamente o gift card como Expirado. Não é possível reativar - emita um novo vale.

Erros comuns e como resolver

• "Gift card não possui email do destinatário." - Causa: tentou reenviar um vale criado sem email. Solução: como o email do destinatário não é editável após a criação, a única opção é emitir um novo gift card já com o email correto e cancelar o antigo.
• "Erro ao enviar email. Tente novamente." - Causa: falha de SMTP/SES no momento do disparo. Solução: aguarde alguns minutos e clique novamente em Reenviar Email. Se persistir, verifique em Configurações > Integrações se o meio de pagamento de email está conectado.
• "Gift card já está cancelado." - Causa: tentou cancelar duas vezes o mesmo vale (por exemplo, em duas abas abertas). Solução: nenhuma - o status já está como Cancelado, basta atualizar a tela.
• Mensagem de validação no campo Valor personalizado - Causa: o valor ficou vazio ou em formato inválido. Solução: use o formato monetário brasileiro com vírgula (1.250,00) ou clique em um dos atalhos R$ 50/100/200/500.
• Mensagem de validação no Telefone - Causa: telefone fora do padrão (00) 00000-0000. Solução: digite normalmente que a máscara formata; ou deixe o campo vazio.
• Mensagem de validação na Data de vencimento - Causa: escolheu uma data igual a hoje ou no passado. Solução: escolha pelo menos o dia seguinte, ou deixe vazio para vale sem prazo.

Onde encontrar

• URL: /admin/gift-cards
• Caminho no menu: Experiências > Gift Cards
• Permissão necessária: gift_cards.view (listar e ver), gift_cards.create (emitir novo) e gift_cards.cancel (cancelar)
• Módulo necessário: Passeios e Experiências (passeios-experiencias)

Veja também

• Vendas de Experiências - para conferir os pedidos em que o gift card foi aplicado.
• Pacotes de Experiências - para preparar combos que o destinatário pode resgatar com o vale.
• Visão geral do módulo de Experiências - para acompanhar o desempenho geral do módulo.