Gérer les cartes cadeaux
Les cartes cadeaux permettent à vos clients de créditer une somme d’argent sur une carte pour un usage ultérieur.
Cette carte peut être offerte et permet à son porteur d’effectuer des achats dans votre commerce.
#1/ Installation
Dans la section Apps de votre compte, installez l’application 'Cartes cadeaux' (option Premium requise).
Un produit 'Cartes cadeaux' est automatiquement créé sur votre compte.
Ce produit est associé à votre taux de taxe par défaut. La TVA est normalement exigible à la vente de la carte, mais l'impact fiscal sera nul car la TVA payée à la vente de la carte est déduite lors de sa consommation.
Dans l’application, vous pouvez saisir une durée de validité par défaut en nombre de jours.
Si aucune durée n’est saisie (0) alors les cartes créées seront valables sans limite de temps.
Sinon, la durée de validité commencera à courir au jour de la vente de la carte.
Il est possible de modifier la date de validité d’une carte dans l’application.
#2/ Vente de la carte cadeau
Créez une vente et cliquez sur le bouton 'Cartes cadeaux' dans la partie droite de la vente.
Saisissez le Montant de la carte dans la section 'Vendre une carte cadeau'.
Le champ Validité indique la date d’échéance de la carte, que vous pouvez modifier. Laissez le champ vide si vous ne souhaitez pas limiter l’usage dans le temps de la carte cadeau.
Le champ Code permet de saisir le code d’une carte pré-imprimée. Ce code doit être unique. Laissez le champ vide si vous souhaitez qu’un code soit attribué automatiquement à la carte.
Cliquez sur le bouton 'Ajouter à la vente' pour valider la création de la carte: le produit 'Cartes cadeaux' est ajouté à la vente et le code de la carte est indiqué dans le champ S/N (numéro de série).
Cliquez sur le bouton en haut à droite 'Retour Vente'.
Puis finalisez la vente normalement avec le moyen de paiement utilisé pour payer la carte.
Pour vendre des cartes cadeaux depuis votre site internet, consultez la section 6 (API).
Sur internet, vous pouvez acheter des lots de cartes cadeaux pré-imprimées et personnalisées à l’image de votre commerce.
Si le champ S/N n’apparaît pas dans les ventes, allez dans 'Paramètres/Utilisateurs/Gestion des accès' et activez le droit : 'Gérer les numéros de série des produits'.
#3/ Utilisation de la carte cadeau
Créez une vente et ajoutez les produits achetés par le client.
Cliquez sur le bouton 'Cartes cadeaux' dans la partie droite de la vente.
Scannez ou tapez manuellement le code de la carte cadeau dans la section 'Utiliser une carte cadeau' et validez. Une ligne d’avoir correspondant au montant total de la carte est créé.
Finalisez la vente :
Si le montant de la vente est positif, encaissez votre client pour le reste à payer.
Si le montant de la vente est négatif, ajoutez une nouvelle carte cadeau avec le solde restant, en suivant la procédure de vente d’un bon cadeau. La vente sera à 0. Validez la avec n’importe quel moyen de paiement.
Si vous ne souhaitez pas générer un nouveau bon cadeau en cas de montant négatif de la vente, vous pouvez utiliser le crédit client, c’est à dire la mise en compte sur la fiche du client du solde restant. Pour cela, liez la vente à votre client et validez la avec le mode de paiement CRED. Plus d’informations sur le crédit client.
#4/ Suivi des cartes cadeaux
Dans l’application, vous pouvez suivre les cartes cadeaux émises, consommées et périmées.
Un tri est possible sur les résultats, qui peuvent être exportés.
Dans vos Synthèses :
le CA lié au produit 'Bons cadeaux' correspond aux cartes cadeaux émises.
le CA négatif lié au produit 'Avoirs/bons cadeaux' correspond aux cartes cadeaux consommées.
#5/ Impression d’une carte cadeau
Si vous n’utilisez pas des cartes cadeaux pré-imprimées, il est possible d’imprimer vos cartes cadeaux au format PDF ou au format ticket de caisse.
a/ Format PDF
– Installez l’application 'Documents PDF' dans la section Apps de votre compte.
– Télécharger le modèle type 'Carte cadeau' et modifiez le dans votre éditeur de texte.
– Enregistrez le fichier au format .odt et ajoutez le dans l’application 'Documents PDF'.
Dans la vente de la carte cadeau via le déroulant 'Action' (en haut à droite), appelez votre modèle 'Carte cadeau' pour générer le PDF de votre carte cadeau.
b/ Format ticket de caisse
– Dans 'Paramètres/Utilisateurs/Gestion des accès', activez le droit : 'Imprimer un billet individuel pour chaque produit de la vente'.
– Dans 'Paramètres/Impression/Billetterie', ajoutez le code suivant et modifiez le avec vos coordonnées:
#@@@@@@= =@@@@@@#
+@@@*..-*#. .#*-..*@@@*
=@@@- -= == -@@@+
:#@@#- #@@@@% -*@@#-
-##############****##############-
*@@@@@@@@@@@@@: :@@@@@@@@@@@@@#
*@@@@@@@@@@@@@: :@@@@@@@@@@@@@#
-+*************************-
#@@@@@@@@@@: :@@@@@@@@@@%
#@@@@@@@@@@: :@@@@@@@@@@%
#@@@@@@@@@@: :@@@@@@@@@@%
*@@@@@@@@@@: :@@@@@@@@@@#
<hibou_use_font_b>
<hibou_font_size>2|2
<hibou_bold>
HIBOUTIK
</hibou_bold>
<hibou_font_size>1|1
30 place du Centre - 01234 MAVILLE
01 23 45 67 89 - contact@hiboutik.com
-------------------------------------------
### <hibou_print_product_serial>###
-------------------------------------------
<hibou_font_size>2|2
<hibou_bold>
CARTE CADEAU
-- <hibou_print_price_product> EUR --
</hibou_bold>
<hibou_font_size>1|2
Code: <hibou_print_product_serial>
<hibou_font_size>1|1
Valable jusqu'au <hibou_print_product_comment>
-------------------------------------------
### <hibou_print_product_serial>###
-------------------------------------------
<hibou_print_this_code128_barcode><hibou_print_product_serial>
<hibou_use_font_a>
Généré le <hibou_print_date_time> - # <hibou_print_num_order_unique>
<hibou_cut_paper_partial>
Dans la partie Paiement de la vente de la carte cadeau, cliquez sur le bouton 'Billetterie' pour imprimer votre carte cadeau au format ticket de caisse.
#6/ API
L’application propose une API pour vendre des cartes cadeaux depuis un autre outil que la caisse, par exemple une page de vente en ligne avec paiement par Stripe, et pour consulter les cartes disponibles.
Cette section s’adresse à la personne qui développe votre site ou votre intégration.
Les cartes créées par l’API sont identiques à celles vendues en caisse : même produit 'Cartes cadeaux', code dans le champ S/N, date de validité dans le commentaire du produit, suivi dans l’application.
a/ Activer l’API
Dans l’application, ouvrez les Paramètres, puis dans la section API cliquez sur 'Générer une clé'.
L’adresse de l’API et la clé de votre compte s’affichent.
– La clé donne accès aux cartes cadeaux de votre compte : gardez-la secrète et utilisez-la uniquement depuis un serveur, jamais dans une page web visible par vos clients.
– Le bouton 'Régénérer la clé' désactive immédiatement l’ancienne clé : pensez à mettre à jour vos intégrations.
– Tant qu’aucune clé n’a été générée, l’API est désactivée pour votre compte.
b/ Appeler l’API
Toutes les requêtes utilisent l’adresse suivante, avec l’action souhaitée :
https://cartescadeaux.hiboutik.net/api/?account=account&action=...
La barre / avant le ? est obligatoire.
La clé est transmise dans l’en-tête HTTP Authorization (ou dans l’en-tête X-Api-Key) :
Authorization: Bearer VOTRE_CLE
Les réponses sont au format JSON.
c/ Vérifier la configuration : action=config
GET https://cartescadeaux.hiboutik.net/api/?account=account&action=config
Réponse :
{
"product_id": 7,
"product_label": "Cartes cadeaux",
"validity_days": 365,
"vat_rate": 0.2,
"can_sell": true
}
validity_days est la durée de validité par défaut, en jours (0 : sans limite de temps).
can_sell vaut false si le taux de TVA du produit 'Cartes cadeaux' est à 0 : l’API refuse alors de créer des cartes.
d/ Ajouter une carte cadeau à une vente : action=add
La carte est ajoutée à une vente ouverte de votre compte, créée par exemple avec l’API Hiboutik (POST /sales/).
POST https://cartescadeaux.hiboutik.net/api/?account=account&action=add
Content-Type: application/json
{ "sale_id": 1001, "amount": 50 }
Paramètres, en JSON ou en formulaire :
– sale_id (obligatoire) : numéro de la vente, qui doit être encore ouverte.
– amount (obligatoire) : montant TTC de la carte, par exemple 50 ou 49.90.
– code (facultatif) : code d’une carte pré-imprimée, qui doit être unique (3 à 64 caractères : lettres, chiffres, - et _). Sans code, un code est attribué automatiquement.
– validite (facultatif) : date d’échéance au format AAAA-MM-JJ. Sans ce paramètre, la durée de validité par défaut s’applique. Envoyé vide, la carte est valable sans limite de temps.
Réponse (code HTTP 201) :
{
"card": {
"code": "1001hi555",
"amount": 50,
"validite": "2027-11-16",
"sale_id": 1001,
"line_item_id": 555,
"product_id": 7
}
}
La carte devient utilisable une fois la vente clôturée, c’est-à-dire payée. Elle peut alors être utilisée en caisse comme indiqué en section 3.
Tant que la vente n’est pas finalisée, la carte n’apparaît pas dans les cartes disponibles.
e/ Lister les cartes disponibles : action=list
Une carte est disponible quand elle a été vendue (vente clôturée), qu’elle n’a pas encore été utilisée et qu’elle n’est pas archivée.
Par défaut, les cartes dont la date de validité est passée ne sont pas listées.
GET https://cartescadeaux.hiboutik.net/api/?account=account&action=list
Filtres facultatifs :
– code : une carte précise, par exemple pour vérifier une carte avant de l’accepter.
– sale_id : les cartes vendues sur une vente.
– include_expired=1 : inclure les cartes périmées, signalées par "expired": true.
– limit (100 par défaut, 500 au plus) et offset : pagination.
Réponse :
{
"total": 1,
"limit": 100,
"offset": 0,
"cards": [
{
"code": "1001hi555",
"amount": 50,
"validite": "2027-11-16",
"expired": false,
"date_sold": "2026-11-16 14:05:12",
"sale_id": 1001,
"line_item_id": 555,
"store_id_sold": 1
}
]
}
Une carte valable sans limite de temps a une validite vide ("").
f/ Consulter une carte : action=card
Renvoie une carte précise, quel que soit son état, par exemple pour afficher la carte à son bénéficiaire.
GET https://cartescadeaux.hiboutik.net/api/?account=account&action=card&code=1001hi555
Réponse :
{
"card": {
"code": "1001hi555",
"amount": 50,
"validite": "2027-11-16",
"expired": false,
"date_sold": "2026-11-16 14:05:12",
"sale_id": 1001,
"line_item_id": 555,
"store_id_sold": 1,
"status": "available",
"date_used": ""
}
}
status indique l’état de la carte : – pending : la vente de la carte n’est pas encore clôturée (paiement en attente). – available : la carte peut être utilisée. – expired : la date de validité est passée. – used : la carte a déjà été utilisée (date dans date_used). – archived : la carte a été archivée dans l’application.
g/ Erreurs
En cas d’erreur, l’API renvoie un code HTTP et un message :
{ "error": "sale_closed", "error_description": "La vente est déjà clôturée." }
– 401 unauthorized : clé absente ou invalide pour ce compte.
– 404 sale_not_found : vente introuvable.
– 404 card_not_found : carte introuvable.
– 409 sale_closed : la vente est déjà clôturée.
– 409 code_in_use : ce code est déjà attribué à une autre carte.
– 409 vat_zero : le taux de TVA du produit 'Cartes cadeaux' est à 0.
– 409 not_configured : produit 'Cartes cadeaux' introuvable. Ouvrez l’application dans Hiboutik pour le recréer.
– 422 invalid_sale_id, invalid_amount, invalid_code, invalid_validite : paramètre manquant ou invalide.
– 502 hiboutik_error : la carte n’a pas pu être ajoutée à la vente.