🇩🇪 Technischer Leitfaden für die Integration

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.

📘 Einstieg: Dokumentation & Überblick

• 👉 API-Dokumentation
• Diese Anleitung fasst alle relevanten API-Endpunkte, technischen Anforderungen und zentrale Hinweise zur erfolgreichen Integration zusammen.

🔌 Wichtige API-Endpunkte

Endpunkt	Beschreibung
GetOrders	Holt alle aktiven Bestellungen für das Restaurant
SetOrderState	Aktualisiert den Bestellstatus (z. B. “acceptedByPos”)
SetPosItems	Überträgt Artikeldaten vom POS an MERGEPORT (Pflicht bei Artikelsync)
DeletePosItem	Entfernt veraltete Artikel (optional)

✅ Technische Anforderungen & Checkliste

Unterstützte Bestellarten (Pflicht)

• Lieferung
• Abholung
• Tischbestellung

Statusverarbeitung & mögliche Statusänderungen (Pflicht)

• acceptedByPos ist verpflichtend (z. B. SMS „Die Zubereitung beginnt“ bei Lieferando). Kann automatisch (Auto-Accept) oder manuell gesetzt werden
• Weitere mögliche Stati: rejectedByPos, canceledByProvider, readyForPickup
• order.possibleStateChanges zeigt erlaubte Stati pro Bestellung
• timeChange: true/false erlaubt Lieferzeitänderung

Umgang mit unbekannten Artikeln (Pflicht bei Plattformen ohne Artikelsync)

Einige Plattformen (z. B. Lieferando) unterstützen keinen Artikelsync. Das Mapping muss dort manuell erfolgen.

Empfohlene Strategien:

• Buchung auf generischen Ersatzartikel
• Manuelle Zuordnung im POS
• Automatisches Matching anhand des Namens
• Erstellung des Artikels mit Name/Preis, höchstem Steuersatz + Benachrichtigung zur Korrektur

Lieferzeit-Anpassung (empfohlen)

Verschiedene Optionen für die Lieferzeitanpassung:

• Einmalig hinterlegte Standardlieferzeit aus POS-Konfiguration
• Dynamisch pro Bestellung via timeChange

Zusatzpositionen (Pflicht)

• Rabatte
• Liefergebühren
• Trinkgeld

Artikeldaten & Synchronisation (Pflicht bei Plattformen mit Artikelsync)

Mögliche Übertragungsmethoden:

• Automatisch bei Änderungen
• Periodisch (z. B. täglich)
• Manuell durch Nutzer:innen

Struktur & Felder:

• parentIds: verbindet Varianten/Toppings mit dem Hauptartikel
• options: enthält Konfigurationsmöglichkeiten (z. B. Auswahlgruppen)
• categoryIds: Zuordnung zu Kategorien
• Menüs: technisch möglich, Integration derzeit nicht empfohlen (weil nicht in Verwendung)

🧠 Artikelsynchronisation

• einige Plattformen (v.a. Self Ordering Lösungen) unterstützen die Artikelsynchronisation. Das bedeutet, sie laden die Artikel von MERGEPORT (die von dem Kassensystem importiert wurden) und bauen darauf basierend ihre Speisekarte auf. Andere (z.B. Lieferando) unterstützt das nicht. In solchen Fällen müssen die Artikel direkt bei der Plattform gepflegt werden und die posItemId dort hinterlegt. Alternativ kann auch eine Strategie implmentiert werden, um unbekannte eingehende Artikel zu verarbeiten (empfohlen)
• Aus Erfahrung eignen sich Artikelstammdaten aus dem POS System nicht für die Darstellung in einer Speisekarte bei den Lieferservices. Meist fehlen wichtige Informationen wie Bilder, deskriptive Texte, Allergene. Deshalb empfehlen wir, weiterhin die Speisekarte bei den Plattformen zu pflegen.
• MERGEPORT versteht das POS-System als „source of truth“

Artikelstruktur in Bestellungen

• internalId: ID bei MERGEPORT
• orderItemId: ID innerhalb der Bestellung
• posItemId: ID aus dem POS / von der Plattform

🔗 Nach erfolgreicher Integration

• Automatisch verbunden mit allen Plattformen: mergeport.com/integrate
• Testshops auf Anfrage verfügbar (z. B. Lieferando, Wolt)

📬 Kontakt

• Kontakt für die technische Integration: support@mergeport.com
• MERGEPORT Controller: https://controller.mergeport.com