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 vollständige OpenAPI-Spezifikation aller Endpunkte sowie WebSocket-Details finden Sie in der Entwickler-Dokumentation:

👉 MERGEPORT API Documentation

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	Hochladen von Artikeldaten (Pflicht bei Plattformen mit Artikelsynchronisation).
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.

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

MERGEPORT unterstützt die Menü-Synchronisierung für Lieferando über JET Connect, Wolt, Uber Eats und foodora. Stimmen Sie mit dem Betreiber und der Plattform ab, welcher der folgenden Wege genutzt wird:

• 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. 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

MERGEPORT unterstützt Menü-Synchronisierung für Lieferando über JET Connect, Wolt, Uber Eats und Foodora. Wenn diese 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.

Support / Entwickler-Hilfe

Für Testshops (z. B. für Lieferando, Wolt oder Uber Eats) sowie bei Fragen zur WebSocket-Implementierung wenden Sie sich direkt an support@mergeport.com.