API anbinden

Über die API können externe Systeme Dienstlisten und Aufträge in deinen Arbeitsbereich übertragen und gespeicherte Routen abrufen. Die Basis lautet /api/customer/v1 auf deiner Operum-Instanz. Alle Aufrufe verwenden JSON und einen API-Token oder einen gültigen Access-Token deiner normalen Anmeldung.

Eine Anbindung vorbereiten

1. Lege Fahrzeuge, Depots und benötigte Kategorien unter Verwaltung an.
2. Erstelle unter Mein Konto → API-Tokens einen Token für diesen Arbeitsbereich.
3. Lies die Flotte oder den gewünschten Tag und merke dir die zurückgegebene revision.
4. Übertrage die Dienstliste und anschließend die Aufträge. Verwende jeweils die neue Revision aus der vorherigen Antwort.
5. Lade den importierten Stand in der App, berechne den Tag und warte auf Alle Änderungen gespeichert.
6. Rufe die gespeicherten Routen über die API ab.

Der Token muss zu dem Konto gehören, das den gewünschten Arbeitsbereich verwaltet. Ein anderes Konto öffnet einen eigenen Arbeitsbereich. Die API legt keine neuen Flottenfahrzeuge, Depots oder Kategorien an und startet keine automatische Optimierung.

Verfügbare Endpunkte

Alle Pfade in der Tabelle sind relativ zu /api/customer/v1.

Methode	Pfad	Funktion
GET	/fleet	Flottenstandards, Depots, Kategorien und Revision lesen.
GET	/days/{date}	Aufträge, effektive Dienstfahrzeuge und gespeichertes Tagesergebnis lesen.
PUT	/days/{date}/vehicles	Vollständige Dienstliste einschließlich Tagesabweichungen setzen.
POST	/days/{date}/jobs	Aufträge ergänzen oder ersetzen.
GET	/days/{date}/routes	Gespeicherte Routen, Haltezeiten, Geometrie und offene Aufträge abrufen.

{date} ist ein Datum im Format YYYY-MM-DD, beispielsweise 2026-11-02. Zeiten sind ganze Sekunden seit 00:00 des Planungstages: 28800 entspricht 08:00 und 86400 dem Tagesende 24:00. Es erfolgt keine Zeitzonenumrechnung. Koordinaten sind WGS84-Breiten- und Längengrade. Die vollständigen Schemas findest du unter /docs und /openapi.json deiner Operum-Instanz.

Versionskonflikte vermeiden

Jeder schreibende Aufruf benötigt die aktuelle revision. Sie gilt für den gesamten Arbeitsbereich, auch für andere Tage und Änderungen in der App. Jeder erfolgreiche Import liefert eine neue Revision, auch wenn die übertragenen Daten unverändert sind.

Bei HTTP 409 mit workspace.conflict liest du den aktuellen Stand erneut, vergleichst ihn mit deinen Änderungen und sendest erst danach einen neuen Aufruf mit der aktuellen Revision. Eine automatische Zusammenführung erfolgt nicht.

Geöffnete Planung nach einem Import neu laden

Ein bereits geöffneter App-Tab übernimmt API-Änderungen nicht automatisch. Sichere wichtige lokale Änderungen vor dem Neuladen. Bei einem Speicherkonflikt hilft Speichern & weiterarbeiten.

Jeder Import wird vollständig geprüft und als Ganzes gespeichert oder verworfen. Frühere Planungsstände werden über den automatischen Verlauf gesichert. Tatsächlich geänderte Aufträge oder Dienstkonfigurationen setzen das Ergebnis des betroffenen Tages zurück; identische Importe erhalten die Berechnung.

Dienstlisten übertragen

Sende die vollständige Dienstliste an PUT /api/customer/v1/days/2026-11-02/vehicles, beispielsweise:

{
  "revision": 12,
  "vehicles": [
    {
      "vehicle_id": "W-01",
      "shift": { "earliest": 28800, "latest": 64800 },
      "equipment": ["ladehilfe-id"]
    },
    { "vehicle_id": "W-02" }
  ]
}

Ersetze Fahrzeug- und Kategorie-IDs durch vorhandene Kennungen aus /fleet. Das Beispiel setzt W-01 für diesen Tag von 08:00 bis 18:00 mit der genannten Ausstattung ein. W-02 übernimmt seine Standards.

Die Dienstliste wird vollständig ersetzt

Nicht aufgeführte Fahrzeuge werden für diesen Tag deaktiviert. vehicles: [] setzt alle Fahrzeuge außer Dienst. Auch bisherige Tagesabweichungen werden ersetzt: nicht erneut mitgesendete Angaben folgen wieder dem Standard.

Fehlendes oder null gesetztes shift beziehungsweise equipment übernimmt den Flottenstandard. equipment: [] bedeutet ausdrücklich keine Ausstattung. Jede Fahrzeug-ID darf nur einmal vorkommen und muss bereits existieren. Depot, Kapazität und Flottenstandards bleiben erhalten. Die Tageswerte siehst du anschließend unter Tagesfahrzeuge.

Aufträge übertragen

Sende Aufträge an POST /api/customer/v1/days/{date}/jobs. Der Aufruf enthält revision, mode und die Liste jobs.

Modus	Wirkung
upsert (Standard)	Ergänzt neue IDs und ersetzt vorhandene Aufträge mit derselben ID vollständig. Andere Tagesaufträge bleiben erhalten.
replace	Ersetzt alle Aufträge des Tages durch die gesendete Liste. Eine leere Liste löscht die Tagesaufträge.

Ein Upsert ist kein einzelnes Feld-Update. Übertrage bei vorhandenen Aufträgen alle benötigten Angaben erneut; ausgelassene optionale Felder erhalten Standardwerte. Stabile IDs verhindern Doppelanlagen bei wiederholter Übertragung. Eine leere Upsert-Liste verändert keine Aufträge.

Ein Lieferauftrag könnte so aussehen:

{
  "revision": 13,
  "mode": "upsert",
  "jobs": [
    {
      "id": "LIEFERUNG-1002",
      "job_type": "delivery",
      "dropoff": { "lat": 48.21, "lon": 16.36, "name": "Lieferadresse Wien" },
      "dropoff_window": { "earliest": 0, "latest": 86400 },
      "service_duration": 180
    }
  ]
}

Ohne job_type gilt transport; dafür sind Abholung und Ziel sowie beide Zeitfenster erforderlich. Eine Lieferung benötigt nur Ziel und Zielzeitfenster. service_duration ist die Zeit je Stopp in Sekunden. required_equipment enthält vorhandene Kategorie-IDs, assigned_vehicle_id optional eine vorhandene Fahrzeug-ID.

return_for_job_id kann auf einen Hintransport desselben Tages zeigen, auch auf einen bereits vorhandenen. Lieferungen haben keine verknüpfte Rückfahrt. series_id gruppiert Aufträge, erzeugt aber keine zusätzlichen Termine. Übertrage jeden gewünschten Tag ausdrücklich. Pro Aufruf sind höchstens 10.000 Fahrzeuge beziehungsweise Aufträge erlaubt; zusätzlich gelten die Kontolimits.

Gespeicherte Routen abrufen

GET /api/customer/v1/days/{date}/routes liefert Tagesaufträge, effektive Dienstfahrzeuge, Ausstattungsbezeichnungen und solution mit Routen und offenen Aufträgen. Halte enthalten Auftrags-ID, Stopptyp, Ort, Ankunfts- und Abfahrtszeit. Geometrie verwendet die Reihenfolge Längengrad, Breitengrad.

Auch auf der Karte ausgeblendete Routen werden exportiert. Offene Aufträge stehen unter unassigned_jobs; Begründungen stehen, soweit vorhanden, unter unassigned_reasons. Der Abruf berechnet keine neuen Routen.

Ohne gespeicherte Berechnung antwortet der Routen-Endpunkt mit HTTP 409 und customer.routesUnavailable. Der normale Tagesabruf funktioniert weiterhin und enthält dann solution: null. Berechne den Tag in der App und lasse das Ergebnis speichern, bevor du die Routen erneut abrufst.

Fehler einordnen

Status	Nächster Schritt
401	Token und Anmeldung prüfen; Ablauf oder Widerruf ausschließen.
403	Freischaltung und Kontolimits prüfen.
409	Den Fehlercode prüfen: aktuellen Stand abgleichen, fehlende Berechnung erstellen oder undatierte Altdaten zuerst in der App einem Tag zuordnen.
422	Gemeldete Felder, IDs, Verknüpfungen und Zeitangaben korrigieren.
503	Verbindung beziehungsweise Verfügbarkeit prüfen und später erneut versuchen.

Die Antwort enthält einen stabilen code und eine englische Fehlerbeschreibung detail. Bei Schemafehlern nennt errors die betroffenen Felder. Gib bei einer Support-Anfrage den Code und das betroffene Datum an; den vollständigen API-Token brauchst du dafür nicht mitzuschicken.