Storefront API¶

La Storefront API fournit une interface JavaScript (window.GiftHeroAPI) pour créer des parcours personnalisés de sélection et d'achat de cartes-cadeaux sur votre boutique en ligne.

Configuration de la Storefront API

Activer l'API¶

Allez dans For developers dans la navigation de gauche.
Cochez Enable storefront API et enregistrez.

L'interface de carte-cadeau générée par l'application sur votre page produit de carte-cadeau est désactivée, et window.GiftHeroAPI est chargé à la place. C'est vous qui créez l'interface.

L'API ne lit pas les soldes des cartes-cadeaux. Elle recueille les choix de l'acheteur et ajoute la carte-cadeau au panier.

Boutiques headless

Sur une boutique headless, l'API est chargée lorsque le mode headless et Enable storefront API sont tous deux activés. Voir Intégration headless.

Initialisation¶

L'API se charge de manière asynchrone. Gift Card Hero déclenche un événement sur window lorsqu'elle est prête. Écoutez-le avant d'appeler toute méthode :

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

Le nom de l'événement contient une faute : initalized

Le nom de l'événement comporte une faute de frappe : gift.hero:initalized (sans second « i »). Utilisez-le exactement tel quel. L'événement est déclenché sur window et non sur document, une fois le script storefront de Gift Card Hero chargé. Si le script n'est pas présent sur la page, ou si la Storefront API est désactivée, l'événement ne se déclenche pas.

Au démarrage, l'API sélectionne la première variante (ou la variante indiquée dans le paramètre d'URL ?variant=) ainsi que la première image.

Méthodes¶

addToCart(quantity?, skipValidation?)¶

Valide les données de la carte et ajoute la carte-cadeau configurée au panier avec /cart/add.js de Shopify.

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

Paramètre	Type	Par défaut	Description
`quantity`	number	1	Nombre de cartes-cadeaux à ajouter
`skipValidation`	boolean	false	Ajoute la carte même si `validate()` signale des erreurs

Retour : une promesse contenant la réponse du panier Shopify ({ status, data }). Elle est rejetée avec { status: 400, data: { errors } } lorsque la validation échoue.

generatePreview()¶

Ouvre un aperçu montrant l'apparence de la carte-cadeau pour le destinataire, à partir des données saisies jusque-là.

window.GiftHeroAPI.generatePreview();

getImages()¶

Renvoie un tableau d'URL d'images disponibles pour la carte-cadeau : vos propres designs, les designs intégrés sélectionnés et, si elles sont activées, les images du produit.

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

getOptions()¶

Renvoie les options du produit, y compris les valeurs disponibles.

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

Renvoie les traductions de l'interface pour la langue actuelle, comme les libellés et le message de validation.

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

Renvoie le tableau des variantes du produit.

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

Définit toutes les données de la carte-cadeau en une seule fois.

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'
});

Champ	Type	Description
`variantId`	number	L'identifiant de la variante sélectionnée
`image`	string	URL de l'image de carte sélectionnée
`message`	string	Message de la carte-cadeau
`from`	string	Nom de l'expéditeur
`to`	string	Nom du destinataire (facultatif)
`deliveryDate`	`Date`	Date de livraison programmée, sous forme d'objet JavaScript `Date` (facultatif)
`email`	string	Adresse e-mail du destinataire (facultatif)

La livraison par SMS n'est pas disponible via l'API : il n'y a donc pas de champ téléphone.

Setters individuels¶

Méthode	Paramètre	Description
`setDeliveryDate(date)`	`Date`	Définit la date de livraison programmée. Génère une erreur si ce n'est pas un objet date valide
`setEmail(email)`	string	Définit l'e-mail du destinataire
`setFrom(name)`	string	Définit le nom de l'expéditeur
`setTo(name)`	string	Définit le nom du destinataire
`setImage(image)`	string	Définit l'URL de l'image de carte sélectionnée
`setMessage(message)`	string	Définit le message de la carte-cadeau
`setVariant(variantId)`	number or string	Définit la variante sélectionnée
`setProperty(name, value)`	string, string	Ajoute une propriété supplémentaire à la ligne du panier

validate()¶

Vérifie les données actuelles de la carte-cadeau et renvoie { valid, errors }, où errors est un tableau de messages construits à partir de vos traductions.

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

Règles de validation :

Si un e-mail de destinataire est renseigné, la date de livraison, le nom de l'expéditeur (from) et le message sont obligatoires.
Si une date de livraison est renseignée, l'e-mail du destinataire, le nom de l'expéditeur et le message sont obligatoires.
Sans e-mail et sans date de livraison, rien n'est obligatoire.

setCustomAmount(amount)¶

Sélectionne un montant personnalisé, dans la devise de votre boutique (par exemple 75 pour 75,00). Cette méthode ne fonctionne que si les montants personnalisés sont activés pour votre boutique ; sinon elle génère l'erreur Custom amount is not enabled. La méthode ne vérifie pas votre minimum et votre maximum : validez donc le montant vous-même.

window.GiftHeroAPI.setCustomAmount(75);

Cartes-cadeaux physiques¶

Si vous vendez des cartes-cadeaux physiques, basculez l'API sur ce type avec setCardType('physical') (utilisez setCardType('eGift') pour revenir en arrière).

Méthode	Description
`setCardType(type)`	`'eGift'` ou `'physical'`. Choisir `'physical'` sélectionne la première variante et la première image physiques
`getPhysicalProduct()`	Le produit carte-cadeau physique
`getPhysicalVariants()`	Les variantes du produit physique
`getPhysicalImages()`	Les URL des images du produit physique
`setPhysicalVariant(variantId)`	Sélectionne une variante physique (type physique uniquement)
`setPhysicalDeliveryAddress(address)`	Définit l'adresse de livraison (type physique uniquement) : `firstName`, `lastName`, `address`, `zipCode`, `city`, `country`, et `state` facultatif
`isPhysicalCard()`	`true` lorsque le type physique est sélectionné

uploadCustomDesign(file, options?)¶

Télécharge une image propre à l'acheteur et renvoie son URL, que vous pouvez transmettre à setImage().

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

Le fichier doit être une image JPG, PNG, GIF ou WebP, d'au plus 5 Mo par défaut. Vous pouvez modifier les limites avec options.maxSize (en octets) et options.allowedTypes. La méthode génère une erreur explicite lorsque le fichier est refusé.

Exemple d'intégration React¶

Un exemple complet d'intégration React est disponible sur JSFiddle. Il montre comment initialiser l'API, créer une interface personnalisée de sélection de carte-cadeau et gérer l'ajout au panier :

Voir l'exemple React sur JSFiddle