Kalender & Terminplanung

Die Calendar API bietet volle Kontrolle über Ereignisse, rechtliche Fristen (Fristen), Meeting-Terminplanung und externe Kalendersynchronisation. Sie ist die zentrale Anlaufstelle für Zeitmanagement in Optimaite Law.

Basis-URL

https://api.optimaite.eu/api/v1/calendar

Authentifizierung

Alle Kalender-Endpunkte erfordern einen gültigen API-Schlüssel mit dem Scope calendar:read. Schreiboperationen erfordern calendar:write.

Kalenderereignisse

Ereignisse auflisten

GET /api/v1/calendar/events?from=2026-01-01&to=2026-12-31&limit=50

Liefert eine paginierte Liste von Kalenderereignissen.

Query-Parameter:

Parameter	Type	Beschreibung
from	ISO date	Beginn des Datumsbereichs (inklusive)
to	ISO date	Ende des Datumsbereichs (inklusive)
type	string	Filter: event, deadline, meeting
case_id	UUID	Ereignisse für eine bestimmte Akte filtern
limit	integer	Max. Ergebnisse pro Seite (Standard 50)
cursor	string	Pagination-Cursor

Antwort:

{
  "data": [
    {
      "id": "evt_550e8400",
      "title": "Court Hearing -- Smith v. Jones",
      "type": "event",
      "start": "2026-03-15T10:00:00+01:00",
      "end": "2026-03-15T12:00:00+01:00",
      "all_day": false,
      "case_id": "550e8400-e29b-41d4-a716-446655440000",
      "location": "Landgericht Berlin",
      "attendees": ["usr_abc123", "usr_def456"]
    }
  ],
  "pagination": { "has_more": false }
}

Ereignis erstellen

POST /api/v1/calendar/events

Request Body:

{
  "title": "Client Meeting",
  "start": "2026-04-01T14:00:00+02:00",
  "end": "2026-04-01T15:00:00+02:00",
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "location": "Office Room 3",
  "description": "Discuss settlement offer",
  "attendees": ["usr_abc123"]
}

Ereignis aktualisieren

PATCH /api/v1/calendar/events/{event_id}

Akzeptiert partielle Updates. Nur übermittelte Felder werden geändert.

Ereignis löschen

DELETE /api/v1/calendar/events/{event_id}

Rechtliche Fristen (Fristen)

Fristen auflisten

GET /api/v1/calendar/fristen?status=open&case_id=550e8400

Liefert rechtliche Fristen mit Verifizierungs- und Delegationsstatus.

Query-Parameter:

Parameter	Type	Beschreibung
status	string	open, verified, expired, all
case_id	UUID	Nach Akte filtern
assigned_to	UUID	Nach Zuständigkeit filtern

Antwort:

{
  "data": [
    {
      "id": "frist_001",
      "title": "Statement of Defense",
      "deadline": "2026-04-15T23:59:00+02:00",
      "case_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "open",
      "verified": false,
      "chain_id": "chain_abc",
      "assigned_to": "usr_abc123"
    }
  ]
}

Frist verifizieren

POST /api/v1/calendar/fristen/{id}/verify

Markiert eine Frist als Vier-Augen-verifiziert (Vier-Augen-Prinzip).

Fristenkette abrufen

GET /api/v1/calendar/fristen/{id}/chain

Liefert alle zusammenhängenden Fristen in der Kette (z. B. Antwortfrist, Gegenklagefrist).

Free/Busy & Terminplanung

Free/Busy-Abfrage

POST /api/v1/calendar/availability/freebusy

Request Body:

{
  "user_ids": ["usr_abc123", "usr_def456"],
  "from": "2026-04-01T08:00:00+02:00",
  "to": "2026-04-01T18:00:00+02:00"
}

Antwort:

{
  "busy": [
    {
      "user_id": "usr_abc123",
      "start": "2026-04-01T10:00:00+02:00",
      "end": "2026-04-01T11:30:00+02:00"
    }
  ]
}

Freie Slots finden

POST /api/v1/calendar/availability/open-slots

Findet verfügbare Zeitfenster für eine Gruppe von Nutzern innerhalb eines Datumsbereichs.

iCal-Feed

iCal-Token erstellen

POST /api/v1/calendar/ical-tokens

Erzeugt ein geheimes Token zum Abonnieren eines iCal-Feeds.

Antwort:

{
  "id": "ical_tok_001",
  "url": "https://api.optimaite.eu/api/v1/calendar/ical/feed?token=abc123...",
  "created_at": "2026-05-27T10:00:00Z"
}

iCal-Token widerrufen

POST /api/v1/calendar/ical-tokens/{id}/revoke

Externe Kalendersynchronisation

Sync-Status

GET /api/v1/calendar/sync/status

Liefert den Synchronisationsstatus für verbundene Google-Calendar- oder Outlook-Konten.

Ereignis in externen Kalender pushen

POST /api/v1/calendar/sync/events/{id}/push

Überträgt ein bestimmtes Ereignis in den verbundenen externen Kalender des Nutzers.

Fehlercodes

Status	Code	Beschreibung
400	INVALID_DATE_RANGE	from muss vor to liegen
403	AUTH_INSUFFICIENT_SCOPE	Fehlender Scope calendar:read oder calendar:write
404	EVENT_NOT_FOUND	Ereignis existiert nicht
409	SLOT_CONFLICT	Ereignis kollidiert mit einem bestehenden Ereignis

Nächste Schritte

• Fristen -- Verwaltung rechtlicher Fristen
• Akten -- Ereignisse mit Akten verknüpfen