Import de ventes POS via FTP (JSON)

⚠️ Mise en garde - Fonctionnalité avancée

L’import de ventes via FTP avec un fichier JSON est une fonctionnalité avancée réservée aux utilisateurs ayant des connaissances très techniques.

Il existe aussi un format CSV plus simple à mettre en place.

ℹ️ Formats de données

Quantités et montants : indiquez-les en chaîne de caractères (string) pour éviter les problèmes d’arrondis liés aux nombres à virgule flottante.
Utilisez toujours un point comme séparateur décimal (ex. 1.23) et non pas une virgule.
Les valeurs doivent être indiquées dans la devise utilisée et non pas en centimes (ex. 1.23 et non 123).

📋 Structure des champs

Champ	Obligatoire	Description
id	Oui	Identifiant unique de la commande.
date	Oui	Date de la vente au format ISO8601 `AAAA-MM-JJ` ou `AAAA-MM-JJThh:mm:ssZ` si vous incluez l’heure.
covers	Non	Nombre de couverts.
amount_including_tax	Non	Montant total T.T.C de la vente.
amount_excluding_tax	Non	Montant total H.T de la vente.
items	Oui	Liste des produits vendus.

Champs pour chaque produit dans items :

Champ	Obligatoire	Description
product_id	Oui	Identifiant unique du produit dans le POS.
product_name	Non	Nom du produit tel que défini dans le POS.
quantity	Oui	Quantité totale vendue pour ce produit
amount_including_tax	Oui	Montant total T.T.C du produit, hors produits liés.
amount_excluding_tax	Oui	Montant total H.T du produit, hors produits liés.
items	Oui	Produits liés à ce produit (ex. éléments d’un menu, suppléments).

Exemple complet de fichier JSON


[
  {
    "id": "000001",
    "date": "2025-01-01T00:00:00Z",
    "amount_excluding_tax": "31.00",
    "amount_including_tax": "37.20",
    "covers": 2,
    "items": [
      {
        "quantity": "2",
        "amount_excluding_tax": "25.00",
        "amount_including_tax": "30.00",
        "product_id": "000001",
        "product_name": "Formule - 15€ la formule sans options",
        "items": [
          {
            "quantity": "2",
            "amount_excluding_tax": "0.00",
            "amount_including_tax": "0.00",
            "product_id": "000002",
            "product_name": "Burger",
            "items": [
              {
                "quantity": "2",
                "amount_excluding_tax": "1.00",
                "amount_including_tax": "1.20",
                "product_id": "000003",
                "product_name": "Supplément fromage - 0.60€ le supplément",
                "items": []
              }
            ]
          },
          {
            "quantity": "2",
            "amount_excluding_tax": "5.00",
            "amount_including_tax": "6.00",
            "product_id": "000004",
            "product_name": "Eau pétillante - 3€ la bouteille",
            "items": []
          }
        ]
      }
    ]
  }
]

🧪 Validation de votre fichier

Avant de déposer votre fichier sur le FTP, vous pouvez vérifier qu’il respecte bien le format attendu en utilisant notre outil de validation :
👉 https://pos-import-report.yokitup.com

🔐 Connexion FTP / SFTP

Les identifiants de connexion (serveur, utilisateur, mot de passe) sont visibles dans la page de l'intégration POS.

⚠️ Après 3 tentatives de connexion échouées, votre adresse IP sera automatiquement bloquée pendant 24 heures.

⏱ Fréquence de traitement des fichiers

Les fichiers déposés sur le FTP sont traités automatiquement toutes les heures.
Chaque traitement va analyser les fichiers présents dans le dossier, en se basant sur leur nom.

⚠️ Fichiers déjà traités

Une fois qu’un fichier a été traité, il ne peut plus être retraité, même si :
- le fichier est supprimé puis recréé avec le même nom ;
- le fichier contenait une erreur (par exemple : format invalide).
Pour forcer un nouveau traitement, vous devez changer le nom du fichier (ajouter une date, une version, etc.).

🚫 Aucune suppression possible

Une fois qu’un fichier a été traité, les ventes et produits enregistrées ne peuvent pas être supprimées.
⚠️ Soyez donc très attentif avant de déposer un fichier sur le FTP.

✅ Gestion des doublons

Si une vente a déjà été traitée (par exemple via un autre fichier), elle sera automatiquement ignorée lors des traitements suivants.
L’identifiant utilisé pour cela est le champ order_remote_id, qui doit être unique pour chaque vente.

🔔 Suivi des erreurs

Après dépôt d’un fichier, vous pouvez vérifier son traitement dans l’onglet Événements de votre intégration POS. Attention, le nom du fichier n’est pas affiché, il faut donc surveiller les dates et types d’erreur indiqués.

📆 Recommandation sur les ventes nocturnes

💡 Conseil : si vous avez des ventes enregistrées entre minuit et 6h du matin et que votre export ne contient que la date (sans l’heure), nous vous recommandons de les rattacher à la date de la veille dans votre export.

Cela permet d’aligner les données avec la réalité opérationnelle des sites ouverts tard le soir et de garantir des statistiques plus cohérentes.

👉 Ce comportement est souvent attendu par les équipes opérationnelles, mais il doit être explicitement géré dans le script d’export, car ce n’est pas le comportement par défaut.

pos.json