Dieser Artikel richtet sich an Entwickler, die Aufträge programmatisch an einen Anbieter senden möchten, der MotionTools verwendet.

Überblick

Um eine Bestellung an einen auf MotionTools laufenden Kurierdienst zu übergeben, nutzt du die MotionTools REST API. Weitere Ressourcen und Guides findest du in unserem Help Center.

MotionTools ist eine Multi-Tenant-Plattform, in der jeder Kurierdienst seinen eigenen Mandanten hat. Du übergibst Bestellungen an deinen Kurierdienst über ein Konto mit der Rolle customer.

Wenn du die URL des Customer Portals deines Lieferdienstes kennst, kannst du selbst ein Customer-Konto erstellen.
Alternativ kontaktiere bitte deinen Lieferdienst, um ein Customer-Konto zu erhalten.

Du kannst Bestellungen über die API entweder als Bookings oder als Packages anlegen. Wenn du eine Booking oder ein Package erstellst, erhältst du als Response ein Objekt, das deine Bestellung in MotionTools repräsentiert. Erfahre mehr in unseren ausführlichen Artikeln zu Bookings und Packages. Wenn du unsicher bist, welche Option besser passt, lies bitte diesen Artikel und besprich das zusätzlich mit deiner Kontaktperson bei deinem zuständigen Operator / 3PL. Dieses Dokument beschreibt die Integration über Bookings. Das ist der Standardfall, wenn du Lieferungen innerhalb von 60 Minuten oder weniger anfragst und der Transport direkt vom Pickup zum Drop-off erfolgt, ohne zwischendurch ein Hub oder Lager zu durchlaufen.

Du kannst den Fortschritt deiner Bestellung verfolgen, indem du relevante Webhooks für deinen Use Case abonnierst. Die vollständige Liste findest du Hier ↗️. Das Einrichten von Webhooks kann nicht direkt in deinem Customer-Konto erfolgen, sondern erfordert Unterstützung durch deine Kontaktperson bei deinem Provider.

Scheduling Mode: Instant vs Scheduled

Wenn du eine Booking erstellst, kannst du angeben, wann der Kurierdienst voraussichtlich am ersten Stop erscheinen soll – das ist in der Regel der Pickup-Stop.

Aktuell stehen zwei Optionen zur Verfügung: instant & scheduled Bookings:

Instant Bookings: bedeuten, dass der Fahrer am ersten Stop jetzt oder so schnell wie möglich eintreffen soll
Scheduled Bookings: bedeuten, dass die Ankunft am ersten Stop zu einem Zeitpunkt in der Zukunft erfolgen soll – das ist die scheduled_at Zeit.

Mehr Details hier.

Zeitfenster

MotionTools ermöglicht es dir, genau festzulegen, wann ein Fahrer an jedem einzelnen Stopp der Buchung ankommen soll (earliest_arrival_at, latest_arrival_at). Zusätzlich kannst du die erwartete Dauer eines Stopps angeben (custom_expected_duration_seconds). Details findest du in der Payload-Beschreibung des Create Booking Endpunkts im Modell booking.stops.

Booking-Lifecycle

Es ist wichtig, die zentralen Konzepte in MotionTools zu verstehen, die im Booking-Lifecycle eine Rolle spielen: Booking, Stop, Tour.

Gehen wir den Ablauf und die relevanten Webhook-Events durch, die du abonnieren solltest:

Erstelle eine Booking in der Rolle customer mit deinem bevorzugten Planungsmodus (booking.created)
Sobald eine Booking in eine Tour eingeplant (dispatched) wurde und ein Fahrer diese Tour startet, triggern wir das Event booking.in_progress
Sobald der Fahrer zu einem bestimmten Stop fährt (z. B. Pickup-Stop oder Drop-off-Stop), gibt es Events für das Ankommen (booking.stop_arrived) und das Abschließen (booking.stop_completed) dieser Stops
Sobald alle Stops einer Booking abgeschlossen sind, ist die Booking operational ebenfalls abgeschlossen (Teil von booking.transition)

Mehr zum Booking-Statusmodell findest du hier: Status model of Bookings

Die relevanten Webhooks und deren Payloads werden im Abschnitt Receiving updates via Webhooks ausführlicher beschrieben.

Füge deine Order-ID als External ID zur Booking hinzu

Um eine Verbindung zwischen Eigenschaften deines internen Order-Modells (z. B. Order id) und der daraus resultierenden Booking in MotionTools herzustellen, füge bitte deine eigene ID als external_id zur Booking hinzu. Dadurch kann deine Order-ID leicht verwendet werden, um die entsprechende Booking in MotionTools zu finden, und du erhältst diese ID außerdem als Teil der Updates, die wir senden, wenn du Webhooks abonniert hast. So kannst du Updates zu deiner Transaktion/Bestellung in deinem System einfach zurückverknüpfen.

Voraussetzungen für die Integration

Um dich mit deinem durch MotionTools gestützten Lieferpartner zu integrieren, benötigst du Folgendes:

Kundenkonto: im MotionTools Tenant deines Anbieters
Kunden-API-Token: Sobald du Zugang zu deinem Konto hast, musst du einen API-Token erstellen.
service_id: Diese wird dir vom Lieferpartner zur Verfügung gestellt und muss beim Erstellen einer Buchung angegeben werden. Wenn der Lieferpartner nur den "Standard-Service" nutzt, kann die service_id beim Erstellen der Buchung weggelassen werden. Mehr über Services findest du hier.

Eine Bestellung per API senden

Bitte lies dir Kunde: Eine Buchung über die API erstellen durch
API-Endpunkt Dokumentation: CreateHailingBooking

Beispiel-Payload für eine Abholung, angepasst für Essenslieferungen (zum Anzeigen ausklappen)

{ "booking": { "stops": [ { "type": "pickup", "earliest_arrival_at": null, "latest_arrival_at": null, "place_id": "7d6991cb-d669-40ae-acb7-6a2b964e212b", // add a valid place id for the pickup location "additional_information": "info for pickup, e.g. order id or name", "metadata": { "public_order_id": "value", "external_order_id": "value" }, }, { "type": "dropoff", "earliest_arrival_at": null, "latest_arrival_at": null, "lat": 53.54439, // optional, MotionTools will geocode if n/a "lng": 9.940334, "street": "Große Elbstraße", "number": "123", "zip_code": "20097", "city": "Hamburg", "country": "Deutschland", "location_name": "Große Elbstraße 123", "first_name": "Vorname", "last_name": "Nachname", "phone_number": "+491601234123", "additional_information": "Please don't ring the bell", "metadata": { "public_order_id": "value", "external_order_id": "value" }, } ], "scheduled_at": "now" // if you only push bookings for now, you can leave this out, otherwise you can add a timestamp, please note that only timestamps in the future are allowed and they have to be within the opening hours of the operator. Scheduled_at is typically the time when you want a driver to pickup the order from the restaurant. } }

Gib die Kontaktdaten des Endempfängers der Bestellung als Stopp-Kontaktdaten beim Auslieferungsstopp an, damit Fahrer/Kuriere deines Lieferpartners den Endempfänger kontaktieren können, wenn sie die Buchung bearbeiten.

Updates über Webhooks empfangen

Webhooks können nur von admin Usern eingerichtet werden.

Um einen Webhook zu erstellen, musst du die URL, an die Webhooks gesendet werden sollen, entweder mit einer Vertreterin/einem Vertreter deines Lieferpartners teilen (da diese admin Zugriff haben sollten) oder mit dem MotionTools Support. Außerdem musst du angeben, welche Events du empfangen möchtest und ggf. welche Filter angewendet werden sollen.

Allgemeine Informationen

MotionTools kann Status-Updates per Webhook für nahezu jedes Ereignis senden, das innerhalb von MotionTools passiert
Die Webhooks sind schlank und enthalten nur die wichtigsten Informationen, z. B. welches Event passiert ist und um welche Booking-ID es geht
Wenn du detailliertere Informationen brauchst, musst du nach Empfang eines Webhooks die relevanten Daten über den passenden Endpoint abrufen, z. B. den Endpoint „show booking“
Die API-Dokumentation für Webhooks findest du hier: https://docs.motiontools.io/#tag/Webhooks
Um sicherzustellen, dass dein Webhook-Consumer-Endpoint nur von authentischen Requests aus MotionTools aufgerufen wird, unterstützen wir Webhook Request Verification. Siehe: Webhook verification

Location Tracking & ETAs

Fahrer-Standort-Updates

Bitte nutze den Webhook booking.driver_location_updated
(API Docs)

Aktuelle Ankunftszeiten

Bitte nutze den Webhook booking.etas_recalculated
(API Docs)

Webhook-Verifizierung

Um zu überprüfen, ob ein eingehender Webhook-Request nicht böswillig gefälscht oder modifiziert wurde, fügen wir eine Signatur als Teil der Request-Header hinzu. Du musst die Signatur auf deiner Seite gegen den öffentlichen Schlüssel validieren, den du von deinem Lieferpartner erhalten hast, als dieser den Webhook konfiguriert hat.

Als Verschlüsselungsalgorithmus wird Ed25519 verwendet, und die Signatur wird Base64-kodiert im X-Mtools-Signature Request-Header übermittelt.

TypeScript-Beispiel eines Cloudflare Workers zur Überprüfung der Webhook-Authentizität

Das folgende Beispiel ist für die Cloudflare Workers/Deno-Laufzeitumgebung geeignet. Wenn du eine andere JavaScript-Laufzeitumgebung wie NodeJs oder Bun verwendest, wird das Beispiel nicht ohne Anpassungen funktionieren. In NodeJs verwendest du zum Beispiel Ed25519 statt NODE-ED25519 als Algorithmus-Bezeichner. Auch bei der Interaktion mit der crypto-Bibliothek kann es Unterschiede geben. Das folgende Beispiel dient nur zur Veranschaulichung. Bitte passe es entsprechend an die Anforderungen deiner Laufzeitumgebung an.

// Replace this with your actual public key (Base64-encoded)const PUBLIC_KEY_BASE64 = 'YOUR_PUBLIC_KEY_HERE';export default { async fetch(request: Request): Promise<Response> { // Read body as ArrayBuffer (Uint8Array required for crypto.subtle) const body = new Uint8Array(await request.arrayBuffer()); // Get signature from header (Base64-encoded) const signatureBase64 = request.headers.get('X-Mtools-Signature'); if (!signatureBase64) { return new Response('Missing signature header', { status: 400 }); } const signature = Uint8Array.from(atob(signatureBase64), c => c.charCodeAt(0)); // Decode public key const publicKey = Uint8Array.from(atob(PUBLIC_KEY_BASE64), c => c.charCodeAt(0)); // Import public key for Ed25519 verify const cryptoKey = await crypto.subtle.importKey( 'raw', publicKey, { name: 'NODE-ED25519', namedCurve: 'NODE-ED25519' }, // For Deno/Cloudflare false, ['verify'] ); // Verify signature const isValid = await crypto.subtle.verify( 'NODE-ED25519', cryptoKey, signature, body ); if (!isValid) { return new Response('Invalid signature', { status: 401 }); } // Signature valid, process webhook try { await procesWebhook(body) return new Response('Webhook verified!', { status: 200 }); } catch (e) { return new Response('Internal server error: error processing webhook.', { status: 500 }); } }};

Richtlinien zur Nutzung von Webhooks

Um die Leistungsstabilität unserer Plattform zu gewährleisten, gelten folgende Einschränkungen für Webhook-Empfänger:

Wir erwarten einen gültigen 2xx Antwort-Code, um die Zustellung eines Webhook-Events als erfolgreich zu betrachten.
15 Sekunden Timeout: Wenn keine 2xx Antwort innerhalb von 15 Sekunden erfolgt, betrachten wir die Zustellung als fehlgeschlagen.
3 Wiederholungsversuche: Jedes Webhook-Event wird 3 Mal wiederholt. Nach 3 Versuchen wird das Webhook-Event nicht mehr erneut gesendet und ist damit verloren.
250 aufeinanderfolgende fehlgeschlagene Zustellungen an dieselbe URL führen zur Blockierung/Deaktivierung des Webhooks und lösen eine E-Mail-Benachrichtigung an den Tenant-Besitzer aus (in diesem Fall dein Lieferpartner). Sollte dies passieren, wird entweder dein Lieferpartner oder der MotionTools-Support dich kontaktieren.

Webhook-Filterung

Wenn du Webhook-Events für Buchungen erhältst, die nicht zu dir gehören, hat dein Lieferpartner möglicherweise die Webhook-Filter nicht korrekt eingerichtet, als er den Webhook für dich konfiguriert hat.

Bitte kontaktiere deinen Lieferpartner, um dies anzupassen. Relevanter Artikel in unserem Help Center: Webhooks an deine Kunden für Buchungsstatus-Updates weiterleiten.

Technische Überlegungen & Empfehlungen

Datenvalidierung

Unsere API & Payload-Strukturen & Status-Modelle entwickeln sich ständig weiter.

Daher empfehlen wir dir:

keine strikte Validierung der Payload-Struktur vorzunehmen → deine Integration sollte nicht abstürzen, wenn neue Eigenschaften in einem MotionTools-Payload auftauchen, das du nutzt
keine strikte Validierung bekannter Schlüsselwerte als Enums (z.B. Status, Übergänge, andere Schlüsselwerte wie now für die booking.scheduled_at Eigenschaft) → deine Integration sollte fehlerfrei und ohne Abstürze mit neuen, unbekannten Status, Übergängen usw. umgehen können

Integration testen

Für Testzwecke bekommst du Zugriff auf deinen eigenen MotionTools-Mandanten, der dem Mandanten deines Lieferpartners sehr ähnlich sein wird. Dieser Mandant dient als deine Sandbox-Umgebung, in der du während der Entwicklung deiner Integration testen, iterieren und experimentieren kannst.

Beachte jedoch, dass du in dieser Entwicklungs-Sandbox-Umgebung Zugriff auf den Mandanten-admin-Benutzer haben wirst, während du in der Produktionsumgebung nur Zugriff auf einen customer-Benutzer im Produktionsmandanten deines Lieferpartners haben wirst.

Stelle daher sicher, dass du in deiner Sandbox-Umgebung auch einen customer-Account anlegst und dessen API-Schlüssel (d.h. Schlüssel mit der customer-Rolle) während der Entwicklung deiner Integration auf deinem Sandbox-Mandanten verwendest.