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; Pflicht für Plattform-Feedback)
• 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

Bei Plattformen ohne Artikelsynchronisation (z. B. Lieferando) muss das Kassensystem mit unbekannten Artikel-IDs umgehen können. Folgende Strategien werden empfohlen:

• Automatische Zuordnung anhand des Namens oder Buchung auf einen generischen Ausweichartikel mit Standardsteuersatz.
• Manuelle Nachpflege im Kassensystem direkt bei Bestelleingang.
• Automatische Anlage des unbekannten Artikels mit dem übertragenen Namen und Preis, wobei aus Sicherheitsgründen der höchste lokale Steuersatz anzuwenden ist.

Artikelsynchronisation (sofern unterstützt)

Für Plattformen, die eine Artikelsynchronisation erlauben, stellt das Kassensystem die „Source of Truth“ dar.

• 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 Optionen über das Feld 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.