Webhook-Ereignisse

RxScale sendet Webhooks für die folgenden Ereignistypen:

Ereignistyp	Beschreibung
`pharmacy_order_created`	Eine neue Apothekenbestellung wurde erstellt und Ihrer Apotheke zugewiesen
`pharmacy_order_updated`	Eine bestehende Apothekenbestellung hat sich geändert — einschließlich Statusänderungen und wenn die Apotheke Sendungen hinzufügt
`pharmacy_sku_stock_updated`	Der Lagerbestand einer Apotheken-SKU hat sich geändert
`appointment_reminder_due`	Eine geplante Terminerinnerung ist fällig geworden
`patient_doctor_meeting_updated`	Eine Patient-Arzt-Besprechung hat ihren Lebenszyklus-Status geändert

HTTP-Header

Webhook-Anfragen enthalten die folgenden HTTP-Header:

Header	Beschreibung
`Content-Type`	Immer `application/json`
`X-Webhook-Event`	Der Ereignistyp (z.B. `pharmacy_order_created`)
`X-Webhook-Signature`	HMAC-SHA256 des unveränderten Anfragekörpers als Hexadezimalzeichenkette in Kleinbuchstaben, mit Ihrem `webhook_secret` als Schlüssel (siehe Sicherheit). Wird bei Abonnements gesendet, die über die External Pharmacy API oder das Apothekenportal registriert wurden.

Falls Sie beim Erstellen des Abonnements einen benutzerdefinierten Header konfiguriert haben, wird dieser ebenfalls mitgesendet. Test-Webhooks sind nicht signiert und enthalten stattdessen den Header X-Webhook-Test: true.

pharmacy_order_created

Wird gesendet, wenn eine neue Apothekenbestellung erstellt und Ihrer Apotheke zugewiesen wird.

Eine Apothekenbestellung wird pro Fulfillment erstellt, nicht pro Shop-Bestellung. Eine Shop-Bestellung kann daher im Lauf der Zeit mehrere Apothekenbestellungen erzeugen — zum Beispiel, wenn sie in mehrere Fulfillments aufgeteilt wird oder später ein Fulfillment hinzukommt. Diese Apothekenbestellungen haben dieselbe data.order.uid. Verwenden Sie data.uid als Schlüssel einer Apothekenbestellung; shop_order_name ist nicht eindeutig. Details finden Sie unter Apothekenbestellungen.

Apothekenbestellungen werden auch für rezeptfreie (OTC) Käufe erstellt, nicht nur für rezeptpflichtige Bestellungen — jede Ihrer Apotheke zugewiesene Erfüllung löst dieses Ereignis aus, unabhängig davon, ob ein Rezept vorliegt. Bei einer reinen OTC-Bestellung sind data.doctor_data und data.prescription_file null, und data.prepaid ist 0.

data.shipments ist immer vorhanden. Bei der Erstellung ist es ein leeres Array — die Apotheke hat noch nicht versendet. Nachdem die Apotheke Pakete hinzugefügt hat (Apothekenportal oder complete_order mit tracking_links), enthalten spätere pharmacy_order_updated-Zustellungen diese Sendungen.

Neue Apothekenbestellungen beginnen im Status waiting for pharmacy. Die Payload zeigt die Bestellung so, wie sie beim Versand der Zustellung ist; eine pharmacy_order_created-Zustellung kann daher bereits einen späteren Status enthalten. Mögliche status-Werte: waiting for pharmacy, pending review, on-hold, in-progress, ready_for_pickup, completed, cancelled

Payload-Beispiel

{
  "event_type": "pharmacy_order_created",
  "timestamp": 1711900000,
  "payload_version": "1",
  "data": {
    "uid": "po-abc123",
    "status": "waiting for pharmacy",
    "name": "#1001",
    "external_status": "OPEN",
    "created_at": 1711899000,
    "updated_at": 1711899000,
    "deleted_at": null,
    "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
      },
      "shipping_costs_amount": 499,
      "shipping_costs_currency": "EUR",
      "priority": 5
    },
    "delivery_type": {
      "uid": "dt-001",
      "display_name": "Standard Shipping",
      "identifier": "standard"
    },
    "shop_shipping_methods": [
      {
        "uid": "ssm-001",
        "display_name": "DHL Standard",
        "external_id": "shopify-standard",
        "pharmacy_mapping": {
          "pharmacy_uid": "ph-xyz",
          "shipping_method_identifier_for_pharmacy": "DHL_STANDARD"
        }
      }
    ],
    "order_items": [
      {
        "uid": "oi-789",
        "amount": 1,
        "sku": {
          "uid": "sku-456",
          "display_name": "Medication X 100mg",
          "pzn": "12345678",
          "product_uid": "prod-789",
          "product_display_name": "Medication X",
          "standard_selling_unit": 1.0,
          "unit": "ml",
          "product_handle": "medication-x"
        },
        "pharmacy_sku": {
          "uid": "psku-456",
          "external_id": "EXT-001",
          "price": 1299,
          "stock": 50
        },
        "total_paid_amount": 1299
      }
    ],
    "payouts": [
      {
        "status": "projected",
        "amount": 999,
        "currency": "EUR",
        "component_type": "item_rest",
        "routing_description": "Medication X 100mg item rest",
        "provider_route_id": null,
        "pharmacy_order_uid": "po-abc123",
        "pharmacy_order_name": "#1001",
        "pharmacy_order_created_at": 1711899000,
        "routing_created_at": null
      },
      {
        "status": "projected",
        "amount": 499,
        "currency": "EUR",
        "component_type": "shipping",
        "routing_description": "Standard Shipping",
        "provider_route_id": null,
        "pharmacy_order_uid": "po-abc123",
        "pharmacy_order_name": "#1001",
        "pharmacy_order_created_at": 1711899000,
        "routing_created_at": null
      }
    ],
    "patient_data": {
      "uid": "pat-123",
      "display_name": "Max Mustermann",
      "email": "max@example.com",
      "date_of_birth": "15.06.1990",
      "phone_number": "+49 170 1234567"
    },
    "doctor_data": {
      "uid": "doc-456",
      "display_name": "Dr. Schmidt"
    },
    "prescription_file": {
      "filename": "prescription_001.pdf",
      "content_base64": "JVBERi0xLjQK..."
    },
    "prepaid": 1,
    "shipments": []
  }
}

Feldreferenz

Feld	Typ	Beschreibung
`data.uid`	string	UID der Apothekenbestellung
`data.status`	string	Aktueller Bestellstatus
`data.name`	string oder null	Lesbarer Bestellname (z.B. `#1001`)
`data.external_status`	string	Externer Status-Bezeichner
`data.created_at`	integer	Unix-Zeitstempel der Erstellung
`data.updated_at`	integer	Unix-Zeitstempel der letzten Aktualisierung
`data.deleted_at`	integer oder null	Unix-Zeitstempel der Löschung oder `null`
`data.pharmacy`	object	Apothekenzusammenfassung mit `uid` und `display_name`
`data.order`	object	Übergeordnete Bestellung mit `uid`, `delivery_address` und `invoice_address`
`data.order.shipping_costs_amount`	integer	Versandkosten in Cent. Immer ein Integer — der Wert ist `0` (niemals `null`), wenn keine Versandkosten anfallen.
`data.order.shipping_costs_currency`	string	ISO-4217-Währungscode der Versandkosten, z.B. `EUR`.
`data.order.priority`	integer	Prioritätshinweis für die bevorzugte Bearbeitung. Höher = dringender. `0` bedeutet keine besondere Priorität.
`data.delivery_type`	object oder null	Versandart mit `uid`, `display_name` und `identifier`. Wird aus der Fulfillment-Methode des verbundenen Shops ermittelt (Shopify-Line-Item `_fulfillment_method` oder `fulfillment_method`, pro Shop gemappt), andernfalls aus der Standard-Versandart der empfangenden Apotheke. `null`, wenn keines von beiden gesetzt ist — gehen Sie nicht davon aus, dass immer eine Versandart vorhanden ist.
`data.shop_shipping_methods`	array	Versandmethoden des verbundenen Shop-Bestellauftrags. Leeres Array, wenn keine Shop-Versandmethoden vorliegen.
`data.shop_shipping_methods[].uid`	string	UID der Shop-Versandmethode
`data.shop_shipping_methods[].display_name`	string	Anzeigename der Versandmethode aus dem Shop
`data.shop_shipping_methods[].external_id`	string oder null	Bezeichner der Versandmethode im verbundenen Shop (z.B. der Shopify-Shipping-Line-Code)
`data.shop_shipping_methods[].pharmacy_mapping`	object oder null	Apothekenspezifisches Mapping aus den RxScale-Apothekeneinstellungen, oder `null`, wenn für die empfangende Apotheke noch kein Mapping konfiguriert wurde. Konfiguriert wird dies im Apotheken-Bildschirm Einstellungen → Versandarten-Zuordnung.
`data.shop_shipping_methods[].pharmacy_mapping.pharmacy_uid`	string	UID der empfangenden Apotheke, für die dieses Mapping gilt
`data.shop_shipping_methods[].pharmacy_mapping.shipping_method_identifier_for_pharmacy`	string	Apothekenspezifischer Bezeichner, den die empfangende Apotheke für diese Versandmethode erwartet (z.B. `DHL_STANDARD`). Verwenden Sie diesen Wert, wenn Sie die Bestellung an Ihr nachgelagertes Versand-/Label-System übergeben.
`data.order_items`	array	Artikel der Bestellung
`data.order_items[].sku`	object	SKU-Informationen inkl. `pzn`, `product_uid`, `product_display_name`, `standard_selling_unit`, `unit` und `product_handle`
`data.order_items[].sku.standard_selling_unit`	number oder null	Standard-Verkaufseinheit der SKU
`data.order_items[].sku.unit`	string oder null	Einheit der SKU, z.B. `ml` oder `g`
`data.order_items[].pharmacy_sku`	object oder null	Apothekenspezifische SKU-Daten mit `uid`, `external_id`, `price` (Cent), `stock`. `price` ist der zum Bestellzeitpunkt erfasste Preis (Snapshot) und ändert sich daher nicht, wenn die Apotheke später ihren Listenpreis anpasst.
`data.order_items[].total_paid_amount`	integer	Vom Patienten beim Checkout gezahlter Betrag für diese Position in Cent (brutto). Wird für vorausbezahlte Bestellungen (`prepaid: 1`) befüllt, sonst `0` — es sei denn, die Bestellung wurde im Apothekenportal als bezahlt markiert. Bei vorausbezahlten Bestellungen ist dies der abzurechnende Preis – nicht `pharmacy_sku.price`.
`data.payouts`	array	Auszahlungskomponenten für diese Apothekenbestellung, bei denen die aktuelle Apotheke der Receiver ist. Es werden nur Komponenten aufgeführt, die an Ihre Apotheke ausgezahlt werden; Beträge an andere Empfänger, etwa der Aufschlag des Shops, sind nicht enthalten. Bezahlte Bestellungen mit physischem Rezept enthalten `projected`-Vorschauen auf Basis aktueller Werte und Routing-Konfiguration. Abgeschlossene Bestellungen enthalten `routed`-Auszahlungen, sobald eine persistierte Split-Payment-Route existiert.
`data.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.
`data.payouts[].amount`	integer	Auszahlungsbetrag in Cent.
`data.payouts[].currency`	string	ISO-4217-Währungscode, z.B. `EUR`.
`data.payouts[].component_type`	string	Auszahlungskomponente. Mögliche Werte sind `item_rest`, `item_markup` und `shipping`.
`data.payouts[].routing_description`	string oder null	Lesbare Beschreibung der gerouteten oder projizierten Komponente.
`data.payouts[].provider_route_id`	string oder null	Routenbezeichner des Zahlungsanbieters. Befüllt bei gerouteten Auszahlungen, wenn der Anbieter einen Bezeichner zurückgegeben hat, und `null` bei `projected`-Auszahlungen.
`data.payouts[].pharmacy_order_uid`	string	UID der zugehörigen Apothekenbestellung.
`data.payouts[].pharmacy_order_name`	string oder null	Lesbarer Name der Apothekenbestellung.
`data.payouts[].pharmacy_order_created_at`	integer	Unix-Zeitstempel der Erstellung der Apothekenbestellung.
`data.payouts[].routing_created_at`	integer oder null	Unix-Zeitstempel der Erstellung der Split-Payment-Route. Bei `projected`-Auszahlungen ist dieser Wert `null`.
`data.patient_data`	object oder null	Patienteninformationen mit `uid`, `display_name`, `email`, `date_of_birth`, `phone_number`
`data.patient_data.uid`	string	ID des Patientenprofils. Sie wird einmal vergeben und nie neu erzeugt. Es gibt ein Profil 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 (und gegebenenfalls auch dessen zuletzt verwendete E-Mail-Adresse).
`data.patient_data.display_name`	string	Vor- und Nachname aus dem Patientenprofil. Leere Zeichenkette, wenn kein Name hinterlegt ist — es gibt keinen Ersatzwert. Der Empfänger in `data.order.delivery_address` kann eine andere Person sein; kein Feld kennzeichnet dies.
`data.patient_data.email`	string	Beim Checkout dieser Bestellung angegebene E-Mail-Adresse. Nicht eindeutig und kann eine leere Zeichenkette sein.
`data.doctor_data`	object oder null	Arzt, der das Rezept signiert hat, mit `uid` und `display_name`. `null`, wenn die Bestellung kein Rezept enthält, das von einem Arzt auf RxScale signiert wurde — zum Beispiel bei reinen OTC-Bestellungen oder extern signierten Rezepten.
`data.doctor_data.uid`	string	ID des Arztes. Stabil für einen Arzt innerhalb einer Organisation; arbeitet derselbe Arzt für eine andere Organisation, hat er dort eine andere `uid`.
`data.prescription_file`	object oder null	Signiertes Rezept-PDF mit `filename` und `content_base64`
`data.prepaid`	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. Sonst `0`. `physical` ist der Rezepttyp; es bedeutet keine handschriftliche oder papierbasierte Signatur.
`data.shipments`	array	Pakete, die zu dieser Apothekenbestellung erfasst wurden. Leer (`[]`), bis die Apotheke eine Sendung hinzufügt. Siehe Sendungen.

shipping_costs_amount und unpaid_shipping_costs_amount sind unterschiedliche Felder — die Garantie „0, niemals null” gilt nur für das erste.data.order.shipping_costs_amount ist immer ein Integer: 0, wenn keine Versandkosten anfallen, niemals null.unpaid_shipping_costs_amount ist eine separate, interne Überschreibung der Versandkosten, die nullable ist und nicht Teil des dokumentierten Webhook-Vertrags ist. Wenn Sie dieses Feld in einer Payload sehen, wenden Sie die Garantie von shipping_costs_amount nicht darauf an: Es kann fehlen oder null sein, und null bedeutet dort nicht „keine Versandkosten”. Verwenden Sie shipping_costs_amount für den Versandkostenabgleich und behandeln Sie unpaid_shipping_costs_amount — sofern Sie es überhaupt auslesen — als optionalen, möglicherweise null-Wert.

Das tatsächliche Zahlungsrouting erfolgt erst, wenn die Apothekenbestellung abgeschlossen wird. projected-Auszahlungen in Webhook-Payloads sind unverbindlich, werden nur für bezahlte Bestellungen mit physischem Rezept angezeigt und können sich vor Abschluss ändern. routed-Auszahlungswerte werden erst nach Abschluss und vorhandenem Routing befüllt.

pharmacy_order_updated

Wird gesendet, wenn sich eine bestehende Apothekenbestellung ändert:

Statusänderungen — im Apothekenportal (einschließlich Sammelaktualisierungen), über die External Pharmacy API (einschließlich Ihrer eigenen Aufrufe von PATCH .../status und complete_order) oder durch die automatische Statusabfrage bei Ihrem Apothekensystem (zum Beispiel, wenn es die Bestellung als versendet, abgeschlossen oder storniert meldet).
Stornierungen — unabhängig davon, ob die Bestellung von Ihrer Apotheke, vom Admin-Team oder durch die automatische Statusabfrage storniert wird.
Sendungen — wenn im Apothekenportal eine Sendung manuell erfasst wird oder wenn Sie die Bestellung über die External Pharmacy API mit tracking_links abschließen. Eine als Carrier-Label gebuchte Sendung erscheint in der nächsten Aktualisierung (siehe Sendungen).
Klärfälle — wenn Ihre Apotheke oder das Admin-Team einen Klärfall zur Bestellung eröffnet, wodurch sie auf on-hold gesetzt wird.
Priorität oder Versandart — wenn Ihre Apotheke die Priorität oder die Versandart der Bestellung im Apothekenportal ändert.

Die Payload-Struktur ist identisch mit pharmacy_order_created und enthält immer den vollständigen aktuellen Stand der Bestellung, nicht nur den geänderten Teil. Das Feld status enthält den aktuellen Status, und data.shipments listet alle aktuell zur Bestellung gehörenden Sendungen auf (nicht nur die zuletzt hinzugefügte). Was sich geändert hat, ermitteln Sie durch Vergleich mit Ihrem gespeicherten Stand — siehe Ereignisse idempotent verarbeiten. Es gibt kein separates Ereignis pharmacy_order_shipment_created. Abonnieren Sie pharmacy_order_updated und lesen Sie data.shipments.

Payload-Beispiel

{
  "event_type": "pharmacy_order_updated",
  "timestamp": 1711910000,
  "payload_version": "1",
  "data": {
    "uid": "po-abc123",
    "status": "in-progress",
    "name": "#1001",
    "external_status": "IN_PROGRESS",
    "created_at": 1711899000,
    "updated_at": 1711910000,
    "deleted_at": null,
    "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
      },
      "shipping_costs_amount": 499,
      "shipping_costs_currency": "EUR",
      "priority": 5
    },
    "delivery_type": {
      "uid": "dt-001",
      "display_name": "Standard Shipping",
      "identifier": "standard"
    },
    "shop_shipping_methods": [
      {
        "uid": "ssm-001",
        "display_name": "DHL Standard",
        "external_id": "shopify-standard",
        "pharmacy_mapping": {
          "pharmacy_uid": "ph-xyz",
          "shipping_method_identifier_for_pharmacy": "DHL_STANDARD"
        }
      }
    ],
    "order_items": [
      {
        "uid": "oi-789",
        "amount": 1,
        "sku": {
          "uid": "sku-456",
          "display_name": "Medication X 100mg",
          "pzn": "12345678",
          "product_uid": "prod-789",
          "product_display_name": "Medication X",
          "standard_selling_unit": 1.0,
          "unit": "ml",
          "product_handle": "medication-x"
        },
        "pharmacy_sku": {
          "uid": "psku-456",
          "external_id": "EXT-001",
          "price": 1299,
          "stock": 50
        },
        "total_paid_amount": 1299
      }
    ],
    "payouts": [
      {
        "status": "projected",
        "amount": 999,
        "currency": "EUR",
        "component_type": "item_rest",
        "routing_description": "Medication X 100mg item rest",
        "provider_route_id": null,
        "pharmacy_order_uid": "po-abc123",
        "pharmacy_order_name": "#1001",
        "pharmacy_order_created_at": 1711899000,
        "routing_created_at": null
      },
      {
        "status": "projected",
        "amount": 499,
        "currency": "EUR",
        "component_type": "shipping",
        "routing_description": "Standard Shipping",
        "provider_route_id": null,
        "pharmacy_order_uid": "po-abc123",
        "pharmacy_order_name": "#1001",
        "pharmacy_order_created_at": 1711899000,
        "routing_created_at": null
      }
    ],
    "patient_data": {
      "uid": "pat-123",
      "display_name": "Max Mustermann",
      "email": "max@example.com",
      "date_of_birth": "15.06.1990",
      "phone_number": "+49 170 1234567"
    },
    "doctor_data": {
      "uid": "doc-456",
      "display_name": "Dr. Schmidt"
    },
    "prescription_file": {
      "filename": "prescription_001.pdf",
      "content_base64": "JVBERi0xLjQK..."
    },
    "prepaid": 1,
    "shipments": [
      {
        "uid": "pos-001",
        "shipment_reference": "#1001-1",
        "sequence_number": 1,
        "carrier_name": "DHL",
        "tracking_number": "00340434782962080954",
        "tracking_url": "https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=00340434782962080954",
        "service": "V01PAK",
        "return_tracking_number": null,
        "return_label_expiry": null,
        "is_test": false,
        "created_at": 1711908000
      }
    ]
  }
}

Sendungen

data.shipments ist die Liste der Pakete, die die Apotheke zu dieser Bestellung erfasst hat. Nutzen Sie sie, um Tracking-Daten zu übernehmen, wenn eine Apotheke versendet — einschließlich Teillieferungen (mehrere Pakete). Wann das Array befüllt ist

Der Abschluss der Bestellung über PATCH /v1/external_pharmacy_api/pharmacy_orders/{uid}/complete_order mit tracking_links legt eine Sendung an und sendet anschließend pharmacy_order_updated.
Das Hinzufügen einer Sendung im Apothekenportal (manuelles Tracking oder ein gebuchtes Carrier-Label, dem eine Bestellaktualisierung folgt) belässt die Sendung an der Bestellung. Die nächste pharmacy_order_updated-Payload enthält alle aktuellen Sendungen, sortiert nach sequence_number.
pharmacy_order_created hat fast immer "shipments": []. Behandeln Sie eine fehlende Tracking-URL bei der Erstellung nicht als Fehler.

So verwenden Sie die Daten

Behandeln Sie uid als stabile Identität eines Pakets. Ein späteres pharmacy_order_updated kann weitere Einträge hinzufügen; bestehende UIDs bleiben gleich.
Bevorzugen Sie tracking_url für die kundenseitige Sendungsverfolgung. tracking_number und carrier_name sind gesetzt, wenn Apotheke oder Carrier sie geliefert haben; beide können bei einer neu angelegten Platzhalter-Sendung null sein.
is_test ist nur true, wenn das Paket gegen eine Carrier-Sandbox gebucht wurde (kein echter Versand). Ignorieren Sie Testsendungen für die Live-Erfüllung.
return_tracking_number und return_label_expiry (YYYY-MM-DD) sind nur gesetzt, nachdem ein Rücksendeetikett ausgestellt wurde; sonst sind sie null.

Feld	Typ	Beschreibung
`data.shipments[].uid`	string	UID der Sendung
`data.shipments[].shipment_reference`	string	Lesbare Referenz, typischerweise `{Bestellname}-{Sequenz}` (z. B. `#1001-1`)
`data.shipments[].sequence_number`	integer	1-basierter Paketindex auf dieser Apothekenbestellung
`data.shipments[].carrier_name`	string	Carrier-Name, z. B. `DHL`, `DPD`, `UPS`, `Hermes`, `FedEx` oder `Other`
`data.shipments[].tracking_number`	string oder null	Tracking-Nummer des Carriers, sofern bekannt
`data.shipments[].tracking_url`	string oder null	HTTPS-Tracking-URL, sofern bekannt
`data.shipments[].service`	string oder null	Carrier-Produkt-/Servicecode, sofern bekannt (z. B. `V01PAK`)
`data.shipments[].return_tracking_number`	string oder null	Tracking-Nummer des Rücksendeetiketts, falls ausgestellt
`data.shipments[].return_label_expiry`	string oder null	Ablaufdatum des Rücksendeetiketts als `YYYY-MM-DD`, oder `null`
`data.shipments[].is_test`	boolean	`true`, wenn diese Sendung im Carrier-Testmodus gebucht wurde
`data.shipments[].created_at`	integer	Unix-Zeitstempel der Erfassung der Sendung

Interne Speicherorte der Etikettendateien sind nicht Bestandteil des Webhooks. Verwenden Sie tracking_url / tracking_number für die Sendungsverfolgung, nicht Speicherpfade.

Webhooks auf Organisationsebene

Wenn das Webhook-Abonnement über die Management API (auf Organisationsebene) erstellt wurde, unterscheiden sich Bestellereignisse wie folgt:

Die sku-Objekte in order_items und fulfillment.items werden um Shopify-Bezeichner (shop_variation_id, shop_product_external_id) erweitert.
Ein fulfillment-Objekt mit Details zur Fulfillment-Bestellung wird hinzugefügt.
prescription_file ist nicht enthalten.

{
  "event_type": "pharmacy_order_updated",
  "timestamp": 1711910000,
  "payload_version": "1",
  "data": {
    "uid": "po-abc123",
    "status": "in-progress",
    "...": "... gleiche Felder wie oben ...",
    "order_items": [
      {
        "uid": "oi-789",
        "amount": 1,
        "sku": {
          "uid": "sku-456",
          "display_name": "Medication X 100mg",
          "pzn": "12345678",
          "product_uid": "prod-789",
          "product_display_name": "Medication X",
          "standard_selling_unit": 1.0,
          "unit": "ml",
          "product_handle": "medication-x",
          "shop_variation_id": "48372910234",
          "shop_product_external_id": "93847261045"
        },
        "pharmacy_sku": {
          "uid": "psku-456",
          "external_id": "EXT-001",
          "price": 1299,
          "stock": 50
        },
        "total_paid_amount": 1299
      }
    ],
    "fulfillment": {
      "uid": "fo-abc123",
      "external_id": "EXT-FO-001",
      "items": [
        {
          "uid": "foi-001",
          "amount": 1,
          "status": "init",
          "external_id": "EXT-FOI-001",
          "order_item": {
            "uid": "oi-789",
            "amount": 1,
            "sku": {
              "uid": "sku-456",
              "display_name": "Medication X 100mg",
              "pzn": "12345678",
              "product_uid": "prod-789",
              "product_display_name": "Medication X",
              "standard_selling_unit": 1.0,
              "unit": "ml",
              "product_handle": "medication-x",
              "shop_variation_id": "48372910234",
              "shop_product_external_id": "93847261045"
            }
          }
        }
      ],
      "order": {
        "uid": "ord-123",
        "shop_order": {
          "uid": "so-456",
          "external_id": "SHOP-789",
          "shop_identifier": "my-shopify-store"
        }
      }
    }
  }
}

Feld	Typ	Beschreibung
`data.order_items[].sku.shop_variation_id`	string oder null	Shopify-Varianten-ID
`data.order_items[].sku.shop_product_external_id`	string oder null	Shopify-Produkt-ID
`data.fulfillment.uid`	string	UID der Fulfillment-Bestellung
`data.fulfillment.external_id`	string oder null	Externer Bezeichner der Fulfillment-Bestellung
`data.fulfillment.items[].order_item.sku.shop_variation_id`	string oder null	Shopify-Varianten-ID
`data.fulfillment.items[].order_item.sku.shop_product_external_id`	string oder null	Shopify-Produkt-ID
`data.fulfillment.order.uid`	string	UID der übergeordneten Bestellung
`data.fulfillment.order.shop_order.uid`	string	UID der Shop-Bestellung
`data.fulfillment.order.shop_order.external_id`	string oder null	Externer Bezeichner der Shop-Bestellung
`data.fulfillment.order.shop_order.shop_identifier`	string	Shop-Bezeichner

Das fulfillment-Feld und die Shopify-Bezeichner (shop_variation_id, shop_product_external_id) in sku-Objekten sind nur in Webhook-Zustellungen auf Organisationsebene enthalten. Webhooks auf Apothekenebene enthalten diese Felder nicht.

pharmacy_sku_stock_updated

Wird gesendet, wenn sich der Lagerbestand einer Apotheken-SKU ändert. Dies umfasst:

Direkte Bestandsaktualisierungen über die Pharmacy-API (PATCH /v1/.../pharmacy_skus/{uid}/stock oder Inventar-Endpunkte).
Automatische Bestandsreduzierung bei Abschluss einer Apothekenbestellung. Dies wird sowohl beim manuellen Abschluss (über die Apotheken-Oberfläche / API) als auch beim automatischen Abschluss ausgelöst, wenn RxScale über die Statusabfrage-Integration mit dem Backend der Apotheke erkennt, dass die Bestellung versendet oder abgeschlossen wurde. Pro Apotheken-SKU der abgeschlossenen Bestellung wird ein Event emittiert.

Payload-Beispiel

{
  "event_type": "pharmacy_sku_stock_updated",
  "timestamp": 1711900000,
  "payload_version": "1",
  "data": {
    "uid": "psku-abc123",
    "pharmacy_uid": "ph-xyz",
    "sku_uid": "sku-456",
    "external_id": "EXT-001",
    "price": 1299,
    "stock": 45,
    "reserved_amount": 7,
    "markup": 0,
    "priority": 0,
    "type": "default",
    "created_at": 1711800000,
    "updated_at": 1711900000,
    "deleted_at": null,
    "sku": {
      "uid": "sku-456",
      "display_name": "Medication X 100mg",
      "pzn": "12345678",
      "product_uid": "prod-789",
      "product_display_name": "Medication X",
      "standard_selling_unit": 1.0,
      "unit": "ml",
      "product_handle": "medication-x"
    }
  }
}

Feldreferenz

Feld	Typ	Beschreibung
`data.uid`	string	UID der Apotheken-SKU
`data.pharmacy_uid`	string	UID der Apotheke
`data.sku_uid`	string	UID der SKU
`data.external_id`	string oder null	Externer Bezeichner in Ihrem eigenen System
`data.price`	integer	Preis in Cent
`data.stock`	integer	Aktueller Lagerbestand
`data.reserved_amount`	integer	Für diese SKU reservierte Einheiten — Summe der Bestellpositionsmengen aller in Bearbeitung befindlichen Apothekenbestellungen (also Bestellungen, die weder abgeschlossen noch storniert sind). Verfügbarer Bestand kann als `stock - reserved_amount` berechnet werden.
`data.markup`	integer	Plattform-Aufschlag in Cent. Nur Webhook: Die External-Pharmacy-REST-SKU-Endpunkte lassen `markup`, `priority` und `type` bewusst weg (Plattform-Marge). Erwarten Sie dieselben Felder nicht bei `GET`/`PATCH` Pharmacy SKUs.
`data.priority`	integer	Prioritätsstufe (nur Webhook; in REST-SKU-Antworten weggelassen)
`data.type`	string	Typ der Apotheken-SKU (nur Webhook; in REST-SKU-Antworten weggelassen)
`data.created_at`	integer	Unix-Zeitstempel der Erstellung
`data.updated_at`	integer	Unix-Zeitstempel der letzten Aktualisierung
`data.deleted_at`	integer oder null	Unix-Zeitstempel der Löschung oder `null`
`data.sku`	object	Verschachtelte SKU- und Produktinformationen
`data.sku.uid`	string	UID der SKU
`data.sku.display_name`	string	Anzeigename der SKU
`data.sku.pzn`	string	Pharmazentralnummer (PZN)
`data.sku.product_uid`	string	UID des übergeordneten Produkts
`data.sku.product_display_name`	string oder null	Anzeigename des übergeordneten Produkts
`data.sku.standard_selling_unit`	number oder null	Standard-Verkaufseinheit der SKU
`data.sku.unit`	string oder null	Einheit der SKU, z.B. `ml` oder `g`
`data.sku.product_handle`	string oder null	URL-Handle/Slug des übergeordneten Produkts

Webhooks auf Organisationsebene

Wenn das Webhook-Abonnement über die Management API (auf Organisationsebene) erstellt wurde, enthalten Lagerbestandsereignisse zusätzliche Daten:

Das sku-Objekt wird um Shopify-Bezeichner (shop_variation_id, shop_product_external_id) erweitert.
Ein shop_identifier-Feld wird auf der data-Ebene hinzugefügt.

{
  "event_type": "pharmacy_sku_stock_updated",
  "timestamp": 1711900000,
  "payload_version": "1",
  "data": {
    "uid": "psku-abc123",
    "pharmacy_uid": "ph-xyz",
    "sku_uid": "sku-456",
    "external_id": "EXT-001",
    "price": 1299,
    "stock": 45,
    "reserved_amount": 7,
    "markup": 0,
    "priority": 0,
    "type": "default",
    "created_at": 1711800000,
    "updated_at": 1711900000,
    "deleted_at": null,
    "shop_identifier": "my-shopify-store",
    "sku": {
      "uid": "sku-456",
      "display_name": "Medication X 100mg",
      "pzn": "12345678",
      "product_uid": "prod-789",
      "product_display_name": "Medication X",
      "standard_selling_unit": 1.0,
      "unit": "ml",
      "product_handle": "medication-x",
      "shop_variation_id": "48372910234",
      "shop_product_external_id": "93847261045"
    }
  }
}

Feld	Typ	Beschreibung
`data.shop_identifier`	string oder null	Shop-Bezeichner
`data.sku.shop_variation_id`	string oder null	Shopify-Varianten-ID
`data.sku.shop_product_external_id`	string oder null	Shopify-Produkt-ID

Das shop_identifier-Feld und die Shopify-Bezeichner (shop_variation_id, shop_product_external_id) im sku-Objekt sind nur in Webhook-Zustellungen auf Organisationsebene enthalten. Webhooks auf Apothekenebene enthalten diese Felder nicht.

appointment_reminder_due

Wird gesendet, wenn eine konfigurierte Terminerinnerung fällig wird. Dieses Ereignis wird ausschließlich an Webhook-Abonnements auf Organisationsebene geliefert.

Erinnerungen können für den Patienten auch direkte Aktions-Links enthalten (Beitreten, Umbuchen, Stornieren) — über RxScales eigene E-Mail-/SMS-Inhalte. Die Felder rebook_allowed und cancel_allowed unten zeigen an, ob diese Aktionen aktuell verfügbar sind — sie sind ausschließlich true, wenn recipient_role gleich patient ist.

Payload-Beispiel

{
  "event_type": "appointment_reminder_due",
  "timestamp": 1893452400,
  "payload_version": "1",
  "data": {
    "appointment_uid": "appt-e2e-123",
    "organisation_uid": "org-abc123",
    "shop_uid": "shop-e2e-1",
    "appointment_type_reminder_uid": "reminder-e2e-1",
    "recipient_role": "doctor",
    "recipient_email": "doctor@example.com",
    "recipient_phone_number": "+491701234567",
    "recipient_display_name": "Dr. Grace Hopper",
    "patient_uid": "patient-e2e-1",
    "patient_display_name": "Ada Lovelace",
    "doctor_uid": "doctor-e2e-1",
    "doctor_display_name": "Dr. Grace Hopper",
    "appointment_type_uid": "type-e2e-1",
    "appointment_type_name": "Consultation",
    "visit_reason": "Medikationsreview vor Dosisanpassung",
    "start_date": 1893456000,
    "end_date": 1893457800,
    "estimated_duration_minutes": 30,
    "minutes_before": 60,
    "rebook_allowed": false,
    "cancel_allowed": false,
    "send_email": true,
    "send_sms": false
  }
}

Feldreferenz

Feld	Typ	Beschreibung
`data.appointment_uid`	string	UID des geplanten Termins
`data.organisation_uid`	string	UID der Organisation, zu der der Termin gehört
`data.shop_uid`	string oder null	Shop-UID des Patienten, falls verfügbar
`data.appointment_type_reminder_uid`	string	UID der Erinnerungsregel
`data.recipient_role`	string	Empfängerrolle: `patient`, `doctor` oder `admin`
`data.recipient_email`	string oder null	Aufgelöste Empfänger-E-Mail, falls verfügbar
`data.recipient_phone_number`	string oder null	Aufgelöste Empfänger-Telefonnummer, falls verfügbar
`data.recipient_display_name`	string oder null	Aufgelöster Anzeigename des Empfängers
`data.patient_uid`	string	Patientenprofil-UID
`data.patient_display_name`	string	Anzeigename des Patienten
`data.doctor_uid`	string	Arzt-UID
`data.doctor_display_name`	string	Anzeigename des Arztes
`data.appointment_type_uid`	string oder null	UID des Termintyps
`data.appointment_type_name`	string oder null	Name des Termintyps
`data.visit_reason`	string oder null	Optionaler Termingrund, angegeben beim Erstellen des Holds oder aktualisiert bei der Bestätigung
`data.start_date`	integer	Startzeit des Termins (Unix-Zeitstempel)
`data.end_date`	integer oder null	Endzeit des Termins (Unix-Zeitstempel), falls bekannt
`data.estimated_duration_minutes`	integer oder null	Geschätzte Dauer des Termins in Minuten
`data.minutes_before`	integer	Erinnerungsvorlauf in Minuten vor dem Termin
`data.rebook_allowed`	boolean	Ob der Patient den Termin aktuell über den Aktions-Link der Erinnerung umbuchen kann. Nur `true`, wenn `recipient_role` gleich `patient` ist, die Terminart patientenseitiges Umbuchen erlaubt und die zeitlichen Regeln (z. B. Mindestvorlauf) aktuell erfüllt sind
`data.cancel_allowed`	boolean	Ob der Patient den Termin aktuell über den Aktions-Link der Erinnerung stornieren kann. Nur `true`, wenn `recipient_role` gleich `patient` ist und die zeitlichen Regeln (z. B. Mindestvorlauf) aktuell erfüllt sind
`data.send_email`	boolean	Ob der RxScale-Notification-Handler für diese Erinnerung eine E-Mail senden soll
`data.send_sms`	boolean	Ob der RxScale-Notification-Handler für diese Erinnerung eine SMS senden soll

patient_doctor_meeting_updated

Wird gesendet, wenn eine Patient-Arzt-Besprechung ihren Lebenszyklus-Status ändert. Dieses Ereignis wird ausschließlich an Webhook-Abonnements auf Organisationsebene geliefert (registriert über die Management API). Mögliche change-Werte:

Wert	Wann ausgelöst
`held`	Ein geplanter Termin wurde gehalten (das Besprechungsfenster öffnete sich)
`confirmed`	Ein geplanter Termin wurde bestätigt
`expired`	Ein geplanter Termin ist abgelaufen, ohne beigetreten zu sein
`cancelled`	Eine Besprechung wurde storniert
`rebooked`	Eine Besprechung wurde umgebucht (eine neue Besprechung hat diese ersetzt)
`completed`	Eine Besprechung wurde abgeschlossen — eine On-Demand-Besprechung endete oder ein Arzt hat einen bestätigten Termin als abgeschlossen erfasst
`no_show`	Ein Arzt hat einen bestätigten Termin als Nichterscheinen erfasst (der Patient ist nicht erschienen)

Verwenden Sie change als maßgeblichen Indikator für das eingetretene Ereignis. status spiegelt den aktuellen Datenbankstatus der Besprechung wider und ist bei On-Demand-Besprechungen null.

Payload-Beispiel

{
  "event_type": "patient_doctor_meeting_updated",
  "timestamp": 1893456000,
  "payload_version": "1",
  "data": {
    "organisation_uid": "org-abc123",
    "meeting_uid": "m-e2e-1",
    "change": "confirmed",
    "status": "confirmed",
    "meeting_type": "consultation",
    "meeting_format": "digital",
    "start_date": 1893456000,
    "end_date": 1893456900,
    "estimated_duration_minutes": 15,
    "confirmed_at": 1893450000,
    "cancelled_at": null,
    "cancellation_reason": null,
    "visit_reason": "Medikationsreview vor Dosisanpassung",
    "expires_at": null,
    "previous_meeting_uid": null,
    "appointment_type_uid": "at-1",
    "doctor_uid": "doc-1",
    "patient_profile_uid": "pat-1"
  }
}

Feldreferenz

Feld	Typ	Beschreibung
`data.organisation_uid`	string	UID der Organisation, zu der die Besprechung gehört
`data.meeting_uid`	string	Eindeutiger Bezeichner der Besprechung
`data.change`	string	Der Lebenszyklus-Übergang, der dieses Ereignis ausgelöst hat — siehe Tabelle oben
`data.status`	string oder null	Aktueller Status der Besprechung. `null` bei On-Demand-Besprechungen; verwenden Sie stattdessen `change` für die Logik
`data.meeting_type`	string	Art der Besprechung (z.B. `consultation`)
`data.meeting_format`	string	Format der Besprechung (z.B. `digital`)
`data.start_date`	integer oder null	Unix-Zeitstempel des geplanten Starts (nur bei geplanten Terminen)
`data.end_date`	integer oder null	Unix-Zeitstempel des geplanten Endes bei geplanten Terminen. Dies ist der ursprünglich geplante Endzeitpunkt, nicht das tatsächliche Ende
`data.estimated_duration_minutes`	integer oder null	Geschätzte Dauer in Minuten
`data.confirmed_at`	integer oder null	Unix-Zeitstempel der Bestätigung oder `null`
`data.cancelled_at`	integer oder null	Unix-Zeitstempel der Stornierung oder `null`
`data.cancellation_reason`	string oder null	Grund für die Stornierung oder `null`
`data.visit_reason`	string oder null	Optionaler Termingrund, angegeben beim Erstellen des Holds oder aktualisiert bei der Bestätigung. Kann auch in Erinnerungen und synchronisierten Kalendereinladungen erscheinen
`data.expires_at`	integer oder null	Unix-Zeitstempel, nach dem der Besprechungslink abläuft, oder `null`
`data.previous_meeting_uid`	string oder null	UID der Besprechung, aus der diese umgebucht wurde, oder `null`. Gesetzt wenn `change` den Wert `rebooked` hat
`data.appointment_type_uid`	string oder null	UID des Termintyps (nur bei geplanten Terminen)
`data.doctor_uid`	string oder null	UID des zugeordneten Arztes
`data.patient_profile_uid`	string	UID des Patientenprofils. Dies ist der einzige Patientenbezeichner im Payload — es werden keine personenbezogenen Daten (Name, Geburtsdatum oder Kontaktdaten) übermittelt

E-Mail-Benachrichtigungen

Unabhängig von Webhooks kann eine Organisation RxScale den Patienten, den Arzt und/oder ihre Admins per E-Mail informieren lassen, wenn eine Besprechung bestätigt, storniert oder verschoben wird. Admins konfigurieren das im Tab “Benachrichtigungen” im Admin-Portal; standardmäßig ist es ausgeschaltet. confirmed ist unabhängig von den beiden anderen Änderungen abonnierbar — das Aktivieren erfordert nicht, dass auch E-Mails zu Absage oder Verschiebung aktiviert sind. Am Webhook-Verhalten ändert das nichts. Das Ereignis feuert weiterhin bei jedem oben aufgeführten Übergang, mit unverändertem Payload — unabhängig davon, ob ein E-Mail-Abonnement besteht. Der Webhook-Payload selbst bleibt durch dieses Feature unverändert. Ein Unterschied ist bei der Planung zu beachten: Eine Verschiebung veröffentlicht zwei Ereignisse — cancelled für die alte und rebooked für die neue Besprechung —, versendet aber höchstens eine E-Mail, nämlich die zur Verschiebung. Wenn Sie diesen Stream in Ihre eigene Patientenkommunikation spiegeln, wenden Sie dieselbe Regel an, sonst hört der Patient erst “storniert” und dann “verschoben”. confirmed ist nicht Teil einer Verschiebung und hat keine solche Paarung: Es wird einmalig für eine frische Buchung veröffentlicht und löst höchstens eine Bestätigungs-E-Mail aus.

Zustellung und Idempotenz

Webhooks werden mindestens einmal zugestellt. Ihr Endpunkt sollte Zustellungen als idempotent behandeln und die Kombination aus data.meeting_uid und data.change als eindeutigen Schlüssel verwenden — erneut zugestellte Events tragen dieselben Werte.

Erste Schritte

Externe Apotheken-API

Management-API

Scheduling API

Öffentliche API

Patienten-API

Anamnese-API

Webhooks

Anleitungen

Ereignisse

Webhook-Ereignisse

HTTP-Header

pharmacy_order_created

Payload-Beispiel

Feldreferenz

pharmacy_order_updated

Payload-Beispiel

Sendungen

Webhooks auf Organisationsebene

pharmacy_sku_stock_updated

Payload-Beispiel

Feldreferenz

Webhooks auf Organisationsebene

appointment_reminder_due

Payload-Beispiel

Feldreferenz

patient_doctor_meeting_updated

Payload-Beispiel

Feldreferenz

Abonnieren

E-Mail-Benachrichtigungen

Zustellung und Idempotenz

​Webhook-Ereignisse

​HTTP-Header

​pharmacy_order_created

​Payload-Beispiel

​Feldreferenz

​pharmacy_order_updated

​Payload-Beispiel

​Sendungen

​Webhooks auf Organisationsebene

​pharmacy_sku_stock_updated

​Payload-Beispiel

​Feldreferenz

​Webhooks auf Organisationsebene

​appointment_reminder_due

​Payload-Beispiel

​Feldreferenz

​patient_doctor_meeting_updated

​Payload-Beispiel

​Feldreferenz

​Abonnieren

​E-Mail-Benachrichtigungen

​Zustellung und Idempotenz

Webhook-Ereignisse

HTTP-Header

pharmacy_order_created

Payload-Beispiel

Feldreferenz

pharmacy_order_updated

Payload-Beispiel

Sendungen

Webhooks auf Organisationsebene

pharmacy_sku_stock_updated

Payload-Beispiel

Feldreferenz

Webhooks auf Organisationsebene

appointment_reminder_due

Payload-Beispiel

Feldreferenz

patient_doctor_meeting_updated

Payload-Beispiel

Feldreferenz

Abonnieren

E-Mail-Benachrichtigungen

Zustellung und Idempotenz