Service-API für mobile Clients

Verwenden Sie die Service-API, um eigene Backoffice- oder mobile Clients an Serviceaufträge anzubinden.

Ressourcen

  • GET /api/v1/service/orders
  • GET /api/v1/service/visits
  • GET /api/v1/service/technicians
  • GET /api/v1/service/visit-assignments

Für Serviceaufträge, Einsätze und Technikerprofile stehen die üblichen CRUD-Endpunkte mit Tenant-Isolation, Client-Metadaten und Berechtigungen bereit. Einsatz-Zuordnungen lesen Sie über die Assignment-Ressource; neue Zuordnungen erstellen Sie über den Command-Endpunkt.

Techniker zuordnen

POST /api/v1/service/visits/{id}/assignments

Der Endpunkt ordnet einen Techniker einem Einsatz zu und erzeugt eine SchedulingBooking mit referenceType=service_visit. Senden Sie mindestens technicianProfileId, scheduledStartAt und scheduledEndAt, wenn der Einsatz noch kein Zeitfenster besitzt.

Status führen

POST /api/v1/service/visits/{id}/status

Erlaubte Aktionen:

  • start_travel
  • arrive_on_site
  • start_work
  • finish_work
  • complete

Statusfelder sind über generisches CRUD geschützt. Ändern Sie sie über diese Aktionen, damit Zeitstempel und Auftragsstatus konsistent bleiben.

Einsätze sind workflow-owned. Die Statusaktion löst die gleichnamige Workflow-Transition auf der service_visit-Instanz aus. Der Standardworkflow projiziert Status und Zeitstempel zurück auf den Einsatz und synchronisiert danach den Serviceauftrag. Serviceaufträge besitzen keinen eigenen Workflow.

Mobile Me-Endpunkte

  • GET /api/v1/service/mobile/me/visits?from=&to=
  • GET /api/v1/service/mobile/me/visits/{visitId}
  • POST /api/v1/service/mobile/me/visits/{visitId}/status

Diese Endpunkte liefern nur Einsätze, die dem aktuellen Technikerprofil der angemeldeten Identität zugeordnet sind.

Berechtigungen

Backoffice und mobile Clients nutzen getrennte Scopes:

  • service_orders:*
  • service_visits:*
  • service_technicians:*
  • service_visit_assignments:*
  • service_mobile:read
  • service_mobile:update

Freigegebene Zeiten an Commerce übergeben

Nutzen Sie für die Kundenabrechnung ausschließlich die servicegebundenen Aktionen an der TaskLog-Ressource:

text
GET  /api/v1/tasks/{taskId}/logs/{logId}/billing-options
POST /api/v1/tasks/{taskId}/logs/{logId}/billing-snapshot

billing-options benötigt service_billing:read und liefert nur tenantgebundene Servicepositionen der mit dem Task verknüpften Bestellung. billing-snapshot benötigt service_billing:prepare, eine freigegebene und noch nicht abgerechnete Zeitrückmeldung sowie die gewählte orderItemId.

Der Server erzeugt daraus den unveränderlichen Kundenpreis-, Währungs- und Steuer-Snapshot. Verwenden Sie TaskLog.financial nicht als Kundenpreis und berechnen Sie Preis oder Steuer nicht im Client neu. Leere Optionslisten oder stabile service_billing.*-Gründe sind fachliche Blocker; zeigen Sie keine rohen Datenbank- oder Treiberfehler an.

Die Übergabe ist erfolgreich, wenn die TaskLog-Antwort den billingSnapshot mit Bestellposition, Menge, Kundenpreis, Währung und Steuer-Snapshot enthält.