Rezepte & Behandlungen

Erstellen Sie Checkout-Sitzungen für Rezepte oder Behandlungen. Diese Endpoints übernehmen die Rezeptvalidierung, die Checkout-Erstellung und geben eine Checkout-URL oder einen Bestellentwurf zurück, über den der Patient seinen Kauf abschließen kann.

Rezept-Checkout erstellen

Laden Sie ein oder mehrere signierte Rezepte (als Base64-kodierte PDFs) zusammen mit Positionen und Patientendaten hoch, um einen Checkout zu erstellen.

POST /v2/public-api/prescriptions/{shop_identifier}

string

erforderlich

Eindeutiger Bezeichner für den Shop

Erforderliche Berechtigung: create_prescription_checkout

Anfragekörper

{
  "reserved_draft_order_id": "123",
  "prescriptions": [
    {
      "id": "my-prescription-001",
      "pdf_base64": "JVBERi0xLjQK..."
    }
  ],
  "lines": [
    {
      "sku_uid": "sku-456",
      "quantity": 1,
      "prescription_id": "my-prescription-001"
    }
  ],
  "patient_data": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "date_of_birth": 631152000,
    "gender": "male"
  },
  "buyerIdentity": {
    "email": "max.mustermann@example.com",
    "phone": "+4917612345678",
    "countryCode": "DE",
    "customerAccessToken": "shopify-customer-access-token"
  },
  "checkout_type": "draft_order",
  "prepaid": false,
  "external_order_id": "order-123",
  "delivery": {
    "delivery_type": "pickup",
    "delivery_price": 499
  },
  "transaction": {
    "transaction_id": "txn-123",
    "transaction_amount": 4299
  },
  "billing_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address1": "Hauptstraße 42",
    "city": "Berlin",
    "province": "",
    "country_code": "DE",
    "zip": "10115"
  },
  "shipping_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address1": "Hauptstraße 42",
    "city": "Berlin",
    "province": "",
    "country_code": "DE",
    "zip": "10115"
  }
}

Feld	Typ	Erforderlich	Beschreibung
`reserved_draft_order_id`	string	Nein	Shopify Legacy-DraftOrder-ID aus dem Produkte-Reservierungsendpoint. Wenn gesetzt, aktualisiert RxScale diesen Bestellentwurf, statt einen neuen Checkout zu erstellen
`prescriptions`	array	Nein	Liste der Rezeptobjekte mit `id` und `pdf_base64`
`prescriptions[].id`	string	Ja	Ihre interne ID für dieses Rezept (wird zur Verknüpfung mit Positionen verwendet). Höchstens 255 Zeichen
`prescriptions[].pdf_base64`	string	Ja	Base64-kodiertes PDF des signierten Rezepts
`lines`	array	Nein	Positionen für den Checkout
`lines[].sku_uid`	string	Bedingt	RxScale-SKU-UID aus dem Produktkatalog. Pro Position ist mindestens eines von `sku_uid` oder `external_id` erforderlich
`lines[].external_id`	string	Bedingt	Ihre Telemedizin-Anbieter-Produkt-ID (`telemedicine_provider_data.external_id` aus dem Produktkatalog). Wird über den mit dem API-Key verknüpften Anbieter aufgelöst. Wenn beide Identifikatoren gesendet werden, hat `sku_uid` Vorrang
`lines[].quantity`	integer	Ja	Zu bestellende Menge
`lines[].prescription_id`	string	Nein	Verknüpft die Position mit einem Rezept über dessen `id`
`patient_data`	object	Ja	Demografische Patientendaten
`patient_data.first_name`	string	Ja	Vorname des Patienten
`patient_data.last_name`	string	Ja	Nachname des Patienten
`patient_data.date_of_birth`	integer	Ja	Geburtsdatum als Unix-Zeitstempel
`patient_data.gender`	string	Ja	Geschlecht des Patienten (`male`, `female`, `divers`)
`buyerIdentity`	object	Bedingt	Shopify-Cart-Buyer-Identity. Erforderlich, wenn `checkout_type` `draft_order_without_checkout_request` ist; wird für `checkout_link`-Carts, Checkout-Anfragen für Bestellentwürfe und zum Überschreiben von E-Mail/Telefon auf einem reservierten Bestellentwurf verwendet
`buyerIdentity.email`	string	Nein	E-Mail-Adresse des Käufers
`buyerIdentity.phone`	string	Nein	Telefonnummer des Käufers
`buyerIdentity.countryCode`	string	Nein	Shopify-Ländercode des Käufers
`buyerIdentity.customerAccessToken`	string	Nein	Shopify-Storefront-Customer-Access-Token. Wenn er mit `checkout_type: "checkout_link"` gesendet wird, verknüpft Shopify den Cart mit dem Kundenkonto
`checkout_type`	string	Nein	Checkout-Typ: `checkout_link`, `draft_order` (Standard) oder `draft_order_without_checkout_request`
`prepaid`	boolean	Nein	Gibt an, ob die Bestellung bereits extern bezahlt wurde. Standardwert ist `false`; der Wert wird als Shopify-Bestellattribut `prepaid=true` oder `prepaid=false` angehängt. Das Feld ändert das Verhalten von `checkout_type` nicht
`external_order_id`	string	Nein	Ihre externe Bestell-ID. Wenn gesetzt, hängt RxScale sie als Shopify-Bestellattribut `external_order_id` an und behandelt sie pro Telemedizin-Anbieter als eindeutig (eine zweite erfolgreiche Übermittlung mit demselben Wert liefert `409`). Höchstens 255 Zeichen
`delivery`	object	Nein	Versandmethode für die Bestellung. Siehe Zuordnung der Versandmethode unten
`delivery.delivery_type`	string	Nein	Ihr eigener Bezeichner für die Versandmethode (zum Beispiel `"pickup"` oder `"express"`). Wenn ein RxScale-Administrator diesen Wert einer der Shopify-Versandmethoden des Stores zugeordnet hat, trägt die Versandposition der Bestellung den Namen dieser Methode; auch deren Preis wird übernommen, sofern Sie keinen abweichenden `delivery_price` senden. Ohne Zuordnung wird aus diesem Wert und `delivery_price` eine Versandposition erstellt. Der Abgleich erfolgt exakt, einschließlich Groß-/Kleinschreibung und Leerzeichen
`delivery.delivery_price`	integer	Nein	Versandpreis in der kleinsten Währungseinheit (z. B. `499` für 4,99 €). Stimmt er mit dem eigenen Preis der zugeordneten Shopify-Versandmethode überein, wird deren Preis für die Versandposition verwendet; weicht er ab, wird stattdessen Ihr Preis verwendet. Fehlt er, gilt der Preis der zugeordneten Methode
`transaction`	object	Nein	Transaktionsdaten, die als Attribute an die Shopify-Bestellung angehängt werden
`transaction.transaction_id`	string	Nein	Transaktions-ID, die als Attribut an die Shopify-Bestellung angehängt wird
`transaction.transaction_amount`	integer	Nein	Transaktionsbetrag, der als Attribut an die Shopify-Bestellung angehängt wird
`billing_address`	object	Nein	Rechnungsadresse, die an den Shopify-Bestellentwurf angehängt wird. Wird ignoriert, wenn `checkout_type` `checkout_link` ist
`billing_address.first_name`	string	Nein	Vorname des Empfängers
`billing_address.last_name`	string	Nein	Nachname des Empfängers
`billing_address.address1`	string	Nein	Einzeilige Straßenadresse inklusive Hausnummer
`billing_address.city`	string	Nein	Stadt
`billing_address.province`	string	Nein	Bundesland, Provinz oder Region. Gesetzt für Länder wie IE; wird als leerer String für Länder wie DE gesendet
`billing_address.country_code`	string	Nein	ISO-Ländercode
`billing_address.zip`	string	Nein	Postleitzahl
`shipping_address`	object	Nein	Lieferadresse, die an den Shopify-Bestellentwurf angehängt wird. Wird ignoriert, wenn `checkout_type` `checkout_link` ist
`shipping_address.first_name`	string	Nein	Vorname des Empfängers
`shipping_address.last_name`	string	Nein	Nachname des Empfängers
`shipping_address.address1`	string	Nein	Einzeilige Straßenadresse inklusive Hausnummer
`shipping_address.city`	string	Nein	Stadt
`shipping_address.province`	string	Nein	Bundesland, Provinz oder Region. Gesetzt für Länder wie IE; wird als leerer String für Länder wie DE gesendet
`shipping_address.country_code`	string	Nein	ISO-Ländercode
`shipping_address.zip`	string	Nein	Postleitzahl

buyerIdentity.customerAccessToken gilt nur, wenn checkout_type auf checkout_link gesetzt ist, da Shopify dieses Feld für Storefront-Carts verwendet. Es verknüpft kein Kundenkonto mit Shopify-Bestellentwürfen.

Senden Sie buyerIdentity, wenn Sie checkout_type: "draft_order_without_checkout_request" verwenden. RxScale lehnt die Anfrage ohne dieses Feld ab, weil keine Shopify-Checkout-Anfrage gesendet wird, über die Kundendaten später erfasst werden könnten.

Zuordnung der Versandmethode

delivery.delivery_type ist Ihr eigener Bezeichner für eine Versandmethode. Ein RxScale-Administrator kann jeden Ihrer delivery_type-Werte einer der Shopify-Versandmethoden des Stores zuordnen. Wenn Sie delivery senden, sucht RxScale nach einer Zuordnung für den exakt gesendeten Wert — der Abgleich unterscheidet Groß-/Kleinschreibung und Leerzeichen, sodass "Express" und "express" als unterschiedliche Werte gelten —, und eines von drei Ergebnissen tritt ein:

Es wird eine zugeordnete Shopify-Versandmethode gefunden, und delivery.delivery_price fehlt oder entspricht dem eigenen Preis dieser Methode. Die Versandposition übernimmt Namen und Preis dieser Methode. In Ihrem Shopify-Adminbereich erscheint sie dabei als benutzerdefinierte Versandposition — nicht als der eigene, aktive Tarif des Stores —, auch wenn Name und Preis exakt mit der zugeordneten Methode übereinstimmen.
delivery.delivery_price weicht vom Preis der zugeordneten Methode ab, Shopify bietet aktuell keinen aktiven Tarif unter dem Namen der zugeordneten Methode an, oder es existiert keine Zuordnung für Ihren delivery_type. Es wird eine Versandposition mit dem von Ihnen gesendeten delivery_price erstellt. Ihr Name ist der Name der zugeordneten Shopify-Versandmethode, sobald eine Zuordnung existiert — auch dann, wenn lediglich der Preis abweicht — und nur ohne Zuordnung der von Ihnen gesendete delivery_type.
Es existiert keine Zuordnung für Ihren delivery_type — oder es existiert eine, aber Shopify bietet aktuell keinen aktiven Tarif unter dem Namen dieser Methode an (zum Beispiel weil sie in Shopify umbenannt oder deaktiviert wurde) —, und es wurde kein delivery.delivery_price angegeben. Der Bestellung wird keine Versandposition hinzugefügt.

delivery.delivery_type und delivery.delivery_price werden weiterhin wie bisher als Shopify-Bestellattribute angehängt — unabhängig davon, welches der drei oben genannten Ergebnisse eintritt. Dies ist eine additive Änderung: Bestehende Integrationen, die diese Attribute auslesen, funktionieren unverändert weiter.

Die Zuordnung der Versandmethode gilt nur, wenn checkout_type draft_order oder draft_order_without_checkout_request ist. Bei checkout_type: "checkout_link" gibt RxScale einen Shopify-Storefront-Cart zurück, der keine Versandposition besitzt — der Kunde wählt seine Versandoption im eigenen Checkout-Prozess von Shopify.

Beispiel: ein zugeordneter Liefertyp ohne Preisüberschreibung

curl -X POST "https://api.rxscale.com/v2/public-api/prescriptions/my-shop" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      {
        "sku_uid": "sku-456",
        "quantity": 1
      }
    ],
    "patient_data": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "date_of_birth": 631152000,
      "gender": "male"
    },
    "delivery": {
      "delivery_type": "express"
    }
  }'

Hat Ihr Store "express" einer Shopify-Versandmethode zugeordnet, übernimmt die Versandposition der entstehenden Bestellung Namen und Preis dieser Methode (im Shopify-Adminbereich sichtbar als benutzerdefinierte Versandposition, nicht als aktiver Tarif des Stores). Die Checkout-Antwort ist unabhängig davon, welches Ergebnis eintritt, unverändert — die aufgelöste Versandposition ist auf dem Shopify-Bestellentwurf bzw. der Bestellung selbst sichtbar, nicht in dieser Antwort:

{
  "status": "success",
  "prescriptions": []
}

Checkout-Typen

Das Feld checkout_type steuert, wie die Bestellung in Shopify erstellt wird:

Wert	Beschreibung
`draft_order`	Erstellt einen Shopify-Bestellentwurf und sendet eine Checkout-Anfrage an den Kunden (Standard)
`checkout_link`	Gibt einen Shopify-Checkout-Link zurück, über den der Kunde die Zahlung direkt abschließen kann
`draft_order_without_checkout_request`	Erstellt einen Shopify-Bestellentwurf, ohne eine Checkout-Anfrage an den Kunden zu senden. Erfordert `buyerIdentity`, weil Kundendaten nicht über eine Shopify-Checkout-Anfrage erfasst werden

Wenn reserved_draft_order_id gesetzt ist, wird checkout_type ignoriert. RxScale speichert die signierten Rezepte und ergänzt _prescription_uid-Metadaten an den passenden reservierten Draft-Order-Positionen (nicht an Bestell-Attributen auf Order-Ebene). Die Zuordnung erfolgt über die Shopify-Variante aus sku_uid; doppelte sku_uid-Werte werden abgelehnt, weil sie nicht eindeutig sind. Schlüssel mit führendem _ sind private Shopify-Properties und in der Shopify-Admin-UI oft ausgeblendet — prüfen Sie sie bei Bedarf über die Admin-GraphQL-API. Wenn buyerIdentity.email und/oder buyerIdentity.phone gesetzt (und nicht leer) sind, überschreiben sie die Käuferkontaktdaten des reservierten Bestellentwurfs; leere Werte werden ignoriert, sodass vorhandene Kontaktdaten nie gelöscht werden. Die billing_address und shipping_address aus der Anfrage werden an den Bestellentwurf übergeben; der Name des Patienten aus patient_data wird in jede Adresse eingesetzt, sofern dort kein Name angegeben ist (Shopify-Bestellentwürfe haben kein separates Kundennamensfeld). Der reservierte Bestellentwurf muss zum Telemedizin-Anbieter gehören, der mit dem API-Schlüssel verknüpft ist.

Beispielanfrage

curl -X POST "https://api.rxscale.com/v2/public-api/prescriptions/my-shop" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reserved_draft_order_id": "123",
    "prescriptions": [
      {
        "id": "rx-001",
        "pdf_base64": "JVBERi0xLjQK..."
      }
    ],
    "lines": [
      {
        "sku_uid": "sku-456",
        "quantity": 1,
        "prescription_id": "rx-001"
      }
    ],
    "patient_data": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "date_of_birth": 631152000,
      "gender": "male"
    },
    "buyerIdentity": {
      "email": "max.mustermann@example.com",
      "phone": "+4917612345678",
      "countryCode": "DE",
      "customerAccessToken": "shopify-customer-access-token"
    },
    "prepaid": false,
    "external_order_id": "order-123",
    "delivery": {
      "delivery_type": "pickup",
      "delivery_price": 499
    },
    "transaction": {
      "transaction_id": "txn-123",
      "transaction_amount": 4299
    },
    "billing_address": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "address1": "Hauptstraße 42",
      "city": "Berlin",
      "province": "",
      "country_code": "DE",
      "zip": "10115"
    },
    "shipping_address": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "address1": "Hauptstraße 42",
      "city": "Berlin",
      "province": "",
      "country_code": "DE",
      "zip": "10115"
    }
  }'

Antwort

{
  "status": "success",
  "prescriptions": [
    {
      "id": "rx-001",
      "prescription_uid": "px-abc123"
    }
  ]
}

Die Antwort ordnet Ihre Rezept-IDs den RxScale-Rezept-UIDs zu. Verwenden Sie diese UIDs, um den Bestellstatus über den Bestellungen-Endpoint abzufragen. Wenn reserved_draft_order_id verwendet wird, erstellt RxScale keinen neuen Checkout und keinen neuen Bestellentwurf. Der vorhandene reservierte Bestellentwurf wird aktualisiert und kann nach der Zahlung den normalen Shopify-Bestell- und Fulfillment-Prozess durchlaufen.

Fehlerantworten

Statuscode	Beschreibung
`400`	Dieselbe `prescriptions[].id` kommt mehrfach in derselben Anfrage vor
`409`	Eine `prescriptions[].id` oder eine `external_order_id` wurde für diesen Telemedizin-Anbieter bereits erfolgreich akzeptiert. Es wird kein neues Rezept, PDF oder keine neue Bestellung erstellt
`422`	Ein Rezept-PDF ist nicht digital signiert (QES) und unsignierte Rezepte sind für Ihren Anbieter nicht erlaubt
`400`	Der Signatur-Validierungsdienst war nicht verfügbar, daher konnte die Rezeptsignatur nicht geprüft werden. Es wird kein Rezept und keine Bestellung erstellt — die Anfrage kann gefahrlos wiederholt werden

Doppelte prescriptions[].id:

{
  "code": "duplicate_prescription_injection",
  "error": "Duplicate prescription injection: prescription id(s) ['rx-123'] already submitted by provider your-provider (existing prescription(s) ['px-abc123']); no order created.",
  "duplicates": [
    {
      "id": "rx-123",
      "prescription_uid": "px-abc123",
      "order_uid": null
    }
  ]
}

Doppelte external_order_id (auch wenn prescriptions[].id neu ist):

{
  "code": "order_already_exists",
  "error": "Duplicate external_order_id: 'order-123' already submitted by provider your-provider (existing prescription px-abc123); no order created.",
  "external_order_id": "order-123",
  "prescription_uid": "px-abc123",
  "order_uid": null
}

code entspricht der Management-API-Antwort bei doppelter Bestellannahme, sodass Retries dieselbe Behandlung nutzen können. Verwenden Sie prescription_uid mit dem Bestellungen-Endpoint, solange order_uid noch null ist (typisch direkt nach der Übermittlung, bevor Shopify die Bestellung anlegt).

Eine prescriptions[].id oder external_order_id wird erst blockiert, wenn sie erfolgreich akzeptiert wurde. Ist eine frühere Anfrage fehlgeschlagen (zum Beispiel mit einem 4xx/5xx-Status vor Abschluss), wird ein erneutes Senden desselben Werts nicht blockiert und normal verarbeitet. Dadurch kann die Rezeptübermittlung nach einer fehlgeschlagenen oder unklaren Anfrage gefahrlos wiederholt werden — eine erneute Übermittlung einer bereits akzeptierten ID liefert 409 statt stillschweigend eine doppelte Bestellung zu erzeugen, und kann daher als idempotenter No-op statt als alarmierender Fehler behandelt werden.

Diese Prüfungen gelten für alle Rezeptübermittlungswege, die diesen Endpoint gemeinsam nutzen, einschließlich anbieterspezifischer Integrationen (zum Beispiel medcanonestop, dransay) und Aktualisierungen reservierter Bestellentwürfe (reserved_draft_order_id).

Behandlungs-Checkout erstellen

Erstellen Sie einen Checkout für behandlungsbasierte Bestellungen (kein Rezept erforderlich).

POST /v2/public-api/treatments/{shop_identifier}

string

erforderlich

Eindeutiger Bezeichner für den Shop

Erforderliche Berechtigung: create_treatment_checkout

Anfragekörper

{
  "lines": [
    {
      "sku_uid": "sku-789",
      "quantity": 1,
      "anamnesis_id": "anam-001"
    }
  ],
  "buyerIdentity": {
    "email": "max.mustermann@example.com",
    "phone": "+4917612345678",
    "countryCode": "DE",
    "customerAccessToken": "shopify-customer-access-token"
  },
  "checkout_type": "draft_order"
}

Feld	Typ	Erforderlich	Beschreibung
`lines`	array	Ja	Positionen für den Checkout
`lines[].sku_uid`	string	Ja	SKU-UID aus dem Produktkatalog
`lines[].quantity`	integer	Ja	Zu bestellende Menge
`lines[].anamnesis_id`	string	Nein	Anamnese-ID zur Verknüpfung mit einem Patientenfragebogen
`buyerIdentity`	object	Bedingt	Shopify-Cart-Buyer-Identity. Erforderlich, wenn `checkout_type` `draft_order_without_checkout_request` ist; wird für `checkout_link`-Carts, Checkout-Anfragen für Bestellentwürfe und zum Überschreiben von E-Mail/Telefon auf einem reservierten Bestellentwurf verwendet
`buyerIdentity.email`	string	Nein	E-Mail-Adresse des Käufers
`buyerIdentity.phone`	string	Nein	Telefonnummer des Käufers
`buyerIdentity.countryCode`	string	Nein	Shopify-Ländercode des Käufers
`buyerIdentity.customerAccessToken`	string	Nein	Shopify-Storefront-Customer-Access-Token. Wenn er mit `checkout_type: "checkout_link"` gesendet wird, verknüpft Shopify den Cart mit dem Kundenkonto
`checkout_type`	string	Nein	Checkout-Typ: `checkout_link`, `draft_order` (Standard) oder `draft_order_without_checkout_request`

Siehe Checkout-Typen oben für Details zu den einzelnen Optionen.

Beispielanfrage

curl -X POST "https://api.rxscale.com/v2/public-api/treatments/my-shop" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      {
        "sku_uid": "sku-789",
        "quantity": 1
      }
    ],
    "buyerIdentity": {
      "email": "max.mustermann@example.com",
      "phone": "+4917612345678",
      "countryCode": "DE",
      "customerAccessToken": "shopify-customer-access-token"
    }
  }'

Antwort

{
  "status": "success",
  "checkout_url": "https://shop.example.com/checkout/abc123"
}

Erste Schritte

Externe Apotheken-API

Management-API

Scheduling API

Öffentliche API

Patienten-API

Anamnese-API

Webhooks

Anleitungen

Rezepte & Behandlungen

Rezepte & Behandlungen

Rezept-Checkout erstellen

Anfragekörper

Zuordnung der Versandmethode

Checkout-Typen

Beispielanfrage

Antwort

Fehlerantworten

Behandlungs-Checkout erstellen

Anfragekörper

Beispielanfrage

Antwort

​Rezepte & Behandlungen

​Rezept-Checkout erstellen

​Anfragekörper

​Zuordnung der Versandmethode

​Checkout-Typen

​Beispielanfrage

​Antwort

​Fehlerantworten

​Behandlungs-Checkout erstellen

​Anfragekörper

​Beispielanfrage

​Antwort

Rezepte & Behandlungen

Rezept-Checkout erstellen

Anfragekörper

Zuordnung der Versandmethode

Checkout-Typen

Beispielanfrage

Antwort

Fehlerantworten

Behandlungs-Checkout erstellen

Anfragekörper

Beispielanfrage

Antwort