Ferramentas para desenvolvedores¶

A página For developers oferece acesso à API, configuração de webhooks, modo headless e opções avançadas de integração. Abra-a por For developers no menu de navegação à esquerda.

Alterações nas caixas de seleção e nas URLs de webhook desta página são aplicadas quando você clica em Save na barra de salvamento. Os botões de token e Generate Secret agem imediatamente. Enable headless mode também precisa de Save.

Ferramentas para desenvolvedores

Storefront API¶

A Storefront API é uma interface JavaScript (window.GiftHeroAPI) para criar a sua própria seleção e compra de cartões-presente na loja virtual.

Enable storefront API — ative para carregar a API JavaScript na página do produto cartão-presente. A interface de cartão-presente gerada pelo app fica desligada nessa página, então o seu desenvolvedor cria a interface.
Disable gift card page animation — aparece quando a storefront API está ativa. Remove a página animada de cartão-presente do app, para que você possa criar uma página personalizada.

A API não lê saldos. Ela coleta as escolhas do cartão-presente (valor, design, mensagem, destinatário) e adiciona o cartão-presente ao carrinho.

Referência completa da API: Storefront API

REST API¶

A REST API permite integrar o Gift Card Hero com sistemas externos — CRMs, painéis de analytics, plataformas de fidelidade e outros.

Ativação¶

Marque Enable REST API e salve. Depois clique em Send me access token — o Gift Card Hero envia o token de acesso à API para o e-mail de contato da loja exibido na página.

Sua loja tem um único token de API por vez, compartilhado por todas as integrações que o utilizam:

Send me access token emite um novo token. O anterior para de funcionar imediatamente, então atualize suas integrações com o novo token. Para consultar o token de novo, procure o e-mail anterior.
Revoke access token desativa o token atual sem emitir um novo — use-o se o token puder ter vazado ou se um parceiro não precisar mais de acesso.
Desligar Enable REST API também revoga o token.

Detalhes: Gerenciando seu token de API

Um link de Postman collection está disponível na página para explorar a API rapidamente. Show available API endpoints lista os principais endpoints na própria página.

Endpoints disponíveis¶

Método	Endpoint	Descrição
`POST`	`/api/external/gift-cards`	Criar um cartão-presente
`POST`	`/api/external/gift-cards/{id}/disable`	Desativar um cartão-presente
`GET`	`/api/external/gift-cards`	Listar cartões-presente (filtráveis por status)
`GET`	`/api/external/gift-cards/{id}`	Obter um único cartão-presente
`GET`	`/api/external/gift-cards/search?query=...`	Pesquisar cartões-presente (por exemplo `last_characters:mnop`)
`PUT`	`/api/external/gift-cards/{id}`	Atualizar um cartão-presente
`PUT`	`/api/external/gift-cards/{id}/balance`	Atualizar o saldo de um cartão-presente
`POST`	`/api/external/gift-cards/{id}/redeem`	Resgatar um cartão-presente a partir de um app de POS ou caixa (envia a notificação de resgate, registra a filial)
`GET`	`/api/external/gift-cards/transactions`	Cartões-presente com as suas transações, paginados
`POST`	`/api/external/gift-cards/assign-to-order`	Atribuir os seus próprios códigos de cartão-presente a um pedido

Referência completa da API: REST API Reference

Webhooks¶

Configuração de webhooks

O Gift Card Hero pode enviar requisições HTTP POST ao seu servidor quando eventos específicos de cartão-presente ocorrem.

As configurações de webhook aparecem nesta página assim que Enable REST API estiver ativo.

Configurando um segredo de webhook¶

Clique em Generate Secret para criar um segredo de assinatura. Copie-o do banner imediatamente — ele é mostrado apenas uma vez. Use-o no seu servidor para verificar se as cargas recebidas vêm do Gift Card Hero. A assinatura é enviada no cabeçalho X-GiftHero-Signature (HMAC-SHA256).

Clique em Regenerate Secret para trocar o segredo, por exemplo se ele tiver vazado. O segredo antigo para de funcionar imediatamente, então atualize o seu servidor com o novo.

Endpoints de webhook¶

Configure as URLs do seu servidor para estes tipos de webhook:

Campo na página	Quando é disparado
Order with gift card webhook URL	Os cartões-presente de um pedido são processados pelo Gift Card Hero
Gift card payment webhook URL	Um pedido é criado e foi pago com um cartão-presente
Gift card balance webhook URL	Não é enviado no momento (veja o guia de integração)

Digite a URL do seu endpoint em cada campo e salve. Uma URL nova ou alterada precisa começar com https:// e ser acessível pela internet; endereços de rede privada são recusados ao salvar.

Guia de integração completo: Webhooks Integration Guide

Editor de código personalizado¶

Adicione CSS personalizado aos componentes de loja do Gift Card Hero sem modificar diretamente o seu tema Shopify.

Clique em Open custom code editor. Ele abre a aba Custom code em Settings.

Editor de código personalizado

O seu CSS é adicionado às páginas de produto de cartão-presente, à página de cartão-presente e às páginas dos produtos de cartão-presente físico e de valor personalizado. Ele não é adicionado ao restante da loja. Use-o para ajustar a aparência do construtor de cartões-presente e da página de cartão-presente. Clique em Save na barra de salvamento para aplicar as alterações.

Somente CSS

O editor aceita somente CSS. CSS que contenha </style é recusado ao salvar. JavaScript personalizado configurado para a sua loja antes desta mudança continua funcionando, mas não pode mais ser editado aqui. Para alterá-lo, entre em contato com o suporte.

Salvar dados de cartões-presente em um metafield¶

Marque Save a gift card data to a metafield para armazenar os dados de cada cartão-presente (design, mensagem, remetente) em um metafield Shopify na sua loja:

Namespace: gift_hero
Key: cards_data

Os dados são indexados pelos últimos quatro caracteres do código do cartão-presente. Isso os deixa disponíveis nos modelos de e-mail do Shopify durante a geração do cartão-presente e nos seus próprios templates Liquid.

Disable gift card page animation for templates with suffix — desativa a página de cartão-presente do app para os cartões que têm um sufixo de template definido (veja template_suffix na REST API), para que o seu próprio template seja exibido.

Modo headless¶

Ative o modo headless para lojas virtuais Shopify personalizadas ou headless que não usam o sistema de temas padrão da Shopify.

Clique em Enable headless mode (o selo de status muda para Enabled). Um trecho de código aparece com valores de exemplo que você substitui pelos dados da sua loja:

Placeholder	Substitua por
`[MONEY_FORMAT]`	A string de formato monetário da sua loja
`[PRODUCT_ID]`	O ID numérico Shopify do seu produto cartão-presente
`[MYSHOPIFY_DOMAIN]`	O domínio `.myshopify.com` da sua loja
`[ADD_TO_CART_CALLBACK]`	Sua função JavaScript personalizada de adicionar ao carrinho
`[LOCALE]`	O código de idioma das suas traduções (ex.: `en`, `fr`). `en` é o padrão

Copie o trecho e integre-o à base de código da sua loja personalizada.

Guia de configuração completo: Headless Integration Guide

Atendimento personalizado de pedidos¶

Esta seção aparece somente para lojas que usam a opção de atendimento próprio (self-fulfillment). Com ela, o Gift Card Hero fica totalmente responsável por criar e entregar os cartões-presente de um pedido, em vez da entrega automática de cartões-presente da Shopify.

Desative o atendimento automático na Shopify primeiro

Nas configurações de checkout (processamento de pedidos) da sua Shopify, escolha Don't fulfill any of the order's line items automatically. A página tem links para Check settings e para um guia da Shopify. Não atenda cartões-presente de um pedido manualmente — eles devem permanecer não atendidos.

O selo mostra o status atual (Enabled ou Disabled). Clique em Enable custom fulfilment ou Disable custom fulfilment para alternar.