Technische POS-Anbindung: Leitfaden für Entwickler

Dieser Leitfaden richtet sich an Entwickler von Kassensystemen (POS), die eine Integration mit MERGEPORT implementieren. MERGEPORT fungiert als standardisierte Schnittstellenschicht, die Bestellungen von angebundenen Liefer- und Bestellplattformen vereinheitlicht und an Ihr Kassensystem weitergibt.

API-Dokumentation & Endpunkte

Die MERGEPORT API-Dokumentation enthält die vollständige OpenAPI-Spezifikation sowie die Verträge für Webhooks, WebSocket und Bestellereignisse. Die folgenden Empfehlungen helfen bei der Auswahl und Umsetzung.

Empfohlener Einstieg: Standard Webhooks

Für neue Cloud-POS-Anbindungen empfehlen wir Webhooks mit Standard Webhooks. MERGEPORT sendet vollständige, vereinheitlichte Bestellungen an Ihren öffentlichen HTTPS-Endpunkt. WebSocket eignet sich für dauerhaft verbundene lokale Systeme ohne öffentlichen Webhook-Endpunkt; Polling bleibt eine Alternative für einfache Anbindungen oder den Abgleich nach Verbindungsproblemen.

Stimmen Sie die Einrichtung der aktiven POS-Verbindung mit MERGEPORT ab und konfigurieren Sie in deren accessDetails:

• webhookUrl: Ihr Endpunkt für vollständige Bestellungen.
• webhookSecret: das gemeinsam hinterlegte Signatur-Secret.
• webhookSigningMode: "standard-webhooks": aktiviert die Signierung ausdrücklich. Ohne diese Einstellung bleibt das bisherige Legacy-Verhalten bestehen.

Prüfen Sie die Header webhook-id, webhook-timestamp und webhook-signature gegen die unveränderten Request-Bytes. MERGEPORT verwendet HMAC-SHA256 mit dem wörtlichen Secret über {webhook-id}.{webhook-timestamp}.{raw-request-body}. Das Secret wird in diesem Modus nicht im Authorization-Header mitgesendet. Prüfen Sie auch den Zeitstempel und verarbeiten Sie Wiederholungen ohne doppelte Buchung. Eine erneute Zustellung derselben Nachricht behält ID und Zeitstempel; berücksichtigen Sie das vereinbarte Wiederholungsfenster bei der Zeitprüfung.

Speichern Sie die Bestellung vor der HTTP-Empfangsbestätigung und behandeln Sie spätere Aktualisierungen bereits bekannter Bestellungen. Eine erfolgreiche HTTP-Antwort bestätigt nur den technischen Empfang. Die Annahme durch die Kasse erfolgt separat über acceptedByPOS.

Einrichtung, Payloads und Signaturprüfung finden Sie unter POS webhook integration. Der verwandte Artikel „Webhook-Benachrichtigung hinzufügen“ beschreibt dagegen den separaten Zusatzservice für Benachrichtigungen und dessen Signierung; er ersetzt nicht die Einrichtung einer aktiven POS-Anbindung.

Bestellereignisse für eine aktuelle POS-Anzeige abonnieren

Ergänzen Sie die Zustellung neuer Bestellungen um eine Order-Event-Subscription, damit Ihre Kasse auch spätere Änderungen an Status, Fahrerinformationen und Lieferaufträgen anzeigen kann.

Ereignis	Bedeutung für die POS-Anzeige
order.statusChanged	Der gespeicherte Bestellstatus hat sich geändert.
order.deliveryUpdated	Fahrerinformationen der Bestellplattform wurden aktualisiert.
order.deliveryFleetUpdated	Ein gebuchter Lieferauftrag wurde geändert, etwa Status, Tracking oder Zeitangaben.
order.posDeliveryFailed	Die letzte technische Zustellung der Bestellung an diese POS-Verbindung ist fehlgeschlagen; dies ist keine Ablehnung durch das Restaurant.

Öffnen Sie im MERGEPORT Controller den Standort und unter Konfiguration die aktive POS-Verbindung. Hinterlegen Sie orderEventsUrl als öffentlichen HTTPS-Endpunkt auf Port 443 ohne Weiterleitungen, ein eigenes orderEventsSecret und die gewünschten orderEventTypes als JSON-Array. Die verfügbaren Felder hängen von der POS-Definition ab; fehlen sie, wenden Sie sich an den Support. Eine leere Liste oder das Entfernen der Event-URL beendet das Abonnement.

HTTP-Order-Events werden immer mit Standard Webhooks und dem separaten orderEventsSecret signiert. Sie enthalten Kennungen und Ereignistyp, aber keine vollständige Bestellung. Prüfen Sie die Signatur, bestätigen Sie den Empfang zügig mit HTTP 2xx und laden Sie bei Bedarf den aktuellen Datensatz über GET /pos/orders/{id} nach. Bei Flottenereignissen ist der Lieferauftrag über GET /pos/deliveries/{deliveryId} abrufbar.

Auch WebSocket-Verbindungen können sich nach dem Login mit subscribeOrderEvents anmelden; nach einem Reconnect ist eine erneute Anmeldung erforderlich. Details und Beispiele stehen in der Order-Events-Dokumentation.

Wichtige API-Endpunkte

Die folgenden Pfade sind relativ zur V4-API-Basis-URL. Für den Abruf aktiver Bestellungen wird der Filter active angegeben.

Methode / Pfad	REST / WebSocket-Aktion	Beschreibung
GET /pos/orders?filter=active	GetOrders	Abrufen aktiver Bestellungen (Status receivedByProvider oder canceledByProvider).
GET /pos/orders/{id}	GetOrder	Abrufen einer einzelnen Bestellung anhand der ID.
PATCH /pos/orders/{id}	SetOrderState	Aktualisieren des Bestellstatus (z. B. auf acceptedByPOS).
POST /pos/items	SetPosItems	Übertragen von Kassenartikeln für Menü-Synchronisierung oder Artikelzuordnung.
DELETE /pos/items/{id}	DeletePosItem	Löschen eines Artikels im MERGEPORT-System.

Technische Anforderungen

1. Bestellarten

Das Kassensystem muss in der Lage sein, die von den Plattformen unterstützten Bestelltypen (z. B. Lieferung, Abholung oder Tischbestellungen) zu verarbeiten. Da die Fähigkeiten der Plattformen variieren, werden Datenfelder optional übertragen.

2. Bestellstatus & Statusübergänge

Das Kassensystem muss den Lebenszyklus einer Bestellung steuern. Gültige Statuswerte in MERGEPORT sind:

• receivedByProvider (Plattform-Bestellannahme)
• fetchedByPOS (von der Kasse als abgeholt bestätigt; erscheint danach nicht mehr in Abfragen mit filter=active)
• acceptedByPOS (Bestätigung der Bearbeitung durch die Kasse; Plattform-Feedback abhängig von Anbindung und Annahmemodus)
• preparing (Zubereitung gestartet)
• ready (Bereit zur Abholung)
• pickedUp (Bestellung abgeholt)
• inDelivery (In Auslieferung durch eigenen Fahrer)
• delivered (Erfolgreich zugestellt)
• canceledByProvider (Stornierung durch Plattform)
• canceledByPOS / rejectedByPOS (Stornierung/Ablehnung durch Kasse)

In der API-Antwort einer Bestellung definiert das Array possibleStateChanges die jeweils erlaubten nächsten Statusübergänge für das Kassensystem. Senden Sie nur angebotene Übergänge. fetchedByPOS ersetzt die anschließende Annahme mit acceptedByPOS nicht. Der verwandte Artikel „Statusverarbeitung & Lieferzeit-Anpassungen“ erläutert die Plattformunterschiede.

3. Lieferzeit-Anpassung

Wenn das Feld possibleStateChanges[].timeChange für einen Status als true definiert ist, kann das Kassensystem im SetOrderState-Request eine neue Liefer- oder Abholzeit mitsenden.

• Wichtig: Der Parameter timeChange im PATCH-Request darf nicht als Boolean übertragen werden. Die API erwartet einen absoluten UTC-Zeitstempel im ISO 8601-Format (z. B. '2000-01-01T10:10:10.123Z').

4. Umgang mit unbekannten Artikeln

Das Kassensystem muss auch bei aktivierter Menü-Synchronisierung mit fehlenden oder unbekannten Artikel-IDs umgehen können. Stimmen Sie die Behandlung mit dem Betreiber ab:

• Stabile IDs zur Zuordnung verwenden und unklare Treffer manuell prüfen.
• Unbekannte Artikel nach einem vereinbarten Verfahren zuordnen oder anlegen.
• Ersatzartikel und Steuereinstellungen prüfen; ein pauschaler Höchststeuersatz ist keine durch MERGEPORT geprüfte Lösung.

Optionale taxRate-Werte ersetzen die Steuerlogik der Kasse nicht. Ein fehlendes Feld bedeutet nicht 0 %.

Menüverwaltung passend zum Betrieb wählen

Für Lieferando über JET Connect, Wolt, Uber Eats und foodora ist Menü-Synchronisierung möglich. Wir empfehlen diesen Weg, wenn die Artikelstammdaten der Kasse für eine hochwertige Online-Speisekarte geeignet sind: verständliche Namen, vollständige Beschreibungstexte, passende Bilder, gepflegte Allergene sowie Auswahlmöglichkeiten und Varianten. Entscheidend ist die Qualität der Inhalte, nicht allein die technische Upload-Möglichkeit. Freischaltung und Feldumfang hängen von der Anbindung ab; ältere Lieferando-Verbindungen haben einen anderen Funktionsumfang.

Stimmen Sie mit dem Betreiber und der Plattform den passenden Weg ab:

• Speisekarte aus der Kasse synchronisieren: Die Kasse liefert Artikel und Menüs über MERGEPORT. Pflegen Sie kundenverständliche Namen, Beschreibungen, Preise, Bilder, Allergene und Optionen vollständig. Welche Felder übertragen werden, hängt vom Menükanal und seinen Feldzuordnungen ab; die aktuelle foodora-Menüübertragung enthält beispielsweise keine Allergenfelder. Ein vollständiger Upload kann die bestehende Plattform-Speisekarte überschreiben.
• Speisekarten auf den Plattformen pflegen: Hinterlegen Sie passende Kassenartikelnummern/PLUs auf der Plattform, soweit verfügbar, oder bieten Sie eine Artikelzuordnung in der Kasse an, etwa für unbekannte Artikel. Stimmen Sie den Betrieb ohne Menü-Synchronisierung mit der Plattform ab; bei JET Connect ist dafür eine Freischaltung erforderlich, bei Uber Eats kann die aktive Menü-Synchronisierung den Menu Maker deaktivieren.
• Artikel im MERGEPORT Controller zuordnen: Verknüpfen Sie importierte Plattformartikel mit Kassenartikeln. Der experimentelle Auto-Mapper unterstützt die Zuordnung; prüfen Sie seine Ergebnisse. Zusätzlich befindet sich KI-gestütztes Item-Mapping in der Testphase. Für einen Testeinsatz wenden Sie sich an den Support; prüfen Sie auch KI-Vorschläge vor der Übernahme. Artikelzuordnung verändert keine kundensichtbare Speisekarte.

Der verwandte Artikel „Menüverwaltung: synchronisieren oder getrennt pflegen“ unterstützt die Entscheidung. „Artikelzuordnung für Online-Bestellungen“ beschreibt die manuelle Zuordnung und den Auto-Mapper; „Menüanforderungen für Wolt, Uber Eats, foodora und JET Connect“ erklärt die Vorbereitung der Menüdaten.

Menüdaten aus der Kasse synchronisieren

Wenn die Synchronisierung aktiviert und auf Plattformseite eingerichtet ist, liefert die Kasse die Menüdaten. Bestelleingang ohne Menü-Synchronisierung bleibt je nach Anbindung möglich.

• Senden Sie Artikeländerungen über den Endpunkt /pos/items an MERGEPORT.
• Verwenden Sie das Feld parentIds, um Varianten oder Toppings hierarchisch mit dem Hauptartikel zu verknüpfen.
• Strukturieren Sie Optionsgruppen über optionsList und deren availableChoices im Artikel-Upload.

Optional: Lieferflotten anbinden

Für Bestellungen, deren Zustellung das Restaurant übernimmt, können Sie zusätzlich eine unterstützte Lieferflotte anbinden. Je nach Einrichtung sind manuelle Buchungen oder gesondert aktivierte automatische Buchungen möglich. Standort, Lieferpartner und Buchungsregeln müssen dafür eingerichtet sein.

Bestellstatus und Lieferstatus bleiben getrennt. Über order.deliveryFleetUpdated und die Delivery-API kann das POS den Lieferauftrag verfolgen. Für Einrichtung, Buchung und Stornierung verwenden Sie den verwandten Artikel „Lieferflotten mit MERGEPORT verbinden“.

Onboarding und Headless-Verwaltung

Neben Bestellereignissen gibt es eine separate Rückmeldung für eine erfolgreich verifizierte Plattformverbindung. Konfigurieren Sie dafür providerLoginSuccessUrl in den POS-accessDetails. Das Payload-Feld lautet exakt event: "providerloginsuccess"; es ist kein Eintrag für orderEventTypes. Unterstützt werden Wolt, Uber Eats, foodora sowie Lieferando einschließlich JET Connect.

Nutzen Sie diese Rückmeldung, um den Verbindungsfortschritt im eigenen Onboarding anzuzeigen. Sie bestätigt die verifizierte Verbindung, aber weder eine fertige Speisekarte noch ein geöffnetes Restaurant oder einen erfolgreichen Bestelltest. Prüfen Sie den aktuellen Verbindungsstatus nach. Der Callback hat einen eigenen Zustellvertrag; die oben beschriebene Standard-Webhooks-Signierung der Bestell- und Order-Event-Webhooks gilt dafür nicht automatisch.

Zugang zur Admin API erhalten Sie auf Anfrage über support@mergeport.com. Damit können berechtigte Partner Standorte und Plattformverbindungen aus ihrer eigenen Anwendung verwalten, etwa anlegen, ändern oder entfernen. So lässt sich ein Headless-Onboarding umsetzen. MERGEPORT stellt die erforderlichen Berechtigungen und die Admin-API-Dokumentation bereit. Bei OAuth-Anbindungen bleibt die Autorisierung durch den Betreiber erforderlich.

Der verwandte Artikel „MERGEPORT-Integration aktivieren – so funktioniert’s“ beschreibt den Einrichtungsablauf im Controller.

Support / Entwickler-Hilfe

Für Entwicklungszugang, Testshops, KI-Mapping-Tests oder Fragen zu Webhooks, Bestellereignissen und der Admin API wenden Sie sich an support@mergeport.com.