Apicbase Anbindung einrichten
Der HsApicbaseConnector verbindet das Hypersoft-Kassensystem mit Apicbase, der Rezept- und Warenwirtschaft. Er überträgt automatisch zwei Arten von Daten von Hypersoft zu Apicbase:
- Produktkatalog: die aktiven, verkaufsfähigen Artikel mit Warengruppe, Verkaufspreis und MwSt.
- Verkaufsdaten: die abgeschlossenen Bons der Kasse, damit Apicbase Verbrauch und Bestand fortschreiben kann.
Die Übertragung läuft nur in eine Richtung (Hypersoft → Apicbase). Der Connector liest nichts aus Apicbase zurück und ändert den Hypersoft-Artikelstamm nicht. Er läuft im Hintergrund im Infobereich der Windows-Taskleiste und benötigt die Lizenz ePOS API - Apicbase.
Funktionsumfang
| Funktion | Beschreibung |
|---|---|
| Katalog-Übertragung | Sendet den vollständigen Artikelstamm einer Preisebene an Apicbase. Automatisch nur bei Änderungen und mindestens einmal täglich ab der eingestellten Katalog-Sendezeit; jederzeit manuell per Button. |
| Verkaufsdaten-Übertragung | Sendet abgeschlossene Bons im eingestellten Takt (Standard: alle 5 Minuten), auch vor der Festschreibung. Kein Bon wird doppelt gesendet. |
| Einrichtungsdialog | Standort-ID, Takt, Katalog-Sendezeit, Preisebene und Apicbase-Zugangsdaten pflegen, Zugangsdaten aus dem Portal abrufen, Verbindung testen. |
| Statusanzeige | Hauptfenster mit Status, Zeitpunkten der letzten Übertragungen, Fehlerliste und Protokoll; farbiges Symbol im Infobereich. |
Voraussetzungen
- Lizenz ePOS API - Apicbase für die Kundennummer (in einer Filiale wird ersatzweise die Lizenz der Zentrale geprüft).
- Die Schnittstelle Apicbase ist im Hypersoft-Portal aktiviert (Kachel Apicbase bei den Schnittstellen), und dort sind Client ID und Client Secret hinterlegt.
- Ein Apicbase-Konto mit Zugang zur Generic POS API, die Standort-ID (location_id) des Betriebs in Apicbase sowie Access-Token und Refresh-Token von Apicbase.
- Internetzugang der Kasse bzw. des Servers zu api.apicbase.com (HTTPS, TLS 1.2) und für den Portalabruf zu www.myhypersoft.de. Ein Proxy oder eine TLS-Inspection darf die Antworten nicht verändern.
- Pro Mandant läuft genau ein Connector. Er bedient genau eine Apicbase-Standort-ID.
Programmstart
Der Start des Connector wird im Remote Commander des Hypersoft Master Control Panel gestartet und läuft auf dem Kassenserver bzw. der Hauptkasse im jeweiligen Mandanten. Folgende Startparameter gibt es:
| Aufruf | Verhalten |
|---|---|
| HsApicbaseConnector.exe MCP <Mandant> <Benutzer> | Startet mit sichtbarem Fenster im angegebenen Mandanten, z. B. „MCP 10 1“. Fehlt die Einrichtung, öffnet sich automatisch der Einrichtungsdialog. |
| HsApicbaseConnector.exe AUTO | Startet unsichtbar im Infobereich der Taskleiste (für den Autostart). Der Mandant kommt aus der Kassen-INI ([HYPERSOFT-KASSE] WORK-MANDANT). Es erscheinen keine Dialoge; Probleme zeigt das rote Symbol mit einer Sprechblase. |
| Ohne oder mit unbekanntem Parameter | Es erscheint ein Hinweis, das Programm beendet sich. |
Pro Mandant und Rechner kann nur ein Connector laufen. Ein zweiter Start meldet im MCP-Modus „Der Apicbase-Connector läuft bereits in dieser Umgebung.“ und beendet sich; im AUTO-Modus beendet er sich still. Connectoren für verschiedene Mandanten dürfen parallel laufen. Der erste automatische Übertragungslauf beginnt direkt nach dem Start.
Ersteinrichtung Schritt für Schritt
- Öffnen Sie im Hypersoft-Portal die Kachel Apicbase, aktivieren Sie die Schnittstelle und tragen Sie Client ID und Client Secret von Apicbase ein. Das Portal prüft dabei die Lizenz ePOS API - Apicbase für den Standort.
- Starten Sie den Connector im MCP-Modus, z. B. „HsApicbaseConnector.exe MCP 10 1“. Der Einrichtungsdialog öffnet sich automatisch (sonst im Hauptfenster auf Einrichtung… klicken).
- Tragen Sie die Standort-ID aus Apicbase ein.
- Prüfen Sie Sales-Intervall, Katalog-Sendezeit und Preisebene. Die Standardwerte sind 5 Minuten, 04:00 Uhr und Preisebene 0 (Hypersoft-Standardpreisebene).
- Klicken Sie auf Zugangsdaten aus Portal abrufen. Client-ID und Client-Secret werden in die Felder übernommen. Alternativ tragen Sie die Werte von Hand ein.
- Tragen Sie Access-Token und Refresh-Token ein.
- Kreuzen Sie Synchronisation aktiv an und klicken Sie auf Speichern.
- Klicken Sie auf Verbindung testen. Die Statusleiste zeigt „Verbindung ok“.
- Klicken Sie im Hauptfenster einmal auf Katalog jetzt senden und prüfen Sie das Ergebnis, z. B. „Katalog gesendet (1.234 Artikel).“
- Nehmen Sie den Connector für den Dauerbetrieb mit dem Parameter AUTO in den Autostart auf.
Wichtige Anmerkungen zur Ersteinrichtung: Beim ersten Einschalten für eine Standort-ID werden keine alten Bons nachgeschickt. Gesendet wird ab dem Zeitpunkt der Aktivierung (siehe Abschnitt „Übertragung der Verkaufsdaten“).
Einrichtungsdialog
Der Dialog besteht von oben nach unten aus einem Lizenz-Banner (nur bei fehlender Lizenz oder während der Lizenzprüfung), der Gruppe Konfiguration, der Gruppe Apicbase-Zugangsdaten, der Statusleiste und den Buttons Verbindung testen, Speichern und Abbrechen.
Felder der Gruppe Konfiguration:
| Feld | Bedeutung und erlaubte Werte |
|---|---|
| Synchronisation aktiv | Schaltet die automatische Übertragung ein oder aus. Ausgeschaltet bleibt der Connector passiv (graues Symbol, Status „Deaktiviert“). |
| Standort-ID | Die Apicbase-Standort-ID (location_id). Pflichtfeld bei aktiver Synchronisation, höchstens 100 Zeichen, ohne die Zeichen [ ] = ; |
| Sales-Intervall (Minuten) | Takt der automatischen Übertragung, 1 bis 60 Minuten (Standard 5). Eine Änderung wirkt ohne Neustart. |
| Katalog-Sendezeit (HH:mm) | Uhrzeit, ab der der Katalog einmal täglich gesendet wird, auch wenn er sich nicht geändert hat (Standard 04:00). |
| Preisebene | Hypersoft-Preisebene, aus der die Katalogpreise stammen. Ganze Zahl ab 0; Standard 0 = Standardpreisebene. |
Apicbase-Zugangsdaten: Für Client-ID, Client-Secret, Access-Token und Refresh-Token zeigt der Dialog nur, ob ein Wert gesetzt oder nicht gesetzt ist, nie den Wert selbst. Mit Ersetzen wird ein Feld leer und editierbar; Verwerfen bricht die Eingabe dieses Felds ab und behält den gespeicherten Wert. Bei der Ersteinrichtung sind alle vier Felder sofort editierbar. Die Werte werden verschlüsselt im Hypersoft-Clientverzeichnis gespeichert.
Speichern und Eingabeprüfung: Geprüft wird erst beim Speichern. Ungültige Felder bekommen ein rotes Fehlersymbol (Fehlertext als Tooltip), die Statusleiste nennt den Fehler bzw. „N Eingaben prüfen“, und der Cursor springt in das erste fehlerhafte Feld. Gespeichert wird nur, wenn alle Felder gültig sind.
Zugangsdaten aus Portal abrufen: Holt Client-ID und Client-Secret aus dem Hypersoft-Portal. Access- und Refresh-Token liefert das Portal nicht. Der Abruf startet nur per Klick:
- Sind bereits Zugangsdaten gespeichert, werden die neuen Werte sofort gespeichert („Zugangsdaten aus dem Portal übernommen und gespeichert.“). Hat sich die Client-ID geändert, müssen Access- und Refresh-Token neu eingetragen werden.
- Bei der Ersteinrichtung werden die Werte nur in die Felder übernommen; tragen Sie danach die Tokens ein und klicken Sie auf Speichern.
- Sind die Werte schon aktuell, erscheint „Zugangsdaten sind bereits aktuell.“.
- Bei einem Fehler bleibt alles unverändert. Häufige Meldungen: „Im Portal sind keine Zugangsdaten hinterlegt / Apicbase nicht freigeschaltet — bitte Portal-Einstellungen prüfen.“ und „Portal nicht erreichbar.“.
- In einer Filiale kann der erste Abruf bis zu 60 Sekunden dauern.
Verbindung testen: Prüft die gespeicherten Zugangsdaten bei Apicbase, also zuerst speichern, dann testen. Das Ergebnis steht in der Statusleiste:
| Anzeige | Bedeutung / Abhilfe |
|---|---|
| Verbindung ok | Zugangsdaten gültig. |
| Authentifizierung fehlgeschlagen | Client-ID/-Secret oder Tokens falsch bzw. abgelaufen: neu eintragen. |
| Rate-Limit erreicht, später erneut versuchen | Zu viele Anfragen; einige Minuten warten. |
| Anfrage von Apicbase abgelehnt / Apicbase-Serverfehler | Problem auf Apicbase-Seite; später erneut versuchen, ggf. Apicbase-Support. |
| Keine Verbindung zu Apicbase | Netzwerk, Firewall oder Proxy prüfen. |
| Zuerst speichern, bevor die Verbindung getestet werden kann. | Es sind noch keine Zugangsdaten gespeichert. |
Wichtige Anmerkungen zu Verbindung testen: Ein erfolgreicher Verbindungstest erneuert das Refresh-Token. Führen Sie den Test daher nicht während einer laufenden Übertragung aus.
Bedienung per Tastatur: Enter speichert, Esc bricht ab. Tastenkürzel: Alt+A (Synchronisation aktiv), Alt+O (Standort-ID), Alt+I (Sales-Intervall), Alt+K (Katalog-Sendezeit), Alt+P (Preisebene), Alt+Z (Portalabruf), Alt+V (Verbindung testen), Alt+S (Speichern), Alt+B (Abbrechen).
Hauptfenster
Statusbereich:
| Zeile | Inhalt |
|---|---|
| Mandant | Aktiver Hypersoft-Mandant. |
| Standort | Eingestellte Standort-ID oder „nicht konfiguriert“. |
| Status | „Aktiv“ (grün), „Deaktiviert“ (grau) oder „Fehler“ (rot), passend zum Symbol im Infobereich. |
| Letzter Katalog-Push | Zeitpunkt der letzten erfolgreichen Katalog-Übertragung (Ortszeit). |
| Letzte Sales-Übertragung | Zeitpunkt der letzten erfolgreichen Übertragung von Verkaufsdaten (Ortszeit). |
| Watermark | Höchste vollständig verarbeitete Bon-Nummer der festgeschriebenen Bons (technischer Wert für den Support). |
| Fehler seit | Zeitpunkt des ersten Fehlschlags eines noch bestehenden Fehlers. |
| Fehlermeldung | Aktueller Fehlertext, z. B. „Katalog: …“ oder „Sales: …“; ohne Fehler „nicht vorhanden“. Lange Texte erscheinen vollständig als Tooltip. |
Buttons:
| Button | Funktion |
|---|---|
| Einrichtung… (Alt+E) | Öffnet den Einrichtungsdialog. |
| Katalog jetzt senden (Alt+K) | Sendet sofort den vollständigen Katalog, auch wenn er unverändert ist, und auch bei ausgeschalteter Synchronisation. |
| Verkaufsdaten senden (Alt+V) | Startet sofort einen zusätzlichen Übertragungslauf (Katalog bei Bedarf, dann Verkaufsdaten). Bei ausgeschalteter Synchronisation passiert nichts. |
| Log öffnen (Alt+L) | Öffnet die Logdatei des aktuellen Tages im Standard-Editor. |
Während eine manuelle Aktion läuft, sind beide Sende-Buttons gesperrt. Das Ergebnis erscheint in der Ergebniszeile unter den Buttons, z. B. „Katalog gesendet (1.234 Artikel).“, „Sales gesendet (12 Tickets).“ oder „Keine neuen Verkaufstickets zu senden.“. Bei einem Fehler erscheint im MCP-Modus zusätzlich ein Meldungsfenster. Automatische Läufe ändern die Ergebniszeile nicht.
Fehlerliste, Details und Protokoll: Die Fehlerliste zeigt die letzten 200 Übertragungen mit Zeitpunkt, Art (catalog = Katalog, sales = Verkaufsdaten, portal = Portalabruf), HTTP-Status, Anzahl Tickets und Ergebnis („Erfolg“ grün, „Fehler“ rot). Ein Klick auf eine Zeile zeigt unter Details einen Auszug aus Anfrage und Antwort, ohne Zugangsdaten. Das Protokoll zeigt die laufenden Logzeilen.
Das Schließen (X) oder Minimieren legt das Fenster in den Infobereich; der Connector läuft weiter. Beendet wird er über das Kontextmenü des Symbols.
Symbol im Infobereich der Taskleiste
| Symbol | Bedeutung |
|---|---|
| Grau | Synchronisation ausgeschaltet. |
| Grün | Aktiv, kein Fehler. |
| Rot | Fehler: Konfiguration unvollständig, letzte Übertragung fehlgeschlagen oder Hypersoft-Datenbank nicht erreichbar. Der Connector versucht es bei jedem Lauf automatisch erneut. |
- Klick bzw. Doppelklick auf das Symbol blendet das Hauptfenster ein oder aus.
- Rechtsklick öffnet das Menü mit Öffnen und Beenden.
- Im AUTO-Modus erscheint bei einem neuen Fehler eine Sprechblase, z. B. „Synchronisation mit Apicbase gestört — wird automatisch wiederholt.“.
- Beim ersten Schließen des Fensters erscheint einmal der Hinweis „Der Connector läuft weiter im Infobereich der Taskleiste.“. Windows kann Sprechblasen unterdrücken (Fokus-Assistent).
Lizenz und Leerlauf
Die Lizenz ePOS API - Apicbase wird einmal beim Programmstart geprüft. Während der Prüfung zeigt ein Banner „Lizenzprüfung läuft…“. Fehlt die Lizenz, läuft das Programm im Leerlauf:
- Es wird nichts übertragen und nichts aus dem Portal abgerufen. Katalog jetzt senden, Verkaufsdaten senden und Zugangsdaten aus Portal abrufen sind gesperrt.
- Einrichtung…, Speichern und Verbindung testen bleiben bedienbar.
- Das Hauptfenster zeigt „Keine Apicbase-Lizenz (534): Das Programm läuft im Leerlauf (keine Synchronisation, kein Portalabruf). Nach der Lizenzierung bitte neu starten.“; im AUTO-Modus erscheint einmal eine Sprechblase.
- Starten Sie den Connector nach dem Einspielen der Lizenz neu.
Übertragung des Produktkatalogs
- Übertragen werden alle aktiven, verkaufsfähigen Artikel der eingestellten Preisebene mit PLU, Name, Warengruppe, Verkaufspreis und MwSt.
- Apicbase ersetzt bei jeder Übertragung den gesamten Katalog des Standorts.
- Automatisch wird der Katalog nur gesendet, wenn er sich seit der letzten erfolgreichen Übertragung geändert hat, und zusätzlich einmal täglich ab der Katalog-Sendezeit. Katalog jetzt senden sendet immer.
- Artikel ohne Namen werden als „Artikel <PLU>“ gesendet, Warengruppen ohne Text als „Warengruppe <Nr>“.
- Meldet Apicbase beim Senden von Verkaufsdaten unbekannte PLUs, sendet der Connector den Katalog automatisch erneut (höchstens einmal pro Stunde).
Kann der Katalog nicht gesendet werden, werden in diesem Lauf auch keine Verkaufsdaten gesendet. Sie folgen ohne Verlust, sobald der Katalog wieder in Ordnung ist.
Übertragung der Verkaufsdaten
Zeitpunkt: Im eingestellten Sales-Intervall (Standard alle 5 Minuten) sowie sofort per Verkaufsdaten senden.
Welche Bons werden gesendet?
- Abgeschlossene Bons, die noch nicht festgeschrieben sind (Tagesdaten), und festgeschriebene Bons nach dem Tagesabschluss. Ein Bon muss also nicht erst festgeschrieben werden, um übertragen zu werden.
- Festgeschriebene Bons werden berücksichtigt, wenn sie höchstens 30 Tage alt sind.
- Unvollständige oder gelöschte Bons werden nicht gesendet.
- Stornos werden mitgesendet (Positionen mit negativer Menge).
- Sales-Mix: Gesendet wird die Kopfzeile des Sales-Mix-Artikels (z. B. „Pizza Sucuk“ mit 12,00), nicht seine Bestandteile.
- Bons ohne übertragbare Position werden als erledigt markiert, aber nicht gesendet.
Kein doppelter Versand: Ein Bon, der vor der Festschreibung gesendet wurde, wird nach der Festschreibung nicht erneut gesendet. Wird ein gesendeter Bon nachträglich geändert, gilt er als neuer Bon und wird erneut gesendet.
Erst-Aktivierung: Beim ersten Einschalten für eine Standort-ID werden keine alten Bons übertragen. Der erste Lauf merkt sich nur den Ausgangsstand; gesendet wird ab dem folgenden Lauf. Wird die Standort-ID später geändert, beginnt die neue Standort-ID ebenso ohne Altbons.
Fehler: Lehnt Apicbase eine Übertragung ab oder ist keine Verbindung möglich, stoppt der Lauf. Das Symbol wird rot und der nächste Lauf wiederholt die Übertragung automatisch. Ein manuelles Zurücksetzen ist nicht nötig; nach einem fehlerfreien Lauf verschwindet der Fehler von selbst.
Protokoll und Logdatei
- Logdatei: <Hypersoft-Clientverzeichnis>\LOG\APICBASE-<Datum>-<Kassennummer>.log, eine Datei pro Tag. Öffnen Sie sie über Log öffnen.
- Jede Übertragung steht zusätzlich in der Fehlerliste des Hauptfensters.
- Logdatei, Fehlerliste und Meldungen enthalten nie Zugangsdaten oder Tokens.
- Alte Logdateien werden nicht automatisch gelöscht.
Meldungen und Fehlerbehebung
| Meldung | Ursache und Abhilfe |
|---|---|
| Katalog leer — kein Artikel aktiv/verkaufbar (Preisebene N). | In der eingestellten Preisebene hat kein verkaufsfähiger Artikel einen Preis. Preisebene im Einrichtungsdialog prüfen (Standard 0). |
| Katalog-Mapping fehlgeschlagen — doppelte PLU / MwSt-Code nicht auflösbar / Verkaufspreis fehlt: <PLUs> | Artikelstamm in Hypersoft korrigieren (genannte PLUs), dann erneut senden. |
| Zugangsdaten fehlen — Einrichtung erforderlich. | Zugangsdaten im Einrichtungsdialog eintragen bzw. aus dem Portal abrufen. |
| Authentifizierung bei Apicbase fehlgeschlagen. | Tokens ungültig oder abgelaufen. Neue Tokens eintragen, Verbindung testen. |
| Apicbase Rate-Limit erreicht. | Wird automatisch im nächsten Lauf wiederholt. |
| Keine Verbindung zu Apicbase möglich. | Netzwerk, Firewall und Proxy prüfen. |
| Antwort ist kein JSON — Proxy? | Ein Proxy oder eine TLS-Inspection verändert die Antwort. Freigabe für api.apicbase.com prüfen. |
| Watermark wurde extern verändert — zweite Instanz? | Ein zweiter Connector für denselben Mandanten und Standort läuft (z. B. auf einem anderen Rechner). Diesen beenden. |
| Sales-Zustand inkonsistent — Neustart erforderlich. | Connector neu starten; bleibt der Fehler, Hypersoft-Support kontaktieren. |
| Sync-Tick übersprungen — Konfiguration ungültig oder LocationId fehlt. | Standort-ID im Einrichtungsdialog eintragen. |
| Zustand in der Hypersoft-Datenbank kann nicht angelegt oder gelesen werden. | Datenbankverbindung und Rechte prüfen; der Connector versucht es automatisch erneut. |
| Gespeicherte Zugangsdaten nicht lesbar — bitte Hypersoft-Support kontaktieren. | Die gespeicherten Zugangsdaten sind beschädigt. Hypersoft-Support kontaktieren. |
| Der Apicbase-Connector läuft bereits in dieser Umgebung. | Für diesen Mandanten läuft schon ein Connector. Symbol im Infobereich prüfen. |
Wird derselbe Verkaufs-Batch dauerhaft mit HTTP 400 abgelehnt, sichern Sie die Details aus der Fehlerliste und kontaktieren Sie den Apicbase- bzw. Hypersoft-Support.
Konfigurationsdatei
Die Einstellungen des Einrichtungsdialogs stehen in der Sektion [APICBASE] der Datei allparam.cfg. Der Dialog ändert nur diese Schlüssel; andere Einträge der Datei bleiben unverändert.
| Schlüssel | Standard | Bedeutung |
|---|---|---|
| Enabled | 0 | Synchronisation aktiv (0/1). |
| LocationId | – | Apicbase-Standort-ID; Pflicht bei Enabled=1. |
| SalesIntervalMinutes | 5 | Takt in Minuten. |
| CatalogTime | 04:00 | Tägliche Katalog-Sendezeit (HH:mm). |
| PriceLevel | 0 | Hypersoft-Preisebene der Katalogpreise. |
Ungültige Werte führen nicht zum Absturz: Der Connector verwendet dann den Standardwert und schreibt eine Warnung ins Log.
Wichtige Anmerkungen zu Einschränkungen
- Nur Übertragung Hypersoft → Apicbase; kein Abgleich in Gegenrichtung.
- Filialen und Zentralen werden nicht zusammengefasst: Ein Mandant bedient genau eine Apicbase-Standort-ID. Mehrere Rechner mit demselben Mandanten werden nicht zuverlässig erkannt; pro Mandant darf nur ein Connector laufen.
- Steht der Connector länger als 30 Tage still, werden ältere festgeschriebene Bons nicht nachgesendet. Bons, die noch nicht festgeschrieben sind, werden weiterhin gesendet.
- Eine Übertragung umfasst bis zu 100 Bons in chronologischer Reihenfolge. Über mehrere Übertragungen hinweg kann ein älterer Bon nach einem jüngeren ankommen; Apicbase berücksichtigt ihn dann ggf. nicht im Bestand.
- Bei 150 % Anzeigeskalierung kann der Einrichtungsdialog auf Bildschirmen mit 1366×768 oder kleiner höher als der Bildschirm sein.
- Eine nachträglich eingespielte Lizenz wird erst nach einem Neustart erkannt.
Weiterführende Themen:
Zurück zum übergeordneten Thema: Stock Management