Documentation fonctionnelle et API KWISATZ

Gestion de la fidélité ZEROSIX

L’interface ZEROSIX externalise la gestion de la fidélité dans une plateforme cloud. KWISATZ recherche ou crée les clients, transmet les tickets encaissés, puis récupère les points, la cagnotte et les bons voucher à afficher ou utiliser en caisse.

Télécharger cette fiche en PDF
Fiche : FID-ZS-001 Module : Vente directe / Fidélité cloud Public : administrateur ou technicien Risque : élevé Catégorie : Fidélité, cartes, abonnements et campagnes clientsMise à jour : 6 août 2026

Réponse directe

Ouvrez Outils > Préférences > Divers > Vente directe > Plateforme ZEROSIX (Fidélité cloud). Cochez Activer, renseignez l’URL API et le token fournis par ZEROSIX, choisissez Programme Cycle ou Programme Cagnotte, puis configurez le règlement voucher, les exclusions et les temporisations. Testez toujours une recherche client avant toute création.
Ne saisissez jamais le token dans la zone URL et ne publiez jamais la clé API dans une capture, un courriel ou une documentation publique.

Conseil technicien général

1. Repères de version

Les références de version ci-dessous sont conservées comme repères documentaires. Les menus, options et comportements doivent être contrôlés sur la version et la sérialisation réellement installées ; une évolution plus récente peut avoir modifié le fonctionnement.

2. Licence et disponibilité

La dépendance de licence mentionnée dans ce document provient des sources. Sa disponibilité peut varier selon la version, la sérialisation, le partenaire ou l’installation ; faites-la valider techniquement avant de modifier l’environnement.

3. Distinguer abonnements et fidélité

Les abonnements correspondent à des prestations disponibles et consommables dans les tickets lorsque le client est sélectionné. Ils ne doivent pas être confondus avec les points ou passages de fidélité. Un devis, une facture, un rendez-vous ou un mouvement financier ne constitue pas, à lui seul, une consommation d’abonnement.

Évitez le double avantage : ne cumulez pas correction du ticket, ajout manuel et recalcul de fidélité. Lors d’un oubli de carte, corrigez le rattachement du ticket sans créditer manuellement une seconde fois.

4. Distinguer KWISATZ des opérations externes

Un enregistrement dans KWISATZ ne prouve pas automatiquement qu’une opération a été exécutée dans un système externe : débit ou remboursement TPE, mouvement physique d’espèces, envoi de SMS ou d’e-mail, ou action réalisée sur une plateforme.

5. Protection des données

6. Architecture de l’interface

Composant Rôle
KWISATZ Vente directe Identifie le client, saisit et encaisse le ticket, propose l’utilisation de la cagnotte ou des vouchers.
API ZEROSIX Recherche, crée et met à jour les contacts ; reçoit les tickets ; calcule les points, avantages et soldes.
Fiche client KWISATZ Conserve les données locales et le champ CLOUD_ID qui relie la fiche au contact ZEROSIX.
Back-office ZEROSIX Définit le programme, les seuils, exclusions, promotions, vouchers et règles marketing.
Règlement KWISATZ Comptabilise l’utilisation d’un voucher ou de la cagnotte selon le mode retenu.
Après encaissement, KWISATZ transmet le ticket à ZEROSIX. La plateforme recalcule la situation de fidélité et la renvoie pour affichage et impression sur le ticket.

7. Prérequis

  • compte commerçant ZEROSIX opérationnel ;
  • URL API fournie par ZEROSIX ;
  • token valide ;
  • programme Cycle ou Cagnotte défini dans l’abonnement ;
  • module ZEROSIX actif sur les caisses concernées ;
  • version KWISATZ récente, idéalement 3.56R4 ou supérieure pour les nouveaux réglages ;
  • connexion Internet stable et HTTPS autorisé ;
  • mode de règlement dédié aux vouchers ;
  • clavier et écran de caisse permettant la recherche ZEROSIX ;
  • politique de consentement et d’information des clients.
Si ZEROSIX remplace une ancienne fidélité, désactivez ou neutralisez les anciennes règles afin d’éviter un double calcul des avantages.

8. Configurer la plateforme ZEROSIX

  1. Ouvrez Outils > Préférences.
  2. Sélectionnez l’onglet Divers.
  3. Ouvrez la section Vente directe.
  4. Dépliez Plateforme ZEROSIX (Fidélité cloud).
  5. Cochez Activer.
  6. Renseignez l’adresse de l’API dans URL.
  7. Renseignez la clé dans Token.
  8. Sélectionnez le type de programme souscrit.
  9. Choisissez le mode de règlement des bons voucher.
  10. Définissez le mode de reprise des vouchers.
  11. Configurez les exclusions promotion et remise.
  12. Réglez le minimum de caractères de recherche et les temporisations.
  13. Enregistrez puis relancez KWISATZ si la version l’exige.
Zone Rôle Conseil
Activer Met en service la fidélité ZEROSIX. Ne l’activer qu’après saisie de l’URL et du token.
URL Adresse de l’API ZEROSIX. Utiliser exactement l’adresse fournie, sans inventer de suffixe.
Token Clé d’authentification du compte commerçant. Conserver le secret hors des documents publics.
Type de programme Cycle ou Cagnotte. Doit correspondre au contrat ZEROSIX.
Bon voucher — règlement associé Règlement KWISATZ utilisé pour la valeur des vouchers. Créer un règlement distinct et contrôlé comptablement.
Reprise voucher par vente négative Remplace la valeur financière du règlement par des lignes négatives. Tester la TVA et le pont comptable avant activation.
Exclure les ventes en promotion Marque les lignes concernées pour exclusion du calcul ZEROSIX. Comparer avec les règles du back-office.
Exclure les ventes avec remise Écarte les lignes remisées du calcul de fidélité selon le paramétrage. Tester remises de ligne et de pied.
Recherche client — nombre minimum Nombre de caractères avant l’appel de recherche. Minimum et défaut documentés : 3 ; augmenter si les réponses sont trop larges.
Connexion — Timeout Délai maximal d’établissement de la connexion. Minimum et défaut documentés : 10 secondes.
Requêtes — Timeout Délai maximal de lecture d’une réponse API. Minimum et défaut documentés : 10 secondes.
Repère de diagnostic : PREFERENCES.INI. Ce repère interne ne doit pas être modifié directement. Faites analyser et valider le réglage par un technicien KWISATZ après sauvegarde et relevé de la configuration.

9. Choisir le bon type de programme

Programme Fonctionnement Utilisation en caisse
Cycle Le client cumule des points. Lorsqu’un seuil est atteint, ZEROSIX crée automatiquement un voucher. Le voucher peut accorder une valeur fixe ou un pourcentage de remise.
Cagnotte Les points sont convertis en euros placés immédiatement dans une cagnotte. La cagnotte peut régler totalement ou partiellement le ticket comme un porte-monnaie électronique.
Un mauvais type de programme peut expliquer l’absence de voucher, l’indisponibilité de la cagnotte ou un solde incohérent dans la caisse.
La sélection explicite Cycle/Cagnotte est documentée dans la version 3.56R4. Sur une ancienne version, mettez KWISATZ à jour avant de diagnostiquer la fidélité.

10. Rechercher, créer et associer les clients

Le champ identifiant cloud interne constitue la liaison principale entre la fiche locale KWISATZ et le contact ZEROSIX.

Client déjà présent dans ZEROSIX

  1. Ouvrez la recherche ZEROSIX depuis la caisse.
  2. Saisissez au moins le nombre de caractères configuré.
  3. Sélectionnez le client dans les résultats.
  4. Si aucune fiche KWISATZ n’est associée, KWISATZ peut créer une fiche locale.
  5. Si une fiche est déjà liée, elle est actualisée.
  6. Contrôlez le CLOUD_ID après validation.
Les informations ZEROSIX sont considérées comme source lors de l’actualisation d’une fiche associée. Identifiez les champs susceptibles d’écraser une donnée locale.

Client absent des deux bases

  1. Utilisez la fonction de création depuis ZEROSIX/KWISATZ.
  2. Complétez la fiche client.
  3. Recueillez le consentement ou l’information nécessaire.
  4. Validez.
  5. KWISATZ crée le contact sur la plateforme et la fiche locale.
  6. Vérifiez que CLOUD_ID contient l’identifiant retourné.

Client présent dans les deux bases sans association

  1. Recherchez le client dans ZEROSIX.
  2. Utilisez la fonction d’association.
  3. Sélectionnez la fiche KWISATZ existante.
  4. Confirmez l’association.
  5. Vérifiez qu’aucune nouvelle fiche n’a été créée.

Client présent uniquement dans KWISATZ

  1. Sélectionnez la fiche KWISATZ.
  2. Utilisez la fonction de création dans ZEROSIX.
  3. Contrôlez le téléphone et les informations obligatoires.
  4. Validez puis contrôlez le CLOUD_ID.
Le téléphone n’est pas une clé unique fiable dans KWISATZ. Ne dédupliquez pas automatiquement deux fiches uniquement parce qu’elles partagent le même numéro. Comparez code client, identité et CLOUD_ID.

11. Qualité des données clients

  • normaliser les numéros de téléphone ;
  • éviter les espaces et séparateurs incohérents pour les portables lorsque le connecteur exige un format précis ;
  • contrôler nom, prénom, courriel et date de naissance selon les règles du programme ;
  • rechercher les fiches sans CLOUD_ID ;
  • rechercher plusieurs fiches KWISATZ portant le même CLOUD_ID ;
  • faire corriger par ZEROSIX les doublons existant côté plateforme ;
  • ne jamais remplacer manuellement un CLOUD_ID sans procédure.
Si plusieurs contacts ZEROSIX possèdent le même téléphone, la fusion ou la correction doit être validée côté plateforme.

12. Traiter un ticket avec fidélité ZEROSIX

  1. Recherchez et sélectionnez le client ZEROSIX.
  2. Contrôlez la situation fidélité affichée.
  3. Saisissez les produits normalement.
  4. Appliquez les promotions et remises prévues.
  5. Appuyez sur Total.
  6. Utilisez la cagnotte ou un voucher si proposé.
  7. Encaissez le solde.
  8. Finalisez le ticket.
  9. KWISATZ transmet le ticket à ZEROSIX.
  10. ZEROSIX recalcule les points ou la cagnotte.
  11. KWISATZ récupère et imprime la nouvelle situation.
Un ticket fiscal déjà validé ne doit pas être modifié directement pour corriger une situation de fidélité. Analysez le ticket et les échanges API, puis utilisez la procédure de correction prévue.
Les versions récentes transmettent un identifiant de ticket permettant de rapprocher le ticket KWISATZ de son enregistrement ZEROSIX.

13. Gérer les bons voucher

Dans le programme Cycle, la plateforme transforme les points en voucher lorsqu’un seuil est atteint. Un voucher peut être exprimé en euros ou en pourcentage.

  1. Sélectionnez le client.
  2. Saisissez les articles.
  3. Appuyez sur Total.
  4. KWISATZ affiche les vouchers disponibles.
  5. Sélectionnez le bon à utiliser.
  6. Contrôlez sa valeur, son type et sa validité.
  7. Validez.
  8. Encaissez le reste éventuel.
  9. Vérifiez le code ZEROSIX imprimé sur le ticket.
  10. Contrôlez que le voucher n’est plus disponible ensuite.

Mode classique

Le voucher est comptabilisé avec le règlement KWISATZ associé.

Mode « Reprise voucher par vente négative »

Le règlement est conservé avec un montant nul pour imprimer le code du voucher, tandis que KWISATZ insère des lignes négatives qui réduisent le total. La ventilation est calculée selon le prorata de TVA représenté sur le ticket.

  • voucher en valeur : articles système de famille ZCOUPON01XX ;
  • voucher en pourcentage : articles système de famille ZCOUPON02XX selon la version ;
  • XX représente le code de TVA rattaché ;
  • quantité générée : -1.
Ne créez pas manuellement ces articles système et ne saisissez pas leurs lignes pour simuler une reprise. Le contrôle du voucher doit précéder leur génération.
Faites valider le mode classique ou vente négative par le comptable, puis comparez chiffre d’affaires, TVA, règlements et pont comptable.

14. Utiliser le programme Cagnotte

Dans le programme Cagnotte, les points sont convertis en euros et peuvent être utilisés sans attendre la génération d’un voucher.

  1. Sélectionnez un client lié par CLOUD_ID.
  2. Contrôlez le solde retourné par ZEROSIX.
  3. Saisissez le ticket.
  4. À Total, choisissez le montant de cagnotte à utiliser si la version le permet.
  5. Vérifiez qu’il ne dépasse ni le solde ni le total autorisé.
  6. Encaissez le complément.
  7. Finalisez le ticket.
  8. Contrôlez le nouveau solde côté caisse et plateforme.
L’usage direct de la cagnotte a fait l’objet d’évolutions autour de la branche 3.56. Une ancienne version peut uniquement proposer les vouchers du programme Cycle.
En cas d’erreur de communication après la demande de débit, vérifiez d’abord le solde ZEROSIX et le ticket transmis avant de refaire l’opération.

15. Promotions, remises et exclusions

Les options d’exclusion permettent de signaler à ZEROSIX que certaines ventes ne doivent pas produire d’avantage.

Option But Test conseillé
Exclure les ventes bénéficiant d’une promotion Ne pas cagnotter ou attribuer de points sur les lignes promotionnelles. Comparer un article au tarif normal et le même article en promotion.
Exclure les ventes bénéficiant d’une remise Écarter les lignes ou tickets remisés selon le fonctionnement documenté. Tester remise de ligne, remise globale et remise client.
Catégorie transmise Permet des exclusions ou règles dans le back-office ZEROSIX. Vérifier que le code famille attendu est transmis.
KWISATZ active une information de type Is_Promo selon les options afin que ZEROSIX applique ses règles d’exclusion.
Après une évolution des promotions ou du mapping des familles, contrôlez un ticket complet côté KWISATZ et côté ZEROSIX.

16. Multi-caisses et licences

Chaque caisse autonome qui communique directement avec ZEROSIX doit disposer du module et de sa propre configuration opérationnelle.

Poste Module ZEROSIX
Caisse autonome recherchant les clients et transmettant les tickets Requis.
Caisse autonome utilisant cagnotte et vouchers Requis.
Back-office sans encaissement Généralement non requis pour l’exploitation de caisse.
Poste rattaché à une architecture centralisée À valider selon la licence et l’architecture réelle.
Avant le devis, distinguez les caisses autonomes des simples postes connectés à un back-office central. Le nombre de modules dépend de l’architecture.

17. Données personnelles et sécurité

  • informer le client du transfert de ses données vers la plateforme ;
  • ne transmettre que les données nécessaires au programme ;
  • protéger le token API ;
  • limiter l’accès aux préférences ;
  • ne pas publier les CLOUD_ID réels ;
  • prévoir la correction, l’opposition et la suppression selon les procédures contractuelles ;
  • anonymiser les tickets transmis au support ;
  • ne pas conserver le token dans les journaux ou captures ;
  • documenter la source de vérité de chaque champ client ;
  • contrôler les doublons avant une campagne marketing.
Un token ZEROSIX permet d’accéder aux données et opérations du compte commerçant. Traitez-le comme un secret critique.

18. Recette avant mise en production

  1. Tester l’URL et le token.
  2. Rechercher un client existant.
  3. Créer un client absent des deux bases.
  4. Associer un client existant dans les deux bases.
  5. Créer dans ZEROSIX un client déjà présent dans KWISATZ.
  6. Contrôler les CLOUD_ID.
  7. Encaisser un ticket sans promotion.
  8. Encaisser un ticket promotionnel.
  9. Encaisser un ticket avec remise.
  10. Contrôler les points ou la cagnotte.
  11. Utiliser un voucher en valeur.
  12. Utiliser un voucher en pourcentage.
  13. Tester le mode vente négative.
  14. Tester une utilisation partielle de cagnotte.
  15. Tester une coupure Internet avant et après Total.
  16. Comparer le ticket KWISATZ et l’historique ZEROSIX.
L’installation est validée lorsque les clients ne sont pas dupliqués, que chaque ticket n’est transmis qu’une fois, que les exclusions sont respectées et que points, cagnotte et vouchers concordent entre la caisse et ZEROSIX.

19. Diagnostic rapide

Erreur lors de l’appel create contact
Vérifiez que l’interface est activée, que l’URL est bien dans la zone URL et le token dans la zone Token. Testez d’abord une recherche client. Relancez KWISATZ si la version ne recharge pas selon le cycle de communication configuré les préférences.
La recherche ne renvoie rien
Vérifiez le minimum de caractères, l’URL, le token, Internet et le délai de connexion. Distinguez « aucun client trouvé » d’une erreur API ou d’un timeout.
La recherche renvoie trop de clients
Augmentez la valeur Recherche client — Nb caractères minimum, puis demandez aux opérateurs de rechercher avec téléphone, nom ou information suffisamment précise.
Une fiche client est créée en double
Comparez les fiches KWISATZ, leur téléphone et leur CLOUD_ID. Si le client existe dans les deux bases sans liaison, utilisez la fonction d’association au lieu d’une nouvelle création.
Plusieurs clients partagent le même téléphone
Le téléphone n’est pas une clé unique suffisante. Comparez identité, date de création et CLOUD_ID. Demandez à ZEROSIX de corriger les doublons côté plateforme si nécessaire.
Le ticket n’apparaît pas dans ZEROSIX
Relevez le numéro ou UID du ticket, le client, la date, la version et les journaux API. Vérifiez l’envoi après encaissement et comparez avec un ticket de test sans promotion.
Le ticket apparaît deux fois dans ZEROSIX
Ne concluez pas selon le cycle de communication configuré à un doublon KWISATZ. Comparez les UID, heures, montants et tentatives d’envoi. Recherchez une relance après timeout ou une duplication côté plateforme.
Les points ne sont pas calculés
Vérifiez le type de programme, les exclusions promotion/remise, les familles transmises, le client associé et la réponse ZEROSIX. Testez avec un article simple non remisé.
La cagnotte n’est pas proposée
Vérifiez que le programme Cagnotte est sélectionné, que le compte ZEROSIX utilise ce programme et que KWISATZ est dans une version récente prenant en charge son utilisation directe.
Aucun voucher n’est proposé à Total
Vérifiez que le programme est Cycle, que le seuil a été atteint, que le voucher est actif et non expiré, et que le règlement associé existe. Consultez la liste des vouchers retournée par la plateforme.
Le voucher est comptabilisé avec un mauvais montant
Contrôlez le règlement associé, le type valeur ou pourcentage et l’option Reprise voucher par vente négative. Comparez les lignes négatives et la ventilation TVA.
Une promotion produit quand même des points
Vérifiez l’option d’exclusion, le statut promotionnel de la ligne, la balise transmise et les règles du back-office ZEROSIX. Contrôlez également le code famille envoyé dans category.
Erreur de timeout
Contrôlez Internet et la disponibilité ZEROSIX. Augmentez modérément Connexion — Timeout ou Requêtes — Timeout au-delà de leur valeur minimale de 10 secondes, puis retestez sans masquer une panne persistante.
La situation fidélité n’est pas imprimée
Vérifiez que le ticket a bien été transmis, que la réponse ZEROSIX contient une situation et que le modèle de ticket affiche les informations attendues. Comparez avec une caisse fonctionnelle.
Le back-office fonctionne mais une caisse autonome non
Vérifiez que cette caisse possède son module ZEROSIX actif, sa connexion Internet et ses préférences. Chaque caisse autonome utilisée en encaissement doit pouvoir appeler l’API.

20. Actions à éviter

  • inverser URL et token ;
  • copier le token d’un autre commerçant ;
  • créer un client avant d’avoir effectué une recherche ;
  • remplacer manuellement un CLOUD_ID ;
  • fusionner des clients sur le seul critère du téléphone ;
  • activer simultanément deux fidélités incompatibles ;
  • forcer un voucher après une erreur API ;
  • réenvoyer un ticket validé sans vérifier son UID ;
  • activer la vente négative sans test de TVA ;
  • modifier les tickets fiscaux pour corriger des points.

21. Liste de contrôle

  • Le compte ZEROSIX est opérationnel.
  • L’URL et le token sont dans les bonnes zones.
  • L’interface est activée.
  • Le programme Cycle ou Cagnotte est correct.
  • Le règlement voucher est configuré.
  • Le mode classique ou vente négative est validé.
  • Les exclusions promotions/remises sont testées.
  • Les seuils et timeouts sont adaptés.
  • Les clients sont liés par CLOUD_ID.
  • Les créations et associations ne génèrent pas de doublons.
  • Les points, vouchers et cagnotte concordent.
  • Chaque caisse autonome concernée possède le module.
  • Les règles RGPD et la protection du token sont appliquées.

22. Évolutions documentées

Période Évolution
2021–2022 Consolidation de l’API ZEROSIX, identification de l’application et gestion des délais de communication.
Avril 2023 Prise en charge des vouchers en valeur ou pourcentage et du mode de reprise par ventes négatives.
2023–2024 Amélioration des exclusions promotion/remise et du contenu transmis à la plateforme.
Juin 2025 — branche 3.56 Ajout du type de programme Cycle/Cagnotte, du seuil de recherche client et des temporisations dans les préférences.
Versions récentes Développements pour utiliser directement la cagnotte et amélioration du rapprochement des tickets, promotions et UID.

23. Sources documentaires

  • Tutoriel KWISATZ — Interface de fidélité ZEROSIX.
  • Version 3.56R4 — Programme Cycle, Programme Cagnotte, seuil de recherche et timeouts.
  • Suivi de développement KWISATZ — vouchers, ventes négatives et exclusions promotion/remise.
  • Base support KWISATZ — création, association, doublons clients et CLOUD_ID.
  • Base support KWISATZ — architecture multi-caisses et nombre de modules.