Technischer Leitfaden
Diese Anleitung richtet sich an Entwickler:innen von Kassensystemen, die ihr POS-System an MERGEPORT anbinden und so eine standardisierte Schnittstelle zu über 30 Bestellplattformen aufbauen möchten.
MERGEPORT
Letztes Update: vor 6 Monaten
Dieser Artikel bietet eine vollständige technische Übersicht zur Integration eines Kassensystems mit MERGEPORT.
Er erklärt die wichtigsten API-Endpunkte, alle verpflichtenden und empfohlenen Anforderungen sowie Best Practices für den Umgang mit Bestellungen, Artikeldaten und Synchronisation.
MERGEPORT fungiert als Integrationsschicht zwischen Ihrem Kassensystem und über 30 angebundenen Bestellplattformen (z. B. Lieferando, Wolt, Uber Eats, Foodora).
Nach erfolgreicher Integration kommuniziert Ihr Kassensystem automatisch mit allen unterstützten Plattformen – Bestellungen werden empfangen, Status aktualisiert und Artikeldaten synchronisiert (sofern unterstützt).
Wenn Sie mit einer neuen Integration starten, hilft Ihnen dieser Leitfaden dabei zu verstehen:
welche API-Endpunkte benötigt werden,
wie Bestellungen und Artikelsynchronisation funktionieren,
wie unbekannte Artikel und Steuern korrekt gehandhabt werden,
und was vor dem Livegang getestet werden sollte.
Dokumentation & Überblick
Die vollständige Dokumentation aller Endpunkte finden Sie hier:
Wichtige API-Endpunkte
| Endpunkt | Beschreibung | URL |
| Holt alle aktiven Bestellungen für das Restaurant | https://ordering.mergeport.com/v4/documentation#operation/GetOrders | |
| SetOrderState | Aktualisiert den Bestellstatus (z. B. “acceptedByPos”) | https://ordering.mergeport.com/v4/documentation#operation/SetOrderState |
| SetPosItems | Überträgt Artikeldaten vom POS an MERGEPORT (Pflicht bei Artikelsync) | https://ordering.mergeport.com/v4/documentation#operation/SetPosItems |
| DeletePosItem | Entfernt veraltete Artikel (optional) | https://ordering.mergeport.com/v4/documentation#operation/DeletePosItem |
Technische Anforderungen & Checkliste
Unterstützte Bestellarten (Pflicht)
- Lieferung
- Abholung
- Tischbestellung
Statusverarbeitung & mögliche Statusänderungen (Pflicht)
Jedes Kassensystem muss Statusänderungen und deren Übergänge unterstützen.
acceptedByPos ist verpflichtend – dieser Status löst z. B. bei Lieferando die Nachricht „Zubereitung begonnen“ aus.
Er kann automatisch beim Eingang der Bestellung oder manuell durch den Benutzer gesetzt werden.
Weitere unterstützte Status: rejectedByPos, canceledByProvider, readyForPickup
Im Feld order.possibleStateChanges sind die erlaubten Statusübergänge definiert.
Das Feld timeChange: true/false zeigt an, ob eine Lieferzeitanpassung erlaubt ist.
Umgang mit unbekannten Artikeln (Pflicht bei Plattformen ohne Artikelsync)
Einige Plattformen (z. B. Lieferando) unterstützen keine Artikelsynchronisation. In diesen Fällen muss die Zuordnung im Kassensystem erfolgen.
Empfohlene Strategien:
A) Automatische Zuordnung nach Name oder Buchung auf einen generischen Ersatzartikel mit Standardsteuersatz.
B) Manuelle Zuordnung im Kassensystem, sobald ein unbekannter Artikel eingeht.
C) Automatische Erstellung unbekannter Artikel im Artikelstamm mit eingehendem Namen und Preis, wobei der höchstmögliche Steuersatz angewendet wird.
Am Ende des Tages sollte das Kassensystem eine Übersicht neu erstellter Artikel anzeigen, damit deren Steuersätze geprüft und ggf. angepasst werden können.
Weitere Informationen zum Thema Steuerlogik und Fiskalisierung finden Sie hier:
👉 Werden über MERGEPORT steuerliche Informationen übermittelt?
Lieferzeit-Anpassung (empfohlen)
Es gibt zwei Optionen:
Feste Lieferzeit über die POS-Konfiguration.
Dynamische Lieferzeit pro Bestellung (aktiviert über timeChange: true).
Zusatzpositionen (Pflicht)
- Rabatte
- Liefergebühren
- Trinkgeld
Artikeldaten & Synchronisation (Pflicht bei Plattformen mit Artikelsync)
Mögliche Synchronisationsmethoden:
Automatisch bei Änderungen (empfohlen)
Periodisch (z. B. täglich über Cronjob)
Manuell durch den Benutzer
Struktur & Felder:
parentIds: Verknüpft Varianten/Toppings mit dem Hauptartikel
options: Definiert Auswahlmöglichkeiten (z. B. Zusatzoptionen)
categoryIds: Ordnet Artikel den Kategorien zu
menus: Technisch unterstützt, aktuell aber nicht empfohlen
Artikelsynchronisation
Einige Plattformen (v. a. Self-Ordering-Lösungen) unterstützen Artikelsynchronisation und laden die Artikeldaten direkt von MERGEPORT (die vom POS bereitgestellt werden).
⚠️ Wichtig:
Plattformen wie Lieferando unterstützen keine Artikelsynchronisation.
In diesem Fall gilt:
Die Speisekarte muss direkt auf der Plattform gepflegt werden.
Die posItemId muss auf Plattformseite manuell hinterlegt werden.
Unbekannte Artikel müssen gemäß den oben beschriebenen Strategien verarbeitet werden.
Hinweis:
Artikeldaten aus dem Kassensystem sind oft nicht optimal für die Kundendarstellung (fehlende Bilder, Beschreibungen, Allergene).
Für eine bestmögliche Nutzererfahrung empfehlen wir, die Speisekarten direkt auf den Bestellplattformen zu pflegen.
MERGEPORT betrachtet das Kassensystem stets als „Source of Truth“ für strukturierte Artikeldaten.
Jede Bestellung enthält folgende Identifikatoren:
internalId: von MERGEPORT verwendete ID
orderItemId: interne ID des Artikels innerhalb der Bestellung
posItemId: POS- oder plattformseitige Artikel-ID
Nach erfolgter Integration
Nach erfolgreicher Integration ist das Kassensystem automatisch mit allen wichtigen Bestell- und Lieferplattformen verbunden.
👉 Übersicht der unterstützten Plattformen
Testumgebung:
Testshops (z. B. Lieferando, Wolt, Uber Eats) stehen auf Anfrage für Entwicklungs- und Testzwecke zur Verfügung.
Technischer Support: support@mergeport.com
MERGEPORT Controller: https://controller.mergeport.com
API-Dokumentation: https://ordering.mergeport.com/v4/documentation