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.create_prescription_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.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_pricefehlt 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_priceweicht 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 Ihrendelivery_type. Es wird eine Versandposition mit dem von Ihnen gesendetendelivery_priceerstellt. 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 gesendetedelivery_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 keindelivery.delivery_priceangegeben. 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."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.
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.Checkout-Typen
Das Feldcheckout_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 Sieprepaid: 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_requestsowie für Anfragen mitreserved_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
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 Listewarnings 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 einencode, 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:
prescriptions[].id:
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.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.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.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
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
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 einencode. 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:
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.