> ## 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.

# Berechtigungen

> Vollständige Referenz der API-Schlüssel-Berechtigungen und ihrer zugehörigen Endpoints

# Berechtigungen

Jeder RxScale API-Schlüssel verfügt über eine Reihe von Berechtigungen, die steuern, auf welche Endpoints der Schlüssel zugreifen kann. Diese Seite bietet eine vollständige Referenz aller verfügbaren Berechtigungen, gruppiert nach API.

## Funktionsweise der Berechtigungen

Beim Erstellen eines API-Schlüssels weisen Sie ihm eine oder mehrere Berechtigungen zu. Jeder API-Endpoint erfordert eine bestimmte Berechtigung -- fehlt dem Schlüssel diese Berechtigung, gibt die Anfrage `403 Permission Denied` zurück.

```bash theme={null}
# Ein Schlüssel mit nur `orders_read` kann Bestellungen auflisten...
curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/" \
  -H "X-API-Key: your-api-key-here"

# ...aber keinen Bestellstatus aktualisieren (erfordert `orders_write`)
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/{uid}/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"status": "in-progress"}'
# Gibt 403 zurück: Permission denied
```

<Note>
  Berechtigungen werden bei der Erstellung des API-Schlüssels festgelegt. Kontaktieren Sie Ihren RxScale-Kundenbetreuer, um Berechtigungen eines bestehenden Schlüssels zu ändern oder zu erweitern.
</Note>

## External Pharmacy API

Die External Pharmacy API verwendet apothekenspezifische API-Schlüssel. Berechtigungen sind einfache Zeichenketten, die zur Laufzeit geprüft werden.

| Berechtigung         | Typ       | Endpoints                                                                       |
| -------------------- | --------- | ------------------------------------------------------------------------------- |
| `orders_read`        | Lesen     | `GET /pharmacy_orders/` -- Apothekenbestellungen auflisten                      |
|                      |           | `GET /pharmacy_orders/{uid}` -- Bestelldetails abrufen                          |
| `orders_write`       | Schreiben | `PATCH /pharmacy_orders/{uid}/status` -- Bestellstatus aktualisieren            |
|                      |           | `PATCH /pharmacy_orders/{uid}/complete_order` -- Bestellung abschließen         |
| `stock_read`         | Lesen     | `GET /pharmacy_skus/` -- Apotheken-SKUs auflisten                               |
| `stock_write`        | Schreiben | `PATCH /pharmacy_skus/{uid}/stock` -- Lagerbestand aktualisieren                |
| `pharmacy_sku_write` | Schreiben | `PATCH /pharmacy_skus/{uid}` -- SKU aktualisieren (Preis, Bestand, External-ID) |
|                      |           | `PATCH /pharmacy_skus/{uid}/stock` -- Lagerbestand aktualisieren                |
|                      |           | `PATCH /pharmacy_skus/{uid}/external_id` -- External-ID aktualisieren           |
| `webhooks_read`      | Lesen     | `GET /webhooks/` -- Webhook-Abonnements auflisten                               |
| `webhooks_write`     | Schreiben | `POST /webhooks/` -- Webhook registrieren                                       |
|                      |           | `DELETE /webhooks/{uid}` -- Webhook entfernen                                   |

<Info>
  Der Endpoint `PATCH /pharmacy_skus/{uid}/stock` akzeptiert entweder `stock_write` oder `pharmacy_sku_write`. Wenn Ihr Schlüssel eine der beiden Berechtigungen besitzt, ist die Anfrage erfolgreich. Alle anderen SKU-Schreib-Endpoints erfordern ausdrücklich `pharmacy_sku_write`.
</Info>

## Management API

Die Management API verwendet organisationsbezogene API-Schlüssel. Berechtigungen folgen der Namenskonvention `ressource:aktion` und werden über den `@require_api_key_permission`-Dekorator durchgesetzt.

| Berechtigung                          | Typ       | Endpoints                                                                                                         |
| ------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `order:read`                          | Lesen     | `GET /orders/{uid}` -- Bestelldetails abrufen                                                                     |
| `prescription:read`                   | Lesen     | `GET /prescriptions/{uid}` -- Rezeptdetails abrufen                                                               |
|                                       |           | Schaltet Rezeptdaten in Bestellantworten frei (in Kombination mit `order:read`)                                   |
| `prescription:external_sign`          | Schreiben | `POST /prescriptions/{uid}/render` -- Asynchrones PDF-Rendering anstoßen                                          |
|                                       |           | `POST /prescriptions/{uid}/external-sign` -- Rezept als `EXTERNALLY_SIGNED` markieren und an Apotheke übermitteln |
| `product:read`                        | Lesen     | `GET /products/` -- Produkte mit verknüpften SKU- und Shop-Daten auflisten                                        |
| `doctor:read`                         | Lesen     | `GET /doctors/` -- Ärzte auflisten                                                                                |
| `doctor_statistics:read`              | Lesen     | `GET /doctors/{uid}/statistics` -- Rezeptstatistiken eines Arztes abrufen                                         |
| `patient:read`                        | Lesen     | `GET /patients/?email={email}` -- Patient nach E-Mail suchen                                                      |
|                                       |           | `GET /patients/{uid}` -- Patientendetails abrufen                                                                 |
|                                       |           | `GET /patients/{uid}/intent/{intent}` -- Intent-Rückgabecode abrufen                                              |
| `waiting_room:read`                   | Lesen     | `GET /waiting-room/{uid}/status` -- Status eines Wartezimmereintrags abrufen                                      |
| `waiting_room:write`                  | Schreiben | `POST /waiting-room/register` -- Patient im Wartezimmer anmelden                                                  |
|                                       |           | `DELETE /waiting-room/{uid}` -- Wartezimmeranmeldung stornieren                                                   |
| `wallet_pass_template:read`           | Lesen     | `GET /wallet-passes/templates` -- Wallet-Pass-Vorlagen auflisten                                                  |
| `wallet_pass:read`                    | Lesen     | `GET /wallet-passes/` -- Wallet-Pässe auflisten                                                                   |
| `wallet_pass_push_notification:write` | Schreiben | `POST /wallet-passes/push-notifications` -- Push-Benachrichtigungen senden                                        |
| `notification_subscription:read`      | Lesen     | `GET /notification-subscriptions/` -- Webhook-Abonnements auflisten                                               |
| `notification_subscription:write`     | Schreiben | `POST /notification-subscriptions/` -- Webhook-Abonnement erstellen                                               |
|                                       |           | `DELETE /notification-subscriptions/` -- Webhook-Abonnement entfernen                                             |
|                                       |           | `POST /notification-subscriptions/test` -- Test-Webhook senden                                                    |

<Warning>
  Wenn ein API-Schlüssel `order:read`, aber nicht `prescription:read` besitzt, werden Rezeptdaten aus den Bestellantworten entfernt. Fügen Sie `prescription:read` hinzu, um vollständige Rezeptdetails in den Bestelldaten zu erhalten.
</Warning>

### Benachrichtigungs-Abonnements

Die Endpoints für Benachrichtigungs-Abonnements (`/notification-subscriptions/`) der Management API erfordern die granularen `notification_subscription`-Berechtigungen. Das Auflisten von Abonnements erfordert `notification_subscription:read`; Erstellen, Entfernen und das Senden von Test-Webhooks erfordern `notification_subscription:write`.

| Endpoint                           | Methode  | Beschreibung                  | Berechtigung                      |
| ---------------------------------- | -------- | ----------------------------- | --------------------------------- |
| `/notification-subscriptions/`     | `GET`    | Webhook-Abonnements auflisten | `notification_subscription:read`  |
| `/notification-subscriptions/`     | `POST`   | Webhook-Abonnement erstellen  | `notification_subscription:write` |
| `/notification-subscriptions/`     | `DELETE` | Webhook-Abonnement entfernen  | `notification_subscription:write` |
| `/notification-subscriptions/test` | `POST`   | Test-Webhook senden           | `notification_subscription:write` |

<Note>
  Schlüssel, die vor Einführung dieser Berechtigungen erstellt wurden, benötigen `notification_subscription:read` / `notification_subscription:write`, bevor sie diese Endpoints wieder aufrufen können. Kontaktieren Sie Ihren RxScale-Kundenbetreuer, um einen bestehenden Schlüssel zu aktualisieren.
</Note>

## Public API

Die Public API verwendet organisationsbezogene API-Schlüssel (mit optionaler Unterstützung des Legacy-Headers `X-RxScale-Authorization`). Sie ist für Telemedizin-Anbieter konzipiert, um Produkte abzufragen und Checkouts zu erstellen.

| Berechtigung                   | Typ       | Endpoints                                                                                     |
| ------------------------------ | --------- | --------------------------------------------------------------------------------------------- |
| `product:read`                 | Lesen     | `GET /products/{shop_identifier}` -- Produkte eines Shops auflisten                           |
|                                |           | `POST /products/{shop_identifier}/live-stock` -- Produktverfügbarkeit vor dem Checkout prüfen |
| `order:read`                   | Lesen     | `GET /orders/{shop_identifier}` -- Bestellstatus nach Rezept-UIDs abfragen                    |
| `create_prescription_checkout` | Schreiben | `POST /prescriptions/{shop_identifier}` -- Rezeptbasierten Checkout erstellen                 |
| `create_treatment_checkout`    | Schreiben | `POST /treatments/{shop_identifier}` -- Behandlungsbasierten Checkout erstellen               |

<Note>
  Die Berechtigungen `product:read` und `order:read` werden zwischen der Management API und der Public API geteilt. Wenn ein Schlüssel `product:read` besitzt, kann er sowohl `GET /products/` der Management API als auch `GET /products/{shop_identifier}` der Public API nutzen (vorausgesetzt, der Schlüssel ist für beide gültig).
</Note>

## Auswahl der richtigen Berechtigungen

Befolgen Sie das **Prinzip der minimalen Berechtigung** -- gewähren Sie nur die Berechtigungen, die Ihre Integration tatsächlich benötigt.

### Häufige Szenarien

| Anwendungsfall                                            | Empfohlene Berechtigungen                                                                  |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Apothekenbestellverwaltungssystem                         | `orders_read`, `orders_write`                                                              |
| Apothekenbestandssynchronisation                          | `stock_read`, `pharmacy_sku_write`                                                         |
| Apothekenbestell- und Bestandsverwaltung                  | `orders_read`, `orders_write`, `stock_read`, `pharmacy_sku_write`                          |
| Apotheke mit Webhook-Benachrichtigungen                   | Zusätzlich `webhooks_read`, `webhooks_write` zu den obigen                                 |
| Telemedizin-Anbieter Checkout-Flow                        | `product:read`, `create_prescription_checkout`                                             |
| Telemedizin-Anbieter mit Bestellverfolgung                | `product:read`, `create_prescription_checkout`, `order:read`                               |
| Organisations-Analyse-Dashboard                           | `order:read`, `prescription:read`, `doctor:read`, `doctor_statistics:read`, `patient:read` |
| Wartezimmer-Integration                                   | `waiting_room:read`, `waiting_room:write`, `patient:read`                                  |
| Wallet-Pass-Verwaltung                                    | `wallet_pass_template:read`, `wallet_pass:read`, `wallet_pass_push_notification:write`     |
| Organisations-Webhook-Benachrichtigungen (Management API) | `notification_subscription:read`, `notification_subscription:write`                        |

### Tipps

* **Lesen und Schreiben trennen** -- Wenn Ihre Integration nur Daten anzeigen muss, fordern Sie ausschließlich Leseberechtigungen an.
* **Dedizierte Schlüssel verwenden** -- Erstellen Sie separate API-Schlüssel für verschiedene Systeme oder Umgebungen, anstatt einen einzigen Schlüssel mit allen Berechtigungen zu teilen.
* **Regelmäßig überprüfen** -- Prüfen Sie Ihre API-Schlüssel regelmäßig und widerrufen Sie nicht mehr verwendete Schlüssel.
* **External Pharmacy API vs. Management API** -- Apothekenspezifische Integrationen sollten die External Pharmacy API mit Apotheken-API-Schlüsseln verwenden. Organisationsweite Integrationen sollten die Management API mit Management-API-Schlüsseln verwenden.