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:- weed.de schickt einen
order.created-Webhook an RxScale. - RxScale prüft das Rezept-PDF: Es muss eine qualifizierte elektronische Signatur (QES) tragen, wie bei allen anderen Telemedizin-Anbietern auch.
- RxScale legt in Ihrem Shop einen Shopify-Bestellentwurf (Draft Order) mit den Produkten, Preisen, Adressen und der Versandart der weed.de-Bestellung an.
- 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.
- Shopify legt die Bestellung an, und sie kommt wie jede andere Shopify-Bestellung in RxScale an.
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 Ersetzen Sie
order.created:{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
UID Ihres weed.de-Telemedizin-Anbieters. Der Anbieter muss zu der Organisation gehören, der der Shop gehört
Das Webhook-Secret, das weed.de bei der Registrierung der URL ausgegeben hat. weed.de sendet es bei jeder Zustellung mit
create_prescription_checkout
Authentifizierung
weed.de kann keinen RxScale-API-Schlüssel senden. Stattdessen schreibt weed.de das Webhook-Secret selbst in den HeaderX-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 mit200 und tut sonst nichts:
404 abgelehnt — die Prüfung durch weed.de schlägt dann fehl.
Webhook-Secret wechseln
Wenn Sie das hinterlegte Webhook-Secret entfernen, ist der Endpoint wieder im Zustand ohne Secret: weed.de-Bestellungen werden mit200 und {"status": "not_configured"} beantwortet, Bestellungen aus dieser Zeit also quittiert, aber nicht angelegt. So wechseln Sie das Secret:
- Registrieren Sie den Webhook bei weed.de neu oder lassen Sie dort ein neues Secret erzeugen.
- 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.
- Prüfen Sie das neue Secret mit der URL-Prüfung, oder senden Sie eine Testbestellung aus der Sandbox von weed.de.
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
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 nurorder.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:
streetundhouseNrwerden zu einer Adresszeile zusammengeführt, zum BeispielHauptstraße 42. Endetstreetbereits mit der Hausnummer, wird sie nicht ein zweites Mal angehängt:Main St 154mithouseNr154bleibtMain St 154.statewird zum Bundesland bzw. zur Region der Adresse.countryist ein Ländername wieGermanyund 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.
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 odernull 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
1bis1000sein.2.0zählt als2; eine Zustellung mit einer Menge wie2.5,0oder1001wird abgelehnt. - Beträge:
unitPrice,totalPriceundpriceBreakdown.deliveryPricemüssen zwischen0und99999.99EUR liegen und dürfen höchstens zwei Nachkommastellen haben. Ein negativer Betrag oder einer wie10.555wird abgelehnt. - Produktpreise: Ist
unitPricegesetzt, ist das der Preis pro Einheit der Position im Bestellentwurf, in EUR, unabhängig davon, was die Variante in Shopify kostet. IstunitPricenull, gilt der Shopify-Preis der Variante. - Summen: Sind
unitPriceundtotalPricebeide gesetzt, musstotalPricegenauunitPrice×quantityentsprechen. Andernfalls wird die Zustellung abgelehnt. - Versandpreis:
priceBreakdown.deliveryPricewird als Versandpreis übernommen, wenn weed.de ihn mitsendet. weed.de sendetpriceBreakdownnur bei vorausbezahlten Bestellungen. Ohne diese Angabe gilt der Preis der zugeordneten Shopify-Versandmethode. EindeliveryPricesetztdeliveryDetails.shippingProvideroderdeliveryDetails.deliveryFormvoraus, damit die Bestellung nie ohne den Versand verbucht wird, den die Patientin oder der Patient bezahlt hat. Eine Zustellung ohne beides wird abgelehnt.
unitPrice 10.5 und quantity 2 wird zu einer Position mit zwei Einheiten zu je 10,50 €, insgesamt 21,00 €.
Vorausbezahlte und offene Bestellungen
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 ausdeliveryDetails.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
deliveryPricegesendet. - Ohne Zuordnung wird eine Versandposition mit dem Wert von weed.de als Namen angelegt, sofern weed.de einen
deliveryPricegesendet 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 SieprescriptionBase64 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.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ßer2xx — 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.
401 — X-Signature fehlt oder ist falsch
401 — X-Signature fehlt oder ist falsch
404 — unbekannter Shop oder Anbieter
404 — unbekannter Shop oder Anbieter
400 — eine Menge, die keine ganze Zahl ist
400 — eine Menge, die keine ganze Zahl ist
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.404 — Produkte, die es im Shop nicht gibt
404 — Produkte, die es im Shop nicht gibt
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.500 — Einrichtung des Anbieters unvollständig
500 — Einrichtung des Anbieters unvollständig
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 mit409 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
- Rezepte & Behandlungen — der generische Checkout-Endpoint, die Zuordnung der Versandmethode und vorausbezahlte Bestellungen
- Bestellungen — Bestellstatus anhand der Rezept-UID abfragen
- Telemedizin-Anbieter — Ihre Anbieter und deren UIDs auflisten
- Fehlerbehandlung — Fehlerformate und Reason-Codes der Public API