Caisse¶

Le sous-onglet Caisse (Configuration > Caisse) configure la connexion entre Caisse-Connect et votre logiciel de caisse. L'interface s'adapte selon que la caisse est déjà configurée ou non.

Première configuration¶

Si aucun système de caisse n'est encore configuré, le sous-onglet affiche une carte Sélection du système de caisse :

Sélectionnez votre caisse dans le menu déroulant (ex: Kwisatz)
Le formulaire de configuration spécifique à la caisse sélectionnée se charge dynamiquement sous le sélecteur
Remplissez les champs de connexion proposés
Cliquez sur Valider

Après validation, Caisse-Connect sauvegarde la configuration et teste automatiquement la connexion. Le résultat du test (succès ou échec) est affiché pendant quelques secondes avant la redirection vers la page de configuration complète.

Systèmes de caisse disponibles

Caisse-Connect est actuellement compatible avec Kwisatz. D'autres systèmes de caisse pourront être ajoutés dans de futures versions.

Configuration Kwisatz¶

Une fois la caisse configurée, le sous-onglet affiche les paramètres de connexion à l'API Kwisatz. Les champs disponibles sont :

Champ	Description
Protocole	HTTP ou HTTPS
URL de base de l'API	Adresse du serveur Kwisatz, sans protocole (ex: `monserveur.kwisatz.fr`)
Port de l'API	Port de l'API (ex: 8888) ; à laisser vide en cas de tunnel proxy type ngrok
Chemin de l'API	Chemin de l'API sur le serveur (ex: `/api/v1/`)
Timeout (secondes)	Délai d'attente maximum pour un appel API (1 à 300, défaut 60)
Nombre max de tentatives de connexion	Nombre de tentatives en cas d'échec (1 à 10, défaut 3)
Clé API Kwisatz	Clé d'authentification fournie par le serveur API Kwisatz. Exigée par les versions récentes du serveur, optionnelle (rétrocompatible) pour les anciennes versions qui ne demandent pas d'authentification. Le champ s'affiche masqué : une clé déjà enregistrée est signalée par un placeholder « clé définie » — laisser vide pour la conserver, ou cocher Supprimer la clé API enregistrée pour l'effacer. Une saisie non vide prime toujours sur la case de suppression (la case est d'ailleurs désactivée dès que le champ est rempli)
Ignorer les produits en sommeil non modifiés depuis le	Date à partir de laquelle un produit mis en sommeil est encore téléchargé depuis la caisse : un produit mis en sommeil avant cette date et jamais modifié depuis n'est plus lu. Laisser vide pour continuer à prendre en compte tous les produits en sommeil
Préfixe commandes	Lettres ajoutées devant le numéro de commande dans les fichiers transmis à la caisse (ex: SLE, ENT). Permet de distinguer les commandes de plusieurs sites reliés à la même caisse. Soit vide (mono-site, pas de préfixe), soit exactement 3 lettres — la casse est ignorée (normalisée en majuscules). L'unicité entre sites frères est vérifiée sans tenir compte de la casse. La longueur fixe (3 lettres) garantit que deux préfixes ne peuvent jamais être l'amorce l'un de l'autre. Un préfixe non conforme est refusé sans enregistrement partiel. En présence de sites frères, ce champ est en lecture seule : sa valeur fait partie de la configuration commune, gérée par l'administrateur
Fréquence de synchro (min)	Intervalle, en minutes, entre deux synchronisations automatiques déclenchées par le poste de caisse (entier de 1 à 1440, défaut 10). En présence de sites frères, ce champ est en lecture seule : sa valeur fait partie de la configuration commune, gérée par l'administrateur

Réglage propre à chaque site

Contrairement au préfixe commandes et à la fréquence de synchro ci-dessus, la date des produits en sommeil ignorés reste modifiable sur chaque site, y compris en présence de sites frères : elle ne fait pas partie de la configuration commune.

Abaisser la date

Abaisser cette date affiche un rappel : pour que les produits en sommeil désormais concernés soient à nouveau pris en compte, lancez une synchronisation complète (Paramètres > Synchronisation > Catégories à synchroniser > « Forcer une synchronisation complète »).

Clé API Kwisatz : stockage hors-webroot

La clé API n'est jamais stockée en base de données : elle réside dans un fichier secret hors-webroot, Caisse-Connect/{domaine}/Secrets/cc-kwisatz-api-key.php (constante CC_KWISATZ_API_KEY), aux côtés des autres secrets. Elle est envoyée au serveur API Kwisatz via l'en-tête X-Api-Key (et non Authorization: Bearer, refusé par le middleware ASP.NET Core du serveur). Tant que le fichier est absent, aucun en-tête d'authentification n'est envoyé — d'où la rétrocompatibilité avec les anciennes versions du serveur. En présence de plusieurs sites frères reliés à la même caisse, chaque site saisit la même clé (elle n'est pas distribuée automatiquement). Un échec d'écriture du fichier (droits insuffisants sur le dossier Secrets) est signalé après enregistrement.

Préfixe commandes : précautions

Ne modifiez pas le préfixe tant que des commandes sont en cours de traitement dans la caisse (statut initialisée, transmise ou ouverte). Attendez que toutes les commandes en cours soient facturées avant de changer le préfixe, sinon le rapprochement automatique des factures ne fonctionnera plus pour ces commandes.

Côté poste de caisse, le module Windows (V1.7 et supérieur) valide le préfixe en début de cycle et bloque le tick (aucune synchro ni échange des commandes) tant qu'un préfixe non conforme est configuré : mono-site = vide ou 3 lettres, multi-site = 3 lettres distinctes entre les sites. Un préfixe invalide interrompt donc franchement la synchronisation jusqu'à correction.

Préfixe obligatoire en présence de sites frères

Lorsqu'au moins un site frère est détecté et que le préfixe de commandes est vide, les numéros de commande des différents sites risquent d'entrer en collision dans la caisse. Une icône d'avertissement orange dédiée s'affiche alors dans le bandeau (indicateur passif à gauche de l'icône caisse, mise à jour en direct par le polling), et un email d'alerte administrateur est émis lors de la synchronisation automatique (au plus toutes les 4 h). Définissez un préfixe distinct par site frère pour lever l'alerte.

Le préfixe peut aussi être saisi dès la procédure d'installation (assistant), à l'étape de configuration de la caisse Kwisatz.

Tester la connexion¶

Le bouton Tester la connexion effectue un appel réel vers le serveur Kwisatz et affiche le résultat :

Succès : la communication avec le serveur est établie. L'icône de statut dans le bandeau passera au vert
Échec : la connexion a échoué. Le message d'erreur détaille la cause (serveur injoignable, timeout, authentification refusée, etc.). En cas de code HTTP 401/403, le message précise que l'accès a été refusé par le serveur API (clé API absente ou invalide) — formulation prudente, car un 403 peut aussi provenir du tunnel ou d'un pare-feu. Le test de connexion post-enregistrement utilise la clé fraîchement saisie (override runtime), sans attendre le rechargement de la page

Impact d'un échec de connexion

Si la connexion à la caisse échoue, la synchronisation automatique des produits et des commandes ne fonctionnera pas. Vérifiez les paramètres de connexion et assurez-vous que le serveur Kwisatz est accessible depuis le serveur hébergeant le site WordPress.

Enregistrer les modifications¶

Après avoir modifié les paramètres, cliquez sur Valider pour sauvegarder la nouvelle configuration. Un test de connexion est recommandé après chaque modification.

Cartes dépliables

Une fois la caisse configurée, les réglages de ce sous-onglet sont présentés sous forme de cartes dépliables, repliées par défaut : cliquez sur le titre d'une carte pour l'ouvrir.

Contrôle des connexions avec la caisse¶

Cette carte (dépliable, repliée par défaut) centralise le pilotage des échanges avec la caisse : deux interrupteurs de suspension et deux réglages de surveillance. Elle s'affiche dès qu'une caisse est configurée.

Enregistrement immédiat, sans bouton « Valider »

Les deux sélecteurs (intervalle de test et délai d'alerte) sont enregistrés en AJAX dès le changement de valeur, avec un retour « ✓ enregistré » transitoire. La couleur du bandeau de statut est rafraîchie aussitôt, sans attendre le polling.

Interrupteurs de suspension¶

Interrupteur	Option	Effet
Suspendre toute connexion avec la caisse	`cc-synchro-pause`	Kill-switch : coupe la remontée entrante, le cron de test de connexion (donc aussi le watchdog qui s'y exécute) et le transport des commandes vers la caisse — rien ne se perd, les commandes attendent la levée de la pause. À la toute première installation, cet interrupteur est posé à `true` automatiquement pour laisser configurer le site sans déclencher d'erreurs ; il faut le lever manuellement ensuite — tant qu'il est actif, un site neuf ne livre aucune commande à la caisse
Désactiver la synchronisation des produits	`cc-synchro-produits-desactivee`	Gèle uniquement la remontée entrante des produits, commandes et factures. Le test de connexion reste actif

Dans les deux cas, la synchronisation manuelle (bandeau/popup), l'enrichissement par lot et les crons Boxtal restent opérationnels. Avec le seul interrupteur produits, les fichiers XML de commandes continuent d'être livrés à la caisse (le transport des commandes n'est coupé que par la suspension totale).

Grisage du maître

Lorsque « Suspendre toute connexion » est actif, l'interrupteur produits et le bloc des réglages de surveillance sont grisés (inactifs) : la suspension totale prime.

Réglages de surveillance¶

Réglage	Option	Description
Intervalle de test de connexion à la caisse	`cc-synchro-delai-verif-connexion`	Fréquence du test périodique de connexion : Jamais (tests désactivés), 5, 10, 20, 30 ou 60 minutes. « Jamais » (`0`) déplanifie le cron de test — et désactive donc aussi les emails d'alerte de silence, puisque le watchdog s'exécute dans ce cron
Délai d'alerte si plus de synchro	`cc-synchro-watchdog-delai-minutes`	Jamais (surveillance désactivée), 15, 30, 60 minutes, 2 h, 4 h, 8 h ou 24 h. Au-delà de ce délai sans contact du poste de caisse, le site signale (bandeau + email) que la synchronisation ne tourne plus (poste éteint, tâche planifiée désactivée, tunnel coupé ou token incorrect). « Jamais » (`0`) désactive cette surveillance

Régler le délai d'alerte au-dessus de la cadence réelle

Le délai d'alerte « plus de synchro » doit être supérieur à la cadence de synchronisation du poste de caisse et à l'intervalle de test de connexion ci-dessus, sous peine de fausse alerte ou de latence de détection. Le watchdog distingue le symptôme (silence prolongé constaté côté serveur via le heartbeat cc-synchro-dernier-contact) du diagnostic posé au 403 (token manquant / invalide).

Sécurité CRON de synchronisation¶

Cette carte gère le token de sécurité et le time-limit de la synchronisation automatique. Elle n'apparaît que lorsqu'une caisse est configurée.

Token de synchronisation¶

Le token est une chaîne secrète nécessaire pour autoriser les appels de synchronisation depuis le poste de caisse (en-tête Authorization: Bearer). Il est affiché en lecture seule.

Bouton	Description
Copier	Copie le token dans le presse-papiers
Régénérer le token	Génère un nouveau token (après confirmation). L'ancien token ne fonctionnera plus

Token commun aux sites frères

En présence de sites frères, le token de synchronisation est commun aux sites frères et géré par l'administrateur : le libellé le rappelle et le bouton Régénérer n'est pas proposé (sa rotation se fait au niveau de la configuration commune). Si la configuration commune est invalide, la carte indique que la synchronisation est suspendue jusqu'à correction par l'administrateur.

Stockage hors-webroot (fichier secret)

Le token n'est pas stocké en base de données : il réside dans un fichier secret hors-webroot, Caisse-Connect/{domaine}/Secrets/cc-synchro-token.php (constante CC_SYNCHRO_TOKEN), aux côtés des autres secrets (clés IA, Boxtal, identifiants e-mail). Sa présence est garantie automatiquement : il est créé à l'activation du plugin, avec un filet de sécurité idempotent qui le recrée si le fichier a disparu ou est corrompu. La régénération réécrit ce fichier de façon atomique.

Mise à jour du token sur la caisse

Après régénération du token, vous devez le mettre à jour dans la configuration du module installé sur le poste de caisse pour que les synchronisations automatiques continuent de fonctionner.

Time-limit de la synchronisation automatique¶

Champ	Limites	Description
Time-limit (secondes)	30 à 1200	Temps maximum en secondes accordé à une synchronisation automatique. Au-delà, le processus est arrêté et un avertissement est envoyé

Cliquez sur Enregistrer pour sauvegarder.