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. Zulässige Werte: init, waiting for pharmacy, pending review, on-hold, in-progress, ready_for_pickup, completed, cancelled.

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.

integer

Inklusive untere Grenze für den created_at-Unix-Zeitstempel der Bestellung (Sekunden). Früher erstellte Bestellungen werden ausgeschlossen.

integer

Inklusive obere Grenze für den created_at-Unix-Zeitstempel der Bestellung (Sekunden). Später erstellte Bestellungen werden ausgeschlossen.

string

Erforderlich für gruppenweite API-Schlüssel

GET /v1/external_pharmacy_api/pharmacy_orders/

Beide Datumsgrenzen sind optional und können unabhängig voneinander verwendet werden — senden Sie nur start_date für „alles seit“ oder nur end_date für „alles bis“. Beide Grenzen sind inklusiv: Eine Bestellung, die exakt zum Zeitpunkt start_date oder end_date erstellt wurde, ist enthalten.

curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/?start_date=1735689600&end_date=1738368000&limit=100" \
  -H "X-API-Key: your-api-key"

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

Die dokumentierten Felder sind der Kernvertrag, keine vollständige Liste. Listen- und Detailantworten für Apothekenbestellungen werden direkt aus dem zugrunde liegenden Bestellmodell serialisiert. Sie können daher weitere Felder enthalten, die hier nicht dokumentiert sind, und neue Felder können jederzeit ohne Vorankündigung hinzukommen.Entwickeln Sie Ihre Integration so, dass sie unbekannte Felder ignoriert, anstatt die Antwort abzulehnen. Konfigurieren Sie Ihren JSON-Deserialisierer so, dass er nicht erkannte Eigenschaften überspringt (zum Beispiel @JsonIgnoreProperties(ignoreUnknown = true) in Jackson oder ein nicht-striktes Schema in Pydantic/marshmallow). Nur die auf dieser Seite dokumentierten Felder sind von unseren Kompatibilitätsgarantien abgedeckt — behandeln Sie alles andere als informativ und verlassen Sie sich nicht darauf.

string | null

Lesbarer Shop-Bestellname von der ursprünglichen Verkaufsplattform (z. B. #1234). Bei einer Bestellung über einen von RxScale gehosteten Storefront ist es die Bestellnummer des Storefronts (z. B. RXS-1001). 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

Versandkosten in Cent, zum Beispiel 499 für EUR 4,99. Immer eine ganze Zahl: 0 (niemals null), wenn keine Versandkosten anfallen. Dieser Wert ist von den Preisen der Produktpositionen getrennt. Bei vorausbezahlten Bestellungen ist er Ihr Anteil an den Versandkosten der Shop-Bestellung — siehe Mehrere Apothekenbestellungen pro Shop-Bestellung.

string

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.

Mehrere Apothekenbestellungen pro Shop-Bestellung

RxScale erstellt eine Apothekenbestellung pro Fulfillment-Auftrag, nicht pro Shop-Bestellung. Wird eine Shop-Bestellung auf mehrere Fulfillment-Aufträge aufgeteilt, erhalten Sie dafür mehrere Apothekenbestellungen:

Jede Apothekenbestellung enthält nur die Artikel ihres eigenen Fulfillment-Auftrags.
Jede Apothekenbestellung wird erstellt, sobald ihr Teil der Shop-Bestellung an eine Apotheke übermittelt werden kann. Rezeptpflichtige Artikel werden erst übermittelt, nachdem das Rezept signiert wurde. Apothekenbestellungen derselben Shop-Bestellung können daher Stunden auseinanderliegen.
Alle Apothekenbestellungen derselben Shop-Bestellung haben dieselbe order.uid.
Wird eine Bestellung storniert und erneut an eine Apotheke übermittelt, bleibt die stornierte Apothekenbestellung bestehen, und für dieselbe Shop-Bestellung wird eine neue Apothekenbestellung mit einer neuen uid erstellt.

Bei vorausbezahlten Bestellungen (prepaid: 1) werden die Versandkosten der Shop-Bestellung gleichmäßig auf alle nicht stornierten Apothekenbestellungen dieser Shop-Bestellung aufgeteilt, auch auf Apothekenbestellungen anderer Apotheken. shipping_costs_amount ist Ihr Anteil. Er wird bei jedem Abruf und jeder Übermittlung der Bestellung neu berechnet und kann sich daher ändern, wenn für dieselbe Shop-Bestellung eine weitere Apothekenbestellung erstellt oder storniert wird.

Verwenden Sie die uid der Apothekenbestellung als Schlüssel. Sie ist eine UUID und ändert sich nie. Verwenden Sie shop_order_name nicht als Schlüssel — der Name ist nicht eindeutig:

Alle Apothekenbestellungen derselben Shop-Bestellung haben denselben Namen.
Derselbe Name kann in verschiedenen Shops vorkommen.
Er ist null, solange der Shop-Bestellname für Ihre Apotheke deaktiviert ist (siehe den Hinweis zur Breaking Change oben).

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

Felder der Detailantwort

integer

1, wenn die Bestellung ein Rezept vom Typ physical mit dem Status signed oder NON_QES_SIGNED enthält (siehe Rezeptstatus) — ein Rezept für physische Produkte, die der Patient bereits beim Checkout bezahlt hat, einschließlich Versand. Andernfalls 0, zum Beispiel bei Bestellungen, die nur rezeptfreie Produkte enthalten.physical bezeichnet den Rezepttyp. Es bezieht sich nicht auf eine Unterschrift auf Papier oder eine handschriftliche Unterschrift.

string

ID des Patientenprofils. Sie wird einmal vergeben und nie neu erzeugt. RxScale führt ein Patientenprofil pro Kundenkonto in einem Shop. Dieselbe Person hat daher in einem anderen Shop oder mit einem anderen Kundenkonto eine andere uid. Werden doppelte Patientenprofile zusammengeführt, zeigen die Bestellungen des entfernten Profils die uid des verbleibenden Profils.

string

Vor- und Nachname aus dem Patientenprofil oder ein leerer String, wenn kein Name hinterlegt ist. Der Empfänger in order.delivery_address kann eine andere Person sein; kein Feld kennzeichnet dies.

string

E-Mail-Adresse des Kunden zu dieser Shop-Bestellung, wie beim Checkout angegeben. Sie ist nicht eindeutig und kann leer sein. Werden doppelte Patientenprofile zusammengeführt, zeigen die Bestellungen des entfernten Profils die zuletzt verwendete E-Mail-Adresse des verbleibenden Profils, sofern vorhanden.

object | null

Der Arzt, der das Rezept signiert hat. null, wenn die Bestellung kein von einem Arzt auf RxScale signiertes Rezept enthält — zum Beispiel bei einer Bestellung, die nur rezeptfreie Produkte enthält.

string

ID des Arztes. Sie ist für einen Arzt innerhalb einer Organisation stabil; ein Arzt, der für mehrere Organisationen tätig ist, hat in jeder eine andere uid.

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 beim Checkout für die Position gezahlte Bruttobetrag in Cent. Er wird für vorausbezahlte Bestellungen (prepaid: 1, siehe oben) und für im Apothekenportal als bezahlt markierte Bestellungen befüllt und ist andernfalls 0.

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. Mit Abschluss verlässt die Bestellung die projected-Menge; als routed erscheint sie nur, wenn eine Split-Payment-Route angelegt wurde. Es gibt keine persistierte projected-Historie nach Abschluss.

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

Mehrere Apothekenbestellungen pro Shop-Bestellung

Bestelldetails abrufen

Antwort (zusätzliche Felder)

Felder der Detailantwort

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

​Mehrere Apothekenbestellungen pro Shop-Bestellung

​Bestelldetails abrufen

​Antwort (zusätzliche Felder)

​Felder der Detailantwort

​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

Mehrere Apothekenbestellungen pro Shop-Bestellung

Bestelldetails abrufen

Antwort (zusätzliche Felder)

Felder der Detailantwort

Positionspreise

Auszahlungen

Bestellstatus aktualisieren

Anfragekörper

Zulässige Statuswerte

Bestellung auf `on-hold` setzen

Bestellung abschließen

Anfragekörper

Antwort

Validierungsfehler-Antwort