Configuration de l'imprimante de reçus : comment connecter et imprimer les commandes

Le Print Agent de RestaurantManage est un service Windows léger qui reçoit les commandes d'impression depuis le cloud et les envoie à votre imprimante thermique de reçus — permettant l'impression automatique de reçus lorsque les commandes sont payées ou lorsque des tickets de cuisine doivent être imprimés. L'agent prend en charge les imprimantes réseau (TCP port 9100), les imprimantes USB et les connexions Windows Spooler. Ce guide couvre l'installation, la configuration, la connexion des imprimantes et le dépannage.

Comment fonctionne l'impression des reçus ?

Le flux d'impression est entièrement automatisé. Lorsqu'un caissier confirme un paiement ou qu'un ticket de cuisine est déclenché, le backend de RestaurantManage génère le reçu complet sous forme de commandes d'octets ESC/POS. Ces octets sont envoyés via une connexion WebSocket sécurisée (PrintHub) au Print Agent fonctionnant sur un PC Windows dans votre restaurant. L'agent décode les données et les transmet directement à l'imprimante thermique connectée. L'ensemble du processus prend moins de deux secondes, de la confirmation du paiement au reçu imprimé.

Le pipeline d'impression complet

Comprendre le pipeline complet aide au dépannage. Voici la séquence d'événements chaque fois qu'un reçu ou un ticket de cuisine est imprimé :

1. Paiement confirmé : Le caissier marque une commande comme payée, ou un ticket de cuisine est déclenché manuellement.
2. Le backend formate le reçu : Le serveur RestaurantManage exécute ReceiptFormattingService, qui construit la mise en page du reçu avec ReceiptBuilder et le convertit en commandes d'octets ESC/POS via EscPosCommands et EscPosRasterEncoder.
3. Données envoyées via PrintHub : Les octets du reçu formaté (encodés en Base64) sont diffusés via un canal WebSocket sécurisé (SignalR PrintHub) vers le bon Print Agent — identifié par l'ID de votre restaurant.
4. Le Print Agent reçoit le travail : Le service Windows fonctionnant sur votre PC local reçoit le payload Base64, le décode en octets ESC/POS bruts et identifie quelle imprimante utiliser.
5. Sortie de l'imprimante : Les octets décodés sont envoyés directement à l'imprimante thermique via TCP réseau, Windows Spooler ou USB — et le reçu est imprimé en quelques secondes.

Ce qui est inclus sur un reçu imprimé

Chaque reçu généré par RestaurantManage comprend un ensemble complet de détails de transaction. L'en-tête affiche le nom, l'adresse et le logo du restaurant (si configuré). Le corps comprend le numéro de table, une liste numérotée de tous les articles commandés avec les quantités et les prix unitaires, les remises applicables et une ventilation fiscale détaillée par catégorie. Le pied de page affiche le total de la commande, le mode de paiement (espèces, carte, etc.), la date et l'heure du paiement et un message de remerciement optionnel. Les tickets de cuisine suivent un format simplifié montrant uniquement le numéro de table, les noms des articles, les quantités et les notes éventuelles.

Quand les reçus sont-ils déclenchés ?

Les reçus clients s'impriment automatiquement lorsque le caissier confirme le paiement total ou partiel d'une commande. Les tickets de cuisine s'impriment lorsqu'une nouvelle commande est soumise depuis le panel caissier ou l'application mobile du serveur. Dans les deux cas, le travail d'impression est entièrement géré par le backend et acheminé automatiquement vers le Print Agent. Le personnel autorisé peut également lancer une réimpression depuis le panel d'administration si l'impression originale a été manquée ou était illisible.

Comment installer le Print Agent ?

L'installation prend environ cinq minutes sur n'importe quel PC Windows moderne. Le PC doit rester allumé pendant les heures de service du restaurant, car le Print Agent fonctionne comme un service Windows en arrière-plan.

1. Télécharger : Obtenez le dernier installateur du Print Agent depuis votre panel d'administration ou contactez le support.
2. Installer : Exécutez l'installateur sur un PC Windows qui restera allumé pendant les heures de service.
3. Configurer : Ouvrez config.json et saisissez l'URL de base de l'API, l'ID du restaurant et la clé secrète de l'agent (fournie par votre administrateur).
4. Connecter l'imprimante : Branchez votre imprimante thermique via USB ou connectez-la au même réseau que le PC.
5. Démarrer le service : Lancez le Print Agent — il se connecte à PrintHub automatiquement et affiche un indicateur d'état vert.
6. Impression de test : Traitez un paiement de test depuis le panel caissier et vérifiez que le reçu s'imprime correctement.

Configuration requise

Le Print Agent a des exigences matérielles minimales mais dépend d'un système d'exploitation et d'un environnement d'exécution compatibles :

• Système d'exploitation : Windows 10 (version 1909 ou ultérieure) ou Windows 11. Le Print Agent est un service exclusif Windows et ne fonctionne pas sur macOS ni Linux.
• Environnement d'exécution : .NET 8 Runtime doit être installé. L'installateur vous invitera à le télécharger s'il n'est pas présent — il est gratuit auprès de Microsoft.
• Connexion Internet : Une connexion Internet stable est requise pour communiquer avec le cloud RestaurantManage. L'agent se reconnecte automatiquement après de brèves interruptions.
• Accès réseau : Le PC doit pouvoir accéder à l'imprimante — soit via câble USB, soit sur le même segment de réseau local.
• Processeur et RAM : Tout processeur moderne avec au moins 512 Mo de RAM disponible est suffisant. L'agent est très léger.

Fonctionner comme service Windows

Pour une utilisation en production, le Print Agent doit être installé comme service Windows afin de démarrer automatiquement au démarrage du PC — même avant qu'un utilisateur ne se connecte. Pour l'enregistrer comme service, faites un clic droit sur install-service.bat et choisissez Exécuter en tant qu'administrateur. Cela enregistre l'agent auprès du Gestionnaire de contrôle de services Windows sous le nom RestaurantPrintAgent. Après l'installation, vous pouvez le gérer depuis le panneau Services (services.msc) ou en ligne de commande avec sc start RestaurantPrintAgent et sc stop RestaurantPrintAgent. Pour supprimer le service, exécutez uninstall-service.bat en tant qu'administrateur.

Trouver votre ID de restaurant et votre clé secrète

L'ID du restaurant est l'identifiant unique de votre restaurant dans le système RestaurantManage. Vous le trouverez dans le panel d'administration sous Paramètres → Informations du restaurant. La clé secrète de l'agent est un identifiant distinct qui authentifie le Print Agent auprès du endpoint WebSocket de PrintHub — ce n'est pas le même que votre mot de passe utilisateur. Pour générer ou régénérer une clé secrète, allez dans Paramètres → Print Agent dans le panel d'administration et cliquez sur Générer une nouvelle clé. Copiez la clé immédiatement et collez-la dans config.json — elle ne sera plus affichée après navigation. Si vous perdez la clé, générez-en simplement une nouvelle ; l'ancienne sera invalidée automatiquement.

Quels types de connexion d'imprimante sont pris en charge ?

Le Print Agent prend en charge trois méthodes de connexion avec basculement automatique entre elles. Les imprimantes réseau, les imprimantes USB et les connexions Windows Spooler sont toutes prises en charge. L'agent essaie d'abord Spooler, puis passe à l'USB direct et tente enfin les partages réseau UNC.

Imprimantes réseau (recommandé)

Les imprimantes réseau sont la méthode de connexion recommandée pour la plupart des restaurants. Une imprimante thermique connectée au réseau dispose de sa propre adresse IP et accepte les données d'impression brutes sur le port TCP 9100 — le port standard pour l'impression ESC/POS. Pour la configuration, connectez l'imprimante au routeur ou au commutateur avec un câble Ethernet, puis utilisez la page de configuration intégrée de l'imprimante ou le menu du panneau avant pour lui attribuer une adresse IP statique (par exemple, 192.168.1.100). Saisissez cette adresse IP et le port 9100 dans la configuration du Print Agent. L'IP statique est importante — si l'imprimante reçoit une nouvelle IP du DHCP à chaque redémarrage, les travaux d'impression échoueront.

Imprimantes USB et Windows Spooler

Les imprimantes thermiques USB se connectent directement au PC Windows exécutant le Print Agent. Après la connexion du câble USB, installez le pilote Windows du fabricant si nécessaire (de nombreuses imprimantes ESC/POS modernes utilisent un pilote générique inclus dans Windows). Le Print Agent détectera l'imprimante via Windows Spooler. Si l'imprimante n'apparaît pas dans le Spooler, la méthode d'adressage USB direct peut être tentée : l'agent peut écrire directement dans des chemins de périphériques USB comme \\?\USB001 ou des chemins de port parallèle comme LPT1.

Ordre de basculement automatique

Lorsqu'un travail d'impression est reçu, le Print Agent essaie les méthodes de connexion dans cet ordre : 1) Windows Spooler — si l'imprimante est enregistrée dans Windows et accessible via le Spooler, cette méthode est utilisée en premier. 2) USB direct — si Spooler échoue, l'agent essaie d'écrire directement dans les chemins de périphériques USB (USB001, USB002, etc.) et les ports LPT. 3) Partage réseau UNC — en dernier recours, l'agent tente d'accéder à l'imprimante via un chemin de partage réseau Windows. Si les trois méthodes échouent, l'erreur est consignée dans le dossier logs/ avec les détails.

Comment configurer le Print Agent ?

Le Print Agent est configuré via un unique fichier config.json situé dans le répertoire d'installation. Tous les paramètres sont en texte brut et prennent effet au prochain démarrage (ou redémarrage) du service. Il n'y a pas d'interface graphique pour la configuration — modifier le fichier avec n'importe quel éditeur de texte suffit.

Explication du fichier config.json

Le fichier de configuration comporte trois champs obligatoires et accepte des paramètres optionnels d'imprimante :

• ApiBaseUrl : L'URL de base de votre serveur RestaurantManage, par exemple <code>https://restaurantmanage.xyz</code>. N'incluez pas de barre oblique finale. Le Print Agent utilise cette URL pour se connecter à PrintHub et vérifier les mises à jour.
• RestaurantId : L'identifiant unique de votre restaurant. Vous le trouverez dans le panel d'administration sous Paramètres → Informations du restaurant.
• AgentSecretKey : La clé secrète générée dans le panel d'administration sous Paramètres → Print Agent. Cette clé authentifie l'agent auprès du serveur sans nécessiter de connexion utilisateur. Gardez-la confidentielle.

Un exemple complet de config.json ressemble à ceci : {"ApiBaseUrl": "https://restaurantmanage.xyz", "RestaurantId": "votre-id-restaurant", "AgentSecretKey": "votre-cle-secrete"}. Après avoir modifié le fichier, redémarrez le service Print Agent pour que les modifications prennent effet.

Configuration du nom et de l'IP de l'imprimante

Pour les imprimantes réseau, vous avez besoin de l'adresse IP de l'imprimante. Pour la trouver : la plupart des imprimantes thermiques impriment une page de configuration lorsque vous maintenez le bouton d'alimentation enfoncé lors du démarrage — l'adresse IP y est indiquée. Vous pouvez aussi vérifier la liste des clients DHCP de votre routeur pour trouver le nom d'hôte de l'imprimante. Une fois l'IP obtenue, attribuez-la comme adresse statique dans les paramètres réseau de l'imprimante. Pour les imprimantes Windows Spooler, le nom de l'imprimante doit correspondre exactement à ce qui apparaît dans Paramètres Windows → Imprimantes et scanners. Les noms d'imprimantes sont sensibles à la casse.

Fichiers journaux et diagnostic

Le Print Agent écrit des journaux détaillés dans le sous-dossier logs/ du répertoire d'installation. Les fichiers journaux sont nommés par date (par ex. log-2026-04-06.txt) et tournent quotidiennement. Chaque entrée de journal comprend un horodatage, un niveau de gravité (INFO, AVERTISSEMENT, ERREUR) et une description de ce qui s'est passé. Si vous diagnostiquez un échec d'impression, consultez le fichier journal de la date du problème — le message d'erreur exact indiquera si le problème est lié au réseau, à l'authentification ou à l'imprimante.

Comment fonctionne la mise à jour automatique ?

Le Print Agent vérifie les mises à jour toutes les 2,5 heures environ en appelant le endpoint de mise à jour sur le serveur RestaurantManage. Si une nouvelle version est disponible, il télécharge le paquet de mise à jour sous forme de fichier ZIP dans un dossier de mises à jour en attente, exécute le script d'installation et redémarre le service automatiquement. Cela signifie que votre restaurant exécute toujours la dernière version sans intervention manuelle. Les vérifications de mise à jour incluent un décalage temporel par restaurant pour éviter que tous les agents se mettent à jour simultanément.

Dépannage des problèmes courants

La plupart des problèmes d'impression appartiennent à l'une de trois catégories : problèmes de connexion, problèmes matériels d'imprimante ou erreurs de configuration. Les fichiers journaux dans le dossier logs/ sont le meilleur point de départ pour diagnostiquer tout problème.

Erreurs de connexion et d'authentification

• L'agent ne se connecte pas au serveur : Vérifiez que ApiBaseUrl dans config.json est correct et accessible depuis le PC. Ouvrez un navigateur sur le même PC et accédez à l'URL de l'API — vous devriez voir une réponse. Vérifiez que le PC dispose d'une connexion Internet active.
• Échec d'authentification (erreur 401 dans les journaux) : AgentSecretKey est incorrect ou a été régénéré. Connectez-vous au panel d'administration, générez une nouvelle clé sous Paramètres → Print Agent, mettez à jour config.json et redémarrez le service.
• La connexion se coupe et se reconnecte fréquemment : Cela indique généralement un problème d'instabilité réseau. Passez du Wi-Fi à l'Ethernet filaire. Vérifiez si un pare-feu ou antivirus bloque les connexions WebSocket sortantes (l'agent utilise HTTPS port 443).
• L'agent se connecte mais ne reçoit pas de travaux d'impression : Confirmez que l'ID du restaurant dans config.json correspond exactement à celui du panel d'administration (sensible à la casse). Vérifiez également que le Print Agent est activé dans Paramètres → Print Agent.

Problèmes de qualité d'impression et d'encodage

• Caractères ou symboles illisibles sur le reçu : Votre imprimante thermique peut ne pas prendre en charge complètement le jeu de commandes ESC/POS utilisé par RestaurantManage. Consultez la documentation de l'imprimante pour vérifier la compatibilité. La plupart des imprimantes thermiques de 58 mm et 80 mm fabriquées après 2015 sont compatibles.
• Le reçu s'imprime mais le texte est coupé : Le paramètre de largeur du papier peut être incorrect. RestaurantManage formate les reçus pour du papier 80 mm par défaut. Si vous utilisez une imprimante 58 mm, contactez le support pour activer le mode papier étroit.
• Le reçu s'imprime vierge ou avec seulement un contenu partiel : Cela peut indiquer un rouleau de papier bas ou une tête d'impression obstruée. Remplacez le papier et nettoyez la tête d'impression avec un chiffon sec. Si le problème persiste, testez l'imprimante directement depuis Windows pour isoler le problème.
• Les caractères spéciaux ou le texte arabe/RTL ne s'impriment pas correctement : Assurez-vous que le jeu de caractères de votre imprimante est réglé sur UTF-8 ou la page de codes appropriée pour votre langue. Ce paramètre est généralement accessible dans le menu de configuration de l'imprimante.

Échecs de démarrage du service

• L'agent ne démarre pas comme service Windows : Vous devez exécuter install-service.bat en tant qu'Administrateur (clic droit → Exécuter en tant qu'administrateur). Sans autorisations élevées, le service ne peut pas être enregistré auprès du Gestionnaire de contrôle de services Windows.
• Le service démarre puis s'arrête immédiatement : Vérifiez l'Observateur d'événements Windows (eventvwr.msc) sous Journaux Windows → Application pour les messages d'erreur de RestaurantPrintAgent. Consultez également le dossier logs/ pour les erreurs de démarrage. Les causes courantes sont un config.json manquant ou mal formé, un runtime .NET 8 manquant ou un conflit de ports.
• Runtime .NET manquant : Téléchargez et installez .NET 8 Runtime depuis https://dotnet.microsoft.com. Après l'installation, redémarrez le service Print Agent.
• Le pare-feu bloque l'agent : Windows Defender ou un pare-feu tiers peut bloquer la connexion sortante de l'agent. Ajoutez une exception pour l'exécutable du Print Agent dans les paramètres de votre pare-feu.

Guides associés

• Panel caissier : Comment traiter les paiements qui déclenchent l'impression des reçus
• Affichage cuisine : Comment l'impression des tickets de cuisine s'intègre dans le flux des commandes
• Démarrage : Guide de configuration complet de l'inscription à la première commande