Appearance

Aufträge per API ​

Überblick ​

So legen Sie Aufträge an und bearbeiten sie. Alle Pfade beziehen sich auf die Basis-URL https://cockpit.beammycar.com/api/external/v1. Die vollständige Feldliste steht in der OpenAPI-Referenz: https://cockpit.beammycar.com/api/external/docs

Auftrag anlegen ​

POST /orders – Pflicht sind pickup (Abholung) und delivery (Lieferung).

json
{
  "externalId": "LOG-2026-00123",
  "client": { "name": "Logether GmbH" },
  "pickup": { "name": "Autohaus Müller GmbH", "city": "Leipzig" },
  "delivery": {
    "name": "Empfänger AG",
    "street": "Hafenstraße",
    "number": "5",
    "zipCode": "20457",
    "city": "Hamburg",
    "contact": "Frau Meier",
    "phone": "+49 40 123456"
  },
  "pickupAt": "2026-11-03T08:00:00+01:00",
  "deliveryAt": "2026-11-03T16:00:00+01:00",
  "licensePlate": "L-AB 123",
  "vin": "WVWZZZ1KZAW000001",
  "commentForDriver": "Schlüssel beim Empfang",
  "commentInternal": "Kunde zahlt bar",
  "extras": { "wash": true, "fullFuel": true }
}

Antwort 201 Created:

json
{
  "id": 4711,
  "orderNumber": "LG12345",
  "externalId": "LOG-2026-00123",
  "status": "open",
  "client": { "id": 17, "name": "Logether GmbH" },
  "pickup": { "id": 9001, "name": "Autohaus Müller GmbH", "city": "Leipzig", "phone": "+49 341 111", "contact": "Herr Schmidt" },
  "delivery": { "id": 9002, "name": "Empfänger AG", "city": "Hamburg" }
}
  • 🔢 orderNumber ist die Auftragsnummer, wie sie im Cockpit erscheint. Mit id sprechen Sie den Auftrag in allen weiteren Aufrufen an.
  • 🏠 Adressen: entweder { "id": … } einer gespeicherten Adresse oder Felder. Wie bekannte Adressen erkannt werden, steht unter Adressen & Kunden erkennen.
  • 🔁 externalId (optional, max. 100 Zeichen) verhindert Doppel: Dieselbe Nummer ein zweites Mal ergibt 409 mit dem vorhandenen Auftrag unter extensions.order.
  • ☑️ extras setzt die Häkchen aus „Auftrag-Extras“ (Waschen, Volltanken, Ausweiskontrolle …). Alle Namen stehen in der Feldreferenz.
  • 💶 Preise nimmt die API nicht an; sie entstehen wie gewohnt über die Preislisten im Cockpit.
python
import requests

BASE = "https://cockpit.beammycar.com/api/external/v1"
HEADERS = {"Authorization": "Bearer bmc_pat_..."}

order = {
    "externalId": "LOG-2026-00123",
    "pickup": {"name": "Autohaus Müller GmbH", "city": "Leipzig"},
    "delivery": {"name": "Empfänger AG", "city": "Hamburg"},
}
response = requests.post(f"{BASE}/orders", json=order, headers=HEADERS)

if response.status_code == 201:
    print("Angelegt:", response.json()["orderNumber"])
elif response.status_code == 409:
    print("Gab es schon:", response.json()["extensions"]["order"]["orderNumber"])
else:
    problem = response.json()
    print("Fehler:", problem["extensions"]["errorCode"], problem["title"])

Auftrag lesen ​

GET /orders/{id} liefert den Auftrag samt status:

StatusBedeutung
openangelegt, noch kein Fahrer (auch: vom Fahrer abgelehnt)
assignedFahrer zugewiesen bzw. hat angenommen
inProgressabgeholt / unterwegs
completedgeliefert und abgeschlossen
canceledstorniert

Auftrag ändern ​

PATCH /orders/{id} – geändert wird nur, was Sie mitschicken. Beispiel:

json
{ "deliveryAt": "2026-11-04T10:00:00+01:00", "commentForDriver": "Neuer Termin" }
  • 🏠 Neue Adressen werden wie beim Anlegen erkannt.
  • 🔒 Was in welchem Zustand änderbar ist, regeln dieselben Prüfungen wie im Cockpit.
  • 🔢 externalId lässt sich nicht ändern.

Auftrag stornieren ​

POST /orders/{id}/cancel – ohne Body. Ein bereits stornierter Auftrag antwortet ebenfalls mit 200.

Fahrer zuweisen ​

PUT /orders/{id}/driver

json
{ "email": "max@spedition.de" }
  • 👥 Die E-Mails Ihrer Fahrer liefert GET /drivers.
  • ➖ { "email": null } nimmt den Fahrer wieder heraus.
  • 🧩 Aufträge mit Teilstrecken (mehrere Fahrer) planen Sie bitte im Cockpit; die API antwortet dort mit multi_leg_not_supported.

Siehe auch ​