Apothekenbestellungen

Verwalten Sie Apothekenbestellungen — sehen Sie eingehende Bestellungen (rezeptpflichtig und rezeptfrei) ein und aktualisieren Sie deren Status während der Bearbeitung.

Bestellungen auflisten

integer

Standard:"0"

Seitennummer (0-indiziert)

integer

Standard:"50"

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

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.Die Suche nach dem Shop-Bestellnamen ist nur für Apotheken aktiv, bei denen der Shop-Bestellname aktiviert ist (siehe den Hinweis zur Breaking Change unten). Ist er deaktiviert, liefert die Suche nach dem Shop-Bestellnamen keine Ergebnisse; die übrigen Suchfelder sind davon nicht betroffen.

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

string | null

Lesbarer Shop-Bestellname von der ursprünglichen Verkaufsplattform (z. B. #1234). null für Bestellungen ohne verknüpfte Shop-Bestellung und null, wenn der Shop-Bestellname für die zugehörige Apotheke deaktiviert ist (siehe den Hinweis zur Breaking Change unten).

Breaking Change — shop_order_name ist jetzt standardmäßig deaktiviert.shop_order_name wird jetzt über eine apothekenspezifische Einstellung gesteuert, die standardmäßig deaktiviert ist. Solange sie deaktiviert ist, geben alle Bestellungen dieser Apotheke shop_order_name: null zurück (sowohl in der Listen- als auch in der Bestelldetail-Antwort), und die Bestellung kann nicht mehr über die Suche nach ihrem Shop-Bestellnamen gefunden werden.Bisher war dieses Feld immer befüllt, sobald eine verknüpfte Shop-Bestellung vorhanden war. Wenn Ihre Integration auf shop_order_name angewiesen ist — zur Anzeige, zum Abgleich oder für die search —, kann der Shop den Shop-Bestellnamen für die betroffene Apotheke selbst im Admin-Tool aktivieren (auf der Detailseite der Apotheke, unter der Einstellung Shop-Bestellname); RxScale muss dabei nicht involviert werden. Nach der Aktivierung ist das Feld wieder befüllt und durchsuchbar wie zuvor.Behandeln Sie ein null bei shop_order_name nicht als „keine Shop-Bestellung” — es kann auch bedeuten, dass die Einstellung deaktiviert ist. Verwenden Sie order.uid bzw. die Apotheken-Bestell-uid als stabile Bezeichner.

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.

object | null

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

integer | null

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

string | null

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

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.

doctor_data und prescription_file sind null bei Bestellungen, die nur rezeptfreie (OTC) Produkte enthalten — diesen Bestellungen ist kein Rezept beigefügt.

shop_order_name folgt hier derselben apothekenspezifischen Einstellung wie in der Listen-Antwort — es ist null, solange die Einstellung deaktiviert ist (Standard). Siehe den Hinweis zur Breaking Change oben.

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
    }
  ]
}

Positionspreise

Jeder order_items[]-Eintrag enthält zwei Preise:

pharmacy_sku.price — der Listenpreis der Apotheke für die SKU in Cent, als Snapshot zum Bestellzeitpunkt (der Preis, der bei der Bestellung erfasst wurde). Er ändert sich nicht, wenn die Apotheke später ihren Listenpreis anpasst.
total_paid_amount — der vom Patienten tatsächlich gezahlte Betrag für die Position in Cent (brutto). Er wird für vorausbezahlte Bestellungen befüllt (solche mit einem signierten physischen Rezept, d. h. prepaid: 1) und ist 0, wenn für die Position keine Zahlung anfällt.

Bei vorausbezahlten Bestellungen sollte gegen total_paid_amount abgerechnet werden, nicht gegen pharmacy_sku.price.

Auszahlungen

Bestelldetail-Antworten enthalten top-level payouts. Jeder Eintrag verwendet dieselbe Struktur wie der Endpoint Auszahlungen.

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.

string

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

integer

Auszahlungsbetrag in Cent.

string

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

string

Auszahlungskomponente, zum Beispiel item_rest, item_markup oder shipping.

string | null

Lesbare Beschreibung der gerouteten oder projizierten Komponente.

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.

string

UID der zugehörigen Apothekenbestellung.

string | null

Lesbarer Name der Apothekenbestellung, zum Beispiel #1001.

integer

Unix-Zeitstempel der Erstellung der Apothekenbestellung.

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

string

erforderlich

Neuer Bestellstatus. Zulässige Werte siehe Tabelle unten.

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.

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

Erste Schritte

Externe Apotheken-API

Management-API

Scheduling API

Öffentliche API

Patienten-API

Anamnese-API

Webhooks

Anleitungen

Apothekenbestellungen

Apothekenbestellungen

Bestellungen auflisten

Antwort

Felder der Bestellantwort

Bestelldetails abrufen

Antwort (zusätzliche Felder)

Positionspreise

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)

​Positionspreise

​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)

Positionspreise

Auszahlungen

Bestellstatus aktualisieren

Anfragekörper

Zulässige Statuswerte

Bestellung auf `on-hold` setzen

Bestellung abschließen

Anfragekörper

Antwort

Validierungsfehler-Antwort