Statusverarbeitung & Lieferzeit-Anpassungen

Wie Bestellstatus und Lieferzeiten plattformübergreifend verarbeitet werden

MERGEPORT normalisiert Bestellungen verschiedener Plattformen und stellt sie POS-Systemen über eine einheitliche API bereit. Statusänderungen und Lieferzeit-Anpassungen werden über denselben Order-Endpunkt gesendet:

PATCH /orders/{orderId}

Beispiel:

{
  "state": "acceptedByPOS",
  "timeChange": "2026-07-06T18:45:00.000Z"
}

Bestellstatus aktualisieren

Der neue Status wird im Feld state gesetzt.

{
  "state": "pickedUp"
}

Wichtige Regeln:

• Es dürfen nur Status verwendet werden, die in possibleStateChanges der Bestellung enthalten sind.
• possibleStateChanges wird bei jeder Bestellung mitgeliefert.
• Der wichtigste Status ist acceptedByPOS: Er bestätigt die Annahme durch das POS. Ob zusätzlich eine Rückmeldung an die Plattform gesendet wird, hängt von der Integration und ihrem Annahmemodus ab.
• Plattformen können intern andere Statusnamen und Statuslogiken verwenden.
• Statusänderungen können Auswirkungen auf Kundenanzeige, Kurierlogik und Plattform-Workflows haben.

possibleStateChanges verstehen

Jede Bestellung enthält mögliche nächste Statusänderungen, zum Beispiel:

"possibleStateChanges": [
  { "state": "acceptedByPOS", "timeChange": true },
  { "state": "ready", "timeChange": false }
]

Das bedeutet:

• state: Dieser Status darf als nächste Änderung gesendet werden.
• timeChange: Gibt an, ob bei dieser Statusänderung zusätzlich eine Zeitänderung erlaubt ist.

Wenn timeChange auf false steht, sollte keine Zeitänderung mitgesendet werden.

Lieferzeit-Anpassungen

Lieferzeit-Anpassungen werden über das Feld timeChange gesendet.

Wichtige Regeln:

• timeChange muss zusammen mit state gesendet werden.
• timeChange muss ein absoluter ISO-8601-Zeitstempel sein.
• timeChange ist keine reine Minuten-Differenz.
• Die Zeit sollte in UTC gesendet werden.

Beispiel:

{
  "state": "acceptedByPOS",
  "timeChange": "2026-07-06T18:45:00.000Z"
}

Empfohlen wird, Zeitänderungen hauptsächlich bei folgenden Statusänderungen zu senden:

• acceptedByPOS
• preparing

Häufige oder wiederholte Zeitänderungen sollten vermieden werden.

Einheitliche Logik über drivingTime

Um das Verhalten für Lieferbestellungen zu vereinheitlichen, kann im Integrations-Setup eine defaultPreparationTime.drivingTime gesetzt werden:

SetSiteSpecs in der MERGEPORT API-Dokumentation

Dann kann das POS bei Lieferbestellungen grundsätzlich die finale Kunden-Lieferzeit als timeChange senden.

MERGEPORT verwendet diese Zeit je nach Plattform unterschiedlich:

• Bei Wolt- und Uber-Eats-Kurierlieferungen kann MERGEPORT daraus die benötigte Pickup- bzw. Ready-Zeit berechnen.
• Bei Wolt selfDelivery wird die finale Kunden-Lieferzeit direkt an Wolt gesendet.
• Bei der bisherigen Lieferando-Anbindung bezieht sich eine erlaubte Zeitänderung bei Lieferbestellungen auf die finale Lieferzeit für den Kunden. JET Connect unterstützt aktuell keine Zeitänderung über MERGEPORT.

Wichtig:

• Bei Pickup/Takeaway ist die relevante Zeit die Abholzeit des Kunden, nicht eine Lieferzeit.
• timeChange darf nur bei Statusänderungen gesendet werden, bei denen possibleStateChanges[].timeChange auf true steht.

Plattform-spezifisches Verhalten

Wolt

Bei Wolt muss zwischen Wolt-Kurierlieferung und selfDelivery unterschieden werden.

Wolt-Kurierlieferung

Bei Wolt-Kurierlieferungen erwartet Wolt grundsätzlich eine Abholzeit für den Kurier.

Wenn das POS eine finale Kunden-Lieferzeit sendet und defaultPreparationTime.drivingTime konfiguriert ist, zieht MERGEPORT die Fahrzeit ab und sendet an Wolt die berechnete Pickup-/Ready-Zeit.

Beispiel:

• POS sendet finale Lieferzeit: 19:00
• drivingTime: 20 Minuten
• MERGEPORT sendet an Wolt: 18:40 als Pickup-/Ready-Zeit

Hinweis: Wolt begrenzt die Anpassung der Pickup-Zeit. Die berechnete bzw. gesendete Pickup-Zeit darf nicht beliebig weit von der ursprünglichen Wolt-Zeit abweichen.

Wolt selfDelivery

Bei Wolt selfDelivery liefert der Händler bzw. dessen eigener Fahrer.

In diesem Fall erwartet Wolt die finale Lieferzeit an den Kunden. MERGEPORT zieht hier keine drivingTime ab.

Das bedeutet:

• POS sendet finale Kunden-Lieferzeit.
• MERGEPORT sendet diese Zeit direkt an Wolt.

Uber Eats

MERGEPORT sendet an Uber Eats grundsätzlich eine Ready-/Pickup-Zeit.

Wenn das POS eine finale Kunden-Lieferzeit senden möchte, sollte defaultPreparationTime.drivingTime gesetzt sein. MERGEPORT zieht dann die Fahrzeit ab und sendet an Uber Eats die entsprechende Ready-/Pickup-Zeit.

Beispiel:

• POS sendet finale Lieferzeit: 19:00
• drivingTime: 20 Minuten
• MERGEPORT sendet an Uber Eats: 18:40 als Ready-/Pickup-Zeit

Lieferando / Just Eat Takeaway

Orientieren Sie neue Anbindungen an JET Connect, das als Standard die bisherige Schnittstelle ablösen soll. Bestehende Restaurants werden nach Abstimmung umgestellt.

JET Connect

JET Connect unterstützt aktuell keine Liefer- oder Abholzeitänderung über die MERGEPORT API. Die angebotenen Statuswechsel haben timeChange: false. Senden Sie daher keine Zeitänderung und keinen preparing-Status, wenn diese nicht in possibleStateChanges angeboten werden.

fetchedByPOS bestätigt nur den Empfang durch das POS. Anschließend muss acceptedByPOS folgen; der Empfang verlängert die Annahmefrist nicht. Im Modus posAccept meldet MERGEPORT die erfolgreiche POS-Annahme an JET zurück. Im Modus autoAccept erfolgt diese technische Bestätigung bereits beim Bestelleingang, ohne die POS-Annahme abzuwarten. Diese Modi bestimmen nicht die kundenseitige Bestellannahme am Orderpad.

Nur für bestehende ältere Verbindungen bis zur Umstellung

Die folgenden Zeitregeln gelten nur, solange Ihr Restaurant noch die bisherige Lieferando-Schnittstelle verwendet. Übernehmen Sie diese Regeln bei einer Umstellung nicht in die JET-Connect-Anbindung.

Bei Lieferando bezieht sich die Zeit bei Lieferbestellungen in der Regel auf die finale Lieferzeit für den Kunden.

Bei Pickup-Bestellungen bezieht sich die Zeit entsprechend auf die Abholzeit des Kunden.

Für Lieferando ist keine Umrechnung über drivingTime erforderlich.

Hinweise:

• Lieferzeit-Anpassungen werden grundsätzlich unterstützt, können aber je nach Lieferando-Setup eingeschränkt sein.
• Bei bestimmten Lieferando-/Scoober-Setups können Einschränkungen gelten.
• Zeitänderungen sollten möglichst früh gesendet werden, idealerweise bei acceptedByPOS oder preparing.

Nicht angenommene Bestellungen und Timeout

Nicht angenommene Bestellungen laufen nach einer gewissen Zeit in einen Timeout.

Plattformen haben eigene Annahmefenster. Wenn eine Bestellung nicht rechtzeitig bestätigt wird, kann sie aus Kundensicht automatisch abgelehnt oder storniert werden.

Deshalb sollte acceptedByPOS immer möglichst zeitnah gesendet werden.

Empfehlung für POS-Integrationen

Für eine möglichst einheitliche Implementierung:

1. Bestellung abrufen oder per Webhook empfangen.
2. possibleStateChanges prüfen.
3. Bestellung zeitnah mit acceptedByPOS bestätigen.
4. Wenn eine Lieferzeit angepasst werden soll:
   • timeChange nur senden, wenn für den Status erlaubt.
   • Einen absoluten ISO-8601-Zeitstempel senden.
   • Bei Lieferbestellungen idealerweise die finale Kunden-Lieferzeit senden.
   • Für Wolt/Uber-Kurierlieferungen defaultPreparationTime.drivingTime konfigurieren, damit MERGEPORT die Pickup-/Ready-Zeit berechnen kann.

Beispiel

POS bestätigt eine Lieferbestellung und setzt die finale Kunden-Lieferzeit:

{
  "state": "acceptedByPOS",
  "timeChange": "2026-07-06T18:45:00.000Z"
}

MERGEPORT verarbeitet diese Zeit je nach Plattform:

• Wolt Kurier: Umrechnung auf Pickup-Zeit, falls drivingTime gesetzt ist.
• Wolt selfDelivery: direkte Weitergabe als Kunden-Lieferzeit.
• Uber Eats: Umrechnung auf Ready-/Pickup-Zeit, falls drivingTime gesetzt ist.
• Bisherige Lieferando-Anbindung: direkte Verwendung als Kunden-Lieferzeit, sofern für den Status erlaubt.
• JET Connect: keine Zeitänderung; timeChange weglassen.