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

# Apothekenbestellungen

> Apothekenbestellungen auflisten, anzeigen und Status aktualisieren

# Apothekenbestellungen

Verwalten Sie Apothekenbestellungen — sehen Sie eingehende Rezeptbestellungen ein und aktualisieren Sie deren Status während der Bearbeitung.

## Bestellungen auflisten

<ParamField query="page" type="integer" default="0">
  Seitennummer (0-indiziert)
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Anzahl der Einträge pro Seite (max. 200)
</ParamField>

<ParamField query="status" type="string">
  Nach Status filtern (z. B. `waiting for pharmacy`, `on-hold`, `in-progress`, `completed`)
</ParamField>

<ParamField query="search" type="string">
  Suchbegriff. Suche ohne Berücksichtigung der Groß-/Kleinschreibung als Substring nach Shop-Bestellname (z. B. `#1234`), Apotheken-Bestellname, Patientenname, Bestell-UID und Apotheken-Bestell-UID.
</ParamField>

<ParamField query="pharmacy_uid" type="string">
  Erforderlich für gruppenweite API-Schlüssel
</ParamField>

```bash theme={null}
GET /v1/external_pharmacy_api/pharmacy_orders/
```

### Antwort

```json theme={null}
{
  "data": [
    {
      "uid": "po-abc123",
      "status": "waiting for pharmacy",
      "name": "#1001",
      "shop_order_name": "#1234",
      "external_status": "OPEN",
      "pharmacy": {
        "uid": "ph-xyz",
        "display_name": "City Pharmacy"
      },
      "order": {
        "uid": "ord-123",
        "delivery_address": {
          "first_name": "Max",
          "last_name": "Mustermann",
          "street": "Hauptstr.",
          "house_number": "1",
          "zip_code": "10115",
          "city": "Berlin",
          "country": "Germany",
          "additional_address": null,
          "province": null
        },
        "invoice_address": {
          "first_name": "Max",
          "last_name": "Mustermann",
          "street": "Hauptstr.",
          "house_number": "1",
          "zip_code": "10115",
          "city": "Berlin",
          "country": "Germany",
          "additional_address": null,
          "province": null
        },
        "priority": 5
      },
      "order_items": [
        {
          "uid": "oi-789",
          "amount": 1,
          "sku": {
            "uid": "sku-456",
            "display_name": "Medication X 100mg",
            "pzn": "12345678"
          },
          "total_paid_amount": 1299
        }
      ],
      "shop_shipping_methods": [
        {
          "uid": "shop-shipping-method-uid",
          "display_name": "DHL Standard",
          "external_id": "shopify-standard",
          "pharmacy_mapping": {
            "pharmacy_uid": "pharmacy-uid",
            "shipping_method_identifier_for_pharmacy": "DHL_STANDARD"
          }
        }
      ],
      "shipping_costs_amount": 499,
      "shipping_costs_currency": "EUR"
    }
  ],
  "totalRegistries": 42,
  "totalPages": 1
}
```

### Felder der Bestellantwort

<ResponseField name="shop_order_name" type="string | null">
  Lesbarer Shop-Bestellname von der ursprünglichen Verkaufsplattform (z. B. `#1234`). `null` für Bestellungen ohne verknüpfte Shop-Bestellung.
</ResponseField>

<ResponseField name="shop_shipping_methods" type="array">
  Shop-Versandarten, die mit der verbundenen Shop-Bestellung verknüpft sind.
  Jeder Eintrag enthält die Shop-Versandart (`uid`, `display_name`,
  `external_id`) und die apothekenspezifische Zuordnung, sofern sie konfiguriert
  wurde.
</ResponseField>

<ResponseField name="shop_shipping_methods[].pharmacy_mapping" type="object | null">
  Apothekenspezifische Zuordnung für diese Shop-Versandart. Wenn vorhanden,
  enthält sie `pharmacy_uid` und `shipping_method_identifier_for_pharmacy`.
</ResponseField>

<ResponseField name="shipping_costs_amount" type="integer | null">
  Versandkosten in Cent, zum Beispiel `499` für EUR 4,99. Dieser Wert ist von
  den Preisen der Produktpositionen getrennt.
</ResponseField>

<ResponseField name="shipping_costs_currency" type="string | null">
  ISO-Währungscode der Versandkosten, zum Beispiel `EUR`.
</ResponseField>

<ResponseField name="order.priority" type="integer">
  Prioritätshinweis für die bevorzugte Bearbeitung. Höher = dringender. `0` bedeutet keine besondere Priorität.
</ResponseField>

<Note>
  Shop-Versandarten stammen aus verbundenen Shop-Bestellungen. Apotheker können
  in den Einstellungen des Apothekentools apothekenspezifische Bezeichner für
  jede Shop-Versandart konfigurieren. Wenn noch keine Zuordnung vorhanden ist,
  gibt die API die Shop-Versandart trotzdem mit `pharmacy_mapping: null` zurück.
  Nachdem ein Apotheker eine Zuordnung gespeichert hat, enthalten zukünftige
  Bestellantworten den konfigurierten
  `shipping_method_identifier_for_pharmacy`.
</Note>

## Bestelldetails abrufen

```bash theme={null}
GET /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid}
```

Gibt die vollständige Bestellung einschließlich Patientendaten, Arztdaten und Rezeptdatei (falls verfügbar) zurück.

### Antwort (zusätzliche Felder)

```json theme={null}
{
  "uid": "po-abc123",
  "shop_order_name": null,
  "patient_data": {
    "uid": "pat-123",
    "display_name": "Max Mustermann",
    "email": "max@example.com",
    "date_of_birth": "1990-01-15"
  },
  "doctor_data": {
    "uid": "doc-456",
    "display_name": "Dr. Schmidt"
  },
  "prescription_file": {
    "filename": "prescription_001.pdf",
    "content_base64": "JVBERi0xLjQK..."
  },
  "shop_shipping_methods": [
    {
      "uid": "shop-shipping-method-uid",
      "display_name": "DHL Standard",
      "external_id": "shopify-standard",
      "pharmacy_mapping": null
    }
  ],
  "shipping_costs_amount": 499,
  "shipping_costs_currency": "EUR",
  "prepaid": 1,
  "payouts": [
    {
      "status": "projected",
      "amount": 1299,
      "currency": "EUR",
      "component_type": "item_rest",
      "routing_description": "Restbetrag für Medication X 100mg",
      "provider_route_id": null,
      "pharmacy_order_uid": "po-abc123",
      "pharmacy_order_name": "#1001",
      "pharmacy_order_created_at": 1711899000,
      "routing_created_at": null
    }
  ]
}
```

### Auszahlungen

Bestelldetail-Antworten enthalten top-level `payouts`. Jeder Eintrag verwendet dieselbe Struktur wie der Endpoint [Auszahlungen](/de/api-reference/external-pharmacy/payouts).

<ResponseField name="payouts" type="array">
  Auszahlungskomponenten für diese Apothekenbestellung, bei denen die angefragte Apotheke der Receiver ist. Bezahlte Bestellungen mit physischem Rezept geben `projected`-Auszahlungsvorschauen auf Basis der aktuellen Bestellwerte und Routing-Konfiguration zurück. Abgeschlossene Bestellungen geben `routed`-Auszahlungen zurück, sobald eine persistierte Split-Payment-Route existiert.
</ResponseField>

<ResponseField name="payouts[].status" type="string">
  `projected` für eine unverbindliche Vorschau oder `routed` für eine persistierte Split-Payment-Route, die nach Abschluss der Apothekenbestellung erstellt wurde.
</ResponseField>

<ResponseField name="payouts[].amount" type="integer">
  Auszahlungsbetrag in Cent.
</ResponseField>

<ResponseField name="payouts[].currency" type="string">
  ISO-4217-Währungscode, zum Beispiel `EUR`.
</ResponseField>

<ResponseField name="payouts[].component_type" type="string">
  Auszahlungskomponente, zum Beispiel `item_rest`, `item_markup` oder `shipping`.
</ResponseField>

<ResponseField name="payouts[].routing_description" type="string | null">
  Lesbare Beschreibung der gerouteten oder projizierten Komponente.
</ResponseField>

<ResponseField name="payouts[].provider_route_id" type="string | null">
  Routenbezeichner des Zahlungsanbieters. Dieser Wert ist bei gerouteten Auszahlungen befüllt, wenn der Anbieter einen Bezeichner zurückgegeben hat, und bei `projected`-Auszahlungen `null`.
</ResponseField>

<ResponseField name="payouts[].pharmacy_order_uid" type="string">
  UID der zugehörigen Apothekenbestellung.
</ResponseField>

<ResponseField name="payouts[].pharmacy_order_name" type="string | null">
  Lesbarer Name der Apothekenbestellung, zum Beispiel `#1001`.
</ResponseField>

<ResponseField name="payouts[].pharmacy_order_created_at" type="integer">
  Unix-Zeitstempel der Erstellung der Apothekenbestellung.
</ResponseField>

<ResponseField name="payouts[].routing_created_at" type="integer | null">
  Unix-Zeitstempel, zu dem die Split-Payment-Route erstellt wurde. Bei `projected`-Auszahlungen ist dieser Wert `null`; bei `routed`-Auszahlungen ist er befüllt.
</ResponseField>

<Warning>
  Das tatsächliche Routing erfolgt erst, wenn die Apothekenbestellung abgeschlossen wird. `projected`-Auszahlungen sind unverbindlich, werden nur für bezahlte Bestellungen mit physischem Rezept angezeigt und können sich vor Abschluss ändern. `routed`-Auszahlungswerte werden erst befüllt, nachdem Abschluss und Routing erfolgt sind.
</Warning>

## Bestellstatus aktualisieren

```bash theme={null}
PATCH /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid}/status
```

### Anfragekörper

```json theme={null}
{
  "status": "in-progress"
}
```

<ParamField body="status" type="string" required>
  Neuer Bestellstatus. Zulässige Werte siehe Tabelle unten.
</ParamField>

<ParamField body="comment" type="string">
  Freitext-Begründung für die Statusänderung. **Erforderlich (und darf nicht leer sein), wenn die Bestellung aus einem anderen Status in `on-hold` überführt wird** — der Kommentar wird zur Beschreibung des automatisch erstellten Admin-Klärfall-Threads. Für alle anderen Statusübergänge wird das Feld ignoriert.
</ParamField>

### Zulässige Statuswerte

| Status                 | Beschreibung                                                                       |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `waiting for pharmacy` | Bestellung befindet sich in Ihrer Warteschlange und wartet auf Bearbeitung         |
| `pending review`       | Bestellung wird geprüft                                                            |
| `on-hold`              | Bestellung ist pausiert, während Apotheke und Admin-Team einen Klärfall bearbeiten |
| `in-progress`          | Bestellung wird vorbereitet                                                        |
| `ready_for_pickup`     | Bestellung ist verpackt und bereit zur Abholung oder zum Versand                   |
| `cancelled`            | Bestellung wurde storniert                                                         |

<Warning>
  Setzen Sie `completed` nicht über diesen Endpoint. Verwenden Sie den dedizierten Complete-Order-Endpoint unten, damit RxScale die Bestellung abschließen, den Bestand reduzieren und die zugehörigen Ereignisse veröffentlichen kann.
</Warning>

### Bestellung auf `on-hold` setzen

Wenn Sie eine Bestellung in `on-hold` überführen, müssen Sie einen `comment` mit der Begründung angeben. RxScale eröffnet automatisch einen Admin-Klärfall-Thread und übernimmt Ihren Kommentar als Thread-Beschreibung, damit das Admin-Team den nötigen Kontext für die Nachverfolgung hat.

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "on-hold",
    "comment": "Bis 01.06.2026 nicht lieferbar"
  }'
```

Eine Anfrage ohne `comment` oder mit einem Kommentar, der nur aus Leerzeichen besteht, wird mit einem `400`-Status und folgendem Body abgelehnt:

```json theme={null}
{
  "error": {
    "comment": ["A comment is required when setting an order on hold"]
  }
}
```

Wiederholte `on-hold`-PATCH-Anfragen für eine Bestellung, die bereits den Status `on-hold` hat, benötigen keinen neuen Kommentar — sie werden als idempotente Wiederholungen behandelt.

## Bestellung abschließen

```bash theme={null}
PATCH /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid}/complete_order
```

Schließt die Apothekenbestellung ab, reduziert den Bestand der enthaltenen Pharmacy SKUs und veröffentlicht Benachrichtigungen zur Bestellaktualisierung. Erfordert die Berechtigung `orders_write`.

<ParamField query="pharmacy_uid" type="string">
  Erforderlich für gruppenweite API-Schlüssel
</ParamField>

### Anfragekörper

```json theme={null}
{
  "tracking_links": [
    {
      "tracking_link": "https://tracking.example.com/parcel/123",
      "carrier": "DHL"
    }
  ]
}
```

`tracking_links` ist optional. Wenn angegeben, wird der erste Tracking-Link mit der Versandaktualisierung weitergegeben.
Erlaubte Werte für `carrier` sind `DHL`, `DPD`, `UPS`, `Hermes`, `FedEx` und `Other`.

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/complete_order" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_links": [
      {
        "tracking_link": "https://tracking.example.com/parcel/123",
        "carrier": "DHL"
      }
    ]
  }'
```

### Antwort

```json theme={null}
{
  "uid": "po-abc123",
  "status": "completed",
  "name": "#1001",
  "external_status": "OPEN",
  "pharmacy": {
    "uid": "pharmacy-uid",
    "display_name": "Beispiel-Apotheke"
  },
  "order_items": [
    {
      "uid": "oi-789",
      "amount": 1,
      "sku": {
        "uid": "sku-456",
        "display_name": "Medication X 100mg",
        "pzn": "12345678"
      }
    }
  ],
  "shop_shipping_methods": [
    {
      "uid": "shop-shipping-method-uid",
      "display_name": "DHL Standard",
      "external_id": "shopify-standard",
      "pharmacy_mapping": {
        "pharmacy_uid": "pharmacy-uid",
        "shipping_method_identifier_for_pharmacy": "DHL_STANDARD"
      }
    }
  ],
  "shipping_costs_amount": 499,
  "shipping_costs_currency": "EUR"
}
```

### Validierungsfehler-Antwort

Wenn `tracking_links` einen nicht unterstützten Carrier oder einen ungültigen Tracking-Link enthält, gibt die API `400` mit dem Validierungsfehler und der Apotheken-Zusammenfassung zurück. So können Sie den Fehler der betroffenen Apotheke zuordnen. Ist die Bestellung bereits abgeschlossen, bleibt ein erneuter `complete_order`-Aufruf nur dann idempotent, wenn keine Tracking-Daten gesendet werden; Tracking-Links für bereits abgeschlossene Bestellungen werden mit `400` abgelehnt, damit Versanddetails nicht stillschweigend verworfen werden.

```json theme={null}
{
  "error": {
    "tracking_links": {
      "0": {
        "tracking_link": ["Invalid tracking link"]
      }
    }
  },
  "pharmacy": {
    "uid": "pharmacy-uid",
    "display_name": "Beispiel-Apotheke"
  }
}
```