Connecteur Caisse PrestaShop (Square, Zettle, SumUp) : documentation

Principe de fonctionnement

PrestaShop est la référence du stock. Chaque changement de stock d’un produit associé est envoyé à la caisse en quantité absolue. Chaque vente en caisse est importée, déduite du stock PrestaShop avec le motif de mouvement « Vente en caisse », puis le nouveau niveau repart vers les autres caisses. Les retours remettent les articles en stock avec le motif « Retour en caisse ».

• Square : stock dans les deux sens, ventes, retours, envoi du catalogue.
• Zettle by PayPal : stock dans les deux sens, ventes, remboursements, envoi du catalogue.
• SumUp : import des ventes uniquement. L’API publique de SumUp n’expose ni stock ni catalogue.

Prérequis

• PrestaShop 8.0 à 9.x.
• Une tâche cron sur votre hébergement.
• HTTPS sur la boutique pour le webhook Zettle.
• Un compte Square, Zettle ou SumUp avec accès développeur.

Installation

1. Dans Modules > Gestionnaire de modules, cliquez sur Installer un module et envoyez le ZIP.
2. Le module ajoute le menu Catalogue > Connecteur de caisse.
3. Le tableau de bord affiche une liste « Mise en route » qui se coche au fur et à mesure de la configuration.

Connecter vos caisses

Ouvrez l’onglet Connexions. Chaque caisse a son propre panneau avec une case Activé. Les identifiants sont chiffrés en base : un champ laissé vide conserve la valeur enregistrée.

Square

1. Créez une application dans le Square Developer Dashboard et copiez son jeton d’accès de production.
2. Collez-le dans Jeton d’accès, choisissez l’environnement, enregistrez, puis cliquez sur Tester la connexion.
3. Choisissez le point de vente qui reçoit le stock. Si vous en avez plusieurs, cochez ceux dont les ventes doivent être importées (10 au maximum).
4. Pour l’import instantané, créez un abonnement webhook sur l’événement order.updated avec l’URL de notification affichée, puis collez la clé de signature dans le module. L’URL doit être strictement identique des deux côtés.

Zettle by PayPal

1. Dans le Zettle Developer Portal, créez une clé API self-hosted avec les scopes READ:PURCHASE, READ:PRODUCT, READ:USERINFO et WRITE:PRODUCT.
2. Saisissez le Client ID et la clé API, enregistrez, puis testez la connexion.
3. Cliquez sur Activer le webhook pour recevoir les ventes en quelques secondes.
4. Le suivi de stock doit être activé sur les produits dans Zettle. Les produits envoyés par le module l’ont automatiquement.

SumUp

1. Saisissez votre clé API secrète (sup_sk_...), enregistrez, puis testez la connexion. Le code marchand est détecté automatiquement.
2. Les ventes SumUp sont associées par nom d’article : référence exacte ou nom exact d’un produit sans déclinaison.

Règles de synchronisation

En haut de l’onglet Connexions :

• Envoyer les niveaux de stock PrestaShop à la caisse, et en option immédiatement après chaque changement.
• Importer les ventes caisse et les déduire du stock PrestaShop.
• Remettre en stock les articles retournés (Square et Zettle).
• Association automatique par référence, par EAN-13 / UPC, et par nom pour SumUp.
• Importer les ventes à partir du : les ventes antérieures sont ignorées. Une vente déjà importée n’est jamais dupliquée.

Tâche planifiée et webhooks

Le tableau de bord affiche deux URL. Programmez la première toutes les 5 minutes et la seconde (avec full=1) une fois par nuit :

*/5 * * * * curl -s "https://votre-boutique.com/module/dfposconnector/cron?token=VOTRE_TOKEN" >/dev/null
0 3 * * * curl -s "https://votre-boutique.com/module/dfposconnector/cron?token=VOTRE_TOKEN&full=1" >/dev/null

Le cron importe les nouvelles ventes, envoie le stock en attente et détecte les écarts créés hors de PrestaShop (import SQL, ERP). La synchronisation de nuit renvoie tous les niveaux associés. Cron et webhooks fonctionnent aussi en mode maintenance.

Associer les produits

Onglet Correspondances produits :

• Lire le catalogue de Square ou Zettle : associe automatiquement par SKU et code-barres.
• Suggérer des produits par nom : propose un produit pour chaque article restant, avec un score. Les suggestions à 90 % ou plus peuvent être acceptées en masse, les autres une par une.
• Association manuelle : recherchez un produit par nom, référence ou EAN.
• Envoyer tout le stock vers la caisse, ou importer le stock de la caisse vers PrestaShop (à n’utiliser qu’une fois, à la mise en place, si le stock de la caisse est le plus fiable).

Envoyer le catalogue vers la caisse

Onglet Envoi du catalogue : choisissez la caisse, une catégorie (sous-catégories incluses), le prix envoyé (TTC ou HT, sans réductions) et si seuls les produits actifs sont concernés.

1. Vérifier ce qui sera envoyé lit d’abord le catalogue de la caisse et associe ce qui existe déjà, puis affiche le nombre de produits et de variantes à créer.
2. Les créer dans la caisse envoie les produits par lots avec une barre de progression. Les déclinaisons deviennent des variantes. Chaque article créé est associé et reçoit son stock.

Ne sont pas envoyés : les produits déjà associés dans cette caisse, les produits virtuels, les packs, les images et les catégories. Zettle accepte au maximum 99 variantes par produit.

Contrôle du stock

L’onglet Contrôle du stock lit les quantités réelles de Square ou Zettle et liste les écarts avec PrestaShop, les plus gros en premier. Pour chaque ligne :

• Envoyer le stock PrestaShop : la caisse reçoit la valeur PrestaShop.
• Prendre le stock caisse : PrestaShop reçoit la valeur de la caisse, avec un mouvement de stock.

Commandes PrestaShop pour les ventes en boutique

Panneau Commandes PrestaShop, désactivé par défaut. Une fois activé, chaque vente dont tous les articles sont associés crée une commande :

• client comptoir dédié à l’adresse de la boutique ;
• transporteur gratuit « Vente en caisse », jamais proposé au checkout ;
• prix du ticket, une remise globale étant répartie sur les lignes ;
• commande datée à l’heure de la vente, avec la référence caisse en note interne ;
• état « Vente en caisse » (payé, livré, sans facture ni email), modifiable dans les réglages.

C’est alors la commande qui déduit le stock. Aucun email n’est envoyé pendant la création. Une vente avec des articles non associés ne reçoit pas de commande : ses articles associés sont déduits directement.

Journal des ventes

L’onglet Ventes caisse liste chaque vente avec ses lignes, sa caisse, son point de vente, son paiement et, le cas échéant, le lien vers la commande. Filtres : caisse, statut (à associer, associées, retours, avec commande), recherche par ticket, article ou point de vente, plage de dates. Le bouton Exporter en CSV exporte la sélection, une ligne par article.

Alertes email

Panneau Alertes email : un email est envoyé quand la synchronisation planifiée échoue 3 fois de suite (au plus un toutes les 6 heures), puis un autre quand elle fonctionne de nouveau. Laissez l’adresse vide pour utiliser celle de la boutique. Le bouton Envoyer une alerte de test vérifie l’envoi.

Dépannage

« Inventaire non initialisé » sur Zettle

Activez le suivi de stock sur au moins un produit dans Zettle, ou envoyez un produit depuis l’onglet Envoi du catalogue.

Webhook Square refusé (signature invalide)

L’URL de notification déclarée dans Square doit être identique, caractère pour caractère, à celle du module, et la clé de signature doit correspondre à cet abonnement.

Le stock ne part pas après une modification en back-office

PrestaShop ne déclenche pas les hooks d’un module pour un employé qui n’a pas le droit « Voir » sur ce module. Le contrôle d’écart du cron rattrape ces changements au passage suivant. Vous pouvez aussi accorder ce droit dans Paramètres avancés > Équipe > Permissions.

Une vente n’a pas créé de commande

Le journal technique indique la raison : articles non associés, devise de la vente absente de PrestaShop, restriction de transporteur sur un produit, ou quantité inférieure à une unité. Le stock a alors été déduit directement.

Désinstallation

La désinstallation supprime les tables du module (correspondances, journal des ventes, file d’attente, journal technique) et ses réglages, et désactive le transporteur « Vente en caisse ». Les commandes créées, l’état de commande, le client comptoir et les motifs de mouvement de stock sont conservés, car l’historique y fait référence.