Connecteur Caisse PrestaShop (Square, Zettle, SumUp) : documentation
Installer le module, connecter Square, Zettle ou SumUp, associer les produits et synchroniser stock et ventes entre la caisse et PrestaShop.
Principe de fonctionnement
Le module relie PrestaShop à votre caisse Square, Zettle by PayPal ou SumUp. Il importe chaque vente, retour et remboursement de la caisse dans un journal, met à jour le stock dans le sens que vous choisissez et peut transformer chaque vente en commande PrestaShop. Il peut aussi envoyer votre catalogue PrestaShop vers la caisse.
Le stock se synchronise dans l’un des trois sens suivants, réglé par caisse :
- Boutique vers caisse : PrestaShop est maître. Les ventes en caisse sont déduites dans PrestaShop, puis le nouveau niveau repart vers la caisse.
- Caisse vers boutique : la caisse est maître. PrestaShop reprend les quantités de la caisse à chaque passage du cron et à chaque webhook de stock.
- Bidirectionnel : les variations faites de chaque côté depuis la dernière synchronisation s’additionnent. Une vente en ligne et une vente en boutique comptent chacune une fois.

Ce que fait chaque caisse
- Square : ventes, retours et remboursements, stock dans les trois sens, plusieurs points de vente, envoi du catalogue avec l’image principale, webhooks signés.
- Zettle by PayPal : ventes et remboursements, stock dans les trois sens, envoi du catalogue, webhook signé créé par le module.
- SumUp : ventes et remboursements, déduits du stock PrestaShop. L’API publique de SumUp n’expose ni stock, ni catalogue, ni webhook des ventes en caisse : l’import passe par le cron, et le stock affiché dans SumUp n’est pas mis à jour.
Le module ne remplace pas votre caisse et n’en fait pas une caisse certifiée. Les tickets, la clôture et les obligations fiscales restent gérés par Square, Zettle ou SumUp.
Prérequis
- PrestaShop 1.7.8 à 9.x. Le module a été testé sur PrestaShop 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) et 9.1.5 (PHP 8.5).
- Une tâche cron sur votre hébergement.
- Une boutique en HTTPS pour les webhooks et pour la connexion OAuth.
- Un compte Square, Zettle ou SumUp, et l’accès à son espace développeur si vous vous connectez par jeton ou par clé API.
Installation et mise à jour
- Dans Modules > Gestionnaire de modules, cliquez sur Installer un module et envoyez le ZIP.
- Le module ajoute le menu Catalogue > Connecteur de caisse. Le tableau de bord affiche une liste Premiers pas qui se coche au fur et à mesure de la configuration.
Pour passer d’une version 1.x à la 2.0.0, envoyez le nouveau ZIP de la même manière. La mise à jour conserve les correspondances, le journal des ventes, les connexions, les curseurs d’import (aucune vente n’est réimportée) et les réglages. Les URL de webhook existantes restent valables. Elle ajoute les nouvelles tables, rechiffre les anciens secrets et retire de l’état « Vente en caisse » le drapeau de livraison qui provoquait un second paiement. Les commandes déjà créées ne sont pas modifiées.
Connecter vos caisses
L’onglet Connexions affiche l’état de chaque caisse et les fonctions disponibles. Chaque caisse a son propre assistant. Les secrets sont stockés chiffrés et ne sont jamais réaffichés ni écrits dans le journal. Un champ laissé vide conserve la valeur enregistrée.

Square
- Choisissez le mode de connexion. OAuth est recommandé : vous autorisez le module depuis votre compte Square, et le jeton est renouvelé automatiquement. Pour une seule boutique, vous pouvez aussi coller un jeton d’accès personnel.
- En OAuth, saisissez l’ID et le secret de votre application Square, et déclarez dans cette application l’URL de redirection affichée. Le module ne demande que les permissions nécessaires : points de vente, commandes, paiements, catalogue, stock et clients en lecture, catalogue et stock en écriture.
- Cliquez sur Se connecter avec Square, acceptez les permissions, puis Tester la connexion.
- Choisissez le point de vente qui porte le stock, et cochez ceux dont les ventes sont importées (10 au maximum).
- Pour l’import instantané, ajoutez dans Webhooks > Subscriptions l’URL de notification affichée avec les événements
order.updated,refund.created,inventory.count.updatedetoauth.authorization.revoked, puis collez la clé de signature dans le module. L’URL doit être identique, caractère pour caractère, des deux côtés.

Le bouton de connexion OAuth vous envoie vers la page d’autorisation de la caisse, sur son propre site, puis vous ramène dans le module. La capture ci-dessous a été prise en mode démonstration, avec un écran d’autorisation simulé.


Zettle by PayPal
- Pour une seule boutique, la clé API auto-hébergée est recommandée : créez-la dans le Zettle Developer Portal et collez-la avec son ID client. Une connexion OAuth est aussi proposée pour une application partenaire, avec un renouvellement automatique des jetons.
- Enregistrez, puis testez la connexion.
- Cliquez sur Activer le webhook : le module crée lui-même l’abonnement (
PurchaseCreated,InventoryBalanceChanged) et garde sa clé de signature chiffrée. Zettle exige une boutique en HTTPS. - Le suivi de stock doit être activé sur les produits dans Zettle. Les produits envoyés par le module l’ont automatiquement.

SumUp
- Collez votre clé API secrète (tableau de bord SumUp, Developers > API keys) avec votre code marchand, ou connectez-vous en OAuth.
- Testez la connexion. Le code marchand est lu automatiquement s’il manque.
- SumUp n’envoie pas de webhook pour les ventes en caisse : elles sont importées par le cron toutes les 5 minutes. Elles sont associées par référence ou par nom d’article.

Déconnecter une caisse
Le bouton Déconnecter révoque les jetons quand la caisse le permet (Square, Zettle) et les supprime de PrestaShop. Les correspondances et le journal des ventes sont conservés.
Sens du stock
Dans Réglages > Stock, choisissez le sens du stock pour Square et pour Zettle : boutique vers caisse, caisse vers boutique, bidirectionnel ou pas de synchronisation du stock. Pour SumUp, les ventes sont déduites du stock PrestaShop, mais sa caisse ne reçoit pas de stock.
- Une seule caisse peut être maître du stock. Si vous en choisissez une deuxième, le module la règle sur Bidirectionnel.
- En bidirectionnel, la source de vérité décide du premier alignement et des conflits.
- Un niveau écrit par le module n’est jamais renvoyé, pour éviter les échos. Quand la caisse compte déjà ses propres ventes, l’import ne les déduit pas une seconde fois.
- L’option Envoyer juste après chaque modification de stock PrestaShop envoie le niveau aussitôt. Sinon, il part au passage suivant du cron.

Associer les produits
L’onglet Correspondances relie chaque article de caisse à un produit ou une déclinaison PrestaShop.
- Lire le catalogue de Square ou Zettle : les articles sont associés automatiquement par SKU (référence du produit ou de la déclinaison) et par code-barres EAN-13 / UPC.
- Suggestions par nom : pour chaque article restant, le module propose le produit le plus proche avec un score. Les suggestions à 90 % ou plus peuvent être acceptées en une fois, les autres une par une. Aucune suggestion n’est enregistrée sans votre validation.
- Association manuelle : recherchez un produit par nom, référence ou EAN.
- Un article vendu en caisse mais absent du catalogue lu apparaît aussi dans la file. Vous pouvez le masquer s’il n’est pas vendu en ligne.

Associer un article rattrape le stock des ventes déjà importées, une seule fois. Les lignes de vente passées sont reliées à la nouvelle règle.
Envoyer le catalogue vers la caisse
L’onglet Catalogue crée vos produits PrestaShop dans Square ou Zettle : déclinaisons en variantes, prix, SKU, code-barres, image principale en option, puis stock. 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.
- Vérifier ce qui sera envoyé lit d’abord le catalogue de la caisse, associe par SKU ou code-barres ce qui existe déjà, puis affiche le nombre de produits et de variantes à créer.
- Cochez la confirmation, puis Les créer dans la caisse : les produits partent par lots, avec une barre de progression, et chaque article créé est associé immédiatement.

Les articles existants de la caisse ne sont jamais modifiés. Sur Square, chaque article est rattaché à une taxe Square existante du même taux : aucune taxe n’est créée. Les produits virtuels et les packs sont exclus, et les catégories ne sont pas envoyées. Zettle accepte au maximum 99 variantes par produit. SumUp ne peut pas recevoir de produits par son API.
Contrôle du stock et réconciliation
L’onglet Stock compare le stock PrestaShop et le stock de la caisse pour chaque article associé, et liste les écarts. Pour chaque écart, ou pour une sélection :
- Garder PrestaShop : la caisse reçoit la quantité PrestaShop.
- Garder la caisse : PrestaShop reçoit la quantité de la caisse, avec un mouvement de stock.
La synchronisation complète de nuit lance une réconciliation et garde son rapport. Les rapports précédents restent consultables. Importer tous les niveaux de la caisse écrase le stock PrestaShop de chaque produit associé : à n’utiliser qu’une fois, à la mise en place, si le stock de la caisse est le plus fiable.

Ventes en caisse
L’onglet Ventes en caisse liste chaque ticket avec ses lignes, sa caisse, son point de vente, son paiement, sa TVA par ligne, son pourboire et, le cas échéant, la commande PrestaShop. Filtres : caisse, type (ventes, retours et remboursements, commandes PrestaShop), écarts de montant, recherche par ticket, article, point de vente ou numéro de commande, et plage de dates. Exporter en CSV exporte la sélection.

L’import est idempotent : une vente déjà importée n’est jamais dupliquée, même si elle arrive par plusieurs webhooks et par le cron en même temps. Les tickets enregistrés hors ligne à la caisse et transmis plus tard sont aussi importés. Les ventes antérieures à la date réglée dans Importer les ventes en caisse à partir du sont ignorées.
Commandes PrestaShop pour les ventes en boutique
Dans Réglages > Commandes et remboursements, l’option Créer une commande PrestaShop pour chaque vente en caisse dont tous les articles sont associés est désactivée par défaut. Une fois activée :
- un client de passage par boutique, à l’adresse de la boutique ;
- un transporteur gratuit « Vente en caisse », jamais proposé au checkout ;
- le moyen de paiement « Caisse – Square / Zettle / SumUp », un seul paiement, et une commande datée à l’heure de la vente ;
- les prix et les remises du ticket, répartis sur les lignes ;
- le pourboire hors du total de la commande, inscrit dans sa note ;
- aucun e-mail, ni au client ni à vous.
L’état par défaut est « Vente en caisse » (payé, livré, sans e-mail ni facture). Si PrestaShop recalcule un total différent du ticket (règles de taxes, arrondis), l’écart est affiché sur la vente et noté au journal.

- Autoriser les factures pour les commandes de caisse : désactivé par défaut, car la caisse fournit déjà le reçu. Sans cette option, un état qui génère une facture est refusé. Avec elle, la facture est créée sur le paiement existant et signalée au journal.
- Clients identifiés (Square) : la commande peut être rattachée au client PrestaShop existant qui a la même adresse e-mail que le client Square. Seul un client existant avec une adresse est utilisé : aucun client ni aucune adresse n’est créé.

Une vente qui contient des articles non associés ne reçoit pas de commande : ses articles associés sont déduits directement du stock.
Retours et remboursements
Les retours Square, les remboursements Zettle et les remboursements SumUp sont importés, partiels compris. Les articles retournés sont remis en stock une seule fois, par la ligne de retour. Un remboursement sans article retourné ne modifie pas le stock. Sur la commande d’origine, choisissez :
- Note dans la commande uniquement (par défaut) ;
- Avoir pour les articles retournés ou le montant remboursé ;
- Avoir, et état « Remboursé » une fois la commande entièrement remboursée.

Tâches planifiées et webhooks
Réglages > Tâches planifiées affiche l’URL du cron. Appelez-la toutes les 5 minutes, et la même URL 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 traite la file des webhooks, importe les nouvelles ventes, renouvelle les jetons et envoie les niveaux de stock en attente. Deux exécutions ne se chevauchent jamais. Le passage de nuit renvoie tous les niveaux associés et génère le rapport de réconciliation.
Chaque webhook est contrôlé avant d’être accepté :
- la clé d’URL propre aux webhooks, distincte du jeton du cron ;
- la signature de la caisse ;
- une taille maximale de 256 Ko ;
- un âge maximal de 96 heures ;
- un identifiant d’événement jamais vu.
Le module répond aussitôt, puis traite l’événement. Une notification non signée, mal signée ou rejouée est refusée et notée au journal.
Journal technique
L’onglet Journal liste les erreurs, avertissements et informations, filtrables par caisse, niveau, problème, texte et date. Chaque erreur connue indique sa cause et sa solution, avec un lien vers l’écran concerné. Les jetons, clés et signatures sont masqués avant d’être écrits. Les entrées sont conservées 30 jours par défaut (réglable), et les derniers événements webhook reçus sont listés.

Alertes
L’onglet Alertes regroupe les problèmes en cours avec leur cause, leur solution et un bouton Corriger maintenant. Une alerte se ferme d’elle-même quand le problème disparaît.
- synchronisation en échec lors de 3 exécutions de suite, puis un message quand elle fonctionne à nouveau ;
- jeton refusé ou impossible à renouveler, permission manquante, signatures de webhook refusées ;
- mises à jour de stock abandonnées, cron qui ne s’exécute plus ;
- articles vendus en caisse sans produit PrestaShop ;
- écarts trouvés par la réconciliation de nuit.

Les alertes peuvent aussi partir par e-mail, au plus un toutes les 6 heures par alerte. Laissez l’adresse vide pour utiliser celle de la boutique. 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 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.
Jeton refusé ou permission manquante
Ouvrez Connexions, reconnectez la caisse avec son assistant et acceptez toutes les permissions listées.
Le stock ne part pas après une modification en back-office
PrestaShop ne déclenche pas les crochets d’un module pour un employé qui n’a pas le droit « Voir » sur ce module. En sens boutique vers caisse, 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 en indique la raison : articles non associés, devise de la vente inactive dans PrestaShop, produit limité à certains transporteurs, ou quantité inférieure à une unité. Le stock a alors été traité directement. Corrigez la cause pour les ventes suivantes. Le bouton Créer la commande PrestaShop n’est proposé que pour une vente dont le stock n’a pas encore été déduit, afin de ne jamais le déduire deux fois.
Le total de la commande diffère du ticket
Vérifiez que la règle de taxe PrestaShop des produits correspond au taux de TVA utilisé en caisse. L’écart est affiché sur la vente.
Désinstallation
La désinstallation supprime les tables du module (correspondances, journal des ventes, files d’attente, journal technique, réconciliations, alertes) et ses réglages, et désactive le transporteur « Vente en caisse ». Les commandes créées, l’état de commande, le client de passage et les motifs de mouvement de stock sont conservés, car l’historique y fait référence.