Apothekenbestellungen

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

Bestellungen auflisten

page

integer

Standard:"0"

Seitennummer (0-indiziert)

limit

integer

Standard:"50"

Anzahl der Einträge pro Seite (max. 200)

status

string

Nach Status filtern (z. B. waiting for pharmacy, on-hold, in-progress, completed)

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.

pharmacy_uid

string

Erforderlich für gruppenweite API-Schlüssel

GET /v1/external_pharmacy_api/pharmacy_orders/

Antwort

{
  "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

shop_order_name

string | null

Lesbarer Shop-Bestellname von der ursprünglichen Verkaufsplattform (z. B. #1234). null für Bestellungen ohne verknüpfte Shop-Bestellung.

shop_shipping_methods

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.

shop_shipping_methods[].pharmacy_mapping

object | null

Apothekenspezifische Zuordnung für diese Shop-Versandart. Wenn vorhanden, enthält sie pharmacy_uid und shipping_method_identifier_for_pharmacy.

shipping_costs_amount

integer | null

Versandkosten in Cent, zum Beispiel 499 für EUR 4,99. Dieser Wert ist von den Preisen der Produktpositionen getrennt.

shipping_costs_currency

string | null

ISO-Währungscode der Versandkosten, zum Beispiel EUR.

order.priority

integer

Prioritätshinweis für die bevorzugte Bearbeitung. Höher = dringender. 0 bedeutet keine besondere Priorität.

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.

Bestelldetails abrufen

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)

{
  "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.

payouts

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.

payouts[].status

string

projected für eine unverbindliche Vorschau oder routed für eine persistierte Split-Payment-Route, die nach Abschluss der Apothekenbestellung erstellt wurde.

payouts[].amount

integer

Auszahlungsbetrag in Cent.

payouts[].currency

string

ISO-4217-Währungscode, zum Beispiel EUR.

payouts[].component_type

string

Auszahlungskomponente, zum Beispiel item_rest, item_markup oder shipping.

payouts[].routing_description

string | null

Lesbare Beschreibung der gerouteten oder projizierten Komponente.

payouts[].provider_route_id

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.

payouts[].pharmacy_order_uid

string

UID der zugehörigen Apothekenbestellung.

payouts[].pharmacy_order_name

string | null

Lesbarer Name der Apothekenbestellung, zum Beispiel #1001.

payouts[].pharmacy_order_created_at

integer

Unix-Zeitstempel der Erstellung der Apothekenbestellung.

payouts[].routing_created_at

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.

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.

Bestellstatus aktualisieren

PATCH /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid}/status

Anfragekörper

{
  "status": "in-progress"
}

status

string

erforderlich

Neuer Bestellstatus. Zulässige Werte siehe Tabelle unten.

comment

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.

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

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.

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.

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:

{
  "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

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.

pharmacy_uid

string

Erforderlich für gruppenweite API-Schlüssel

Anfragekörper

{
  "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.

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

{
  "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.

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

​Apothekenbestellungen

​Bestellungen auflisten

​Antwort

​Felder der Bestellantwort

​Bestelldetails abrufen

​Antwort (zusätzliche Felder)

​Auszahlungen

​Bestellstatus aktualisieren

​Anfragekörper

​Zulässige Statuswerte

​Bestellung auf on-hold setzen

​Bestellung abschließen

​Anfragekörper

​Antwort

​Validierungsfehler-Antwort

Apothekenbestellungen

Bestellungen auflisten

Antwort

Felder der Bestellantwort

Bestelldetails abrufen

Antwort (zusätzliche Felder)

Auszahlungen

Bestellstatus aktualisieren

Anfragekörper

Zulässige Statuswerte

Bestellung auf `on-hold` setzen

Bestellung abschließen

Anfragekörper

Antwort

Validierungsfehler-Antwort