Belegdrucker einrichten: Verbindung herstellen und Bestellungen drucken

Der Print Agent von RestaurantManage ist ein schlanker Windows-Dienst, der Druckbefehle aus der Cloud empfängt und an Ihren Thermodrucker weiterleitet – für automatischen Belegdruck bei bezahlten Bestellungen oder Küchentickets. Der Agent unterstützt Netzwerkdrucker (TCP-Port 9100), USB-Drucker und Windows-Spooler-Verbindungen. Diese Anleitung behandelt Installation, Konfiguration, Druckerverbindung und Fehlerbehebung.

Wie funktioniert der Belegdruck?

Der Druckvorgang ist vollständig automatisiert. Wenn ein Kassierer eine Zahlung bestätigt oder ein Küchenticket ausgelöst wird, generiert das RestaurantManage-Backend den vollständigen Beleg als ESC/POS-Byte-Befehle. Diese Bytes werden über eine sichere WebSocket-Verbindung (PrintHub) an den Print Agent gesendet, der auf einem Windows-PC in Ihrem Restaurant läuft. Der Agent dekodiert die Daten und leitet sie direkt an den angeschlossenen Thermodrucker weiter. Der gesamte Prozess dauert weniger als zwei Sekunden von der Zahlungsbestätigung bis zum gedruckten Beleg.

Die vollständige Druckpipeline

Das Verständnis der gesamten Pipeline hilft bei der Fehlerbehebung. Dies ist die Ereignissequenz bei jedem Beleg- oder Küchenticketdruck:

1. Zahlung bestätigt: Der Kassierer markiert eine Bestellung als bezahlt, oder ein Küchenticket wird manuell ausgelöst.
2. Backend formatiert den Beleg: Der RestaurantManage-Server führt ReceiptFormattingService aus, der das Beleglayout mit ReceiptBuilder erstellt und es über EscPosCommands und EscPosRasterEncoder in ESC/POS-Byte-Befehle umwandelt.
3. Daten über PrintHub gesendet: Die formatierten Beleg-Bytes (als Base64 kodiert) werden über einen sicheren WebSocket-Kanal (SignalR PrintHub) an den richtigen Print Agent übertragen – identifiziert durch Ihre Restaurant-ID.
4. Print Agent empfängt den Auftrag: Der Windows-Dienst auf Ihrem lokalen PC empfängt die Base64-Nutzlast, dekodiert sie in rohe ESC/POS-Bytes und ermittelt, welcher Drucker verwendet werden soll.
5. Druckerausgabe: Die dekodierten Bytes werden direkt über Netzwerk-TCP, Windows-Spooler oder USB an den Thermodrucker gesendet – und der Beleg wird innerhalb von Sekunden gedruckt.

Was auf einem gedruckten Beleg enthalten ist

Jeder von RestaurantManage generierte Beleg enthält vollständige Transaktionsdetails. Die Kopfzeile zeigt Restaurantname, Adresse und Logo (falls konfiguriert). Der Hauptteil enthält Tischnummer, eine nummerierte Liste aller bestellten Artikel mit Mengen und Einzelpreisen, anwendbare Rabatte und eine detaillierte Steueraufschlüsselung nach Steuerkategorie. Die Fußzeile zeigt die Bestellsumme, Zahlungsmethode (Bar, Karte usw.), Datum und Uhrzeit der Zahlung sowie eine optionale Dankesnachricht. Küchentickets folgen einem vereinfachten Format, das nur Tischnummer, Artikelbezeichnungen, Mengen und etwaige Anmerkungen zeigt.

Wann werden Belege ausgelöst

Kundenbelege werden automatisch gedruckt, wenn der Kassierer die vollständige oder teilweise Zahlung einer Bestellung bestätigt. Küchentickets werden gedruckt, wenn eine neue Bestellung über das Kassiererpanel oder die mobile Kellner-App eingereicht wird. In beiden Fällen verwaltet das Backend den Druckauftrag vollständig und leitet ihn automatisch an den Print Agent weiter. Autorisiertes Personal kann auch einen Neudruck über das Admin-Panel initiieren, falls der ursprüngliche Druck fehlgeschlagen oder unleserlich war.

Wie installiere ich den Print Agent?

Die Installation dauert auf jedem modernen Windows-PC etwa fünf Minuten. Der PC muss während der Servicezeiten des Restaurants eingeschaltet bleiben, da der Print Agent als Windows-Dienst im Hintergrund läuft.

1. Herunterladen: Holen Sie sich den neuesten Print Agent-Installer aus Ihrem Admin-Panel oder kontaktieren Sie den Support.
2. Installieren: Führen Sie den Installer auf einem Windows-PC aus, der während der Servicezeiten eingeschaltet bleibt.
3. Konfigurieren: Öffnen Sie config.json und geben Sie die API-Basis-URL, die Restaurant-ID und den geheimen Agentenschlüssel ein (vom Administrator bereitgestellt).
4. Drucker verbinden: Schließen Sie Ihren Thermodrucker per USB an oder verbinden Sie ihn mit demselben Netzwerk wie den PC.
5. Dienst starten: Starten Sie den Print Agent – er verbindet sich automatisch mit PrintHub und zeigt einen grünen Statusindikator.
6. Testdruck: Verarbeiten Sie eine Testzahlung über das Kassiererpanel und überprüfen Sie, ob der Beleg korrekt gedruckt wird.

Systemanforderungen

Der Print Agent hat minimale Hardwareanforderungen, benötigt jedoch ein unterstütztes Betriebssystem und eine kompatible Laufzeitumgebung:

• Betriebssystem: Windows 10 (Version 1909 oder höher) oder Windows 11. Der Print Agent ist ein reiner Windows-Dienst und läuft nicht unter macOS oder Linux.
• Laufzeitumgebung: .NET 8 Runtime muss installiert sein. Der Installer fordert Sie zum Download auf, falls nicht vorhanden – kostenlos von Microsoft.
• Internetverbindung: Eine stabile Internetverbindung ist für die Kommunikation mit der RestaurantManage-Cloud erforderlich. Der Agent verbindet sich nach kurzen Unterbrechungen automatisch neu.
• Netzwerkzugang: Der PC muss den Drucker erreichen können – entweder per USB-Kabel oder im selben lokalen Netzwerksegment.
• Prozessor und RAM: Jeder moderne Prozessor mit mindestens 512 MB freiem RAM ist ausreichend. Der Agent ist sehr ressourcenschonend.

Als Windows-Dienst ausführen

Für den Produktionseinsatz sollte der Print Agent als Windows-Dienst installiert werden, damit er beim PC-Start automatisch gestartet wird – noch bevor sich ein Benutzer anmeldet. Um ihn als Dienst zu registrieren, klicken Sie mit der rechten Maustaste auf install-service.bat und wählen Sie Als Administrator ausführen. Dadurch wird der Agent beim Windows Service Control Manager unter dem Namen RestaurantPrintAgent registriert. Nach der Installation können Sie ihn über das Dienste-Panel (services.msc) oder die Befehlszeile mit sc start RestaurantPrintAgent und sc stop RestaurantPrintAgent verwalten. Um den Dienst zu entfernen, führen Sie uninstall-service.bat als Administrator aus.

Restaurant-ID und geheimen Schlüssel finden

Die Restaurant-ID ist der eindeutige Bezeichner Ihres Restaurants im RestaurantManage-System. Sie finden sie im Admin-Panel unter Einstellungen → Restaurantinformationen. Der geheime Agentenschlüssel ist eine separate Anmeldeinformation, die den Print Agent gegenüber dem PrintHub-WebSocket-Endpunkt authentifiziert – nicht identisch mit Ihrem Benutzerpasswort. Um einen geheimen Schlüssel zu generieren oder neu zu generieren, gehen Sie zu Einstellungen → Print Agent im Admin-Panel und klicken auf Neuen Schlüssel generieren. Kopieren Sie den Schlüssel sofort und fügen Sie ihn in config.json ein – er wird nach dem Navigieren nicht mehr angezeigt. Wenn Sie den Schlüssel verlieren, generieren Sie einfach einen neuen; der alte wird automatisch ungültig.

Welche Druckerverbindungstypen werden unterstützt?

Der Print Agent unterstützt drei Verbindungsmethoden mit automatischem Fallback zwischen ihnen. Netzwerkdrucker, USB-Drucker und Windows-Spooler-Verbindungen werden alle unterstützt. Der Agent versucht zunächst Spooler, wechselt dann zu direktem USB und versucht schließlich UNC-Netzwerkfreigaben.

Netzwerkdrucker (empfohlen)

Netzwerkdrucker sind die empfohlene Verbindungsmethode für die meisten Restaurants. Ein netzwerkverbundener Thermodrucker hat seine eigene IP-Adresse und akzeptiert rohe Druckdaten auf TCP-Port 9100 – dem Standardport für ESC/POS-Druck. Zur Einrichtung verbinden Sie den Drucker mit einem Ethernet-Kabel mit Ihrem Router oder Switch und verwenden dann die eingebaute Konfigurationsseite des Druckers oder das Frontpanelmenü, um ihm eine statische IP-Adresse zuzuweisen (z. B. 192.168.1.100). Geben Sie diese IP-Adresse und Port 9100 in der Print Agent-Konfiguration ein. Eine statische IP ist wichtig – wenn der Drucker bei jedem Neustart eine neue IP vom DHCP erhält, schlagen Druckaufträge fehl.

USB- und Windows-Spooler-Drucker

USB-Thermodrucker verbinden sich direkt mit dem Windows-PC, auf dem der Print Agent läuft. Nach dem Anschließen des USB-Kabels installieren Sie bei Bedarf den Windows-Treiber des Herstellers (viele moderne ESC/POS-Drucker verwenden einen in Windows enthaltenen Standardtreiber). Der Print Agent erkennt den Drucker über den Windows-Spooler. Wenn der Drucker nicht im Spooler erscheint, kann die direkte USB-Adressierung versucht werden: Der Agent kann direkt in USB-Gerätepfade wie \\?\USB001 oder Parallelportpfade wie LPT1 schreiben.

Automatische Fallback-Reihenfolge

Wenn ein Druckauftrag eingeht, versucht der Print Agent die Verbindungsmethoden in dieser Reihenfolge: 1) Windows-Spooler – wenn der Drucker in Windows registriert und über den Spooler erreichbar ist, wird diese Methode zuerst verwendet. 2) Direktes USB – schlägt Spooler fehl, versucht der Agent, direkt in USB-Gerätepfade (USB001, USB002 usw.) und LPT-Ports zu schreiben. 3) UNC-Netzwerkfreigabe – als letzter Ausweg versucht der Agent, den Drucker über einen Windows-Netzwerkfreigabepfad zu erreichen. Schlagen alle drei Methoden fehl, wird der Fehler im Ordner logs/ mit Details protokolliert.

Wie konfiguriere ich den Print Agent?

Der Print Agent wird über eine einzige config.json-Datei im Installationsverzeichnis konfiguriert. Alle Einstellungen sind im Klartext und treten beim nächsten Start (oder Neustart) des Dienstes in Kraft. Es gibt keine grafische Oberfläche für die Konfiguration – das Bearbeiten der Datei mit einem beliebigen Texteditor genügt.

Die Datei config.json erklärt

Die Konfigurationsdatei hat drei Pflichtfelder und akzeptiert optionale Druckereinstellungen:

• ApiBaseUrl: Die Basis-URL Ihres RestaurantManage-Servers, z. B. <code>https://restaurantmanage.xyz</code>. Fügen Sie keinen abschließenden Schrägstrich hinzu. Der Print Agent verwendet diese URL, um sich mit PrintHub zu verbinden und nach Updates zu suchen.
• RestaurantId: Der eindeutige Bezeichner Ihres Restaurants. Sie finden ihn im Admin-Panel unter Einstellungen → Restaurantinformationen.
• AgentSecretKey: Der im Admin-Panel unter Einstellungen → Print Agent generierte geheime Schlüssel. Dieser Schlüssel authentifiziert den Agent gegenüber dem Server ohne Benutzeranmeldung. Halten Sie ihn vertraulich.

Ein vollständiges config.json-Beispiel sieht so aus: {"ApiBaseUrl": "https://restaurantmanage.xyz", "RestaurantId": "ihre-restaurant-id", "AgentSecretKey": "ihr-geheimer-schluessel"}. Starten Sie nach dem Bearbeiten der Datei den Print Agent-Dienst neu, damit die Änderungen wirksam werden.

Druckername und IP-Konfiguration

Für Netzwerkdrucker benötigen Sie die IP-Adresse des Druckers. So finden Sie sie: Die meisten Thermodrucker drucken eine Konfigurationsseite, wenn Sie beim Einschalten die Vorschubtaste gedrückt halten – die IP-Adresse ist dort aufgeführt. Alternativ prüfen Sie die DHCP-Clientliste Ihres Routers nach dem Hostnamen des Druckers. Sobald Sie die IP haben, weisen Sie sie als statische Adresse in den Netzwerkeinstellungen des Druckers zu, damit sie sich nie ändert. Für Windows-Spooler-Drucker muss der Druckername exakt mit dem übereinstimmen, was in Windows-Einstellungen → Drucker und Scanner angezeigt wird. Druckernamen unterscheiden Groß- und Kleinschreibung.

Protokolldateien und Diagnose

Der Print Agent schreibt detaillierte Protokolle in den Unterordner logs/ im Installationsverzeichnis. Protokolldateien werden nach Datum benannt (z. B. log-2026-04-06.txt) und täglich rotiert. Jeder Protokolleintrag enthält einen Zeitstempel, Schweregrad (INFO, WARNUNG, FEHLER) und eine Beschreibung des Vorgangs. Wenn Sie einen Druckfehler diagnostizieren, prüfen Sie die Protokolldatei des Problemdatums – die genaue Fehlermeldung gibt an, ob das Problem netzwerk-, authentifizierungs- oder druckerbezogen ist.

Wie funktionieren automatische Updates?

Der Print Agent prüft etwa alle 2,5 Stunden auf Updates, indem er den Update-Endpunkt auf dem RestaurantManage-Server aufruft. Wenn eine neue Version verfügbar ist, lädt er das Update-Paket als ZIP-Datei in einen Ordner für ausstehende Updates herunter, führt das Installationsskript aus und startet den Dienst automatisch neu. So läuft Ihr Restaurant immer mit der neuesten Version ohne manuellen Eingriff. Update-Prüfungen enthalten ein zeitliches Jitter pro Restaurant, um zu verhindern, dass alle Agenten gleichzeitig aktualisieren.

Häufige Probleme beheben

Die meisten Druckprobleme fallen in eine von drei Kategorien: Verbindungsprobleme, Druckerhardwareprobleme oder Konfigurationsfehler. Die Protokolldateien im Ordner logs/ sind der beste Ausgangspunkt für die Diagnose jedes Problems.

Verbindungs- und Authentifizierungsfehler

• Agent verbindet sich nicht mit dem Server: Überprüfen Sie, ob ApiBaseUrl in config.json korrekt und vom PC erreichbar ist. Öffnen Sie einen Browser auf demselben PC und navigieren Sie zur API-URL – Sie sollten eine Antwort sehen. Stellen Sie sicher, dass der PC eine aktive Internetverbindung hat.
• Authentifizierungsfehler (Fehler 401 in den Protokollen): AgentSecretKey ist falsch oder wurde neu generiert. Melden Sie sich beim Admin-Panel an, generieren Sie einen neuen Schlüssel unter Einstellungen → Print Agent, aktualisieren Sie config.json und starten Sie den Dienst neu.
• Verbindung bricht häufig ab und stellt sich neu her: Dies deutet in der Regel auf Netzwerkinstabilität hin. Wechseln Sie von WLAN zu kabelgebundenem Ethernet. Prüfen Sie, ob eine Firewall oder Antivirensoftware ausgehende WebSocket-Verbindungen blockiert (der Agent verwendet HTTPS-Port 443).
• Agent verbindet sich, empfängt aber keine Druckaufträge: Bestätigen Sie, dass die Restaurant-ID in config.json genau mit der im Admin-Panel übereinstimmt (Groß-/Kleinschreibung beachten). Stellen Sie auch sicher, dass der Print Agent unter Einstellungen → Print Agent aktiviert ist.

Druckqualitäts- und Kodierungsprobleme

• Unleserliche Zeichen oder Symbole auf dem Beleg: Ihr Thermodrucker unterstützt möglicherweise den von RestaurantManage verwendeten ESC/POS-Befehlssatz nicht vollständig. Prüfen Sie die Druckerdokumentation auf Kompatibilität. Die meisten 58-mm- und 80-mm-Thermodrucker, die nach 2015 hergestellt wurden, sind kompatibel.
• Beleg wird gedruckt, aber Text ist abgeschnitten: Die Papierbreiteneinstellung könnte falsch sein. RestaurantManage formatiert Belege standardmäßig für 80-mm-Papier. Wenn Sie einen 58-mm-Drucker verwenden, kontaktieren Sie den Support, um den Schmalpapiermodus zu aktivieren.
• Beleg wird leer oder nur mit teilweisem Inhalt gedruckt: Dies kann auf eine leere Papierrolle oder einen verstopften Druckkopf hinweisen. Ersetzen Sie das Papier und reinigen Sie den Druckkopf mit einem trockenen Tuch. Wenn das Problem anhält, testen Sie den Drucker direkt unter Windows, um das Problem zu isolieren.
• Sonderzeichen oder arabischer/RTL-Text werden nicht korrekt gedruckt: Stellen Sie sicher, dass der Zeichensatz Ihres Druckers auf UTF-8 oder die geeignete Codepage für Ihre Sprache eingestellt ist. Diese Einstellung ist in der Regel über das Konfigurationsmenü des Druckers zugänglich.

Fehler beim Starten des Dienstes

• Agent startet nicht als Windows-Dienst: Sie müssen install-service.bat als Administrator ausführen (Rechtsklick → Als Administrator ausführen). Ohne erhöhte Berechtigungen kann der Dienst nicht beim Windows Service Control Manager registriert werden.
• Dienst startet und stoppt sofort: Prüfen Sie die Windows-Ereignisanzeige (eventvwr.msc) unter Windows-Protokolle → Anwendung auf Fehlermeldungen von RestaurantPrintAgent. Prüfen Sie auch den Ordner logs/ auf Startfehler. Häufige Ursachen sind fehlende oder fehlerhafte config.json, fehlendes .NET 8 Runtime oder Portkonflikte.
• .NET Runtime fehlt: Laden Sie .NET 8 Runtime von https://dotnet.microsoft.com herunter und installieren Sie es. Starten Sie danach den Print Agent-Dienst neu.
• Firewall blockiert den Agent: Windows Defender oder eine Drittanbieter-Firewall könnte die ausgehende Verbindung des Agents blockieren. Fügen Sie eine Ausnahme für die ausführbare Datei des Print Agents in Ihren Firewall-Einstellungen hinzu.

Verwandte Anleitungen

• Kassiererpanel: So verarbeiten Sie Zahlungen, die den Belegdruck auslösen
• Küchenanzeige: So integriert sich der Küchenticket-Druck in den Bestellablauf
• Erste Schritte: Vollständige Einrichtungsanleitung von der Registrierung bis zur ersten Bestellung