API LEO2Click - Envoi de commandes

Note importante sur les tarifs

Utilisation des prix unitaires

Sommaire >> API LEO2Click - Envoi de commandes

Notes de version

Version mars 2024

Pour les commandes avec produits ayant des messages, il faut obligatoirement spécifier l'ID message correspondant pour tout message ayant un tarif (attribut `add_price`).

Version mai 2023

Modification sur les montants des lignes produits: bascule sur le prix unitaire produit au lieu du total produit, sur tous les champs "prices", ajout des attributs "unit_ht" & "unit_ttc" (montants unitaires) et suppression des attributs "ht" & "ttc" (total pour le produit). Les anciens champs resteront fonctionnels jusqu'à la prochaine version de l'API

Ancienne version :


"price": {
"ht": 1.5, // Prix total HT pour le produit
"tva_rate": 20, // Taux de TVA
"ttc": 1.8 // Prix total TTC pour le produit
}

Nouvelle version :


"price": {
"unit_ht": 1.5, // Prix unitaire HT
"tva_rate": 20, // Taux de TVA
"unit_ttc": 1.8 // Prix unitaire TTC
}

La nouvelle version de Leo2API nécessite d'effectuer un arrondi des montants unitaires HT à 2 décimales pour rester cohérent avec LEO2. Le prix unitaire TTC est la donnée de base immuable, l'ajustement doit se faire sur le HT. Cette façon de procéder permet également de mieux préparer les données à la nouvelle loi sur la facture numérique.

Livraison / retrait: ajout de l'attribut "delivery->id_type" pour préciser dans quel type de commande on est (retrait sur place, livraison, ...)

La synchronisation des commandes a pour objectif de permettre la communication entre un outil tiers et une caisse LEO2 utilisée dans un magasin physique. Cette communication permet d'envoyer sur la caisse enregistreuse les commandes passées sur le site e-commerce ou l'outil afin que le commerçant puisse les préparer et les intégrer au milieu de ses autres commandes. Cette synchronisation est importante pour la facturation en caisse, ainsi que pour l'envoi d'informations sur le retrait de la commande (livraison, sur place, etc.).

Mise à jour des statuts

En outre, la synchronisation des commandes permet également de récupérer les changements de statut pouvant être effectués sur la caisse enregistreuse, tels que "en cours de préparation" ou "prêt au retrait". L'objectif est de pouvoir mettre à jour les statuts de commandes sur l'outil tiers et envoyer les alertes nécessaires au client, comme un email de confirmation de commande ou un email d'information sur le statut de la commande. Cette synchronisation améliore ainsi l'expérience utilisateur et renforce la satisfaction du client.

Note importante sur les tarifs

Utilisation des prix unitaires

La caisse ne peux réceptionner que des prix unitaires pour chaque ligne produit d'une commandes. Historiquement il était possible d'envoyer le total pour chaque ligne produits mais cette données ne sera plus exploitée par l'API prochainement, seuls les montants unitaires seront pris en compte.

Arrondis sur les montants HT

La caisse ne peux réceptionner que des montants unitaires à 2 décimales. Il est donc impératif que la solution tierce qui va envoyer des commandes à la caisse via l'API respecte cette règle car sinon l'utilisateur pourra observer des écarts de montants si la même précision n'est pas identique sur les différentes solutions.
Cette obligation est imposée par la nouvelle loi sur la facture numérique qui sera mise en application à partir de 2024.

Liste des statuts

Liste des statuts possibles lors de l'envoi de la commande

Lors de l'ajout de l'envoi des commandes, il faut préciser le statut en cours pour la commande, si vous souhaitez envoyer à la caisse uniquement les commandes validée & payées, le statut à mettre sera toujours zéro, Si vous souhaitez envoyer les commandes non valides, il faudra associer le statut correspondant.

-3 : Commande envoyé à la caisse manuellement
-2 : Commande non finalisée
-1 : Commande en erreur
0 : Commande finalisée / en attente de validation caisse

NB: Il n'est pas obligatoire d'envoyer à la caisse les commandes en erreur ou non finalisées. En principe on envoie à la caisse uniquement les paniers définitivement validés (correspond au statut 0).

Liste des statuts de retour transmis par la caisse

Une fois la commande reçu par la caisse, le statut sera mis à jour par la personne qui traite la commande sur la caisse. Lors de la mise à jour du statut d'une commande, vous pourrez avoir l'une des valeurs suivantes :

1 : Commande reçue - En attente de validation
2 : Commande validée
3 : En cours de préparation
4 : Commande prête / attente de récupération
5 : En livraison
6 : Problème: contactez le marchand
8 : Commande annulée
9 : Commande livrée / récupérée

Pour la synchro des statuts des commandes, vous recevrez uniquement l'ID de commande, le dernier statut en cours, la date/heure de changement de statut.

Flux pour les commandes

Requête: /api.php?module=atoo_shop&type=order&method=atoo_post_order

/api.php?module=atoo_shop&type=order&method=atoo_post_order&shop=ID_MAGASIN&pub_key=CLEF_API

Quantité: les valeurs peuvent être entières ou flottantes (pour les poids par ex.).

Exemple d'envoi de commande: envoi uniquement données obligatoires

class="json_comment fullwidth"> { "id": 12345, "state": 0, "products": [ { "id": 39, "idx": 2, "quantity": 2, "price": { "unit_ht": 1.5, // Prix unitaire HT "tva_rate": 20, // Taux de TVA "unit_ttc": 1.8 // Prix unitaire TTC } }, { "id": 34, "idx": 5, "quantity": 1, "price": { "unit_ht": 1, // Prix unitaire HT "tva_rate": 20, // Taux de TVA "unit_ttc": 1.2 // Prix unitaire TTC } } ], "customer": { "lastname": "Customer name", "zipcode": "30000", "email": "XXXXXXXXXX@gmail.com" }, "billing": null, "delivery": null, "total_order" : { "ht": 4, // Montant total HT à payer "tva_amount": 0.8, // Montant TVA à payer "ttc": 4.8 // Montant TTC à payer }, "payment": null }

Exemple d'envoi de commande: envoi complet


{
"id": "ID", //Your unique internal order ID
"state": 0, //Order is valid or not (wait, error or pay)
"products" : [
{
"id" : "LEO2 product ID",
"idx" : "Your unique internal product identifier",
"quantity" : 1,
"price": {
"unit_ht": 5, // Prix unitaire HT
"tva_rate": 20, // Taux de TVA
"unit_ttc": 6 // Prix unitaire TTC
}
},
{
"id" : "LEO2 product ID",
"idx" : "Your unique internal product identifier",
"quantity" : 3,
"price": {
"unit_ht": 5, // Prix unitaire HT
"tva_rate": 20, // Taux de TVA
"unit_ttc": 6 // Prix unitaire TTC
}
}
],
"menus": null,
"customer" : {
"lastname" : "", // Mandatory
"zipcode" : "", // Mandatory
"email" : ""
},
"billing" : {
"firstname": "Test",
"lastname": "IDalizes",
"company": "",
"text_1": "36 Rue Clérisseau",
"text_2": "",
"other": "",
"zipcode": "30000",
"city": "Nîmes",
"country": "FR",
"phone": ""
},
"delivery": {
"id_type" : 2, // Identifiant du type de retrait parmi ceux possibles (voir liste ci dessous)
"title": "your delivery name: Sur place, à emporter, ...",
"date": "2021-11-15", // Date de retrait choisie (a renseigner si retrait en magasin, sinon peut être null)
"h": "11:00", // Heure de retrait choisie (a renseigner si retrait en magasin, sinon peut être null)
"address": { //-- Si retrait sur place, adresse du magasin ou mettre à null (si le champs title suffit a défini le point de retrait)
"firstname": "Test",
"lastname": "IDalizes",
"company": "",
"text_1": "36 Rue Clérisseau",
"text_2": "",
"other": "",
"zipcode": "30000",
"city": "Nîmes",
"country": "FR",
"phone": ""
}
},
"total_order" : {
"ht": 20, // Montant total HT à payer
"tva_amount": 4, // Montant TVA à payer
"ttc": 24 // Montant TTC à payer
},
"payment": {
"name" : "Name of payemt method: Atos, Stripe, Paypal",
"amount": 24,
"message": "optional message from bank",
"valid": true // Payment is ok or not
},
"placename": null, // option: nom emplacement ou table
"comment": null // option: commentaire pour la commande

}

Exemple d'envoi de commande: envoi simple + produits avec messages

Pour les commandes avec produits ayant des messages, il faut obligatoirement spécifier l'ID message correspondant pour tout message ayant un tarif (attribut `add_price`). Si pas de montant, l'identifiant message est optionnel.


{
"id": 12345,
"state": 0,
"products": [
{
"id": 39,
"idx": 2,
"quantity": 2,
"price": {
"unit_ht": 5.35, // Prix unitaire HT
"tva_rate": 20, // Taux de TVA
"unit_ttc": 6.42 // Prix unitaire TTC
},
"msg" : [
{
"id":258, // ID du message
"name":"Sauce roquefort",
"quantity":1,
"add_price":2.5 // Si augmentation de prix, montant unitaire TTC
},
{
"name":"A point",
"quantity":1,
"add_price":0
}
]
},
{
"id": 34,
"idx": 5,
"quantity": 1,
"price": {
"unit_ht": 5.35, // Prix unitaire HT
"tva_rate": 20, // Taux de TVA
"unit_ttc": 6.42 // Prix unitaire TTC
},
"msg" : [
{
"name":"Sans sauce",
"quantity":1,
"add_price":0
}
]
},
{
"id": 42,
"idx": 7,
"quantity": 2,
"price": {
"unit_ht": 1.5, // Prix unitaire HT
"tva_rate": 20, // Taux de TVA
"unit_ttc": 1.8 // Prix unitaire TTC
}
}
],
"customer": {
"lastname": "Customer name",
"zipcode": "30000",
"email": "XXXXXXXXXX@gmail.com"
},
"billing": null,
"delivery": null,
"total_order" : {
"ht": 19.05,
"tva_amount": 3.81,
"ttc": 22.86
},
"payment": null,
"placename": null,
"comment": null
}

Exemple d'envoi de commande: envoi avec menus


{
"id": 12345,
"state": 0,
"products": [
{
"id": 39,
"idx": 2,
"quantity": 2,
"price": {
"unit_ht": 1.5,
"tva_rate": 20,
"unit_ttc": 1.8
},
"msg" : [
{
"name":"Sauce roquefort",
"quantity":1,
"add_price":0
},
{
"name":"Saignant",
"quantity":1,
"add_price":0
},
{
"name":"Frites",
"quantity":1,
"add_price":0
}
]
}
],
"menus": [ // Liste des menus de la commande
{
"id": "LEO2 menu ID",
"idx": "Your unique internal menu identifier",
"price": {
"unit_ht": 12,
"tva_rate": 20,
"unit_ttc": 14.4
},
"products": [ // Liste des produits sélectionnés pour le menu
{
"id": 12,
"idx": 32,
"quantity": 1 // Dans le cas du menu, en général toujours 1
},
{
"id": 14,
"idx": 33,
"quantity": 1
}
]
},
{
"id": "12",
"idx": "15",
"price": {
"unit_ht": 24,
"tva_rate": 20,
"unit_ttc": 28.8
},
"products": [ // Liste des produits sélectionnés pour le menu
{
"id": 15,
"idx": 45,
"quantity": 1
},
{
"id": 23,
"idx": 47,
"quantity": 1
},
{
"id": 36,
"idx": 52,
"quantity": 1
}
]
}
],
"customer": {
"lastname": "Customer name",
"zipcode": "30000",
"email": "XXXXXXXXXX@gmail.com"
},
"billing": null,
"delivery": null,
"total_order" : {
"ht": 39,
"tva_amount": 7.8,
"ttc": 46.8
},
"payment": null,
"placename": null,
"comment": null
}

Précisions sur certains attributs

Attribut "customer"

Le logiciel de caisse est sous la norme NF525 : le code postal et le nom du client sont les 2 mentions obligatoires pour un compte client.

Attribut "placename"

Champ texte pour préciser un nom d'emplacement ou de table.

Attribut "comment"

Champ texte pour ajouter un commentaire associé à la commande.

Livraison / retrait: Attribut "delivery->id_type"

Si l'attribut "delivery" est défini, il faut obligatoirement spécifier l'identifiant du type de livraison. Il y a actuellement 3 identifiants possibles :

1 : Retrait en magasin
2 : Livraison à domicile
4 : Consommation sur place

NB: si l'attribut n'est pas défini, il est pour l'instant par défaut sur 2. A l'avenir cet ID devrai être obligatoirement fourni à partir du moment ou l'attribut "delivery" ne sera pas à null.

Exemple retrait magasin

....
  "delivery": {
    "id_type" : 1, // Identifiant du type de retrait
    "title": "Retrait au magasin 1",
    "date": "2021-11-15", // Date de retrait choisie (a renseigner si retrait en magasin, sinon peut être <i>null</i>)
    "h": "11:00", // Heure de retrait choisie (a renseigner si retrait en magasin, sinon peut être <i>null</i>)
    "address": null
  },
....

Exemple livraison

....
  "delivery": {
    "id_type" : 2, // Identifiant du type de retrait
    "title": "Commande en livraison",
    "date": null,
    "h": null,
    "address": {
        "firstname": "Test",
        "lastname": "IDalizes",
        "company": "",
        "text_1": "36 Rue Clérisseau",
        "text_2": "",
        "other": "",
        "zipcode": "30000",
        "city": "Nîmes",
        "country": "FR",
        "phone": ""
    }
  },
....

Paiement

Si les infos de paiement ne sont pas envoyées (valeur à NULL), la commande sera marquée comme non payée et en mode paiement sur place.

Liste des erreurs lors de l'envoi de commande

no_post_json: Erreur sur le JSON envoyé
missing_post_field: Champs manquant
invalid_type_post_field: Champs invalide
product_tva_error: Aucun taux de TVA correspondant sur la caisse
guest_account_create: Erreurt de création du compte guest pour la commande.
order_already_registered: Commande déjà envoyée à la caisse

Valeur de retour lors de l'envoi de commande

Exemple de commande valide


{
"type": "data",
"view": "order",
"method": "ORDER_atoo_post_order",
"data": {
"is_valid": true,
"message": null
}
}

Exemple de commande non valide (champs manquant)


{
"error": {
"id": "missing_post_field",
"message": "Missing: Order->customer->email",
"log": null,
"list": null
}
}

Exemple de réception de mise à jour de statut de commande

Si vous avez spécifié une URL de rappel dans l'administration LEO2Click, vous pourrez recevoir les changements de statut des commandes effectués depuis la caisse.


{
"id_shop" : null, // ID du magasin
"date" : null, // Date heure de l'opération
"order_list_state" : [
{
"id": "API order ID",
"id_ext": "Your order ID",
"shop": "ID magasin",
"state" : "current_state_ID",
"updated" : "Date updated"
},
{
"id": "API order ID",
"id_ext": "Your order ID",
"shop": "ID magasin",
"state" : "current_state_ID",
"updated" : "Date updated"
},
{
"id": "API order ID",
"id_ext": "Your order ID",
"shop": "ID magasin",
"state" : "current_state_ID",
"updated" : "Date updated"
}
]
}

Si vous n'avez pas d'URL de rappel, il sera possible de fournir un flux comportant cette liste des états des commandes sur un intervalle donné.
Statuts des dernières commandes envoyées en caisse :

./api.php?module=atoo_shop&type=order&method=atoo_statelist_order&shop=ID_MAGASIN&pub_key=CLEF_API

Statuts de toutes les dernières commandes (envoyées en caisse ou non) :

./api.php?module=atoo_shop&type=order&method=atoo_statelist_order_all&shop=ID_MAGASIN&pub_key=CLEF_API

API Leo2
API Leo2 V2
- LEO2API Version 2 - Authentification
Spécifications LEO2Click application web
Fonctions spécifiques
- Leo2Click - QRCode commande Leo2clic sur emplacement
Autres
- API globale Leo2Click