POS-Integrationen

Die Einstellungsseite Integrationen verbindet einen berechtigten HandyCafe-Server mit einem Ödeal-D2D-Terminal. Die Verfügbarkeit wird über HandyCafe Cloud geprüft. Menüeintrag und Seite sind vollständig ausgeblendet, wenn das Café Ödeal nicht nutzen darf.

Bevor Sie beginnen

Sie benötigen ein aktives HandyCafe-Cloud-Abonnement, einen Ödeal Merchant Key und einen Ödeal Secret Key. Außerdem müssen Sie das Terminal im Ödeal-Bereich Cihazlarım anlegen. Der genaue Name, den Sie diesem Terminal geben, ist sein externalDeviceKey. Beginnen Sie mit der Stage-Umgebung. Wechseln Sie erst dann zu Production, wenn Ödeal die Produktionsanmeldedaten und die Callback-Einrichtung freigegeben hat.

Ödeal einrichten

1. Öffnen Sie Einstellungen und wählen Sie Integrationen.
2. Geben Sie unter Ödeal-Konto den Merchant Key und den Secret Key ein, die Sie von Ödeal erhalten haben. HandyCafe sendet diese Werte direkt an HandyCafe Cloud. Sie werden verschlüsselt und weder in der lokalen Datenbank gespeichert noch erneut angezeigt.
3. Wählen Sie Verbindungstest. Liegen neue Schlüssel vor, speichert HandyCafe sie sicher, bevor die Verbindung zur Ödeal-API getestet wird. Dieser Test prüft ausschließlich das Ödeal-Konto. Er belegt nicht, dass das Terminal gekoppelt oder online ist.
4. Fügen Sie das Terminal hinzu. Vergeben Sie einen eindeutigen lokalen Gerätenamen. Tragen Sie unter Ödeal-Gerätename (externalDeviceKey) genau den Gerätenamen ein, der in Ödeal angelegt wurde. Ergänzen Sie anschließend die optionale PaxID, die Umgebung, die Zahlungswartezeit, die Stadt und den Bezirk des Kunden sowie den Mehrwertsteuersatz für Sitzungen und den für Bestellungen.
5. Aktivieren Sie POS-Integration aktiv und wählen Sie Speichern.
6. Führen Sie in der Stage-Umgebung eine Barzahlung mit Belegdruck und eine Kartenzahlung durch, um die Terminalkopplung und beide Abrechnungswege zu prüfen.

Pro Server wird in dieser Version nur ein aktives Ödeal-Terminal unterstützt. Das verhindert, dass eine Zahlung an ein ungewolltes Terminal geleitet wird, solange es keine Terminalauswahl für Kassierer gibt.

HandyCafe speichert den Terminalbestand lokal, bevor die Cloud ein neues Anmeldedatenpaar überprüft. Weist Ödeal die Anmeldedaten zurück, gehen Terminalname und Kopplungsfelder nicht verloren. Ein Terminal, das neue Anmeldedaten benötigt, wird als inaktiv gespeichert, bis diese Anmeldedaten für die gewählte Umgebung überprüft sind.

Die Seite Integrationen liest den Terminalbestand direkt aus der lokalen SQLite-Datenbank und zeigt ihn an, ohne auf die Cloud zu warten. Nur der Status der verschlüsselten Anmeldedaten und die zentrale Freigabe des Anbieters erfordern eine Cloud-Anfrage.

Weist Ödeal die Konfiguration zurück, zeigt HandyCafe die von Ödeal zurückgemeldete Erklärung an. Die Antwort, dass kein Organisationsprofil gefunden wurde, bedeutet, dass das Paar aus Merchant Key und Secret Key zu keiner Organisation in der gewählten Stage- oder Production-Umgebung gehört.

Zahlungsverhalten

Ist die aktive Zahlungsmethode Bar oder Karte, senden die Abrechnung einer PC-Sitzung, die Abrechnung einer Konsolensitzung und der Abschluss einer eigenständigen Bestellung einen idempotenten Warenkorb an Ödeal. Bar wird als die von Ödeal dokumentierte Zahlungsoption CASH übermittelt. Das Terminal erfasst die Barzahlung und druckt den Fiskalbeleg oder den e-Archiv-Beleg, ohne einen Bildschirm zur Kartenzahlung zu öffnen. Karte wird als CREDITCARD übermittelt; HandyCafe wartet auf das Callback-Ergebnis, während der Kunde die Zahlung am Terminal abschließt. Eine Abrechnung, die Bar und Karte enthält, sendet beide Zahlungsoptionen mit den jeweiligen Beträgen.

Der Kunde kann am Terminal eine Ratenzahlung wählen, sofern Karte und Händlervertrag dies unterstützen. HandyCafe speichert die gemeldete Anzahl der Raten zusammen mit dem lokalen Verkauf. Der lokale Verkauf wird erst gebucht, nachdem Ödeal die Transaktion bestätigt hat. Schlägt die lokale Buchung nach der Bestätigung fehl, fordert HandyCafe eine taggleiche Stornierung an. Eine fehlgeschlagene Stornierung erzeugt einen Fehler zur manuellen Abstimmung und muss im Ödeal-Transaktionsbericht geprüft werden. Andere Zahlungsarten als Bar und Karte laufen weiterhin über den bestehenden Abrechnungsablauf von HandyCafe.

Tests und Terminalvorgänge

Der Verbindungstest prüft ausschließlich die Händleranmeldedaten für Ödeal und den API-Zugriff. Er druckt keinen Beleg, belastet keine Karte und belegt nicht, dass externalDeviceKey mit dem Terminal gekoppelt ist.

Die gelieferte D2D-API-Dokumentation definiert keine eigenen Endpunkte für Testbeleg drucken oder Testbelastung. Die Abnahmeprüfung erfolgt mit normalen Warenkörben in der Stage-Umgebung: Senden Sie einen Warenkorb mit Barzahlung und prüfen Sie den gedruckten Beleg, senden Sie danach einen Warenkorb mit Kartenzahlung und schließen Sie am Terminal eine Einmalzahlung oder eine Ratenzahlung ab. Verwenden Sie ausschließlich die von Ödeal bereitgestellten Stage-Testkartendaten.

Zu den Abnahmefällen von Ödeal gehören der Tagesabschluss und der erneute Druck des letzten Belegs. Beides sind jedoch Terminalvorgänge. D2D dokumentiert dafür keine Fern-API-Aufrufe, deshalb bietet HandyCafe sie nicht als Schaltflächen für den Fernzugriff an.

Aus der Ferne aktivieren und deaktivieren

HandyCafe-Administratoren steuern Ödeal im Dashboard über Admin > Admin-Einstellungen > POS-Anbieter. Der globale Schalter ist die übergeordnete Steuerung. Länderstandards verwenden zweistellige ISO-Codes wie TR. Über die Café-Steuerung lässt sich Ödeal für eine einzelne Lizenz ausdrücklich öffnen oder schließen. Eine café-spezifische Entscheidung hat Vorrang vor dem Länderstandard. Wird die Café-Entscheidung zurückgesetzt, folgt dieses Café wieder seinem Land.

Die Entscheidungsreihenfolge lautet: globaler Schalter, café-spezifische Entscheidung, dann Länderstandard. Ein deaktivierter globaler Schalter schließt Ödeal für jedes Café. Eine ausdrückliche Schließung für ein Café blendet die Seite auch dann aus, wenn dessen Land geöffnet ist. Eine ausdrückliche Öffnung für ein Café erlaubt die Seite auch dann, wenn dessen Land nicht in der Standardliste steht. Wird der Zugang abgeschaltet, ist das Anlegen neuer Warenkörbe sofort gesperrt. Bereits offene Transaktionen lassen sich weiterhin prüfen oder stornieren, damit eine laufende Zahlung nicht hängen bleibt.

Der Server prüft die Verfügbarkeit über HandyCafe Cloud und speichert die zuletzt erfolgreich bestätigte Entscheidung für Land und Café zwischen. Der Anbieterkatalog antwortet mit HTTP 200 und einem strukturierten error.code, wenn seine Anmeldedaten ungültig sind. Die Desktop-Anwendung behandelt diese Antwort, indem sie die Anmeldedaten erneuert und den Aufruf wiederholt. Ein vorübergehender Authentifizierungs- oder Netzwerkfehler deutet eine aktivierte Admin-Entscheidung nicht als deaktiviert um, sodass das Menü Integrationen stabil bleibt. Eine spätere erfolgreiche Antwort aktualisiert den Zwischenspeicher sofort, auch wenn der Administrator die Deaktivierung entschieden hat. Liegt keine zuvor bestätigte Entscheidung vor, bleibt die Seite bei unbekanntem Café-Land, inaktivem Abonnement oder deaktiviertem Anbieter ausgeblendet. Neue Ödeal-Vorgänge werden immer erneut von der Cloud autorisiert, selbst wenn die zwischengespeicherte Sichtbarkeit genutzt wird. Hat das synchronisierte Café-Profil kein Land, wird das auf der Lizenz hinterlegte Land verwendet.

Sicherheit und Wiederherstellung

Ödeal-Anmeldedaten werden in HandyCafe Cloud mit dem Vault-Schlüssel der Installation verschlüsselt. Callback-Anfragen werden über den konfigurierten Anfrageschlüssel oder über die Ödeal-Header für Merchant Key und Secret Key authentifiziert. Warenkorb-Referenzcodes bleiben je Bestellung oder Sitzung stabil. Eine wiederholte Abrechnung desselben Vorgangs erzeugt keine zweite Belastung.

Eine Stornierung bei Ödeal ist nur nach den taggleichen Regeln von Ödeal möglich, solange der Terminal-Batch noch nicht geschlossen ist. Ein offener Warenkorb kann vor Abschluss der Zahlung separat entfernt werden. Ödeal D2D bietet keine allgemeine Rückerstattungsfunktion. Ist das Stornofenster verstrichen, nutzen Sie das Ödeal-Backoffice und den Transaktionsbericht.

Ödeal D2D bietet keinen dokumentierten Z-Bericht und keinen Tagesabschluss aus der Ferne. Führen Sie den Tagesabschluss am Terminal durch. HandyCafe kann Transaktionsberichte zur Abstimmung auslesen und erfasst Payback-Callbacks von Ödeal.