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, da damit die Bestellung gegenüber der Plattform bestätigt wird.
• 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 Lieferando bezieht sich die Zeit bei Lieferbestellungen auf die finale Lieferzeit für den Kunden.

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

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.
• Lieferando: direkte Verwendung als Kunden-Lieferzeit.