API: Werkstatttermine

Endpunkte zum Anlegen von Werkstattterminen in Werkstattkalender (calendar_timeline in Doku genannt)
sowie zur Ermittlung freier Termin-Slots. Folgt dem Auth-Muster von /api/invoices/create.

Übersicht der Endpunkte

Web-DEMOs

Werkstatttermin per API anlegen – Demo

Freie Werkstatt-Slots ermitteln

Slot suchen und Termin anlegen

POST /api/workshop-appointments/free-slots

Berechnet freie Termin-Slots im angegebenen Zeitraum über alle Tage hinweg.
Berücksichtigt belegte Einträge in calendar_timeline
mit Branch-Scope und optionalen Filtern.

Request-Felder

Beispiel-Aufruf

POST /api/workshop-appointments/free-slots
Content-Type: application/json

{
  "token": "xxxxxxxx",
  "date_from": "2026-05-22",
  "date_to": "2026-05-26",
  "slot_minutes": 30,
  "section_name": "Werkstatt",
  "employee_name": "Max Mustermann",
  "resource_name": "Hebebühne 1",
  "workshop_start": "08:00",
  "workshop_end": "17:00",
  "include_weekends": 0,
  "max_slots": 50
}

Erfolgsantwort (HTTP 200)

{
  "data": {
    "range": { "date_from": "2026-05-22", "date_to": "2026-05-26" },
    "slot_minutes": 30,
    "workshop_start": "08:00",
    "workshop_end": "17:00",
    "include_weekends": 0,
    "filters": {
      "section_id": 9991,
      "section_name": "Werkstatt",
      "employee_id": 42,
      "employee_name": "Max Mustermann",
      "resource_id": 3,
      "resource_name": "Hebebühne 1",
      "branch_id": 1
    },
    "count": 3,
    "slots": [
      {
        "date": "2026-05-22",
        "start_date": "2026-05-22 08:00:00",
        "end_date": "2026-05-22 08:30:00",
        "section_id": 9991,
        "section_name": "Werkstatt",
        "employee_id": 42,
        "employee_name": "Max Mustermann",
        "resource_id": 3,
        "resource_name": "Hebebühne 1"
      }
    ]
  },
  "status": 1,
  "message": "Success"
}

Fehler-Antworten

HTTP 401  { "status": 0, "message": "Invalid Token" }
HTTP 422  { "status": 0, "message": "date_from and date_to are required (Y-m-d)" }
HTTP 422  { "status": 0, "message": "date_from must be <= date_to" }
HTTP 422  { "status": 0, "message": "date range must not exceed 92 days" }
HTTP 422  { "status": 0, "message": "slot_minutes must be between 5 and 720" }
HTTP 404  { "status": 0, "message": "section_name not found: ..." }
HTTP 404  { "status": 0, "message": "employee_name not found: ..." }
HTTP 500  { "status": 0, "message": "DB connect failed" }

POST /api/workshop-appointments/create

Legt einen neuen Werkstatttermin in calendar_timeline an.
Optional können Kunde, Fahrzeug, Auftrag, Abteilung, Mitarbeiter, Werkstattbahn (Resource) und Werkstattwagen verknüpft werden.
Wenn kein customer_id bekannt ist, kann mit dem Objekt
customer ein Find‑or‑Create ausgelöst werden.
Analog für Fahrzeuge mit vehicle.

Request-Felder

Customer Find-or-Create

Wenn customer_id nicht gesetzt ist und stattdessen
customer übergeben wird, sucht das System einen passenden Kunden in
customers und legt nur dann einen neuen Datensatz an, wenn kein eindeutiger Treffer vorliegt.

Match-Reihenfolge (deterministisch, jeweils nur wenn vorherige Stufe leer):

1. Exakter Treffer auf email, email_2 oder email_3.
2. Telefon (normalisiert, nur Ziffern, ≥ 5 Stellen) gegen phone_mobile, phone_business, phone_private.
3. Kombination zip + (surname oder company_name).

Vehicle Find-or-Create

Wenn vehicle_id nicht gesetzt ist und stattdessen
vehicle übergeben wird, sucht das System ein passendes Fahrzeug in
clientmobiles und legt es nur dann neu an, wenn kein eindeutiger Treffer vorliegt.

1. Exakter Treffer auf chassis_number (VIN), optional eingeschränkt auf customer_id bzw. current_owner_id.
2. Exakter Treffer auf mobile_sign (Kennzeichen), analog kunden-eingeschränkt.

Mindestens eines von chassis_number oder
mobile_sign ist erforderlich.

Beispiel-Aufruf (JSON)

POST /api/workshop-appointments/create
Content-Type: application/json

{
  "token": "xxxxxxxx",
  "title": "Inspektion 30tkm",
  "start_date": "2026-05-22 09:00:00",
  "end_date":   "2026-05-22 11:00:00",
  "invoice_id": 14074,
  "department_id": 1,
  "employee_name": "Max Mustermann",
  "resource_name": "Hebebühne 1",
  "work_type": 2,
  "notes": "Kunde bringt Schlüssel morgens",
  "check_conflicts": true,
  "customer": {
    "email": "max.mustermann@example.com",
    "forename": "Max",
    "surname": "Mustermann",
    "zip": "80331",
    "city": "München",
    "street": "Musterstr. 1",
    "phone_mobile": "+49 170 1234567",
    "customer_match_mode": "strict"
  },
  "vehicle": {
    "chassis_number": "WVWZZZ3CZWE123456",
    "mobile_sign": "B-AB 1234",
    "fabricator": "Volkswagen",
    "modell": "Golf VII",
    "ez": "2018-03-15",
    "mileage": 85000,
    "vehicle_match_mode": "strict"
  }
}

Erfolgsantwort (HTTP 200)

{
  "data": {
    "event_id": 5821,
    "title": "Inspektion 30tkm",
    "start_date": "2026-05-22 09:00:00",
    "end_date":   "2026-05-22 11:00:00",
    "customer_id": 12034,
    "customer_resolution": "matched",
    "vehicle_id": 1085,
    "vehicle_resolution": "matched",
    "vehicle_label": "Volkswagen Golf VII (B-AB 1234)",
    "vehicle_sign": "B-AB 1234",
    "vehicle_vin":  "WVWZZZ3CZWE123456",
    "invoice_id": 14074,
    "section_id": 9991,
    "section_name": "Werkstatt",
    "department_id": 1,
    "employee_id": 42,
    "employee_name": "Max Mustermann",
    "resource_id": 3,
    "resource_name": "Hebebühne 1",
    "work_type": 2,
    "branch_id": 1,
    "check_conflicts": 1
  },
  "status": 1,
  "message": "Success"
}

Fehler-Antworten (Auswahl)

HTTP 401  { "status": 0, "message": "Invalid Token" }
HTTP 422  { "status": 0, "message": "title is required" }
HTTP 422  { "status": 0, "message": "start_date must be before end_date" }
HTTP 404  { "status": 0, "message": "Customer not found" }
HTTP 404  { "status": 0, "message": "Vehicle not found" }
HTTP 404  { "status": 0, "message": "Invalid section_id (no matching active team or user)" }
HTTP 404  { "status": 0, "message": "employee_name not found: ..." }
HTTP 404  { "status": 0, "message": "Workshop vehicle (resources.id) not found or inactive" }
HTTP 422  { "status": 0, "message": "Vehicle does not belong to provided customer" }
HTTP 409  { "status": 0, "message": "Ambiguous customer match: 3 candidates",
            "data": { "candidates": [12034, 12089, 12190] } }
HTTP 409  { "status": 0, "message": "Ambiguous vehicle match: 2 candidates",
            "data": { "vehicle_candidates": [1085, 1240], "vehicle_match_strategy": "chassis_number" } }
HTTP 409  { "status": 0, "message": "Slot conflict detected (check_conflicts=true)",
            "data": { "conflicts": [ {"event_id": 5810, "start_date": "...", "end_date": "..."} ] } }
HTTP 500  { "status": 0, "message": "Failed to create customer (check PHP error log for SQL details)" }
HTTP 500  { "status": 0, "message": "Failed to insert appointment: <sql error>" }

Field Mapping — calendar_timeline

Race Conditions & Hinweise

Empfohlener Workflow

1. Mit POST /api/workshop-appointments/free-slots freie Slots für den gewünschten Mitarbeiter / die Werkstattbahn ermitteln.
2. Vom Anwender den Slot auswählen lassen.
3. Mit POST /api/workshop-appointments/create den Termin anlegen — idealerweise mit check_conflicts=true, damit konkurrierende Buchungen ein HTTP 409 auslösen.
4. Bei 409 Slot conflict detected: Slots erneut abfragen und neu anbieten.