Integração com POS¶
O Gift Card Hero adiciona um bloco ao Shopify POS que dá à equipe da loja ferramentas de cartões-presente sem sair da tela do POS. Você controla o que a equipe pode fazer em POS tools, no Gift Card Hero.
Não usa o Shopify POS? Se a sua loja funciona com um caixa que não é da Shopify (Square, Clover, Lightspeed, Zettle e similares), veja Cartões-presente no POS de terceiros (PWA).
O que a equipe pode fazer no POS¶
- Consultar o saldo de um cartão-presente: digite ou leia um código para ver o saldo atual
- Registrar um cartão-presente físico: transformar o código de um cartão impresso em um cartão-presente ativo com saldo
- Recarregar um cartão: definir um novo saldo, ou adicionar ou deduzir um valor, opcionalmente com um pagamento no carrinho
- Processar um reembolso para um cartão-presente: emitir um valor reembolsado como crédito da loja em um cartão novo ou existente
- Ver os cartões-presente de um cliente: ver todos os cartões vinculados a um cliente e recarregá-los
- Sincronizar um cartão com a sua rede de lojas: para configurações de multiloja
Configuração¶
Passo 1: adicionar o bloco à tela inicial do POS¶
- Abra o app Shopify POS
- Pressione o botão Add tile
- Vá ao item de menu Apps
- Selecione Gift Card Hero na lista
- Pressione o botão POS UI Extension
- Pressione Done
O bloco Gift Hero ("Manage gift cards and rewards") agora aparece na tela inicial do POS. Ao pressioná-lo, abrem-se as ferramentas do Gift Card Hero. Os mesmos passos são mostrados no Gift Card Hero em POS tools → Shopify POS, na caixa How to Add POS Tools to Your POS App.
Use a POS UI Extension, não o App link
A Shopify também oferece um bloco App link. Ele está obsoleto e não é recomendado.
Passo 2: escolher o que a equipe pode fazer¶
Abra POS tools no menu de navegação à esquerda e permaneça na aba Shopify POS. As configurações são salvas com o botão Save na barra de salvamento.
| Configuração | Efeito |
|---|---|
| Disable balance reload functionality in Shopify POS app | A equipe não pode recarregar cartões. Reload Gift Card mostra "Gift card reload is not allowed." |
| Disable gift card registration in Shopify POS app | Oculta o registro de cartões-presente, para que a equipe não possa criar cartões sem pagamento. Register Gift Card mostra "Gift card registration is not allowed." |
| Increase balance only after payment is completed | Uma recarga só é aplicada depois que o pagamento é concluído no Shopify POS. |
| Default to 'Add payment to cart' on the reload screen | Pré-seleciona Add payment to cart em vez de No payment required. |
| Allow only redeeming gift cards in POS | A equipe só pode gastar saldos: recarregar e adicionar a um saldo ficam desativados. |
| Available balance change actions | Both (padrão), Set final balance ou Set amount (exibido no POS como Add or deduct amount): quais métodos de ajuste a equipe vê na tela de recarga. |
As opções de pagamento ficam indisponíveis enquanto Disable balance reload estiver marcada, e Allow only redeeming não pode ser combinada com ela.
Modo rápido¶
Marque Enable Quick Mode para pular o menu principal: ao abrir o bloco, você vai direto para a lista de cartões de Reload Balance. Depois, use Hide fields on Reload Balance screen para remover o que a equipe não precisa: Adjustment method, Payment options, Internal note, Email notification e Transaction history.
Recursos da extensão de POS¶
A extensão de POS do Gift Card Hero adiciona vários elementos ao Shopify POS:
Bloco da tela inicial¶
O bloco Gift Hero abre o Gift Hero Tools, com Check Balance, Reload Gift Card e Register Gift Card. (Com o Modo rápido ativado, ele abre a lista de cartões para recarga.)
Check Balance¶
Toque em Scan gift card QR code ou digite o código em Search gift cards e toque em Search. O resultado mostra o cartão-presente (últimos caracteres), seu Balance e, quando aplicável, a data em que foi desativado ou em que expira. Se o código não for encontrado, é oferecido Register this gift card.
Em um dispositivo sem câmera, ou sem permissão de câmera, a tela informa isso e sugere um leitor de hardware.
Register Gift Card¶
Ativa um cartão-presente impresso no caixa. A equipe lê o QR code do cartão ou digita o código (com pelo menos 8 caracteres), digita o Gift card value e toca em Register Gift Card. O código se torna um cartão-presente ativo da Shopify com esse saldo; um código que já existe como cartão-presente é recusado.
Registrar cria o cartão sem receber pagamento, então a equipe deve garantir que o valor do cartão foi pago. Para ocultar esta opção da equipe, marque Disable gift card registration in Shopify POS app em POS tools. Veja Cartões-presente físicos para as outras formas de ativar cartões impressos.
Reload Balance¶
Adicione fundos a um cartão-presente no caixa. Pesquise o cartão pelo código, ou deixe a pesquisa vazia para listar os cartões, depois toque no cartão (cartões desativados não podem ser abertos). A tela de recarga mostra o Current balance e:
- Adjustment method: Set final balance, ou Add or deduct amount (depois Add to balance ou Deduct from balance).
- O New balance, o Amount to add ou o Amount to deduct.
- No payment required ou Add payment to cart, com um Payment amount que acompanha o valor adicionado.
- Uma Internal note opcional.
- Send email notification para avisar o cliente: disponível quando o cartão está vinculado a um cliente. O assunto e a mensagem vêm preenchidos e podem ser editados; o texto vem do e-mail de recarga de saldo.
- Apply changes. As Recent transactions do cartão são listadas abaixo.
Order Refund¶
Na tela de detalhes de um pedido, a equipe toca em Refund to gift card. A tela de reembolso oferece:
- Refund to existing gift card: os cartões do cliente (os três primeiros), quando o pedido tem um cliente.
- Items to refund: uma quantidade para cada item do pedido. O Refund amount acompanha a seleção e pode ser editado.
- Uma Note interna e o e-mail do cliente; se o pedido não tiver um, a equipe pode adicionar um.
- No expiration ou Add expiration date para o novo cartão.
Toque no botão Refund (ele mostra o valor) para emitir o reembolso. A tela Gift Card Details então mostra o valor e o código do cartão, e permite reemitir o cartão, se necessário. Para o lado da política, veja Reembolsos como cartões-presente.
Customer Gift Cards¶
Quando um cliente está aberto no POS, a tela de detalhes do cliente tem um botão Manage gift cards (e View gift cards no menu de ações). Ele abre os cartões-presente do cliente, cada um com seu saldo, histórico de transações e um botão Reload balance.
Sincronizar um cartão com a rede¶
Para lojas em uma rede de multiloja, os detalhes do pedido e a tela pós-compra oferecem Sync gift card to network: leia ou digite um código de cartão-presente e toque em Sync to network para disponibilizar o cartão em todas as lojas da rede.
Aceitando um cartão-presente como pagamento¶
O resgate de cartão-presente no checkout é feito nativamente pelo Shopify POS: nenhuma ação do Gift Card Hero é necessária. Quando um cliente quer pagar com um cartão-presente:
- Adicione os itens ao carrinho normalmente
- Toque em Charge
- Selecione Gift Card como forma de pagamento
- Leia ou digite o código
O Shopify POS desconta do saldo automaticamente.
Se você ativar notificações de resgate, o portador do cartão, o comprador ou ambos, dependendo de Quem é notificado, também são informados do valor gasto, do saldo restante e da filial.
Solução de problemas¶
O bloco do Gift Card Hero não aparece no POS¶
- Atualize o app Shopify POS para a versão mais recente
- Abra o seletor de blocos (Add tile → Apps) e confira se Gift Card Hero está listado; depois adicione-o novamente usando POS UI Extension
- Em iPads: force o fechamento e reabra o app POS
Erro "Failed to load" no bloco do POS¶
O dispositivo do POS não consegue acessar a API do Gift Card Hero. Verifique: - O dispositivo está conectado à internet? - Há um firewall ou filtro de conteúdo bloqueando conexões de saída? - Tente trocar de Wi-Fi para dados móveis (ou o contrário) para isolar um problema de rede
"Action not allowed"¶
A ação foi desativada em POS tools → Shopify POS. Desmarque a configuração correspondente se a equipe deve poder usá-la.
A câmera mostra uma tela preta ao ler (iPad)¶
A extensão do Gift Card Hero depende de uma versão recente da API do Shopify POS (2026-07 ou posterior) para mostrar a câmera no iPad. Atualize o app Shopify POS para a versão mais recente e reabra o bloco. Se a câmera continuar preta, digite o código em Search gift cards, ou use um leitor de hardware.
O botão de leitura não aparece¶
O dispositivo não tem câmera ou não recebeu permissão para usá-la. Permita a câmera para o Shopify POS nas configurações do dispositivo, ou use um leitor de hardware ou digite o código.
O saldo consultado mostra um valor errado¶
O saldo mostrado é buscado ao vivo na Shopify. Se parecer desatualizado, verifique a conexão com a internet do dispositivo e tente novamente.
O QR code do e-mail do cartão-presente ou da página de saldo não é lido no POS¶
Sintomas: - Todos os e-mails de cartão-presente mostram o que parece ser o mesmo QR code - Ler esse QR no Shopify POS não faz nada ou retorna "not found" - O QR adicionado ao Apple Wallet é lido corretamente
Causa: a página de saldo do cartão-presente (/gift_cards/{id}/{token}) não tem o objeto Liquid dinâmico QrCode, necessário para renderizar o QR de cada cartão. Quando esse objeto não é exposto, o Gift Card Hero usa uma imagem estática de substituição, então todos os e-mails acabam com o mesmo código não legível.
Correção: entre em contato com o suporte do Gift Card Hero com o domínio da loja afetada. Corrigiremos a renderização do nosso lado para que o QR de cada cartão seja gerado corretamente. Depois da correção, tanto o e-mail quanto a página de saldo mostrarão o QR único que é lido no POS.