Skip to main content

weed.de Integration

weed.de is a cannabis marketplace. When your pharmacy sells on weed.de, weed.de sends every new order to a webhook URL that you register with weed.de. Register an RxScale URL there, and each weed.de order arrives in your shop the same way as an order from any other telemedicine provider:
  1. weed.de sends an order.created webhook to RxScale.
  2. RxScale validates the prescription PDF: it must carry a qualified electronic signature (QES), as for every other telemedicine provider.
  3. RxScale creates a Shopify draft order in your shop with the products, prices, addresses and delivery method of the weed.de order.
  4. A prepaid weed.de order is booked as paid. For an order that is not yet paid, Shopify sends the patient an invoice.
  5. Shopify creates the order, and it arrives in RxScale like any other Shopify order.
weed.de calls the endpoint described on this page. You do not call it yourself: you set up the integration once in the RxScale Admin Tool and at weed.de.

Before You Start

  • Your organisation runs a Shopify shop in RxScale, and the products you want to sell on weed.de are in that shop.
  • The shop sells in EUR. weed.de sends every amount in EUR, and RxScale sets weed.de’s prices on the draft order in EUR.
  • Your pharmacy has access to the weed.de Pharmacy API (in weed.de’s API Management), where you register webhooks and manage your product data.

Set Up the Integration

1

Create a telemedicine provider for weed.de

In the Admin Tool, open Settings → Telemedicine providers and choose Add provider. Enter a display name (for example weed.de) and an identifier (for example weed). Attach an API key that has the create_prescription_checkout permission, or create a new one with that permission.weed.de never sends this API key, and you do not give it to weed.de. RxScale uses it to decide what the integration is allowed to do.
2

Book prepaid orders as paid

Open the new provider. Under Prepaid orders, choose Change handling, type the provider identifier to confirm, and choose Book prepaid orders as paid.Patients usually pay on weed.de. With this setting, a prepaid weed.de order is booked as paid in Shopify, and the patient receives no payment request. See Prepaid and Unpaid Orders.
3

Map weed.de's delivery methods

Open Settings → Shipping Method Mappings and choose Create Mapping. Select your shop and the weed.de provider. As External Delivery Type, enter the shipping provider exactly as weed.de names it (for example DHL Standard), and as Shopify Shipping Method Title the matching shipping method of your shop. Create one mapping for each shipping provider you offer on weed.de, and one for pickup. See Delivery Method.
4

Link your weed.de products to your Shopify variants

In your weed.de product data, set the externalId of every product to the ID of its Shopify product variant in your shop. That is the number at the end of the variant’s address in the Shopify admin, for example 44012345678901. The variant’s GID, gid://shopify/ProductVariant/44012345678901, is accepted as well; any other GID, such as a product’s, is not.weed.de sells by the gram, so each of these variants must stand for 1 g. See Prices and Quantities.
5

Register the webhook URL at weed.de

Register this URL at weed.de for the event order.created only:
Replace {shop_identifier} with your shop’s identifier and {telemedicine_provider_uid} with the UID of the provider you created in step 1. The UID is the last part of the provider page’s address in the Admin Tool. The Management API also returns it as uid.weed.de checks that the URL answers before it accepts it. RxScale answers that check successfully (see URL Check), and weed.de then shows you a webhook secret.
6

Enter the webhook secret

In the Admin Tool, open the weed.de provider again. Under Credentials, enter the secret weed.de showed you as Webhook secret and save it. The webhook secret then shows as Configured.Do this straight away: until the secret is stored, RxScale does not process weed.de orders. See Before the Secret Is Stored.
7

Send a test order

Send a test order (“Testbestellung”) from weed.de and check that it arrives in your shop. A test order is processed like a real one: it creates a draft order in your shop, and a prepaid test order is booked as paid. Cancel it in Shopify once you have checked it.

Endpoint

string
required
Unique identifier for the shop
string
required
UID of your weed.de telemedicine provider. The provider must belong to the organisation that owns the shop
string
required
The webhook secret weed.de issued when you registered the URL. weed.de sends it with every delivery
Required permission (on the API key attached to the provider): create_prescription_checkout

Authentication

weed.de cannot send an RxScale API key. Instead, weed.de puts the webhook secret itself into the X-Signature header of every delivery. Despite its name, the header carries no signature computed over the request body. RxScale compares the value with the webhook secret stored for the provider. Spaces before or after the value are ignored. A delivery without the header, or with a different value, is refused with 401. An RxScale API key sent in X-API-Key does not replace X-Signature. When weed.de gives you a new secret, replace the stored one under Credentials — see Changing the Webhook Secret. Until you do, deliveries are refused with 401.

Before the Secret Is Stored

weed.de only shows the secret after the URL has answered its check. So as long as no webhook secret is stored for the provider, RxScale answers every request to this URL with 200 and does nothing else:
The shop and the provider are checked first. A URL with a shop identifier or provider UID that does not exist, or with a provider of another organisation, is refused with 404 even before a secret is stored, so weed.de’s check fails.
While no webhook secret is stored, weed.de orders are acknowledged but not processed. weed.de counts them as delivered and does not send them again. Enter the secret right after registering the URL, before you take orders on weed.de, and do not remove it while you sell on weed.de.

Changing the Webhook Secret

Removing the stored webhook secret puts the endpoint back into the state without a secret: weed.de orders are answered with 200 and {"status": "not_configured"}, so orders delivered in that time are acknowledged but not created. To change the secret:
  1. Register the webhook again, or rotate the secret, at weed.de.
  2. Straight away, enter the new secret under Credentials in the Admin Tool and save it. Saving replaces the old secret; do not remove the old one first.
  3. Check the new secret with the URL check, or send a test order from weed.de’s sandbox.
Deliveries that weed.de sends with the new secret before you have saved it are refused with 401. weed.de retries them, so they arrive once the new secret is saved, as long as that happens before weed.de’s last retry (see Responses and Retries). Removing the secret instead would answer them with not_configured, and weed.de would not send them again.

URL Check

weed.de checks the URL before it accepts the registration. For that check the URL also answers GET and HEAD, with the same path parameters and the same X-Signature header. No request body is read, and nothing is stored or sent, so you can also use it yourself to test the stored secret without creating an order. HEAD answers with the same status and no body.

Events

RxScale processes order.created only. Every other event is answered with 200 and changes nothing. Its data is not checked:

How a weed.de Order Is Mapped

weed.de sends each order as {"event", "data", "timestamp"}, where data is the order. RxScale uses these fields of data: Addresses are converted as follows:
  • street and houseNr become one address line, for example Hauptstraße 42. When street already ends with the house number, it is not added a second time: Main St 154 with houseNr 154 stays Main St 154.
  • state becomes the state or province of the address.
  • country is a country name such as Germany, and is converted to its country code. An address without a country, or with a country name that cannot be recognised, is refused.
  • An address whose fields are all empty counts as no address.
Products are identified by externalId only. Other product fields, such as pzn or name, do not change the draft order: each line shows the variant from your shop. Fields not listed here are neither used nor checked, for example customer.dateOfBirth, priceBreakdown.productsTotalPrice and priceBreakdown.totalPrice. Fields that weed.de adds to its webhooks in the future are accepted and ignored.

Order Attributes

Next to the attributes RxScale adds to the orders of every telemedicine provider, the Shopify order carries these attributes. An attribute whose weed.de field is missing or null is left out, and true / false are written as text.

Prices and Quantities

All amounts are in EUR, and the shop must sell in EUR. Quantities and amounts must be sent as JSON numbers. A value sent as text, such as "10.50", is refused. weed.de sells by the gram: products[].unit is "g", and quantity is the number of grams. RxScale uses the quantity as the number of units of the Shopify variant, so each variant you list on weed.de must stand for 1 g. A quantity of 5 orders five units of the variant, that is 5 g.
  • Quantities must be whole numbers from 1 to 1000. 2.0 counts as 2; a delivery with a quantity such as 2.5, 0 or 1001 is refused.
  • Amounts: unitPrice, totalPrice and priceBreakdown.deliveryPrice must be between 0 and 99999.99 EUR, with at most two decimal places. A negative amount, or one such as 10.555, is refused.
  • Product prices: when unitPrice is set, it is the line’s price per unit in the draft order, in EUR, whatever the variant costs in Shopify. When unitPrice is null, the variant’s Shopify price applies.
  • Totals: when both unitPrice and totalPrice are set, totalPrice must equal unitPrice × quantity exactly. Otherwise the delivery is refused.
  • Shipping price: priceBreakdown.deliveryPrice is used as the shipping price when weed.de sends it. weed.de sends priceBreakdown for prepaid orders only. Without it, the price of the mapped Shopify shipping method applies. A deliveryPrice needs deliveryDetails.shippingProvider or deliveryDetails.deliveryForm, so that the order is never booked without the delivery the patient paid for. A delivery that has neither is refused.
For example, a product with unitPrice 10.5 and quantity 2 becomes a line of two units at €10.50 each, €21.00 in total.

Prepaid and Unpaid Orders

Booking prepaid orders as paid needs the Book prepaid orders as paid setting from step 2. Without it, a prepaid weed.de order stays an unpaid draft order in Shopify, and the patient receives no payment request either. A booked order cannot be turned back into a draft.
If Shopify does not book a prepaid order as paid, the delivery is answered with 502. The code says whether the order may have been booked anyway; see Prepaid Orders.

Delivery Method

RxScale takes the delivery method from deliveryDetails.shippingProvider (for example DHL Standard). When weed.de sends no shipping provider, it takes deliveryDetails.deliveryForm instead (for example pickup). It looks this value up in the shipping method mappings of your weed.de provider. The value must match exactly, including upper and lower case and spaces. The shipping line then follows the same rules as for every telemedicine provider, described under Shipping Method Mapping:
  • With a mapping, the shipping line carries the name of the mapped Shopify shipping method. Its price is that method’s price, unless weed.de sent a different deliveryPrice.
  • Without a mapping, a shipping line named after the weed.de value is added when weed.de sent a deliveryPrice. Without a price, the draft order gets no shipping line.

Example Delivery

You can send a delivery yourself to try your setup. The request below is shortened: weed.de sends more fields. Replace prescriptionBase64 with the Base64-encoded content of a signed prescription PDF, and the externalId values with variant IDs of your shop.
A request you send yourself is processed like a real weed.de order. It creates a draft order in your shop, and with "prepaid": true that order is booked as paid.
With the mapping DHL Standard from step 3, this creates a draft order with two lines: two units at €10.50 and one unit at €7.00. It has a shipping line for the mapped method at €4.99, the billing address Hauptstraße 42 and the shipping address Nebenstraße 7, and it is booked as paid.

Response

prescriptions[].id is the weed.de order number (data.id). prescription_uid identifies the prescription in RxScale. You can use it to look up the order with the Orders endpoint. A successful response can also carry a warnings list. It is only present when there is something to report, so check for the key rather than for an empty list. Currently its only entry is phone_not_forwarded with field data.customer.phone: the order was accepted, but customer.phone was not set as the contact phone number of the order, because it could not be converted to E.164 or Shopify rejected it. See Warnings.

Responses and Retries

weed.de waits up to 30 seconds for an answer. Any answer other than 2xx, and no answer at all, counts as a failed delivery. In production, weed.de retries a failed order.created delivery up to four times: after 5 minutes, 30 minutes, 1 hour and 2 hours. Every error body carries a code, except the 422 and the 400 for an unavailable signature-validation service. See Public API Reason Codes.
details names each refused field by its path in the delivery. A message about a product names it by its weed.de id and its externalId; messages never repeat the value that was sent. All problems are reported together: here the quantity 2.5 of the second product, and the totalPrice that no longer matches it. Other fields are reported the same way, for example data.customer.address.country with Unknown country. or Country is required., a value sent as text with Not a valid number., an overlong id with Longer than maximum length 255., an overlong externalId with Length must be between 1 and 255., and a missing email on an unpaid order, data.customer.email, with Required when prepaid is false: the patient is sent the invoice by email.
lines holds every product whose externalId is not a variant of the shop, with the externalId and quantity weed.de sent. Products that were found are not listed.
A delivery refused with a 4xx creates nothing: no prescription and no draft order. Once you have fixed the cause, for example a missing externalId or a wrong secret, the next retry from weed.de can succeed. After the last retry, weed.de does not send the order again.

Duplicates

Each weed.de order is accepted once. A second delivery of an order that was already accepted is answered with 409 and creates nothing. The code is duplicate_prescription_injection or order_already_exists; treat both the same way:
duplicates[].id is the weed.de order number. order_uid stays null until Shopify has created the order and it has arrived in RxScale. This usually happens when RxScale accepted an order but weed.de did not receive the answer in time. weed.de counts the 409 as a failed delivery and retries, at most four times. Each retry is answered with 409 again, and nothing needs to be done. The one exception is an order whose first delivery was answered with 502 and draft_order_complete_uncertain: contact RxScale so the order can be reconciled. An order whose earlier delivery was refused is not blocked: its next delivery is processed normally.

See Also