Storefront API¶

A Storefront API fornece uma interface JavaScript (window.GiftHeroAPI) para criar fluxos personalizados de seleção e compra de cartões-presente na sua loja virtual.

Configuração da Storefront API

Ativar a API¶

Acesse For developers no menu de navegação à esquerda.
Marque Enable storefront API e salve.

A interface de cartão-presente que o app gera na sua página de produto fica desligada, e window.GiftHeroAPI é carregado em seu lugar. Você constrói a interface.

A API não lê saldos de cartões-presente. Ela coleta as escolhas do comprador e adiciona o cartão-presente ao carrinho.

Lojas virtuais headless

Em uma loja virtual headless, a API é carregada quando o modo headless e Enable storefront API estão ambos ativos. Veja Integração headless.

Inicialização¶

A API carrega de forma assíncrona. O Gift Card Hero dispara um evento em window quando estiver pronto. Escute-o antes de chamar qualquer método:

window.addEventListener('gift.hero:initalized', function () {
  const api = window.GiftHeroAPI;
  // API is ready to use
});

O nome do evento está escrito initalized

O nome do evento tem um erro de digitação: gift.hero:initalized (sem o segundo "i"). Use-o exatamente como está escrito. O evento é disparado em window, não em document, depois que o script da loja do Gift Card Hero é carregado. Se o script não estiver na página, ou se a API da loja estiver desativada, o evento não é disparado.

Quando a API inicia, ela seleciona a primeira variante (ou a variante do parâmetro de URL ?variant=) e a primeira imagem.

Métodos¶

addToCart(quantity?, skipValidation?)¶

Valida os dados do cartão e adiciona o cartão-presente configurado ao carrinho com /cart/add.js da Shopify.

try {
  const result = await window.GiftHeroAPI.addToCart(1);
  // result: { status: 200, data: { ... } }
} catch (e) {
  // e: { status: 400, data: { errors: ['...'] } } when validation fails
}

Parâmetro	Tipo	Padrão	Descrição
`quantity`	number	1	Número de cartões-presente a adicionar
`skipValidation`	boolean	false	Adiciona o cartão mesmo que `validate()` relate erros

Retorna: uma promise com a resposta do carrinho da Shopify ({ status, data }). Ela é rejeitada com { status: 400, data: { errors } } quando a validação falha.

generatePreview()¶

Abre uma prévia mostrando como o cartão-presente aparecerá para o destinatário, usando os dados preenchidos até o momento.

window.GiftHeroAPI.generatePreview();

getImages()¶

Retorna um array com as URLs de imagens disponíveis para o cartão-presente: os seus próprios designs, os designs integrados selecionados e, se ativadas, as imagens do produto.

const images = window.GiftHeroAPI.getImages();
// ['https://cdn.shopify.com/...', 'https://cdn.shopify.com/...']

getOptions()¶

Retorna as opções do produto, incluindo os valores disponíveis.

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

Retorna as traduções da interface para o idioma atual, como os rótulos e a mensagem de validação.

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

Retorna o array de variantes do produto.

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

Define todos os dados do cartão-presente de uma vez.

window.GiftHeroAPI.setCardData({
  variantId: 12345678,
  image: 'https://cdn.shopify.com/...',
  message: 'Happy Birthday!',
  from: 'Alice',
  to: 'Bob',
  deliveryDate: new Date('2026-12-25'),
  email: 'recipient@example.com'
});

Campo	Tipo	Descrição
`variantId`	number	O ID da variante selecionada
`image`	string	URL da imagem do cartão selecionada
`message`	string	Mensagem do cartão-presente
`from`	string	Nome do remetente
`to`	string	Nome do destinatário (opcional)
`deliveryDate`	`Date`	Data de entrega agendada, como um objeto `Date` do JavaScript (opcional)
`email`	string	E-mail do destinatário (opcional)

A entrega por SMS não está disponível pela API, por isso não há campo de telefone.

Setters individuais¶

Método	Parâmetro	Descrição
`setDeliveryDate(date)`	`Date`	Define a data de entrega agendada. Gera um erro se não for um objeto de data válido
`setEmail(email)`	string	Define o e-mail do destinatário
`setFrom(name)`	string	Define o nome do remetente
`setTo(name)`	string	Define o nome do destinatário
`setImage(image)`	string	Define a URL da imagem do cartão selecionada
`setMessage(message)`	string	Define a mensagem do cartão-presente
`setVariant(variantId)`	number ou string	Define a variante selecionada
`setProperty(name, value)`	string, string	Adiciona uma propriedade extra de item à linha do carrinho

validate()¶

Verifica os dados atuais do cartão-presente e retorna { valid, errors }, em que errors é um array de mensagens criadas a partir das suas traduções.

const { valid, errors } = window.GiftHeroAPI.validate();

Regras de validação:

Se um e-mail de destinatário estiver definido, a data de entrega, o nome do remetente (from) e a mensagem são obrigatórios.
Se uma data de entrega estiver definida, o e-mail do destinatário, o nome do remetente e a mensagem são obrigatórios.
Sem e-mail e sem data de entrega, nada é obrigatório.

setCustomAmount(amount)¶

Seleciona um valor personalizado, na moeda da sua loja (por exemplo 75 para 75.00). Funciona somente quando os valores personalizados estão ativados para a sua loja; caso contrário, lança o erro Custom amount is not enabled. O método não verifica o seu mínimo e máximo, então valide o valor você mesmo.

window.GiftHeroAPI.setCustomAmount(75);

Cartões-presente físicos¶

Se você vende cartões-presente físicos, troque a API para eles com setCardType('physical') (use setCardType('eGift') para voltar).

Método	Descrição
`setCardType(type)`	`'eGift'` ou `'physical'`. Selecionar `'physical'` escolhe a primeira variante e imagem físicas
`getPhysicalProduct()`	O produto de cartão-presente físico
`getPhysicalVariants()`	Variantes do produto físico
`getPhysicalImages()`	URLs de imagens do produto físico
`setPhysicalVariant(variantId)`	Seleciona uma variante física (somente no tipo físico)
`setPhysicalDeliveryAddress(address)`	Define o endereço de entrega (somente no tipo físico): `firstName`, `lastName`, `address`, `zipCode`, `city`, `country` e `state` opcional
`isPhysicalCard()`	`true` quando o tipo físico está selecionado

uploadCustomDesign(file, options?)¶

Envia a imagem própria do comprador e retorna a URL dela, que você pode passar para setImage().

const { url } = await window.GiftHeroAPI.uploadCustomDesign(file);
window.GiftHeroAPI.setImage(url);

O arquivo precisa ser uma imagem JPG, PNG, GIF ou WebP, de até 5 MB por padrão. Você pode alterar os limites com options.maxSize (bytes) e options.allowedTypes. O método gera um erro com uma mensagem clara quando o arquivo é recusado.

Exemplo de integração com React¶

Um exemplo completo de integração com React está disponível no JSFiddle. Ele demonstra como inicializar a API, criar uma interface personalizada de seleção de cartão-presente e tratar o fluxo de adicionar ao carrinho:

Ver exemplo em React no JSFiddle