Documentation technique d’intégration de ZEROSIX dans un logiciel de caisse 

L’intégration se fait sur la base de l’API Rest de ZEROSIX et d’appels HTTP sécurisés, authentifiés, formatés en JSON et encodés en utf-8. 

L’authentification des appels API se fait grâce à une clé API que ZEROSIX fourni, qui identifie de manière unique un établissement particulier. Le logiciel qui nous intègre doit donc pouvoir stocker cette clé et l’utiliser dans chacun des appels effectués. 

Les headers des appels contiennent obligatoirement : 

'Authorization: Token YOUR-API-KEY' 

'Content-Type: application/json' 

'User-Agent: Software/Version' 

L’identification du client se fait via le mobile uniquement. Le mobile est obligatoire et unique, il ne peut pas y avoir plusieurs clients avec le même mobile. L’identification doit se refaire à chaque fois qu’un client est sélectionné sur le logiciel de façon à obtenir les dernières informations à jour. 

Si aucun client n’est trouvé, une code statut 404 sera retourné.

Afin d’identifier le client il faut appeler le endpoint suivant : 

GET "https://api.zerosix.com/members/{mobile}" 

La réponse sera de cette forme : 

Les éléments qui doivent être obligatoirement traités sont marqués en bleu : 

• owner_info : Champ construit à partir du nom, prénom, programme de fidélité et statut du client. Ces informations sont totalement dépendantes de la configuration ZEROSIX de l’enseigne et peuvent donc varier à tout moment. C’est pour cette raison qu’il est important d’utiliser ce champ construit par ZEROSIX. Il devra être affiché sur la caisse une fois le client identifié.
  
  
• url : L’url de la carte utilisée lors de la transmission de la vente. Ne doit surtout pas être stockée car elle peut changer à tout moment, seulement le mobile doit être utilisé pour identifier le client.
  
  
• points_balance : Le nombre de points disponibles sur la carte de fidélité.
  
  
• terms_accepted : Indique si le client a accepté les conditions générales d’utilisation. Si ce n’est pas le cas, il faut l’indiquer quelque part sur la caisse afin que le vendeur puisse prévenir le client que s’il veut bénéficier de ses avantages il doit les accepter. De plus, la carte sera supprimée au bout de 90 jours si les conditions ne sont pas acceptées.
  
  
• available_vouchers : La liste des codes promos disponibles pour le client. Il existe trois types de codes : €, % et produit offert, le type de code est indiqué dans “unit”. Pour les codes € et % la valeur est indiquée dans “value”. Si un minimum d’achat est configuré pour le code, il sera indiqué dans “minimum_amount”. Enfin, pour les codes promos de type produit offert, la liste des ids de produits sélectionnables est indiquée dans “external_ids”, cette liste représente les ids des produits dans le logiciel de caisse et est configurée côté ZEROSIX.

Un élément non obligatoire mais intéressant si possible de l’afficher :

• dashboard_url : Lien vers la fiche client du tableau de bord ZEROSIX. Il permet au vendeur d’effectuer des opérations occasionnelles, comme par exemple faire une migration de programme de fidélité vers un programme plus avantageux (étudiant, entreprise,…)

Si aucun client n’est retourné lors de l’identification, alors il faudra le créer.

Afin de créer le client il faut appeler le endpoint suivant : 

POST "https://api.zerosix.com/contacts/" 

Le payload sera à minima de cette forme : 

Il est possible de remplir d’autres champs facultatifs, la liste complète est disponible sur la documentation API.

Si une carte existe déjà avec ce numéro de téléphone, alors un code statut 409 sera renvoyé.

Si la création s'est bien passée, la réponse sera de cette forme :

Une fois que la vente est validée sur le logiciel, il faut l’envoyer avec le endpoint suivant : 

POST "https://api.zerosix.com/visits/"

Le payload sera de cette forme : 

• card : url de la carte récupérée lors de l’identification/création du client
  
  
• reference : référence de la vente unique sur le logiciel. Permet de dédoublonner les ventes en cas d’appels doublés.
  
  
• date : date sous la forme “YYYY-MM-JJ HH:MM:SS” à laquelle la vente a été clôturée.  Si cette date n’est pas renseignée ZEROSIX attribuera la date et heure de réception de la vente.
  
  
• details : liste des articles de la vente. Pour chaque article il est important de mentionner la référence unique de l’article dans le logiciel, la catégorie, le nom, la quantité, le prix unitaire et le prix total.
  
  
• used_vouchers : liste des vouchers utilisés, est utilisée pour griller ces vouchers.
  
  

💡 Points importants sur les items dans le cas de l’utilisation de vouchers :

1. Si un voucher de type remise (en valeur ou en pourcentage) est utilisé, alors le montant déduit doit être répercuté sur la somme des items de la vente. Il y a deux moyens d’y parvenir : 
   
   • Ajouter un item supplémentaire au prix négatif correspondant à celui du voucher
   • Ventiler la valeur déduite du voucher proportionnellement au prix de chaque article. 
     Exemple pour une vente de 45€ avec utilisation d’un voucher de 10 € :
     
     Détails du panier avant remise
     Ligne 1 : total = 10 € 
     Ligne 2 : total = 20 € 
     Ligne 3 : total = 15 €
     
     Détails du panier après remise
     Ligne 1 : total = 10 € - (10/45 * 10 €)
     Ligne 2 : total = 20 € - (20/45 * 10 €)
     Ligne 3 : total = 15 € - (15/45 * 10 €)
     
2. Si un voucher en valeur et un voucher en pourcentage sont utilisés sur la même vente, nous préconisons de favoriser le commerçant, c’est donc le voucher en valeur qui doit être appliqué en premier.