Zum Hauptinhalt springen

weed.de-Integration

weed.de ist ein Cannabis-Marktplatz. Verkauft Ihre Apotheke über weed.de, schickt weed.de jede neue Bestellung an eine Webhook-URL, die Sie bei weed.de hinterlegen. Hinterlegen Sie dort eine RxScale-URL, dann kommt jede weed.de-Bestellung genauso in Ihrem Shop an wie die Bestellung eines anderen Telemedizin-Anbieters:
  1. weed.de schickt einen order.created-Webhook an RxScale.
  2. RxScale prüft das Rezept-PDF: Es muss eine qualifizierte elektronische Signatur (QES) tragen, wie bei allen anderen Telemedizin-Anbietern auch.
  3. RxScale legt in Ihrem Shop einen Shopify-Bestellentwurf (Draft Order) mit den Produkten, Preisen, Adressen und der Versandart der weed.de-Bestellung an.
  4. Eine auf weed.de bereits bezahlte Bestellung wird als bezahlt verbucht. Für eine noch nicht bezahlte Bestellung schickt Shopify der Patientin oder dem Patienten eine Rechnung.
  5. Shopify legt die Bestellung an, und sie kommt wie jede andere Shopify-Bestellung in RxScale an.
Den auf dieser Seite beschriebenen Endpoint ruft weed.de auf, nicht Sie selbst. Sie richten die Integration einmalig im RxScale-Admin-Tool und bei weed.de ein.

Voraussetzungen

  • Ihre Organisation betreibt in RxScale einen Shopify-Shop, und die Produkte, die Sie über weed.de verkaufen möchten, sind in diesem Shop vorhanden.
  • Der Shop verkauft in EUR. weed.de sendet alle Beträge in EUR, und RxScale setzt die Preise von weed.de im Bestellentwurf in EUR.
  • Ihre Apotheke hat Zugang zur Pharmacy API von weed.de (im API-Management von weed.de). Dort registrieren Sie Webhooks und pflegen Ihre Produktdaten.

Integration einrichten

1

Telemedizin-Anbieter für weed.de anlegen

Öffnen Sie im Admin-Tool Einstellungen → Telemedizin-Anbieter und wählen Sie Anbieter hinzufügen. Geben Sie einen Anzeigenamen (zum Beispiel weed.de) und eine Kennung (zum Beispiel weed) ein. Verknüpfen Sie einen API-Schlüssel mit der Berechtigung create_prescription_checkout, oder legen Sie einen neuen Schlüssel mit dieser Berechtigung an.weed.de sendet diesen API-Schlüssel nie, und Sie geben ihn auch nicht an weed.de weiter. RxScale legt anhand des Schlüssels fest, was die Integration tun darf.
2

Vorausbezahlte Bestellungen als bezahlt verbuchen

Öffnen Sie den neuen Anbieter. Wählen Sie unter Vorausbezahlte Bestellungen die Option Handhabung ändern, geben Sie zur Bestätigung die Kennung des Anbieters ein und wählen Sie Als bezahlt verbuchen.In der Regel bezahlt die Patientin oder der Patient direkt auf weed.de. Mit dieser Einstellung wird eine vorausbezahlte weed.de-Bestellung in Shopify als bezahlt verbucht, und es geht keine Zahlungsaufforderung an die Patientin oder den Patienten. Siehe Vorausbezahlte und offene Bestellungen.
3

Versandarten von weed.de zuordnen

Öffnen Sie Einstellungen → Versandmethoden-Zuordnungen und wählen Sie Zuordnung erstellen. Wählen Sie Ihren Shop und den weed.de-Anbieter. Tragen Sie als Externer Liefertyp den Versanddienstleister genau so ein, wie weed.de ihn bezeichnet (zum Beispiel DHL Standard), und als Shopify-Versandmethodentitel die passende Versandmethode Ihres Shops. Legen Sie für jeden Versanddienstleister, den Sie auf weed.de anbieten, eine Zuordnung an, und eine weitere für pickup (Abholung). Siehe Versandmethode.
4

weed.de-Produkte mit Ihren Shopify-Varianten verknüpfen

Setzen Sie in Ihren Produktdaten bei weed.de die externalId jedes Produkts auf die ID der zugehörigen Shopify-Produktvariante in Ihrem Shop. Das ist die Zahl am Ende der Adresse der Variante im Shopify-Adminbereich, zum Beispiel 44012345678901. Die GID der Variante, gid://shopify/ProductVariant/44012345678901, wird ebenfalls angenommen, jede andere GID — etwa die eines Produkts — dagegen nicht.weed.de verkauft grammweise, deshalb muss jede dieser Varianten für 1 g stehen. Siehe Preise und Mengen.
5

Webhook-URL bei weed.de registrieren

Registrieren Sie diese URL bei weed.de, und zwar nur für das Ereignis order.created:
Ersetzen Sie {shop_identifier} durch die Kennung Ihres Shops und {telemedicine_provider_uid} durch die UID des Anbieters aus Schritt 1. Die UID ist der letzte Teil der Adresse der Anbieterseite im Admin-Tool. Die Management API liefert sie außerdem als uid.weed.de prüft, ob die URL antwortet, bevor es sie annimmt. RxScale beantwortet diese Prüfung erfolgreich (siehe URL-Prüfung), und weed.de zeigt Ihnen anschließend ein Webhook-Secret an.
6

Webhook-Secret hinterlegen

Öffnen Sie im Admin-Tool wieder den weed.de-Anbieter. Tragen Sie unter Zugangsdaten das von weed.de angezeigte Secret als Webhook-Secret ein und speichern Sie es. Das Webhook-Secret wird danach als Hinterlegt angezeigt.Erledigen Sie das sofort: Solange das Secret fehlt, verarbeitet RxScale keine weed.de-Bestellungen. Siehe Solange kein Secret hinterlegt ist.
7

Testbestellung senden

Senden Sie bei weed.de eine Testbestellung und prüfen Sie, ob sie in Ihrem Shop ankommt. Eine Testbestellung wird wie eine echte Bestellung verarbeitet: Sie legt einen Bestellentwurf in Ihrem Shop an, und eine vorausbezahlte Testbestellung wird als bezahlt verbucht. Stornieren Sie sie in Shopify, sobald Sie sie geprüft haben.

Endpoint

string
erforderlich
Eindeutiger Bezeichner für den Shop
string
erforderlich
UID Ihres weed.de-Telemedizin-Anbieters. Der Anbieter muss zu der Organisation gehören, der der Shop gehört
string
erforderlich
Das Webhook-Secret, das weed.de bei der Registrierung der URL ausgegeben hat. weed.de sendet es bei jeder Zustellung mit
Erforderliche Berechtigung (am API-Schlüssel des Anbieters): create_prescription_checkout

Authentifizierung

weed.de kann keinen RxScale-API-Schlüssel senden. Stattdessen schreibt weed.de das Webhook-Secret selbst in den Header X-Signature jeder Zustellung. Anders als der Name vermuten lässt, enthält der Header keine über den Anfragekörper berechnete Signatur. RxScale vergleicht den Wert mit dem Webhook-Secret, das für den Anbieter hinterlegt ist. Leerzeichen vor oder nach dem Wert werden ignoriert. Eine Zustellung ohne diesen Header oder mit einem anderen Wert wird mit 401 abgelehnt. Ein RxScale-API-Schlüssel im Header X-API-Key ersetzt X-Signature nicht. Gibt Ihnen weed.de ein neues Secret, ersetzen Sie das hinterlegte unter Zugangsdaten — siehe Webhook-Secret wechseln. Bis dahin werden Zustellungen mit 401 abgelehnt.

Solange kein Secret hinterlegt ist

weed.de zeigt das Secret erst an, nachdem die URL die Prüfung bestanden hat. Solange für den Anbieter kein Webhook-Secret hinterlegt ist, beantwortet RxScale deshalb jede Anfrage an diese URL mit 200 und tut sonst nichts:
Shop und Anbieter werden zuerst geprüft. Eine URL mit einer Shop-Kennung oder Anbieter-UID, die es nicht gibt, oder mit dem Anbieter einer anderen Organisation, wird schon vor dem Hinterlegen eines Secrets mit 404 abgelehnt — die Prüfung durch weed.de schlägt dann fehl.
Solange kein Webhook-Secret hinterlegt ist, werden weed.de-Bestellungen zwar quittiert, aber nicht verarbeitet. weed.de wertet sie als zugestellt und sendet sie nicht erneut. Hinterlegen Sie das Secret direkt nach der Registrierung der URL, bevor Sie Bestellungen über weed.de annehmen, und entfernen Sie es nicht, solange Sie über weed.de verkaufen.

Webhook-Secret wechseln

Wenn Sie das hinterlegte Webhook-Secret entfernen, ist der Endpoint wieder im Zustand ohne Secret: weed.de-Bestellungen werden mit 200 und {"status": "not_configured"} beantwortet, Bestellungen aus dieser Zeit also quittiert, aber nicht angelegt. So wechseln Sie das Secret:
  1. Registrieren Sie den Webhook bei weed.de neu oder lassen Sie dort ein neues Secret erzeugen.
  2. Tragen Sie das neue Secret sofort im Admin-Tool unter Zugangsdaten ein und speichern Sie es. Das Speichern ersetzt das alte Secret; entfernen Sie das alte nicht vorher.
  3. Prüfen Sie das neue Secret mit der URL-Prüfung, oder senden Sie eine Testbestellung aus der Sandbox von weed.de.
Zustellungen, die weed.de mit dem neuen Secret sendet, bevor Sie es gespeichert haben, werden mit 401 abgelehnt. weed.de wiederholt sie, sodass sie ankommen, sobald das neue Secret gespeichert ist — vorausgesetzt, das geschieht vor der letzten Wiederholung durch weed.de (siehe Antworten und Wiederholungen). Würden Sie das Secret stattdessen entfernen, bekämen diese Zustellungen not_configured als Antwort, und weed.de würde sie nicht erneut senden.

URL-Prüfung

weed.de prüft die URL, bevor es die Registrierung annimmt. Für diese Prüfung beantwortet die URL auch GET und HEAD, mit denselben Pfadparametern und demselben Header X-Signature. Dabei wird kein Anfragekörper gelesen und nichts gespeichert oder gesendet — Sie können damit also auch selbst das hinterlegte Secret testen, ohne eine Bestellung anzulegen. HEAD antwortet mit demselben Status, aber ohne Antwortkörper.

Ereignisse

RxScale verarbeitet nur order.created. Jedes andere Ereignis wird mit 200 beantwortet und ändert nichts. Sein data wird nicht geprüft:

So wird eine weed.de-Bestellung übernommen

weed.de sendet jede Bestellung als {"event", "data", "timestamp"}, wobei data die Bestellung enthält. RxScale verwendet diese Felder aus data: Adressen werden so umgesetzt:
  • street und houseNr werden zu einer Adresszeile zusammengeführt, zum Beispiel Hauptstraße 42. Endet street bereits mit der Hausnummer, wird sie nicht ein zweites Mal angehängt: Main St 154 mit houseNr 154 bleibt Main St 154.
  • state wird zum Bundesland bzw. zur Region der Adresse.
  • country ist ein Ländername wie Germany und wird in den Ländercode umgewandelt. Eine Adresse ohne Land oder mit einem Ländernamen, der sich nicht zuordnen lässt, wird abgelehnt.
  • Eine Adresse, deren Felder alle leer sind, gilt als keine Adresse.
Produkte werden ausschließlich über externalId erkannt. Andere Produktfelder wie pzn oder name verändern den Bestellentwurf nicht: Jede Position zeigt die Variante aus Ihrem Shop. Felder, die hier nicht aufgeführt sind, werden weder verwendet noch geprüft, etwa customer.dateOfBirth, priceBreakdown.productsTotalPrice und priceBreakdown.totalPrice. Felder, die weed.de künftig zu seinen Webhooks hinzufügt, werden angenommen und ignoriert.

Bestellattribute

Zusätzlich zu den Attributen, die RxScale an die Bestellungen aller Telemedizin-Anbieter hängt, trägt die Shopify-Bestellung diese Attribute. Ein Attribut, dessen weed.de-Feld fehlt oder null ist, entfällt; true / false werden als Text geschrieben.

Preise und Mengen

Alle Beträge sind in EUR, und der Shop muss in EUR verkaufen. Mengen und Beträge müssen als JSON-Zahlen gesendet werden. Ein Wert, der als Text gesendet wird, etwa "10.50", wird abgelehnt. weed.de verkauft grammweise: products[].unit ist "g", und quantity ist die Anzahl Gramm. RxScale übernimmt die Menge als Anzahl Einheiten der Shopify-Variante. Jede Variante, die Sie auf weed.de anbieten, muss deshalb für 1 g stehen. Eine Menge von 5 bestellt fünf Einheiten der Variante, also 5 g.
  • Mengen müssen ganze Zahlen von 1 bis 1000 sein. 2.0 zählt als 2; eine Zustellung mit einer Menge wie 2.5, 0 oder 1001 wird abgelehnt.
  • Beträge: unitPrice, totalPrice und priceBreakdown.deliveryPrice müssen zwischen 0 und 99999.99 EUR liegen und dürfen höchstens zwei Nachkommastellen haben. Ein negativer Betrag oder einer wie 10.555 wird abgelehnt.
  • Produktpreise: Ist unitPrice gesetzt, ist das der Preis pro Einheit der Position im Bestellentwurf, in EUR, unabhängig davon, was die Variante in Shopify kostet. Ist unitPrice null, gilt der Shopify-Preis der Variante.
  • Summen: Sind unitPrice und totalPrice beide gesetzt, muss totalPrice genau unitPrice × quantity entsprechen. Andernfalls wird die Zustellung abgelehnt.
  • Versandpreis: priceBreakdown.deliveryPrice wird als Versandpreis übernommen, wenn weed.de ihn mitsendet. weed.de sendet priceBreakdown nur bei vorausbezahlten Bestellungen. Ohne diese Angabe gilt der Preis der zugeordneten Shopify-Versandmethode. Ein deliveryPrice setzt deliveryDetails.shippingProvider oder deliveryDetails.deliveryForm voraus, damit die Bestellung nie ohne den Versand verbucht wird, den die Patientin oder der Patient bezahlt hat. Eine Zustellung ohne beides wird abgelehnt.
Beispiel: Ein Produkt mit unitPrice 10.5 und quantity 2 wird zu einer Position mit zwei Einheiten zu je 10,50 €, insgesamt 21,00 €.

Vorausbezahlte und offene Bestellungen

Damit vorausbezahlte Bestellungen als bezahlt verbucht werden, brauchen Sie die Einstellung Als bezahlt verbuchen aus Schritt 2. Ohne sie bleibt eine vorausbezahlte weed.de-Bestellung ein unbezahlter Bestellentwurf in Shopify, und die Patientin oder der Patient erhält auch keine Zahlungsaufforderung. Eine verbuchte Bestellung lässt sich nicht wieder in einen Entwurf zurückverwandeln.
Verbucht Shopify eine vorausbezahlte Bestellung nicht als bezahlt, wird die Zustellung mit 502 beantwortet. Der code sagt, ob die Bestellung trotzdem verbucht sein könnte; siehe Vorausbezahlte Bestellungen.

Versandmethode

RxScale entnimmt die Versandart aus deliveryDetails.shippingProvider (zum Beispiel DHL Standard). Sendet weed.de keinen Versanddienstleister, wird stattdessen deliveryDetails.deliveryForm verwendet (zum Beispiel pickup). Dieser Wert wird in den Versandmethoden-Zuordnungen Ihres weed.de-Anbieters nachgeschlagen. Er muss exakt übereinstimmen, einschließlich Groß- und Kleinschreibung und Leerzeichen. Für die Versandposition gelten danach dieselben Regeln wie bei jedem Telemedizin-Anbieter, beschrieben unter Zuordnung der Versandmethode:
  • Mit Zuordnung trägt die Versandposition den Namen der zugeordneten Shopify-Versandmethode. Ihr Preis ist der Preis dieser Methode, es sei denn, weed.de hat einen anderen deliveryPrice gesendet.
  • Ohne Zuordnung wird eine Versandposition mit dem Wert von weed.de als Namen angelegt, sofern weed.de einen deliveryPrice gesendet hat. Ohne Preis erhält der Bestellentwurf keine Versandposition.

Beispiel-Zustellung

Sie können selbst eine Zustellung senden, um Ihre Einrichtung zu testen. Die folgende Anfrage ist gekürzt: weed.de sendet weitere Felder. Ersetzen Sie prescriptionBase64 durch den Base64-kodierten Inhalt eines signierten Rezept-PDFs und die externalId-Werte durch Varianten-IDs aus Ihrem Shop.
Eine Anfrage, die Sie selbst senden, wird wie eine echte weed.de-Bestellung verarbeitet. Sie legt einen Bestellentwurf in Ihrem Shop an, und mit "prepaid": true wird er als bezahlt verbucht.
Mit der Zuordnung für DHL Standard aus Schritt 3 entsteht ein Bestellentwurf mit zwei Positionen: zwei Einheiten zu 10,50 € und eine Einheit zu 7,00 €. Er erhält eine Versandposition für die zugeordnete Methode zu 4,99 €, die Rechnungsadresse Hauptstraße 42 und die Lieferadresse Nebenstraße 7, und er wird als bezahlt verbucht.

Antwort

prescriptions[].id ist die weed.de-Bestellnummer (data.id). prescription_uid identifiziert das Rezept in RxScale. Damit können Sie die Bestellung über den Bestellungen-Endpoint abfragen. Eine erfolgreiche Antwort kann zusätzlich eine 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. Derzeit ist ihr einziger Eintrag phone_not_forwarded mit field data.customer.phone: Die Bestellung wurde angenommen, aber customer.phone wurde nicht als Kontakttelefonnummer der Bestellung gesetzt, weil sich die Nummer nicht nach E.164 umwandeln ließ oder Shopify sie abgelehnt hat. Siehe Warnungen.

Antworten und Wiederholungen

weed.de wartet bis zu 30 Sekunden auf eine Antwort. Jede Antwort außer 2xx — und auch gar keine Antwort — gilt als fehlgeschlagene Zustellung. Im Produktivbetrieb wiederholt weed.de eine fehlgeschlagene order.created-Zustellung bis zu viermal: nach 5 Minuten, 30 Minuten, 1 Stunde und 2 Stunden. Jede Fehlerantwort enthält einen code — ausgenommen die 422 und die 400 bei nicht erreichbarem Signatur-Validierungsdienst. Siehe Reason-Codes der Public API.
details nennt jedes abgelehnte Feld mit seinem Pfad in der Zustellung. Eine Meldung zu einem Produkt nennt es mit seiner weed.de-id und seiner externalId; die gesendeten Werte werden in den Meldungen nie wiederholt. Alle Probleme werden gemeinsam gemeldet: hier die Menge 2.5 des zweiten Produkts und der totalPrice, der dadurch nicht mehr passt. Andere Felder werden genauso gemeldet, zum Beispiel data.customer.address.country mit Unknown country. oder Country is required., ein als Text gesendeter Wert mit Not a valid number., eine zu lange id mit Longer than maximum length 255., eine zu lange externalId mit Length must be between 1 and 255. und eine fehlende E-Mail-Adresse bei einer offenen Bestellung, data.customer.email, mit Required when prepaid is false: the patient is sent the invoice by email.
lines enthält jedes Produkt, dessen externalId keine Variante des Shops ist, mit der externalId und der quantity, die weed.de gesendet hat. Gefundene Produkte werden nicht aufgeführt.
Eine mit 4xx abgelehnte Zustellung legt nichts an: kein Rezept und keinen Bestellentwurf. Sobald Sie die Ursache behoben haben, zum Beispiel eine fehlende externalId oder ein falsches Secret, kann die nächste Wiederholung durch weed.de gelingen. Nach der letzten Wiederholung sendet weed.de die Bestellung nicht mehr.

Duplikate

Jede weed.de-Bestellung wird nur einmal angenommen. Eine erneute Zustellung einer bereits angenommenen Bestellung wird mit 409 beantwortet und legt nichts an. Der code ist duplicate_prescription_injection oder order_already_exists; behandeln Sie beide gleich:
duplicates[].id ist die weed.de-Bestellnummer. order_uid bleibt null, bis Shopify die Bestellung angelegt hat und sie in RxScale angekommen ist. Das passiert meist, wenn RxScale eine Bestellung angenommen hat, die Antwort aber nicht rechtzeitig bei weed.de angekommen ist. weed.de wertet die 409 als fehlgeschlagene Zustellung und wiederholt sie höchstens viermal. Jede Wiederholung wird wieder mit 409 beantwortet; Sie müssen nichts tun. Die einzige Ausnahme ist eine Bestellung, deren erste Zustellung mit 502 und draft_order_complete_uncertain beantwortet wurde: Wenden Sie sich dann an RxScale, damit die Bestellung abgeglichen wird. Eine Bestellung, deren frühere Zustellung abgelehnt wurde, ist nicht blockiert: Ihre nächste Zustellung wird ganz normal verarbeitet.

Siehe auch