> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminplanung

> Termine, Termintypen, Erinnerungen und Arztverfügbarkeiten über die Management-API verwalten

# Terminplanung

Verwalten Sie die Terminplanungs-Konfiguration Ihrer Organisation per API-Schlüssel
statt über die Admin-Oberfläche. Sie können geplante Termine auflisten und stornieren,
Termintypen und deren Erinnerungen verwalten sowie die wiederkehrenden
Verfügbarkeitsregeln jedes Arztes konfigurieren.

Alle Endpunkte sind auf die Organisation beschränkt, der der API-Schlüssel gehört.
UIDs, die zu einer anderen Organisation gehören, werden als nicht gefunden behandelt.

## Berechtigungen

Die Terminplanungs-Endpunkte werden durch zwei Berechtigungen gesteuert:

* `scheduling:read` — erforderlich für alle Lese-Endpunkte (`GET`).
* `scheduling:admin` — erforderlich für alle Schreib-Endpunkte (`POST`, `PATCH`, `DELETE`).

Ein Schlüssel mit `scheduling:admin` erhält nicht automatisch `scheduling:read`;
fügen Sie beide hinzu, wenn Sie lesen und schreiben müssen. Wenden Sie sich an Ihren
RxScale-Ansprechpartner, um Berechtigungen anzupassen.

Alle Anfragen authentifizieren sich über den Header `X-API-Key`. Details finden Sie
unter [Authentifizierung](/authentication).

## Termine

### Termine auflisten

```bash theme={null}
GET /v1/management/scheduling/appointments
```

Gibt eine paginierte Liste der geplanten Termine der Organisation zurück.

**Erforderliche Berechtigung:** `scheduling:read`

<ParamField query="page" type="integer" default="0">
  Seitenzahl (0-basiert)
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Anzahl der Termine pro Seite
</ParamField>

<ParamField query="doctor_uid" type="string">
  Termine nach Arzt-UID filtern
</ParamField>

<ParamField query="patient_uid" type="string">
  Termine nach Patienten-UID filtern
</ParamField>

<ParamField query="status" type="string">
  Nach Terminstatus filtern. Einer von `held`, `confirmed`, `cancelled`,
  `expired`, `completed`, `no_show` oder `all`. Wird der Wert weggelassen,
  gilt die serverseitige Standardfilterung.
</ParamField>

<ParamField query="from" type="integer">
  Termine ab diesem Unix-Zeitstempel (einschließlich) filtern
</ParamField>

<ParamField query="to" type="integer">
  Termine bis zu diesem Unix-Zeitstempel (einschließlich) filtern. Muss größer
  als `from` sein, wenn beide angegeben werden.
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointments?page=0&limit=25&status=confirmed" \
  -H "X-API-Key: your-api-key-here"
```

#### Antwort

```json theme={null}
{
  "data": [
    {
      "uid": "mtg-abc123",
      "status": "confirmed",
      "doctor_uid": "doc-456",
      "doctor_display_name": "Dr. Schmidt",
      "patient_uid": "pat-789",
      "patient_display_name": "Jane Doe",
      "appointment_type_uid": "apt-001",
      "appointment_type_name": "Initial consultation",
      "visit_reason": "Medikationsreview vor Dosisanpassung",
      "meeting_type": "CONSULTATION",
      "meeting_format": "DIGITAL",
      "start_date": 1712300000,
      "end_date": 1712301800,
      "created_at": 1712200000,
      "cancelled_at": null,
      "cancellation_reason": null
    }
  ],
  "totalRegistries": 42,
  "totalPages": 2
}
```

#### Antwortfelder

| Feld                           | Typ             | Beschreibung                                                                                                                      |
| ------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `data[].uid`                   | string          | UID des geplanten Termins                                                                                                         |
| `data[].status`                | string          | Terminstatus (`held`, `confirmed`, `cancelled`, `expired`, `completed`, `no_show`)                                                |
| `data[].doctor_uid`            | string          | Arzt-UID                                                                                                                          |
| `data[].doctor_display_name`   | string          | Anzeigename des Arztes                                                                                                            |
| `data[].patient_uid`           | string          | Patienten-UID                                                                                                                     |
| `data[].patient_display_name`  | string          | Anzeigename des Patienten                                                                                                         |
| `data[].appointment_type_uid`  | string \| null  | UID des Termintyps, falls vorhanden                                                                                               |
| `data[].appointment_type_name` | string \| null  | Name des Termintyps, falls vorhanden                                                                                              |
| `data[].visit_reason`          | string \| null  | Optionaler bei der Buchung angegebener Termingrund. Kann auch in Erinnerungen und synchronisierten Kalendereinladungen erscheinen |
| `data[].meeting_type`          | string          | Terminart (z. B. `CONSULTATION`, `FOLLOW_UP`, `INITIAL`, `REVIEW`, `ON_DEMAND`)                                                   |
| `data[].meeting_format`        | string          | Terminformat (`DIGITAL`, `IN_PERSON`)                                                                                             |
| `data[].start_date`            | integer         | Startzeit (Unix-Zeitstempel)                                                                                                      |
| `data[].end_date`              | integer         | Endzeit (Unix-Zeitstempel)                                                                                                        |
| `data[].created_at`            | integer         | Erstellungszeitpunkt (Unix)                                                                                                       |
| `data[].cancelled_at`          | integer \| null | Stornierungszeitpunkt (Unix), falls storniert                                                                                     |
| `data[].cancellation_reason`   | string \| null  | Bei der Stornierung angegebener Grund, falls storniert                                                                            |
| `totalRegistries`              | integer         | Gesamtzahl der Termine, die dem Filter entsprechen                                                                                |
| `totalPages`                   | integer         | Gesamtzahl der Seiten                                                                                                             |

### Einen Termin stornieren

```bash theme={null}
POST /v1/management/scheduling/appointments/{meeting_uid}/cancel
```

Storniert einen geplanten Termin und erfasst den angegebenen Grund.

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="meeting_uid" type="string" required>
  Die UID des geplanten Termins
</ParamField>

<ParamField body="reason" type="string" required>
  Grund für die Stornierung des Termins (darf nicht leer sein)
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointments/mtg-abc123/cancel" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Patient requested cancellation"
  }'
```

#### Antwort

```json theme={null}
{
  "appointment_uid": "mtg-abc123",
  "status": "cancelled",
  "cancelled_at": 1712250000,
  "cancellation_reason": "Patient requested cancellation"
}
```

## Termintypen

Ein Termintyp definiert eine buchbare Art von Termin (Dauer, Reservierungsverhalten,
Raum- und Umbuchungsstrategie).

### Termintypen auflisten

```bash theme={null}
GET /v1/management/scheduling/appointment-types
```

**Erforderliche Berechtigung:** `scheduling:read`

#### Beispielanfrage

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointment-types" \
  -H "X-API-Key: your-api-key-here"
```

#### Antwort

```json theme={null}
{
  "data": [
    {
      "uid": "apt-001",
      "organisation_uid": "org-123",
      "name": "Initial consultation",
      "meeting_type": "CONSULTATION",
      "duration_minutes": 30,
      "hold_ttl_seconds": 900,
      "booking_min_notice_minutes": 10,
      "cancellation_min_notice_minutes": 60,
      "rebooking_min_notice_minutes": 120,
      "room_strategy": "persistent_per_provider",
      "rebooking_mode": "same_doctor_only",
      "doctor_assignment_mode": "all_available_doctors",
      "allow_patient_rebooking": true,
      "active": true,
      "created_at": 1712100000,
      "updated_at": 1712100000
    }
  ]
}
```

### Einen Termintyp erstellen

```bash theme={null}
POST /v1/management/scheduling/appointment-types
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField body="name" type="string" required>
  Anzeigename (1–255 Zeichen)
</ParamField>

<ParamField body="meeting_type" type="string" required>
  Terminart. Einer von `CONSULTATION`, `FOLLOW_UP`, `INITIAL`, `REVIEW`,
  `ON_DEMAND`.
</ParamField>

<ParamField body="duration_minutes" type="integer" required>
  Termindauer in Minuten (1–1440)
</ParamField>

<ParamField body="hold_ttl_seconds" type="integer" required>
  Wie lange eine vorläufige Reservierung gilt, bevor sie abläuft, in Sekunden
  (1–86400)
</ParamField>

<ParamField body="booking_min_notice_minutes" type="integer" default="0">
  Standard-Mindestvorlauf, bevor Patienten diese Terminart buchen können, in
  Minuten. Arztspezifische Einstellungen können diesen Wert überschreiben.
</ParamField>

<ParamField body="cancellation_min_notice_minutes" type="integer" default="0">
  Mindestvorlaufzeit für eine Stornierung, in Minuten (≥ 0)
</ParamField>

<ParamField body="rebooking_min_notice_minutes" type="integer" default="0">
  Mindestvorlaufzeit für eine Umbuchung, in Minuten (≥ 0)
</ParamField>

<ParamField body="room_strategy" type="string" required>
  Strategie zur Raumzuweisung. Einer von `persistent_per_provider`,
  `per_appointment`.
</ParamField>

<ParamField body="rebooking_mode" type="string" required>
  Umbuchungsmodus. Einer von `same_doctor_only`,
  `any_doctor_same_organisation`.
</ParamField>

<ParamField body="doctor_assignment_mode" type="string" default="all_available_doctors">
  Steuert, welche Ärzte diese Terminart anbieten können. Nutzen Sie
  `all_available_doctors` für alle Ärzte mit Verfügbarkeit oder
  `selected_doctors_only`, wenn eine aktive arztspezifische Einstellung
  erforderlich sein soll.
</ParamField>

<ParamField body="allow_patient_rebooking" type="boolean" default="false">
  Ob Patienten ihre eigenen Termine dieses Typs umbuchen dürfen
</ParamField>

<ParamField body="active" type="boolean" default="true">
  Ob der Termintyp buchbar ist
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointment-types" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Initial consultation",
    "meeting_type": "CONSULTATION",
    "duration_minutes": 30,
    "hold_ttl_seconds": 900,
    "booking_min_notice_minutes": 10,
    "cancellation_min_notice_minutes": 60,
    "rebooking_min_notice_minutes": 120,
    "room_strategy": "persistent_per_provider",
    "rebooking_mode": "same_doctor_only",
    "doctor_assignment_mode": "all_available_doctors",
    "allow_patient_rebooking": true,
    "active": true
  }'
```

Gibt `201 Created` mit dem erstellten Termintyp zurück (gleiche Struktur wie ein
Listeneintrag).

### Einen Termintyp aktualisieren

```bash theme={null}
PATCH /v1/management/scheduling/appointment-types/{appointment_type_uid}
```

Teilaktualisierung — nur die gesendeten Felder werden geändert. Alle Body-Felder
sind optional und akzeptieren dieselben Werte und Bereiche wie beim Erstellen.

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  Die UID des Termintyps
</ParamField>

<ParamField body="name" type="string">
  Anzeigename (1–255 Zeichen)
</ParamField>

<ParamField body="meeting_type" type="string">
  Einer von `CONSULTATION`, `FOLLOW_UP`, `INITIAL`, `REVIEW`, `ON_DEMAND`
</ParamField>

<ParamField body="duration_minutes" type="integer">
  Termindauer in Minuten (1–1440)
</ParamField>

<ParamField body="hold_ttl_seconds" type="integer">
  Lebensdauer der Reservierung in Sekunden (1–86400)
</ParamField>

<ParamField body="booking_min_notice_minutes" type="integer">
  Standard-Mindestvorlauf für Buchungen in Minuten (≥ 0)
</ParamField>

<ParamField body="cancellation_min_notice_minutes" type="integer">
  Mindestvorlaufzeit für eine Stornierung in Minuten (≥ 0)
</ParamField>

<ParamField body="rebooking_min_notice_minutes" type="integer">
  Mindestvorlaufzeit für eine Umbuchung in Minuten (≥ 0)
</ParamField>

<ParamField body="room_strategy" type="string">
  Einer von `persistent_per_provider`, `per_appointment`
</ParamField>

<ParamField body="rebooking_mode" type="string">
  Einer von `same_doctor_only`, `any_doctor_same_organisation`
</ParamField>

<ParamField body="doctor_assignment_mode" type="string">
  Einer von `all_available_doctors`, `selected_doctors_only`
</ParamField>

<ParamField body="allow_patient_rebooking" type="boolean">
  Ob Patienten ihre eigenen Termine dieses Typs umbuchen dürfen
</ParamField>

<ParamField body="active" type="boolean">
  Ob der Termintyp buchbar ist
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "duration_minutes": 45,
    "active": false
  }'
```

Gibt `200 OK` mit dem aktualisierten Termintyp zurück.

### Einen Termintyp löschen

```bash theme={null}
DELETE /v1/management/scheduling/appointment-types/{appointment_type_uid}
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  Die UID des Termintyps
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001" \
  -H "X-API-Key: your-api-key-here"
```

Gibt bei Erfolg `204 No Content` zurück.

## Erinnerungen

Erinnerungen werden pro Termintyp konfiguriert und benachrichtigen eine
Empfängerrolle eine feste Anzahl von Minuten vor Beginn des Termins.

### Erinnerungen auflisten

```bash theme={null}
GET /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders
```

**Erforderliche Berechtigung:** `scheduling:read`

<ParamField path="appointment_type_uid" type="string" required>
  Die UID des Termintyps
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders" \
  -H "X-API-Key: your-api-key-here"
```

#### Antwort

```json theme={null}
{
  "data": [
    {
      "uid": "rem-001",
      "appointment_type_uid": "apt-001",
      "recipient_role": "patient",
      "minutes_before": 1440,
      "send_email": true,
      "send_sms": false,
      "active": true
    }
  ]
}
```

#### Antwortfelder

| Feld                          | Typ     | Beschreibung                                           |
| ----------------------------- | ------- | ------------------------------------------------------ |
| `data[].uid`                  | string  | UID der Erinnerung                                     |
| `data[].appointment_type_uid` | string  | UID des übergeordneten Termintyps                      |
| `data[].recipient_role`       | string  | Wer benachrichtigt wird (`patient`, `doctor`, `admin`) |
| `data[].minutes_before`       | integer | Minuten vor dem Termin zum Senden                      |
| `data[].send_email`           | boolean | Ob eine E-Mail gesendet wird                           |
| `data[].send_sms`             | boolean | Ob eine SMS gesendet wird                              |
| `data[].active`               | boolean | Ob die Erinnerung aktiv ist                            |

### Eine Erinnerung erstellen

```bash theme={null}
POST /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  Die UID des Termintyps
</ParamField>

<ParamField body="recipient_role" type="string" required>
  Wer benachrichtigt wird. Einer von `patient`, `doctor`, `admin`.
</ParamField>

<ParamField body="minutes_before" type="integer" required>
  Minuten vor dem Termin zum Senden der Erinnerung (1–86400, also bis zu 60
  Tage)
</ParamField>

<ParamField body="send_email" type="boolean" default="false">
  Ob eine E-Mail gesendet wird
</ParamField>

<ParamField body="send_sms" type="boolean" default="false">
  Ob eine SMS gesendet wird
</ParamField>

<ParamField body="active" type="boolean" default="true">
  Ob die Erinnerung aktiv ist
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_role": "patient",
    "minutes_before": 1440,
    "send_email": true,
    "send_sms": false,
    "active": true
  }'
```

Gibt `201 Created` mit der erstellten Erinnerung zurück (gleiche Struktur wie ein
Listeneintrag).

### Eine Erinnerung aktualisieren

```bash theme={null}
PATCH /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}
```

Teilaktualisierung — nur die gesendeten Felder werden geändert.

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  Die UID des Termintyps
</ParamField>

<ParamField path="reminder_uid" type="string" required>
  Die UID der Erinnerung
</ParamField>

<ParamField body="recipient_role" type="string">
  Einer von `patient`, `doctor`, `admin`
</ParamField>

<ParamField body="minutes_before" type="integer">
  Minuten vor dem Termin zum Senden der Erinnerung (1–86400)
</ParamField>

<ParamField body="send_email" type="boolean">
  Ob eine E-Mail gesendet wird
</ParamField>

<ParamField body="send_sms" type="boolean">
  Ob eine SMS gesendet wird
</ParamField>

<ParamField body="active" type="boolean">
  Ob die Erinnerung aktiv ist
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders/rem-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "minutes_before": 60,
    "send_sms": true
  }'
```

Gibt `200 OK` mit der aktualisierten Erinnerung zurück.

### Eine Erinnerung löschen

```bash theme={null}
DELETE /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  Die UID des Termintyps
</ParamField>

<ParamField path="reminder_uid" type="string" required>
  Die UID der Erinnerung
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders/rem-001" \
  -H "X-API-Key: your-api-key-here"
```

Gibt bei Erfolg `204 No Content` zurück.

## Verfügbarkeitsregeln

Verfügbarkeitsregeln definieren die wiederkehrenden wöchentlichen Buchungsfenster
eines Arztes. Zeiten werden als Minuten ab Mitternacht angegeben (zum Beispiel
ist `540` 09:00 Uhr und `1020` 17:00 Uhr).

### Verfügbarkeitsregeln auflisten

```bash theme={null}
GET /v1/management/scheduling/doctors/{doctor_uid}/availability-rules
```

**Erforderliche Berechtigung:** `scheduling:read`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules" \
  -H "X-API-Key: your-api-key-here"
```

#### Antwort

```json theme={null}
{
  "data": [
    {
      "uid": "rule-001",
      "doctor_uid": "doc-456",
      "weekday": 0,
      "start_time": 540,
      "end_time": 1020,
      "buffer_minutes": 10,
      "valid_from": null,
      "valid_until": null,
      "active": true,
      "appointment_type_uid": null
    }
  ]
}
```

#### Antwortfelder

| Feld                          | Typ             | Beschreibung                                                                                                                                                                                                |
| ----------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data[].uid`                  | string          | UID der Verfügbarkeitsregel                                                                                                                                                                                 |
| `data[].doctor_uid`           | string          | Arzt-UID                                                                                                                                                                                                    |
| `data[].weekday`              | integer         | Wochentag (0 = Montag … 6 = Sonntag)                                                                                                                                                                        |
| `data[].start_time`           | integer         | Beginn des Fensters, in Minuten ab Mitternacht (0–1440)                                                                                                                                                     |
| `data[].end_time`             | integer         | Ende des Fensters, in Minuten ab Mitternacht (0–1440)                                                                                                                                                       |
| `data[].buffer_minutes`       | integer         | Puffer zwischen Terminen, in Minuten                                                                                                                                                                        |
| `data[].valid_from`           | integer \| null | Optionaler Gültigkeitsbeginn (Unix-Zeitstempel)                                                                                                                                                             |
| `data[].valid_until`          | integer \| null | Optionales Gültigkeitsende (Unix-Zeitstempel)                                                                                                                                                               |
| `data[].active`               | boolean         | Ob die Regel aktiv ist                                                                                                                                                                                      |
| `data[].appointment_type_uid` | string \| null  | Termintyp, auf den diese Regel beschränkt ist, oder `null` für alle Termintypen. Siehe [Verfügbarkeit auf einen einzelnen Termintyp beschränken](#verfügbarkeit-auf-einen-einzelnen-termintyp-beschränken). |

### Eine Verfügbarkeitsregel erstellen

```bash theme={null}
POST /v1/management/scheduling/doctors/{doctor_uid}/availability-rules
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

<ParamField body="weekday" type="integer" required>
  Wochentag (0 = Montag … 6 = Sonntag)
</ParamField>

<ParamField body="start_time" type="integer" required>
  Beginn des Fensters, in Minuten ab Mitternacht (0–1440)
</ParamField>

<ParamField body="end_time" type="integer" required>
  Ende des Fensters, in Minuten ab Mitternacht (0–1440)
</ParamField>

<ParamField body="buffer_minutes" type="integer" default="0">
  Puffer zwischen Terminen, in Minuten (≥ 0)
</ParamField>

<ParamField body="valid_from" type="integer">
  Optionaler Gültigkeitsbeginn (Unix-Zeitstempel)
</ParamField>

<ParamField body="valid_until" type="integer">
  Optionales Gültigkeitsende (Unix-Zeitstempel)
</ParamField>

<ParamField body="active" type="boolean" default="true">
  Ob die Regel aktiv ist
</ParamField>

<ParamField body="appointment_type_uid" type="string">
  Optional. Weglassen oder auf `null` setzen, um die Regel auf alle Termintypen
  anzuwenden. Setzen Sie den Wert, um die Regel auf einen einzelnen Termintyp zu
  beschränken. Siehe [Verfügbarkeit auf einen einzelnen Termintyp
  beschränken](#verfügbarkeit-auf-einen-einzelnen-termintyp-beschränken).
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "weekday": 0,
    "start_time": 540,
    "end_time": 1020,
    "buffer_minutes": 10,
    "active": true
  }'
```

Gibt `201 Created` mit der erstellten Verfügbarkeitsregel zurück (gleiche Struktur
wie ein Listeneintrag).

### Eine Verfügbarkeitsregel aktualisieren

```bash theme={null}
PATCH /v1/management/scheduling/doctors/{doctor_uid}/availability-rules/{rule_uid}
```

Teilaktualisierung — nur die gesendeten Felder werden geändert. Um eine
vorhandene Gültigkeitsgrenze zu entfernen, senden Sie das entsprechende
`clear_*`-Flag anstelle eines Werts.

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

<ParamField path="rule_uid" type="string" required>
  Die UID der Verfügbarkeitsregel
</ParamField>

<ParamField body="weekday" type="integer">
  Wochentag (0 = Montag … 6 = Sonntag)
</ParamField>

<ParamField body="start_time" type="integer">
  Beginn des Fensters, in Minuten ab Mitternacht (0–1440)
</ParamField>

<ParamField body="end_time" type="integer">
  Ende des Fensters, in Minuten ab Mitternacht (0–1440)
</ParamField>

<ParamField body="buffer_minutes" type="integer">
  Puffer zwischen Terminen, in Minuten (≥ 0)
</ParamField>

<ParamField body="valid_from" type="integer">
  Gültigkeitsbeginn setzen (Unix-Zeitstempel)
</ParamField>

<ParamField body="valid_until" type="integer">
  Gültigkeitsende setzen (Unix-Zeitstempel)
</ParamField>

<ParamField body="active" type="boolean">
  Ob die Regel aktiv ist
</ParamField>

<ParamField body="clear_valid_from" type="boolean" default="false">
  Vorhandene `valid_from`-Grenze entfernen (auf null setzen)
</ParamField>

<ParamField body="clear_valid_until" type="boolean" default="false">
  Vorhandene `valid_until`-Grenze entfernen (auf null setzen)
</ParamField>

<ParamField body="appointment_type_uid" type="string">
  Die Regel auf einen einzelnen Termintyp beschränken. Siehe [Verfügbarkeit auf
  einen einzelnen Termintyp
  beschränken](#verfügbarkeit-auf-einen-einzelnen-termintyp-beschränken).
</ParamField>

<ParamField body="clear_appointment_type" type="boolean" default="false">
  Die vorhandene Termintyp-Beschränkung entfernen, sodass die Regel wieder für alle
  Termintypen gilt
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules/rule-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": 960,
    "clear_valid_until": true
  }'
```

Gibt `200 OK` mit der aktualisierten Verfügbarkeitsregel zurück.

### Eine Verfügbarkeitsregel löschen

```bash theme={null}
DELETE /v1/management/scheduling/doctors/{doctor_uid}/availability-rules/{rule_uid}
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

<ParamField path="rule_uid" type="string" required>
  Die UID der Verfügbarkeitsregel
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules/rule-001" \
  -H "X-API-Key: your-api-key-here"
```

Gibt bei Erfolg `204 No Content` zurück.

## Verfügbarkeits-Datumsausnahmen

Datumsausnahmen legen die Verfügbarkeit eines Arztes für ein **bestimmtes
Kalenderdatum** fest und ersetzen an diesem Datum seine wiederkehrenden
Wochenregeln. Jede Ausnahme ist entweder ein **Zeitfenster** (individuelle Zeiten
an diesem Tag) oder ein **freier Tag** (keine buchbaren Slots an diesem Tag). An
jedem Datum mit mindestens einer Ausnahme werden die wiederkehrenden Regeln des
Arztes unterdrückt und es gelten nur die Ausnahmen.

* `date` ist der **UTC-Mitternachts-Unix-Zeitstempel** des Kalenderdatums — ein
  Vielfaches von `86400` (zum Beispiel ist `1749427200` der 09.06.2025 00:00:00
  UTC).
* `start_time` / `end_time` sind Minuten ab Mitternacht (zum Beispiel ist `480`
  08:00 Uhr und `720` 12:00 Uhr). Für einen freien Tag sind beide `null`.

### Datumsausnahmen auflisten

```bash theme={null}
GET /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides
```

**Erforderliche Berechtigung:** `scheduling:read`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

<ParamField query="from" type="integer">
  Nur Ausnahmen an oder nach diesem UTC-Mitternachts-Zeitstempel zurückgeben
</ParamField>

<ParamField query="to" type="integer">
  Nur Ausnahmen an oder vor diesem UTC-Mitternachts-Zeitstempel zurückgeben
</ParamField>

<ParamField query="page" type="integer" default="0">
  Nullbasierte Seitennummer
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Seitengröße (maximal 200)
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides?from=1749427200&limit=50" \
  -H "X-API-Key: your-api-key-here"
```

#### Antwort

Die Liste ist paginiert, und eine einzelne Anfrage darf **höchstens \~6 Monate**
umfassen. Lassen Sie `from` und `to` weg für „ab heute“; geben Sie einen Wert an,
um das Fenster zu verankern, oder beide für einen Bereich — eine Spanne von mehr
als \~6 Monaten wird am `to`-Ende gekürzt. `totalRegistries` ist die Anzahl der zum
(gekürzten) Fenster passenden Ausnahmen und `totalPages` ist
`ceil(totalRegistries / limit)`.

```json theme={null}
{
  "data": [
    {
      "uid": "ovr-001",
      "doctor_uid": "doc-456",
      "date": 1749427200,
      "start_time": 480,
      "end_time": 720,
      "buffer_minutes": 0,
      "appointment_type_uid": null
    },
    {
      "uid": "ovr-002",
      "doctor_uid": "doc-456",
      "date": 1749513600,
      "start_time": null,
      "end_time": null,
      "buffer_minutes": 0,
      "appointment_type_uid": null
    }
  ],
  "totalRegistries": 2,
  "totalPages": 1
}
```

#### Antwortfelder

| Feld                          | Typ             | Beschreibung                                                                                                                                                                                                   |
| ----------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data[].uid`                  | string          | UID der Datumsausnahme                                                                                                                                                                                         |
| `data[].doctor_uid`           | string          | Arzt-UID                                                                                                                                                                                                       |
| `data[].date`                 | integer         | UTC-Mitternachts-Zeitstempel des Kalenderdatums (ein Vielfaches von 86400)                                                                                                                                     |
| `data[].start_time`           | integer \| null | Beginn des Fensters, in Minuten ab Mitternacht (0–1440); `null` bei freiem Tag                                                                                                                                 |
| `data[].end_time`             | integer \| null | Ende des Fensters, in Minuten ab Mitternacht (0–1440); `null` bei freiem Tag                                                                                                                                   |
| `data[].buffer_minutes`       | integer         | Puffer zwischen Terminen, in Minuten                                                                                                                                                                           |
| `data[].appointment_type_uid` | string \| null  | Termintyp, auf den diese Ausnahme beschränkt ist, oder `null` für alle Termintypen. Siehe [Verfügbarkeit auf einen einzelnen Termintyp beschränken](#verfügbarkeit-auf-einen-einzelnen-termintyp-beschränken). |

### Eine Datumsausnahme erstellen

```bash theme={null}
POST /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

<ParamField body="date" type="integer" required>
  UTC-Mitternachts-Zeitstempel des Kalenderdatums (ein Vielfaches von 86400)
</ParamField>

<ParamField body="day_off" type="boolean" default="false">
  Wenn true, ist das Datum vollständig nicht verfügbar — `start_time`/`end_time` weglassen
</ParamField>

<ParamField body="start_time" type="integer">
  Beginn des Fensters, in Minuten ab Mitternacht (0–1440). Erforderlich, sofern `day_off` nicht true ist
</ParamField>

<ParamField body="end_time" type="integer">
  Ende des Fensters, in Minuten ab Mitternacht (0–1440). Erforderlich, sofern `day_off` nicht true ist
</ParamField>

<ParamField body="buffer_minutes" type="integer" default="0">
  Puffer zwischen Terminen, in Minuten (≥ 0)
</ParamField>

<ParamField body="appointment_type_uid" type="string">
  Optional. Weglassen oder auf `null` setzen für eine Ausnahme, die für alle
  Termintypen gilt. Setzen Sie den Wert, um die Ausnahme (auch einen freien Tag)
  auf einen einzelnen Termintyp zu beschränken. Siehe [Verfügbarkeit auf einen
  einzelnen Termintyp
  beschränken](#verfügbarkeit-auf-einen-einzelnen-termintyp-beschränken).
</ParamField>

#### Beispielanfrage — individuelle Zeiten

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "date": 1749427200,
    "start_time": 480,
    "end_time": 720
  }'
```

#### Beispielanfrage — freier Tag

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "date": 1749513600,
    "day_off": true
  }'
```

Gibt `201 Created` mit der erstellten Datumsausnahme zurück (gleiche Struktur wie
ein Listeneintrag). Das Hinzufügen eines freien Tags entfernt vorhandene Fenster
an diesem Datum, und das Hinzufügen eines Fensters entfernt eine vorhandene
Freier-Tag-Markierung.

### Eine Datumsausnahme aktualisieren

```bash theme={null}
PATCH /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides/{override_uid}
```

Teilaktualisierung — nur die gesendeten Felder werden geändert. Senden Sie
`day_off: true`, um das Datum in einen freien Tag umzuwandeln (das Fenster wird
entfernt).

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

<ParamField path="override_uid" type="string" required>
  Die UID der Datumsausnahme
</ParamField>

<ParamField body="date" type="integer">
  UTC-Mitternachts-Zeitstempel des Kalenderdatums (ein Vielfaches von 86400)
</ParamField>

<ParamField body="day_off" type="boolean" default="false">
  Wenn true, das Fenster entfernen und als freien Tag markieren
</ParamField>

<ParamField body="start_time" type="integer">
  Beginn des Fensters, in Minuten ab Mitternacht (0–1440)
</ParamField>

<ParamField body="end_time" type="integer">
  Ende des Fensters, in Minuten ab Mitternacht (0–1440)
</ParamField>

<ParamField body="buffer_minutes" type="integer">
  Puffer zwischen Terminen, in Minuten (≥ 0)
</ParamField>

<ParamField body="appointment_type_uid" type="string">
  Die Ausnahme auf einen einzelnen Termintyp beschränken. Siehe [Verfügbarkeit auf
  einen einzelnen Termintyp
  beschränken](#verfügbarkeit-auf-einen-einzelnen-termintyp-beschränken).
</ParamField>

<ParamField body="clear_appointment_type" type="boolean" default="false">
  Die vorhandene Termintyp-Beschränkung entfernen, sodass die Ausnahme wieder für
  alle Termintypen gilt
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides/ovr-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": 540,
    "end_time": 660
  }'
```

Gibt `200 OK` mit der aktualisierten Datumsausnahme zurück.

### Eine Datumsausnahme löschen

```bash theme={null}
DELETE /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides/{override_uid}
```

**Erforderliche Berechtigung:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  Die Arzt-UID
</ParamField>

<ParamField path="override_uid" type="string" required>
  Die UID der Datumsausnahme
</ParamField>

#### Beispielanfrage

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides/ovr-001" \
  -H "X-API-Key: your-api-key-here"
```

Gibt bei Erfolg `204 No Content` zurück. Für das Datum gilt dann wieder die
wiederkehrende Verfügbarkeit des Arztes.

## Verfügbarkeit auf einen einzelnen Termintyp beschränken

Sowohl Verfügbarkeitsregeln als auch Datumsausnahmen akzeptieren ein optionales
`appointment_type_uid`. Damit kann ein Arzt unterschiedliche Zeiten für
unterschiedliche Terminarten anbieten — zum Beispiel Video-Nachsorgetermine nur
nachmittags, während für Präsenz-Erstgespräche die allgemeinen Vormittagszeiten des
Arztes gelten.

* **`null` (der Standard) bedeutet alle Termintypen.** Wenn Sie
  `appointment_type_uid` weglassen oder `null` senden, verhält sich die Regel oder
  Ausnahme wie bisher und gilt für jeden Termintyp. Bestehende Regeln und Ausnahmen
  bleiben unverändert.
* **Eine beschränkte Regel ersetzt die allgemeinen Zeiten des Arztes für diesen
  Typ, pro Wochentag.** An einem Wochentag, an dem der Arzt mindestens eine auf
  einen bestimmten Typ beschränkte Regel hat, verwendet dieser Typ an diesem
  Wochentag nur die beschränkten Regeln; die allgemeinen Regeln (für alle Typen)
  werden für diesen Typ an diesem Wochentag ignoriert. Wochentage ohne beschränkte
  Regel für den Typ greifen auf die allgemeinen Zeiten des Arztes zurück.
* **Eine beschränkte Ausnahme ersetzt die allgemeine Ausnahme des Arztes für diesen
  Typ, pro Datum.** An einem Datum, an dem der Arzt eine auf einen bestimmten Typ
  beschränkte Ausnahme hat, verwendet dieser Typ an diesem Datum nur die
  beschränkte Ausnahme; an Daten ohne beschränkte Ausnahme greift der Typ auf die
  allgemeine Ausnahme zurück (oder, falls es keine gibt, auf die wiederkehrenden
  Regeln).
* **Ein allgemeiner freier Tag unterdrückt jeden Termintyp** — es sei denn, dieser
  Typ hat eine eigene Ausnahme für das Datum. Um einen Termintyp an einem ansonsten
  geschlossenen Tag buchbar zu halten, fügen Sie für dasselbe Datum eine auf diesen
  Typ beschränkte Datumsausnahme hinzu.
* Der Termintyp muss zur selben Organisation gehören wie der Arzt; andernfalls wird
  die Anfrage als nicht gefunden behandelt.

Die UID des Termintyps wird bei jeder Regel und Ausnahme als
`appointment_type_uid` zurückgegeben (`null`, wenn keine Beschränkung gesetzt ist).

#### Beispielanfrage — Nachmittagszeiten für einen Termintyp

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "weekday": 2,
    "start_time": 840,
    "end_time": 960,
    "appointment_type_uid": "apt-001"
  }'
```

#### Antwort

```json theme={null}
{
  "uid": "rule-001",
  "doctor_uid": "doc-456",
  "weekday": 2,
  "start_time": 840,
  "end_time": 960,
  "buffer_minutes": 0,
  "valid_from": null,
  "valid_until": null,
  "active": true,
  "appointment_type_uid": "apt-001"
}
```

#### Eine Regel oder Ausnahme auf alle Termintypen zurücksetzen

Senden Sie an einem der beiden `PATCH`-Endpunkte `clear_appointment_type: true`,
um die Beschränkung zu entfernen, sodass die Regel oder Ausnahme wieder für alle
Termintypen gilt:

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules/rule-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "clear_appointment_type": true
  }'
```