Outils pour développeurs¶

La page For developers donne accès à l'API, à la configuration des webhooks, au mode headless et à des options d'intégration avancées. Ouvrez-la depuis For developers dans la navigation de gauche.

Les modifications des cases à cocher et des URL de webhook sur cette page sont appliquées lorsque vous cliquez sur Save dans la barre d'enregistrement. Les boutons de jeton et Generate Secret agissent immédiatement. Enable headless mode nécessite aussi un clic sur Save.

Outils pour développeurs

Storefront API¶

La Storefront API est une interface JavaScript (window.GiftHeroAPI) qui permet de créer votre propre interface de sélection et d'achat de cartes-cadeaux sur votre boutique en ligne.

Enable storefront API : activez cette option pour charger l'API JavaScript sur votre page produit de carte-cadeau. L'interface de carte-cadeau générée par l'application est alors désactivée sur cette page, et votre développeur crée l'interface à la place.
Disable gift card page animation : apparaît une fois la Storefront API activée. Supprime la page de carte-cadeau animée de l'application, pour que vous puissiez créer une page de carte-cadeau personnalisée.

L'API ne lit pas les soldes. Elle recueille les choix de la carte-cadeau (montant, design, message, destinataire) et ajoute la carte-cadeau au panier.

Référence complète de l'API : Storefront API

REST API¶

La REST API permet d'intégrer Gift Card Hero à des systèmes externes : CRM, tableaux de bord d'analyse, plateformes de fidélité, etc.

Activation¶

Cochez Enable REST API puis enregistrez. Cliquez ensuite sur Send me access token : Gift Card Hero envoie le jeton d'accès à l'API à l'adresse e-mail de contact de la boutique indiquée sur la page.

Votre boutique n'a qu'un seul jeton d'API à la fois, partagé par toutes les intégrations qui l'utilisent :

Send me access token émet un nouveau jeton. L'ancien cesse de fonctionner immédiatement : mettez donc à jour vos intégrations avec le nouveau jeton. Pour retrouver le jeton, recherchez l'e-mail précédent.
Revoke access token désactive le jeton actuel sans en émettre un nouveau. Utilisez-le si le jeton a pu fuiter ou si un partenaire n'a plus besoin d'accès.
Désactiver Enable REST API révoque aussi le jeton.

Détails : Gérer votre jeton d'API

Un lien Postman collection est disponible sur la page pour explorer rapidement l'API. Show available API endpoints affiche la liste des principaux points de terminaison directement sur la page.

Points de terminaison disponibles¶

Méthode	Point de terminaison	Description
`POST`	`/api/external/gift-cards`	Créer une carte-cadeau
`POST`	`/api/external/gift-cards/{id}/disable`	Désactiver une carte-cadeau
`GET`	`/api/external/gift-cards`	Lister les cartes-cadeaux (filtrable par statut)
`GET`	`/api/external/gift-cards/{id}`	Obtenir une seule carte-cadeau
`GET`	`/api/external/gift-cards/search?query=...`	Rechercher des cartes-cadeaux (par exemple `last_characters:mnop`)
`PUT`	`/api/external/gift-cards/{id}`	Mettre à jour une carte-cadeau
`PUT`	`/api/external/gift-cards/{id}/balance`	Mettre à jour le solde d'une carte-cadeau
`POST`	`/api/external/gift-cards/{id}/redeem`	Utiliser une carte-cadeau depuis une application POS ou de caisse (envoie la notification d'utilisation, enregistre la boutique)
`GET`	`/api/external/gift-cards/transactions`	Cartes-cadeaux avec leurs transactions, paginées
`POST`	`/api/external/gift-cards/assign-to-order`	Rattacher vos propres codes de carte-cadeau à une commande

Référence complète de l'API : REST API Reference

Webhooks¶

Configuration des webhooks

Gift Card Hero peut envoyer des requêtes HTTP POST à votre serveur lorsque des événements précis de carte-cadeau se produisent.

Les réglages des webhooks apparaissent sur cette page une fois Enable REST API activé.

Configurer un secret de webhook¶

Cliquez sur Generate Secret pour créer un secret de signature. Copiez-le immédiatement depuis la bannière : il n'est affiché qu'une seule fois. Utilisez-le sur votre serveur pour vérifier que les données reçues proviennent bien de Gift Card Hero. La signature est envoyée dans l'en-tête X-GiftHero-Signature (HMAC-SHA256).

Cliquez sur Regenerate Secret pour changer le secret, par exemple s'il a fuité. L'ancien secret cesse de fonctionner immédiatement : mettez donc votre serveur à jour avec le nouveau.

Points de terminaison des webhooks¶

Renseignez les URL de vos serveurs pour ces types de webhooks :

Champ sur la page	Déclenchement
Order with gift card webhook URL	Les cartes-cadeaux d'une commande sont traitées par Gift Card Hero
Gift card payment webhook URL	Une commande payée avec une carte-cadeau est créée
Gift card balance webhook URL	Non envoyé pour le moment (voir le guide d'intégration)

Saisissez l'URL de votre point de terminaison dans chaque champ, puis enregistrez. Une URL nouvelle ou modifiée doit commencer par https:// et être accessible depuis Internet ; les adresses de réseau privé sont refusées à l'enregistrement.

Guide d'intégration complet : Webhooks Integration Guide

Éditeur de code personnalisé¶

Ajoutez du CSS personnalisé aux composants de boutique de Gift Card Hero, sans modifier directement votre thème Shopify.

Cliquez sur Open custom code editor. Cela ouvre l'onglet Custom code dans Settings.

Éditeur de code personnalisé

Votre CSS est ajouté aux pages produit de carte-cadeau, à la page de carte-cadeau et aux pages des produits de carte-cadeau physique et à montant personnalisé. Il n'est pas ajouté au reste de votre boutique. Utilisez-le pour ajuster l'apparence du créateur de carte-cadeau et de la page de carte-cadeau. Cliquez sur Save dans la barre d'enregistrement pour appliquer vos modifications.

CSS uniquement

L'éditeur n'accepte que du CSS. Le CSS contenant </style est refusé à l'enregistrement. Le JavaScript personnalisé configuré pour votre boutique avant ce changement continue de fonctionner, mais il ne peut plus être modifié ici. Pour le changer, contactez le support.

Enregistrer les données des cartes-cadeaux dans un metafield¶

Cochez Save a gift card data to a metafield pour stocker les données de chaque carte-cadeau (design, message, expéditeur) dans un metafield Shopify sur votre boutique :

Espace de noms : gift_hero
Clé : cards_data

Les données sont indexées par les quatre derniers caractères du code de la carte-cadeau. Elles sont ainsi disponibles dans les modèles d'e-mail Shopify lors de la génération de la carte-cadeau, et dans vos propres modèles Liquid.

Disable gift card page animation for templates with suffix : désactive la page de carte-cadeau de l'application pour les cartes-cadeaux dont un suffixe de modèle est défini (voir template_suffix dans la REST API), pour afficher à la place votre propre modèle.

Mode headless¶

Activez le mode headless pour les boutiques en ligne Shopify personnalisées ou headless qui n'utilisent pas le système de thèmes standard de Shopify.

Cliquez sur Enable headless mode (le badge de statut passe à Enabled). Un extrait de code apparaît avec des valeurs fictives que vous remplacez par les données de votre boutique :

Espace réservé	Remplacer par
`[MONEY_FORMAT]`	La chaîne de format monétaire de votre boutique
`[PRODUCT_ID]`	L'identifiant numérique Shopify de votre produit carte-cadeau
`[MYSHOPIFY_DOMAIN]`	Le domaine `.myshopify.com` de votre boutique
`[ADD_TO_CART_CALLBACK]`	Votre fonction JavaScript personnalisée d'ajout au panier
`[LOCALE]`	Le code de langue de vos traductions (par ex. `en`, `fr`). `en` est la valeur par défaut

Copiez l'extrait et intégrez-le à votre base de code de boutique personnalisée.

Guide de configuration complet : Headless Integration Guide

Exécution personnalisée¶

Cette section n'apparaît que pour les boutiques qui utilisent l'option d'exécution autonome. Dans ce cas, Gift Card Hero se charge entièrement de créer et de livrer les cartes-cadeaux d'une commande, au lieu de l'exécution automatique des cartes-cadeaux de Shopify.

Désactivez d'abord l'exécution automatique dans Shopify

Dans les réglages de paiement (traitement des commandes) de Shopify, choisissez Don't fulfill any of the order's line items automatically. La page renvoie vers Check settings et vers un guide Shopify. Ne traitez pas vous-même les cartes-cadeaux d'une commande : elles doivent rester non exécutées.

Le badge indique le statut actuel (Enabled ou Disabled). Cliquez sur Enable custom fulfilment ou Disable custom fulfilment pour changer d'état.