Gift Card Hero REST API¶

L'API REST vous permet de gérer les cartes-cadeaux par programmation depuis des systèmes externes : CRM, tableaux de bord analytiques, plateformes de fidélité, services de logistique, et plus encore.

Configuration de l'API REST

URL de base¶

Toutes les requêtes API utilisent l'URL de base suivante :

https://gifthero.syncu.be/api/external

Authentification¶

Chaque requête doit inclure un jeton Bearer dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_TOKEN

Pour obtenir votre jeton API, allez dans For developers dans le menu de gauche, cochez Enable REST API et enregistrez. Cliquez sur Send me access token : le jeton est envoyé à l'adresse e-mail de contact de la boutique affichée sur la page.

Le jeton n'expire pas tant que vous ne le remplacez pas ou ne le révoquez pas. Traitez-le comme un mot de passe : stockez-le dans les paramètres secrets de votre intégration, et ne le collez pas dans des discussions, des tickets ou des documents partagés.

Gérer votre jeton API¶

Un seul jeton à la fois. Votre boutique dispose d'un seul jeton API. Chaque système qui appelle l'API (un POS, un CRM, le service d'un partenaire) utilise ce même jeton.

Envoyer un nouveau jeton remplace l'ancien. Chaque clic sur Send me access token émet un nouveau jeton, et le précédent cesse immédiatement de fonctionner. Mettez à jour toutes les intégrations avec le nouveau jeton sans attendre. Si vous voulez seulement retrouver le jeton, recherchez l'e-mail précédent au lieu d'en envoyer un nouveau.

Révoquer un jeton. Si un jeton a pu fuiter, ou si un partenaire qui le possédait ne travaille plus avec vous, cliquez sur Revoke access token sur la page For developers et confirmez. Le jeton cesse immédiatement de fonctionner, et aucun nouveau jeton n'est émis. Quand vous êtes prêt, cliquez sur Send me access token pour en émettre un nouveau.

Désactiver l'API REST. Désactiver Enable REST API puis enregistrer révoque aussi le jeton. Après avoir réactivé l'API, envoyez-vous un nouveau jeton.

Ce que voit votre intégration. Une requête avec un jeton remplacé ou révoqué reçoit une réponse 401 :

{
  "error": {
    "statusCode": 401,
    "name": "UnauthorizedError",
    "message": "Error verifying token : The token has been revoked or replaced."
  }
}

La solution est toujours la même : placez le jeton actuel dans l'en-tête Authorization.

Les jetons émis avant l'introduction des identifiants de jeton continuent de fonctionner jusqu'à la première fois que vous envoyez un nouveau jeton ou révoquez le jeton.

Autres erreurs d'authentification :

Statut	Signification
`401`	L'en-tête `Authorization` est absent ou n'est pas de type `Bearer`, ou le jeton n'est pas valide
`402`	La boutique n'a pas de forfait Gift Card Hero actif

Points de terminaison¶

Lister les cartes-cadeaux¶

GET /gift-cards

Paramètres :

Paramètre	Type	Description
`status`	string	Filtrer par statut de carte-cadeau
`limit`	integer	Nombre maximal de résultats (250 max.)
`since_id`	string	Renvoyer les résultats après cet identifiant de carte-cadeau
`fields`	string	Liste de champs séparés par des virgules à inclure

La requête est transmise à la liste des cartes-cadeaux de Shopify, donc les paramètres propres à Shopify s'appliquent. Chaque carte de la réponse contient un objet recipient (id, email, name) ou null. Un champ code est inclus lorsque Gift Card Hero a le code complet enregistré (voir Notes importantes).

Une requête HEAD /gift-cards renvoie 200 sans corps. Certains clients HTTP l'utilisent comme contrôle préalable.

Lister les cartes-cadeaux avec leurs transactions¶

GET /gift-cards/transactions

Renvoie les cartes-cadeaux, les plus récentes en premier, chacune avec jusqu'à ses 50 transactions les plus récentes. Prend en charge la pagination par curseur.

Pagination :

Paramètre	Type	Description
`limit`	integer	Cartes-cadeaux par page (50 par défaut)
`page_info`	string	Curseur de la page de résultats suivante

Filtres :

Filtre	Type	Description
`query`	string	Requête de recherche, selon la syntaxe de recherche des cartes-cadeaux de Shopify
`balance_status`	string	Une des valeurs : `full`, `partial`, `empty`, `full_or_partial`
`created_at`	string	Filtrer par date de création
`expires_on`	string	Filtrer par date d'expiration
`source`	string	Une des valeurs : `manual`, `purchased`, `api_client`
`status`	string	Une des valeurs : `disabled`, `enabled`, `expired`, `expiring`
`initial_value`	string	Filtrer par valeur initiale
`id`	string	Filtrer par identifiant de carte-cadeau

Tous les filtres utilisent la logique ET lorsqu'ils sont combinés.

Réponse :

Chaque carte-cadeau contient id, balance, currency, initial_value, created_at, updated_at, disabled_at, customer_id, recipient, note, expires_on, template_suffix, last_characters, order_id, transactions et issued_by. La réponse n'inclut pas le code de la carte-cadeau. Chaque transaction contient id, amount (négatif pour un débit), processed_at, note, pos_user et pos_order_name.

Identifiants de transaction :

transactions[].id est l'identifiant Shopify numérique de la transaction de carte-cadeau, c'est-à-dire le nombre à la fin de son GID gid://shopify/GiftCardDebitTransaction/… ou gid://shopify/GiftCardCreditTransaction/…. Les versions précédentes de l'API renvoyaient null ici.

Champs POS :

Les cartes-cadeaux émises ou utilisées via le POS Gift Card Hero indiquent le caissier qui a effectué l'opération. Ces champs sont ajoutés à la réponse standard :

Champ	Type	Description
`transactions[].pos_user`	object or null	`{ "username": "woodgrove", "name": "Woodgrove" }` pour un débit effectué au POS ; `null` sinon
`transactions[].pos_order_name`	string or null	Nom de commande saisi au POS pour ce débit, le cas échéant ; `null` sinon
`issued_by`	object or null	`{ "username", "name", "issued_at" }` pour une carte émise au POS ; `null` sinon

Le journal d'activité du POS ne stocke pas les identifiants de transaction Shopify : un débit est donc associé à une utilisation au POS par carte, montant et heure (l'utilisation doit avoir été enregistrée de quelques secondes avant à une minute après la transaction). Les paiements en ligne, les modifications faites dans l'administration Shopify et les débits sans enregistrement POS correspondant reçoivent null. name vaut null si l'utilisateur du POS a depuis été supprimé.

Obtenir une carte-cadeau¶

GET /gift-cards/{gift_card_id}

Renvoie les détails d'une carte-cadeau à partir de son identifiant, avec son recipient et, lorsque Gift Card Hero le possède, son code.

Créer une carte-cadeau¶

POST /gift-cards

Corps de la requête :

{
  "note": "Loyalty reward",
  "initial_value": "50.00",
  "code": "ABCD-EFGH-IJKL-MNOP",
  "template_suffix": "custom"
}

Champ	Type	Obligatoire	Description
`note`	string	Non	Note interne de la carte-cadeau
`initial_value`	string	Oui	Solde de départ
`code`	string	Non	Code de carte-cadeau personnalisé (doit être unique ; généré automatiquement si omis)
`template_suffix`	string	Non	Suffixe de modèle Shopify
`customer_id`	integer	Non	Client Shopify propriétaire de la carte
`email`	string	Non	E-mail du client, utilisé lorsque `customer_id` n'est pas envoyé. Gift Card Hero retrouve le client, ou en crée un avec le tag `gifthero:import`

Le corps est transmis au point de terminaison des cartes-cadeaux de Shopify, qui accepte d'autres champs comme expires_on. La réponse est la carte-cadeau Shopify, y compris le code complet.

Important : Conservez le code complet de la réponse de création si vous en avez besoin. Les réponses suivantes n'incluent le code complet que pour les cartes dont Gift Card Hero a le code enregistré ; sinon, seuls les 4 derniers caractères (last_characters) sont renvoyés.

Mettre à jour le solde d'une carte-cadeau¶

PUT /gift-cards/{gift_card_id}/balance

Corps de la requête :

{
  "balance": "100.00"
}

Définit le solde de la carte-cadeau à la valeur indiquée. Une valeur précédée d'un signe, comme "+25.00" ou "-10.00", est appliquée comme un ajustement du solde actuel. Si le solde ne change pas, le solde actuel est renvoyé et rien n'est enregistré. Lorsque la boutique a Increase limit activé, un rechargement peut dépasser la limite standard des cartes-cadeaux Shopify.

Il s'agit d'une correction de solde : aucune notification n'est envoyée au client et aucun point de vente n'est enregistré. Lorsqu'un client utilise la carte en caisse, utilisez plutôt Utiliser une carte-cadeau.

Utiliser une carte-cadeau¶

POST /gift-cards/{gift_card_id}/redeem

Débite (utilise) une carte-cadeau depuis un POS ou une application de caisse tierce, en dehors du paiement Shopify. Le titulaire de la carte reçoit la notification d'utilisation de votre boutique (e-mail ou SMS) avec le nom du point de vente, ou l'acheteur à la place, ou les deux, si Who gets notified dans vos paramètres de notifications d'utilisation le prévoit. L'utilisation apparaît avec son point de vente dans les rapports de Gift Card Hero. Utilisez cette méthode plutôt que d'appeler directement giftCardDebit de Shopify : un débit direct n'envoie ni point de vente ni notification.

Utiliser ou mettre à jour le solde : utilisez Update gift card balance pour fixer le solde à une valeur sans prévenir qui que ce soit. Utilisez Redeem lorsqu'un client dépense la carte et que vous voulez enregistrer la notification et le point de vente.

Corps de la requête :

{
  "amount": "1500.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "note": "Table 12"
}

Champ	Type	Obligatoire	Description
`amount`	string	Oui	Montant à utiliser. Doit être supérieur à 0 et ne pas dépasser le solde de la carte, dans la devise de la carte, avec 2 décimales maximum
`branch`	string	Oui	Nom du point de vente ou du site. Affiché dans l'e-mail et le SMS d'utilisation (lorsque Include the store location est activé dans les notifications d'utilisation) et dans les rapports
`reference`	string	Oui	Votre identifiant unique pour cette utilisation, 255 caractères maximum. Voir Nouvelles tentatives et doublons
`note`	string	Non	Écrit sur la transaction de carte-cadeau dans Shopify. Gift Card Hero ajoute `[ref:<reference>]` à la note, afin que vous puissiez retrouver chaque utilisation API par sa référence dans l'administration Shopify

Réponse (200) :

{
  "id": 661944893757,
  "last_characters": "7nsf",
  "amount": "1500.00",
  "currency": "KES",
  "balance_before": "5090.00",
  "balance": "3590.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "processed_at": "2026-10-12T10:30:00Z",
  "notification": "queued",
  "duplicate": false
}

Champ	Description
`notification`	`queued` : la notification d'utilisation a été transmise aux paramètres de notifications d'utilisation de votre boutique, qui décident de l'envoi (à chaque utilisation, ou seulement lorsque la carte est entièrement utilisée). `disabled` : les notifications d'utilisation sont désactivées pour votre boutique
`duplicate`	`true` lorsque cette `reference` a déjà été traitée et que la réponse est le résultat d'origine

Erreurs :

Les erreurs suivent le format habituel : {"error": {"statusCode": 422, "name": "...", "message": "..."}}.

Statut	Signification	Que faire
`400`	`amount`, `branch` ou `reference` est absent ou invalide	Corrigez le corps de la requête
`401`	Le jeton est absent, invalide, révoqué ou remplacé par un plus récent	Vérifiez l'en-tête `Authorization`. Si le jeton a été révoqué ou remplacé, demandez-en un nouveau
`403`	L'application n'a pas une autorisation d'accès sur votre boutique	Le propriétaire de la boutique doit approuver les nouvelles autorisations de l'application dans l'administration Shopify
`404`	Carte-cadeau introuvable	Vérifiez l'identifiant de la carte-cadeau
`409`	La `reference` a déjà été utilisée pour une autre carte ou un autre montant, ou une requête avec cette `reference` est encore en cours de traitement	Pour une nouvelle utilisation, utilisez une nouvelle `reference`. Si la requête est encore en cours, attendez quelques secondes et réessayez avec la même `reference`
`422`	La carte est désactivée ou expirée, ou le montant dépasse le solde. Le `message` indique lequel. Le solde n'a pas changé	Corrigez la cause. La `reference` n'est pas consommée : réessayez avec la même
`429`	Shopify limite le nombre de requêtes de votre boutique	Patientez et réessayez avec la même `reference`
`500`	Le résultat n'a pas pu être confirmé auprès de Shopify	Réessayez avec la même `reference` : la carte ne sera pas débitée deux fois

Une requête échouée (404 ou 422) ne consomme pas la reference.

Nouvelles tentatives et doublons¶

Générez une reference par utilisation, et réutilisez-la uniquement lorsque vous réessayez cette même utilisation. Si une requête expire ou échoue sur le réseau, réessayez avec la même reference. C'est toujours sans risque : la carte n'est jamais débitée deux fois, et vous recevez le résultat d'origine avec "duplicate": true.

Mettre à jour une carte-cadeau¶

PUT /gift-cards/{gift_card_id}

Seuls les champs suivants peuvent être mis à jour :

Champ	Type	Description
`expires_on`	string	Date d'expiration
`note`	string	Note interne
`template_suffix`	string	Suffixe de modèle Shopify
`customer_id`	integer	Client Shopify propriétaire de la carte. Vous pouvez envoyer `email` à la place, comme lors de la création d'une carte

La réponse inclut le code lorsque Gift Card Hero l'a enregistré.

Désactiver une carte-cadeau¶

POST /gift-cards/{gift_card_id}/disable

Désactive définitivement la carte-cadeau. Cette action ne peut pas être annulée. Renvoie la carte-cadeau désactivée.

Rechercher des cartes-cadeaux¶

GET /gift-cards/search

Paramètres :

Paramètre	Type	Description
`order`	string	Ordre de tri
`query`	string	Requête de recherche, par exemple `last_characters:mnop`. Utilisez `recipient:name@example.com` pour trouver les cartes envoyées à un destinataire
`limit`	integer	Nombre maximal de résultats
`fields`	string	Liste de champs séparés par des virgules à inclure

Champs indexés (disponibles pour les requêtes de recherche) :

created_at, updated_at, disabled_at, balance, initial_value, amount_spent, last_characters

Attribuer des codes de cartes-cadeaux à une commande¶

POST /gift-cards/assign-to-order

Attribue vos propres codes de cartes-cadeaux à une commande Shopify, pour les boutiques qui génèrent les codes en dehors de l'application. Cela ne fonctionne que lorsque Skip gift codes generation est activé dans les paramètres de Regular products as gift cards ; sinon, il renvoie 400. Il renvoie aussi 400 si orderId n'est pas numérique ou si un code existe déjà dans votre boutique, et 404 si la commande est introuvable.

Prend en charge l'attribution d'un code unique comme de plusieurs codes.

Code unique :

{
  "orderId": "1234567890",
  "giftCode": "ABCD-EFGH-IJKL-MNOP"
}

Plusieurs codes :

{
  "orderId": "1234567890",
  "giftCodes": [
    { "lineItemId": "111", "code": "ABCD-EFGH-IJKL-MNOP" },
    { "lineItemId": "222", "code": "QRST-UVWX-YZ12-3456" }
  ]
}

Réponse :

{
  "scheduled": true
}

scheduled vaut false lorsque la commande n'a aucune carte-cadeau à traiter.

Pagination¶

Le point de terminaison des transactions utilise la pagination par curseur. La réponse inclut un en-tête Link avec le curseur de la page suivante :

Link: <https://gifthero.syncu.be/api/external/gift-cards/transactions?page_info=CURSOR>; rel="next"

L'en-tête est absent sur la dernière page. Extrayez la valeur page_info de l'en-tête Link et transmettez-la comme paramètre de requête dans votre requête suivante, avec les mêmes filtres. L'URL de la page suivante les contient déjà.

Notes importantes¶

Unicité des codes : lors de la création de cartes-cadeaux avec des codes personnalisés, chaque code doit être unique. L'API renvoie une erreur si un code en double est envoyé.
Visibilité des codes : la réponse de création inclut le code complet. Dans les réponses suivantes, un champ code n'apparaît que pour les cartes dont Gift Card Hero a le code complet enregistré (cartes qu'il a générées et codes que vous avez attribués). Sinon, seuls les 4 derniers caractères (last_characters) sont renvoyés. Le point de terminaison des transactions ne renvoie jamais de codes.
Nouvelles tentatives d'utilisation : envoyez toujours une reference unique lors de l'utilisation d'une carte-cadeau, et réessayez avec la même reference après un délai d'attente. Voir Nouvelles tentatives et doublons.
Limites de débit : les requêtes sont transmises à Shopify, donc les limites de Shopify pour votre boutique s'appliquent. Si vous recevez une réponse 429, patientez et réessayez.
Collection Postman : elle couvre les points de terminaison des cartes-cadeaux, sauf /gift-cards/transactions et /gift-cards/assign-to-order.

Collection Postman¶

Téléchargez la collection Postman pour explorer rapidement l'API :

Télécharger la collection Postman