2.19 Order Create - Auftrag anlegen

Zweck

Anlegen eines neuen Fahrauftrags im FSM‑System.

Neu angelegte Aufträge erhalten immer den Status Neu (1). Ohne Angabe von customer_id wird der Auftrag dem Kundenkonto zugeordnet, dessen JWT für den API‑Aufruf verwendet wird.

Umgebungen

Umgebung	Basis-URL
Produktion	https://app.fahrservicemeybaum.de/api.htm
Entwicklung / Test	https://dev.fahrservicemeybaum.de/api.htm

Hinweis: Für Entwicklung und Tests ausschließlich die Dev‑Umgebung verwenden.

Endpoint

POST /api.htm?action=order_create

Der Endpoint kann per GET oder POST aufgerufen werden. Die Parameter action und data werden als URL‑Parameter (GET) oder im Request‑Body (POST, application/x-www-form-urlencoded) übertragen. Das data‑Feld enthält ein JSON‑Objekt (URL‑kodiert).

Empfehlung: POST verwenden. Bei GET stehen Adressen, Namen und Telefonnummern in der URL und damit in Server‑ und Proxy‑Logs.

Berechtigungen

• Authentifizierung: JWT (Authorization Header). Rolle und Identität werden serverseitig aus dem Token abgeleitet.
• Nur authentifizierte Benutzer mit der Berechtigung „Auftrag anlegen“ dürfen Aufträge anlegen. Kundenkonten haben diese Berechtigung standardmäßig.
• Kunden:
  • customer_id weglassen oder 0 → der Auftrag wird dem eigenen Kundenkonto zugeordnet.
  • customer_id eines anderen Kundenkontos derselben Firma → der Auftrag wird diesem Konto zugeordnet.
  • customer_id eines Kontos einer anderen Firma oder eines Nicht‑Kunden → Fehler.
• Manager / Supervisor / Manager_Special: customer_id ist Pflicht.
• Unabhängig von customer_id wird immer der aufrufende Benutzer als Ersteller (created_by) gespeichert. Der Ersteller behält Zugriff auf den Auftrag.
• Clients (Unterkonten eines Kunden) dürfen keine Aufträge anlegen.

Token holen

Das Access‑Token wird über auth_login angefordert (gültig 1 Stunde, Refresh‑Token 60 Tage):

curl -s -X POST "https://dev.fahrservicemeybaum.de/api.htm?action=auth_login" \
  --data-urlencode 'data={"email":"kunde@example.de","password":"<passwort>","os":"android"}'

Das Token steht in der Antwort unter data.access_token. Ist es abgelaufen, antwortet die API mit error_code 5. Dann über auth_refresh ein neues Token holen und den Aufruf wiederholen.

Auth‑Hinweis

Setze das Access‑Token im Header:

Authorization: Bearer <access_token>

(Alternativ nur bei multipart/form-data Uploads: access_token im data‑Objekt.)

Parameter

Kunde und Zuordnung

Parameter	Typ	Pflicht	Beschreibung
customer_id	int	Nein*	Kunden‑ID, für die der Auftrag angelegt wird (für Manager Pflicht)
client_id	int	Nein	ID eines Clients (Unterkonto) der eigenen Firma
client_company_id	int	Nein	ID einer Client‑Firma der eigenen Firma

Termine

Parameter	Typ	Pflicht	Beschreibung
pickup_date	string	Ja	Abholdatum im Format YYYY-MM-DD, nicht in der Vergangenheit
pickup_time	string	Nein	Abholzeit als Freitext, z. B. 09:00
delivery_date	string	Ja	Lieferdatum im Format YYYY-MM-DD, nicht vor pickup_date
delivery_time	string	Nein	Lieferzeit als Freitext, z. B. 11:00
pickup_delivery_flexible	int	Nein***	1 = Termin flexibel (siehe Validierungsregeln)
pickup_delivery_remark	string	Nein***	Bemerkung zum flexiblen Termin

Abholort

Parameter	Typ	Pflicht	Beschreibung
pickup_at	string	Ja	Firma bzw. Abholort
pickup_name	string	Ja	Ansprechpartner am Abholort
pickup_phone	string	Ja	Telefonnummer am Abholort
pickup_street	string	Ja	Straße und Hausnummer am Abholort
pickup_zip	string	Ja	Postleitzahl am Abholort
pickup_city	string	Ja	Ort am Abholort

Lieferort

Parameter	Typ	Pflicht	Beschreibung
delivery_to	string	Ja	Empfänger bzw. Zielunternehmen
delivery_name	string	Ja	Ansprechpartner am Lieferort
delivery_phone	string	Ja	Telefonnummer am Lieferort
delivery_street	string	Ja	Straße und Hausnummer am Lieferort
delivery_zip	string	Ja	Postleitzahl am Lieferort
delivery_city	string	Ja	Ort am Lieferort

Fahrzeug

Parameter	Typ	Pflicht	Beschreibung
car_model	string	Ja	Fahrzeugmodell
car_no_plate	string	Ja	Amtliches Kennzeichen des Fahrzeugs
car_vin	string	Nein**	Fahrzeug‑Identifizierungsnummer (FIN), 17 Zeichen
car_no_id	string	Nein	Interne Fahrzeug‑ bzw. Bestandsnummer
car_type	int	Nein	Fahrzeugtyp (siehe Wertebereiche)
brand_selector	int	Nein**	Fahrzeugmarke (ID)
special_route	int	Nein	1 = Sonderroute

Rückfahrzeug

Parameter	Typ	Pflicht	Beschreibung
return_present	int	Nein	Kennzeichnung für Rückgabe / Rückfahrt (0 = nein, 1 = ja)
return_car_model	string	Nein	Modell des Rückgabefahrzeugs
return_car_no_plate	string	Nein	Kennzeichen des Rückgabefahrzeugs
return_car_vin	string	Nein	FIN des Rückgabefahrzeugs, 17 Zeichen

Kostenstelle

Parameter	Typ	Pflicht	Beschreibung
cost_center_number	string	Nein	Kostenstellennummer, erscheint auf der Rechnung
cost_center_recipient	string	Nein	Empfänger bzw. Bezeichnung der Kostenstelle
cost_center_email	string	Nein	E‑Mail‑Adresse zur Kostenstelle

Benachrichtigungen

Parameter	Typ	Pflicht	Beschreibung
notify_pickup	int	Nein***	1 = E‑Mail bei Abholung senden
notify_pickup_email	string	Nein***	Empfängeradresse für die Abholungs‑Mail
notify_delivery	int	Nein***	1 = E‑Mail bei Lieferung senden
notify_delivery_email	string	Nein***	Empfängeradresse für die Lieferungs‑Mail
notify_return	int	Nein***	1 = E‑Mail bei Rückgabe senden
notify_return_email	string	Nein***	Empfängeradresse für die Rückgabe‑Mail

Es wird nur gemailt, wenn das jeweilige notify_*‑Flag 1 ist und eine Adresse angegeben ist. Adressen werden nie automatisch ergänzt.

Sonstiges

Parameter	Typ	Pflicht	Beschreibung
comment	string	Nein	Bemerkung zum Auftrag
distance	float	Nein	Entfernung in Kilometern
point3	object	Nein	Dritter Anlaufpunkt (siehe unten)

* Für Kundenkonten optional, für Manager Pflicht. ** Kann firmenspezifisch zum Pflichtfeld gemacht werden (siehe Validierungsregeln). *** Nur wirksam, wenn die Funktion für die Firma freigeschaltet ist. Sonst wird der Wert ignoriert.

Dritter Anlaufpunkt (point3)

Optionales Objekt für einen zusätzlichen Lieferort:

"point3": {
  "enabled": 1,
  "delivery_date": "2026-10-08",
  "delivery_time": "10:00",
  "delivery_to": "Zweitempfänger GmbH",
  "delivery_name": "Ansprechpartner",
  "delivery_phone": "+49 40 123456",
  "delivery_street": "Musterweg 1",
  "delivery_zip": "20095",
  "delivery_city": "Hamburg",
  "notify": 0,
  "notify_email": ""
}

notify und notify_email werden nur übernommen, wenn Benachrichtigungen für den dritten Punkt für die Firma freigeschaltet sind.

Wertebereiche

Fahrzeugtyp (car_type)

Wert	Bedeutung
0	Nicht gesetzt
1	Neufahrzeug
2	Gebrauchtfahrzeug

Rückgabe / Rückfahrt (return_present)

Wert	Bedeutung
0	Nein
1	Ja

Validierungsregeln

• Abholdatum: darf nicht in der Vergangenheit liegen.
• Lieferdatum: darf nicht vor dem Abholdatum liegen.
• FIN (car_vin, return_car_vin): Leerzeichen und Bindestriche werden entfernt, Kleinbuchstaben in Großbuchstaben umgewandelt. Danach muss die FIN leer sein oder aus genau 17 Buchstaben (A–Z) und Ziffern bestehen.
• Firmenspezifische Pflichtfelder:
  • Ist für die Firma „FIN erforderlich“ aktiv, ist car_vin Pflicht.
  • Ist für die Firma „Marke erforderlich“ aktiv, ist brand_selector Pflicht.
• Rückfahrzeug: Ist return_present nicht 1, werden return_car_model, return_car_no_plate und return_car_vin verworfen.
• Gesperrte Liefertage (Kundenkonten): Der Auftrag wird abgelehnt, wenn das Lieferdatum in einem für die Firma gesperrten Zeitraum liegt oder an diesem Tag keine Fahrer mehr verfügbar sind. In diesem Fall ein anderes Lieferdatum wählen.
• Flexibler Termin: Ist pickup_delivery_flexible = 1 gesetzt, entfällt die Prüfung auf gesperrte Liefertage. Sind zusätzlich pickup_delivery_remark gefüllt, setzt das System Abhol‑ und Lieferdatum auf einen Platzhalter (heute + 1 Jahr). Der tatsächliche Termin wird dann mit dem Disponenten abgestimmt.
• Client‑Zuordnung: client_id und client_company_id müssen zur Firma des Auftragskunden gehören. Werden beide angegeben, muss der Client zur angegebenen Client‑Firma gehören.

Request‑Beispiel (JWT, POST)

curl -s -X POST "https://dev.fahrservicemeybaum.de/api.htm?action=order_create" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json" \
  --data-urlencode 'data={
    "pickup_date":"2026-10-06",
    "pickup_time":"09:00",
    "pickup_at":"Fahrservice Meybaum GmbH",
    "pickup_name":"Ansprechpartner Abholung",
    "pickup_phone":"+49 4122 123456",
    "pickup_street":"Grauer Esel 34B",
    "pickup_zip":"25492",
    "pickup_city":"Heist",
    "delivery_date":"2026-10-07",
    "delivery_time":"11:00",
    "delivery_to":"Lieferfirma GmbH",
    "delivery_name":"Ansprechpartner Lieferung",
    "delivery_phone":"+49 4821 123456",
    "delivery_street":"Robert-Koch-Str. 2",
    "delivery_zip":"25524",
    "delivery_city":"Itzehoe",
    "car_model":"Audi Q5 Sport",
    "car_no_plate":"IZ-M 2930",
    "car_vin":"WVWZZZ3CZWE123456",
    "car_type":1,
    "comment":"Bitte vorher anrufen",
    "cost_center_number":"KST-4711",
    "cost_center_recipient":"Buchhaltung Nord",
    "cost_center_email":"buchhaltung@example.de"
  }'

Response‑Beispiel (Erfolg)

{
  "status": "success",
  "data": {
    "order_id": 22422,
    "number": "0626-482917",
    "customer_id": 1188,
    "created_by": 1188
  }
}

Feld	Beschreibung
order_id	Interne ID des Auftrags
number	Auftragsnummer
customer_id	Kundenkonto, dem der Auftrag zugeordnet wurde
created_by	Benutzer, der den Auftrag angelegt hat (Inhaber des JWT)

Fehler

Fehler werden immer mit HTTP‑Status 200 zurückgegeben. Maßgeblich sind die Felder status, error_code und error_reason. Mehrere Validierungsfehler werden in error_reason mit ; getrennt.

{
  "status": "error",
  "error_code": "2",
  "error_reason": "Pickup Date is empty; Delivery Date is empty"
}

error_code	error_reason (Beispiele)	Ursache
2	Access denied	Keine Berechtigung zum Anlegen von Aufträgen
2	Pickup Date is empty, Pickup at is empty, Car Model is empty, …	Pflichtfeld fehlt
2	Pickup Date can not be in the past	Abholdatum liegt in der Vergangenheit
2	Delivery Date can not be older than Pickup Date	Lieferdatum vor Abholdatum
2	FIN ist erforderlich	Firma verlangt FIN, car_vin leer
2	Fahrzeugmarke Auswahlen	Firma verlangt Marke, brand_selector leer
2	FIN‑Formatfehler	FIN hat nicht genau 17 Zeichen A–Z / 0–9
2	The delivery date is within the prohibited period oder firmenspezifischer Text	Lieferdatum in gesperrtem Zeitraum
2	No available drivers. Enter another day for delivery.	Am Liefertag keine Fahrer frei
2	Invalid customer_id	customer_id existiert nicht oder ist kein Kundenkonto
2	customer_id belongs to a different company	customer_id gehört zu einer anderen Firma
2	client_id belongs to a different company / client_company_id belongs to a different company / client_id does not belong to client_company_id	Client‑Zuordnung passt nicht zur Firma
2	Select customer	Manager hat customer_id nicht angegeben
5	–	Access‑Token fehlt, ist ungültig oder abgelaufen

Sicherheits‑Anforderungen

• API‑Aufrufe ausschließlich über HTTPS ausführen.
• Der Auftrag wird serverseitig anhand des im JWT identifizierten Benutzers einem Kundenkonto zugeordnet.
• Tokens nicht in URLs übermitteln oder in öffentlichen Repositories speichern.
• POST statt GET verwenden, damit personenbezogene Daten nicht in URLs landen.

Hinweise für Integratoren

• Für Tests die Dev‑Umgebung verwenden.
• Pflichtfelder vollständig und im erwarteten Format übergeben.
• Immer status auswerten, nicht den HTTP‑Status.
• Bei error_code 5 das Token über auth_refresh erneuern und den Aufruf wiederholen.
• Manager, die Aufträge im Namen anderer Kunden anlegen, müssen customer_id angeben.
• Die order_id aus der Antwort speichern. Sie wird für Folgeaufrufe (Status, Kommentare, Bilder) benötigt.