Feldreferenz

Überblick

Alle Felder, die Sie senden können oder zurückbekommen – mit Typ, Pflicht, Höchstlänge und Format.

Allgemeine Formate

Thema	Regel
Format	JSON, UTF-8, Header Content-Type: application/json
Feldnamen	camelCase, genau wie unten angegeben
Unbekannte Felder	werden ohne Fehler ignoriert – Tippfehler im Feldnamen fallen also nicht auf
Leere Felder	weglassen oder null senden. In Antworten fehlen Felder ohne Wert ganz.
Texte	führende/folgende Leerzeichen werden entfernt. Zu lange Texte ergeben 422 validation_failed.
IDs	ganze Zahlen (id, client.id, Adress-id)

Datum & Uhrzeit

• Zeitpunkte müssen im Format ISO 8601 mit Zeitzone gesendet werden:
  • 2026-11-03T08:00:00+01:00 (deutsche Winterzeit)
  • 2026-11-03T08:00:00+02:00 (deutsche Sommerzeit)
  • oder in UTC: 2026-11-03T07:00:00Z
  • Sekunden und Sekundenbruchteile sind optional: 2026-11-03T08:00+01:00, 2026-11-03T07:00:00.000Z
  • Die Zeitzone mit Doppelpunkt (+01:00, nicht +0100) und Z als Großbuchstabe
• ⛔ Ohne Zeitzone (2026-11-03T08:00:00), nur ein Datum (2026-11-03) oder deutsche Schreibweise (03.11.2026 08:00) werden mit 422 validation_failed abgelehnt. Der title nennt die betroffenen Felder. So landet nie ein Termin still zur falschen Uhrzeit im Cockpit.
• Antworten enthalten Zeitpunkte immer in UTC: 2026-11-03T07:00:00Z. Das Cockpit zeigt sie in deutscher Zeit an.

Python-Beispiel mit korrekter Zeitzone:

from datetime import datetime
from zoneinfo import ZoneInfo

pickup_at = datetime(2026, 11, 3, 8, 0, tzinfo=ZoneInfo("Europe/Berlin")).isoformat()
# '2026-11-03T08:00:00+01:00'

Auftrag senden

Gilt für POST /orders (anlegen) und PATCH /orders/{id} (ändern). Beim Ändern wird nur geändert, was Sie mitschicken.

Feld	Typ	Pflicht beim Anlegen	Max.	Beschreibung
externalId	Text	nein	100	Ihre eigene Auftragsnummer, schützt vor Doppeln. Nur beim Anlegen, beim Ändern ignoriert.
client	Kunden-Referenz	nein	–	Auftraggeber-Kunde. Ohne Angabe entsteht der Auftrag ohne Kunden.
pickup	Adresse	ja	–	Abholung
delivery	Adresse	ja	–	Lieferung
pickupAt	Zeitpunkt mit Zeitzone	nein	–	Abholung frühestens
pickupLatestAt	Zeitpunkt mit Zeitzone	nein	–	Abholung spätestens
deliveryAt	Zeitpunkt mit Zeitzone	nein	–	Lieferung frühestens
deliveryLatestAt	Zeitpunkt mit Zeitzone	nein	–	Lieferung spätestens
licensePlate	Text	nein	20	Kennzeichen, wird in Großbuchstaben gespeichert (L-AB 123)
vin	Text	nein	200	Fahrgestellnummer (FIN), wird in Großbuchstaben gespeichert
commentForDriver	Text	nein	2000	Hinweis für den Fahrer, erscheint in der App
commentInternal	Text	nein	2000	Interner Hinweis, nur im Cockpit sichtbar
extras	Auftrag-Extras	nein	–	Häkchen wie „Waschen“ oder „Volltanken“

Nicht über die API möglich: Preise, Dokumente und Fotos. Diese pflegen Sie im Cockpit.

Auftrag-Extras

Die Häkchen aus dem Bereich „Auftrag-Extras“ im Cockpit, jeweils true oder false.

Feld	Im Cockpit
removePlates	Kennzeichen entfernen
redPlates	Rote Kennzeichen
wash	Waschen
fullFuel	Volltanken
idCheck	Übergabe mit Ausweiskontrolle
notReadyToDrive	Fahrzeug nicht fahrbereit
notRegistered	Fahrzeug ist nicht zugelassen
noTuv	Fahrzeug hat kein TÜV

• Beim Anlegen gilt jedes nicht mitgeschickte Extra als false.
• Beim Ändern bleibt jedes nicht mitgeschickte Extra, wie es ist. { "extras": { "wash": false } } nimmt nur „Waschen“ heraus.
• In Antworten sind immer alle acht Extras enthalten.

Adresse

Für pickup und delivery. Entweder nur id, oder Felder (mindestens name + city für eine neue Adresse), oder id plus einzelne Felder zum Überschreiben.

Feld	Typ	Max.	Beschreibung
id	Zahl	–	ID einer gespeicherten Adresse (aus GET /addresses)
name	Text	200	Firmen- oder Ortsname, z. B. Autohaus Müller GmbH. Wird mit gespeicherten Adressen abgeglichen.
contact	Text	200	Ansprechpartner vor Ort
street	Text	200	Straße ohne Hausnummer
number	Text	20	Hausnummer, z. B. 12a
zipCode	Text	20	Postleitzahl als Text (führende Nullen bleiben erhalten: 04109)
city	Text	200	Ort
country	Text	20	Land, empfohlen als Ländercode DE
phone	Text	200	Telefon, beliebiges Format, z. B. +49 341 123456
email	Text	200	E-Mail vor Ort

Wie gespeicherte Adressen erkannt werden: Adressen & Kunden erkennen.

Kunden-Referenz

Feld	Typ	Beschreibung
id	Zahl	ID des Kunden (aus GET /clients)
name	Text	Alternativ: genauer Kundenname, Groß-/Kleinschreibung egal

Eines von beiden genügt. Ist id gesetzt, zählt id.

Fahrer zuweisen

Body für PUT /orders/{id}/driver:

Feld	Typ	Beschreibung
email	Text oder null	E-Mail des Fahrers (aus GET /drivers). null entfernt den Fahrer.

Suchparameter

Aufruf	Parameter	Verhalten
GET /addresses	search (Pflicht)	Teiltreffer in Name, Straße, Ort oder Ansprechpartner; neueste zuerst; max. 50
GET /clients	search (optional)	Teiltreffer im Namen; alphabetisch; max. 50. Ohne search alle (max. 50).
GET /drivers	–	alle aktiven Fahrer, nach Nachname sortiert

Antworten

Auftrag

Antwort von POST, GET, PATCH, cancel und driver:

Feld	Typ	Beschreibung
id	Zahl	Technische ID für alle weiteren Aufrufe
orderNumber	Text	Auftragsnummer wie im Cockpit, z. B. LG12345
externalId	Text	Ihre Nummer, falls angegeben
status	Text	open, assigned, inProgress, completed oder canceled – siehe Status
client	Kunde	falls gesetzt
pickup, delivery	Adresse	inklusive der aus dem Cockpit ergänzten Felder
pickupAt, pickupLatestAt, deliveryAt, deliveryLatestAt	Zeitpunkt (UTC)
licensePlate, vin, carModel	Text	carModel z. B. VW Golf, falls im Cockpit gepflegt
commentForDriver, commentInternal	Text
extras	Auftrag-Extras	immer alle acht, true oder false
driver	Fahrer	nur für Administrator/Disponent und nur, wenn zugewiesen

Adresse in Antworten

Dieselben Felder wie beim Senden (id, name, contact, street, number, zipCode, city, country, phone, email). Die id in einer Auftragsantwort gehört zur Adresse dieses Auftrags.

Kunde

Feld	Typ
id	Zahl
name	Text
city	Text
phone	Text
email	Text

Fahrer

Feld	Typ
name	Text (Vor- und Nachname)
email	Text – damit weisen Sie zu

Vollständiges Beispiel

{
  "externalId": "LOG-2026-00123",
  "client": { "id": 17 },
  "pickup": { "id": 9001, "contact": "Frau Weber" },
  "delivery": {
    "name": "Empfänger AG",
    "contact": "Herr Meier",
    "street": "Hafenstraße",
    "number": "5",
    "zipCode": "20457",
    "city": "Hamburg",
    "country": "DE",
    "phone": "+49 40 123456",
    "email": "logistik@empfaenger.de"
  },
  "pickupAt": "2026-11-03T08:00:00+01:00",
  "pickupLatestAt": "2026-11-03T10:00:00+01:00",
  "deliveryAt": "2026-11-03T15:00:00+01:00",
  "deliveryLatestAt": "2026-11-03T18:00:00+01:00",
  "licensePlate": "L-AB 123",
  "vin": "WVWZZZ1KZAW000001",
  "commentForDriver": "Schlüssel liegt beim Empfang",
  "commentInternal": "Rückfahrt mit Bahn",
  "extras": { "wash": true, "fullFuel": true, "idCheck": true }
}

Siehe auch

• Aufträge per API
• Fehlerreferenz