Zum Hauptinhalt springen

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.
string
erforderlich
Eindeutiger Bezeichner für den Shop
Erforderliche Berechtigung: create_prescription_checkout

Anfragekörper

Ein Rezept wird ausschließlich über lines[].prescription_id mit einer Bestellung verknüpft. Setzen Sie das Feld auf jeder Position, die das Rezept abdeckt. Ein Rezept, auf das keine Position verweist, wird trotzdem gespeichert und seine id ist verbraucht — eine erneute Übermittlung dieser prescriptions[].id wird mit 409 abgelehnt —, die entstehende Bestellung ist aber nicht mit ihm verknüpft. Eine prescription_id, die keiner prescriptions[].id derselben Anfrage entspricht, wird mit 400 abgelehnt, bevor etwas gespeichert wird.
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:
  1. 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.
  2. 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.
  3. 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.
Der Endpoint /medcanonestop ordnet sein Feld shipping über dieselbe Zuordnung zu, als delivery_type. MedCanOneStop sendet keinen eigenen Versandpreis. RxScale verwendet deshalb als delivery_price, was von totalGross nach Abzug der Produkte (price × quantity je Produkt) übrig bleibt: totalGross 18250 bei Produkten über 17250 ergibt einen Versandpreis von 1000 (10,00 €). Fehlt totalGross oder der price eines Produkts, oder ist totalGross niedriger als die Summe der Produkte, wird kein Preis verwendet, und es tritt Ergebnis 1 oder 3 ein. "shipping": "Abholung" wird genauso zugeordnet: Eine Abholung hat keine Lieferadresse, deshalb bietet Shopify dafür keinen Tarif an, und die Versandposition trägt den verbleibenden Preis, in der Regel 0. Bei einer vorausbezahlten Bestellung (prepaid: 1) ist die Versandposition Teil des als bezahlt gebuchten Betrags. Die Bestellattribute medcanonestop_shipping und medcanonestop_total_gross werden wie bisher angehängt.
Beispiel: ein zugeordneter Liefertyp ohne Preisüberschreibung
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:

Rabatte

Für einen Rabatt auf einen Bestellentwurf braucht es zwei Dinge: Sie fordern ihn in der Anfrage an, und RxScale hat ihn für Ihr Konto freigeschaltet. Fehlt eines von beiden, wird kein Rabatt angewendet. Bitten Sie Ihren RxScale-Kontakt, eine Option freizuschalten.
Was passiert, wenn eine Option für Ihr Konto nicht freigeschaltet ist: Einen Rabattcode, den Shopify nicht auf die Bestellung anwenden kann, etwa weil er abgelaufen ist oder die Produkte nicht abdeckt, überspringt Shopify ohne Fehler. Die Bestellung wird ohne diesen Rabatt erstellt.
Diese Regeln gelten für Bestellentwürfe (draft_order, draft_order_without_checkout_request und reservierte Bestellentwürfe). Bei checkout_type: "checkout_link" bezahlt der Kunde im regulären Store-Checkout: Automatische Rabatte greifen dort, der Kunde kann Codes eingeben, und discountCodes wird auf den Cart angewendet. apply_automatic_discounts und allow_discount_codes_in_checkout werden bei checkout_link ignoriert.
apply_automatic_discounts und allow_discount_codes_in_checkout lassen sich nicht mit prepaid: true kombinieren. Eine solche Anfrage wird mit 400 und code: "discounts_not_supported_with_prepaid" abgelehnt, weil der bereits eingezogene Betrag nicht mehr zur Bestellsumme passen würde. Aus demselben Grund wird discountCodes bei prepaid: true ignoriert: Die Bestellung wird ohne die Codes erstellt.
Geschenkgutscheine lassen sich über die API nicht auf einen Bestellentwurf anwenden. Der Kunde löst einen Geschenkgutschein im Checkout ein.

Checkout-Typen

Das Feld checkout_type steuert, wie die Bestellung in Shopify erstellt wird:
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.

Vorausbezahlte Bestellungen

Wenn Sie die Zahlung selbst von der Patientin oder dem Patienten einziehen, senden Sie prepaid: true. Standardmäßig wird damit nur die Shopify-Bestellung gekennzeichnet: Der Bestellentwurf bleibt unbezahlt und die Patientin oder der Patient erhält weiterhin eine Zahlungsaufforderung. RxScale kann pro Anbieter eine Behandlung aktivieren, die die Bestellung stattdessen als bezahlt verbucht. Das wird von RxScale konfiguriert und nicht über die API — wenden Sie sich dafür an Ihren RxScale-Kontakt. Ist es aktiviert, bewirkt eine Anfrage mit prepaid: true:
  • die Shopify-Bestellung wird als bezahlt verbucht, es wird keine Zahlungsaufforderung an die Patientin oder den Patienten gesendet;
  • es wird kein Geld eingezogen — die von Ihnen bereits eingezogene Zahlung läuft nicht über den Shop;
  • es gilt für checkout_type: "draft_order", draft_order_without_checkout_request sowie für Anfragen mit reserved_draft_order_id.
checkout_type: "checkout_link" ist davon nicht betroffen: Ein Checkout-Link existiert gerade, damit die Patientin oder der Patient bezahlt, es gibt also nichts als bezahlt zu verbuchen. Verwenden Sie für vorausbezahlte Warenkörbe einen Draft-Order-Checkout-Typ. Alles andere bleibt unverändert: Antwortformat, die 409-Regeln für Duplikate und die Webhooks sind dieselben. Eine verbuchte Bestellung kann nicht wieder in einen Entwurf zurückverwandelt werden — senden Sie prepaid: true daher nur, wenn die Zahlung wirklich eingezogen wurde. Dasselbe gilt für die anbieterspezifischen Endpunkte zur Rezeptübermittlung (zum Beispiel /docnow24, /medcanonestop), bei denen prepaid: 1 dieselbe Bedeutung hat. Schlägt das Verbuchen fehl, antwortet die Anfrage mit 502, und der code sagt, ob eine Wiederholung gefahrlos ist: Im unklaren Fall wird Ihre Übermittlung absichtlich behalten: Ist das Verbuchen doch durchgelaufen, würde eine Wiederholung eine zweite bezahlte Bestellung für denselben Warenkorb anlegen, und das lässt sich nicht zurücknehmen.

Beispielanfrage

Antwort

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.

Warnungen

Eine erfolgreiche Antwort kann eine optionale Liste warnings enthalten. Sie ist nur vorhanden, wenn es etwas zu melden gibt — prüfen Sie daher auf den Schlüssel, nicht auf eine leere Liste.
phone_not_forwarded bedeutet: Das Rezept wurde angenommen, aber buyerIdentity.phone wurde nicht als Kontakttelefonnummer der Bestellung gesetzt — entweder ließ sich die Nummer nicht nach E.164 umwandeln, oder Shopify hat sie als ungültig abgelehnt. Korrigieren Sie die Nummer auf Ihrer Seite; die Anfrage muss nicht wiederholt werden.

Fehlerantworten

Jeder Fehler-Body enthält einen code, mit Ausnahme des 422 unten. Verzweigen Sie darüber, nicht über den Status: siehe Reason-Codes der Public API. Eine lines[].prescription_id, die keinem hochgeladenen Rezept entspricht:
Doppelte prescriptions[].id:
Doppelte external_order_id (auch wenn prescriptions[].id neu ist):
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 Produkte, die einem Patienten nach einem Fragebogen angeboten wurden. Es wird kein Rezept hochgeladen: Wo ein Produkt eines braucht, stellt ein RxScale-Arzt es nach der Bezahlung aus. RxScale speichert zu dieser Anfrage nichts; die Bestellung kommt an, sobald der Patient bezahlt hat.
string
erforderlich
Eindeutiger Bezeichner für den Shop
Erforderliche Berechtigung: create_treatment_checkout

Anfragekörper

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.
pharmacy_uid wird beim Erstellen des Checkouts gegen Ihre Organisation geprüft. Wohin die Bestellung geht, entscheidet sich nach der Bezahlung. Damit sie diese Apotheke erreicht, muss die Apotheke mit dem Shop verbunden sein, und eine Apotheke, die Rezepte per E-Mail erhält, braucht zusätzlich ihre Adresse, gesendet als Eintrag pharmacy_email in attributes. Fehlt eines von beiden, geht die Bestellung möglicherweise nicht an diese Apotheke.
Die Regeln unter Rabatte oben gelten auch für diesen Endpoint. Er hat kein Feld prepaid, die Einschränkung für vorausbezahlte Bestellungen greift hier also nicht. Dem Bestellentwurf wird keine Versandzeile hinzugefügt.

Attribute

attributes der Bestellung und jeder Position gehen unverändert an Shopify und kommen mit der Bestellung an. Einige Schlüssel ändern, wie RxScale die Bestellung verarbeitet. Dieser Endpoint nimmt sie deshalb von einem Aufrufer nicht an. Eine Anfrage, die einen davon an der Bestellung oder an einer Position trägt, wird mit 400 abgelehnt; die Antwort nennt den Schlüssel:
  • _skip_validation
  • _rxscale_skip_validation
  • _doctor_uid
  • _rxscale_doctor_uid
Verwenden Sie die Felder der Anfrage statt Attributen, wo es eines gibt: lines[].anamnesis_id statt eines Positionsattributs _anamnesis_uid und pharmacy_uid statt eines Bestellattributs pharmacy_uid. Die Felder werden gegen Ihre Organisation geprüft, bevor der Checkout erstellt wird. Ein Tippfehler wird Ihnen so gemeldet und geht nicht später verloren. Wird beides gesendet, gilt das Feld.

Beispielanfrage

Antwort

Unter checkout_url bezahlt der Patient: der Checkout des Carts bei checkout_link, die Rechnungsseite des Bestellentwurfs bei draft_order und draft_order_without_checkout_request. Bei draft_order sendet Shopify diesen Link zusätzlich an buyerIdentity.email.

Fehlerantworten

Jeder Fehler-Body enthält einen code. Verzweigen Sie darüber, nicht über den Status: siehe Reason-Codes der Public API. Eine Anfrage, die mit einem dieser Codes oder von der Validierung abgelehnt wird, legt im Shop nichts an. Bei checkout_type: "draft_order" wird zuerst der Bestellentwurf angelegt und danach die Rechnungs-E-Mail gesendet. Kann die E-Mail nicht gesendet werden, schlägt die Anfrage fehl, obwohl der Bestellentwurf existiert. Senden Sie bei diesem Checkout-Typ immer buyerIdentity.email mit, und wiederholen Sie eine so gescheiterte Anfrage nicht unverändert: Jeder Versuch legt einen weiteren Bestellentwurf an. Ein abgelehnter Attributschlüssel:
Eine anamnesis_id, die nicht zu Ihrer Organisation gehört:

Umstieg vom bisherigen Treatments-Endpoint

Der Anfragekörper des bisherigen Treatments-Endpoints wird hier angenommen. Die meisten Integrationen ändern also die URL und die folgenden Punkte. Rabatte sind neu: Der bisherige Endpoint hat auf einen Bestellentwurf nie einen Rabatt angewendet. Siehe Rabatte.