External Telemedicine Connector¶

Submit order requests from external telemedicine or prescription platforms through your assigned PharmaOne shop URL.

This connector is intentionally narrow: partners receive an API key and a shop base URL only. They do not need Manager hostnames, JWT exchange, inventory routes, or other PharmaOne API endpoints.

When to use this connector¶

Scenario	Use this connector
Telemedicine platform sends a patient order + optional prescription PDF	Yes
Partner should only call their assigned shop domain	Yes
Full ERP/POS sync (orders, stock, reports)	No — use the PharmaOne API overview

Provisioning model

Org owners create an integration API key in Manager → Org Settings → Integrations and share it together with the shop URL (e.g. https://your-shop.pharmaone.app). The key authenticates the request; the shop URL determines which organization and shop the order request belongs to.

Architecture¶

sequenceDiagram
    participant TM as Telemedicine platform
    participant Shop as P1 Shop (your domain)
    participant PO as PharmaOne

    TM->>Shop: POST /api/v1/external-order + apikey
    Note over Shop: Resolves org and shop from your assigned URL
    Shop->>PO: Forward order request
    PO-->>TM: 200 pending + request id
    Note over PO: Pharmacy staff review → approve → order

Your shop URL determines which organization and shop the order request belongs to. You do not send org_id or shop_id in the request body.

Endpoint¶

POST https://{your-shop-domain}/api/v1/external-order
Content-Type: application/json
apikey: {your_integration_api_key}

Replace {your-shop-domain} with the shop URL assigned to you (e.g. https://your-shop.pharmaone.app).

Authentication¶

Send the integration API key using one of:

Method	Example
Header `apikey`	`apikey: your-key-here`
Header `X-API-Key`	`X-API-Key: your-key-here`
Query parameter	`?apikey=your-key-here`

Status	Meaning
`401`	Missing or invalid API key
`502`	Shop could not reach PharmaOne

Request body¶

Same JSON envelope as Order requests. You do not need shop_id or org_id in the payload when calling the shop endpoint.

{
  "external_reference": "TM-RX-2026-0042",
  "source": "external-telemedicine",
  "payload": {
    "customer_name": "Max Mustermann",
    "customer_email": "max@example.com",
    "address_street": "Musterstr. 1",
    "address_city": "Berlin",
    "address_postal_code": "10115",
    "address_phone": "+49123456789",
    "shipping_option": "Versand",
    "payment_status": "pending",
    "total_amount": 51.00,
    "prescription_pdf_base64": "<base64-encoded-pdf>",
    "items": [
      {
        "name": "Cannabis flos 27/1 Flapjacks",
        "quantity": 10,
        "price": 5.10,
        "p1_id": "12345"
      }
    ]
  }
}

Top-level fields¶

Field	Required	Description
`external_reference`	Recommended	Your trace / idempotency reference
`source`	Recommended	Platform identifier (defaults to `shop:{shop_id}` if omitted)
`payload`	Yes	Customer, items, and optional prescription data

Payload fields¶

Field	Required	Description
`customer_name`	Yes*	Full name
`customer_email`	Yes*	Email address
`customer_id`	No	Existing PharmaOne customer id
`address_street`	No	Street address
`address_city`	No	City
`address_postal_code`	No	Postal code
`address_phone`	No	Phone number
`shipping_option`	No	`Abholung`, `Versand`, `Express`, `Uber Eats`
`cash_on_pickup`	No	Boolean (default `true`)
`payment_status`	No	`cash_on_pickup`, `paid`, `pending`
`payment_reference`	No	Payment transaction id
`total_amount`	No	Order total (EUR)
`prescription_pdf_base64`	No	Base64-encoded prescription PDF
`prescription_pdf_url`	No	HTTPS URL to prescription PDF
`items`	Yes**	Line items (see below)

* At least one of customer_name or customer_email is required.

** Required unless submitting prescription-only data via prescription_pdf_base64 or prescription_pdf_url (see Order requests).

Item fields¶

Field	Required	Description
`name`	Yes*	Product name
`quantity`	Yes	Integer quantity
`price`	Yes	Unit price (EUR)
`p1_id`	No	PharmaOne catalog product id
`product_id`	No	Alias for product id

* At least one of name, p1_id, or product_id per line item.

Items use quantity

Order-request line items use quantity, not qty (which is used on direct order upsert).

Attaching a prescription PDF¶

Telemedicine flows often include a signed prescription document:

# macOS
PDF_B64=$(base64 -i prescription.pdf | tr -d '\n')

# Linux
PDF_B64=$(base64 -w 0 prescription.pdf)

Include the result in payload.prescription_pdf_base64. Pharmacy staff can review the PDF before approving the request.

Success response — `200 OK`¶

{
  "id": "e5347f5f-cdac-4f66-997f-c14ed1aab40f",
  "status": "pending",
  "message": "Order request received.",
  "external_reference": "TM-RX-2026-0042"
}

Store the returned id for support and reconciliation.

Error responses¶

Status	Typical cause
`400`	Missing customer name/email, invalid items, or shop/org mismatch
`401`	Invalid API key
`500`	Server error
`502`	Shop could not reach PharmaOne

Fulfillment flow¶

Submit — Telemedicine platform POSTs to {shop}/api/v1/external-order.
Review — Request appears for pharmacy staff review (pending).
Approve — Staff review customer data, prescription, and line items.
Order created — Approved request becomes a normal pharmacy order in the fulfillment pipeline.

Outbound order_request_submitted webhooks may be available depending on your integration agreement. See Webhooks.

cURL examples¶

Minimal order (pickup)¶

curl -X POST "https://YOUR-SHOP.pharmaone.app/api/v1/external-order" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d '{
    "external_reference": "TM-001",
    "source": "external-telemedicine",
    "payload": {
      "customer_name": "Max Mustermann",
      "customer_email": "max@example.com",
      "shipping_option": "Abholung",
      "items": [
        { "name": "Bedrocan 22/1", "quantity": 5, "price": 11.20 }
      ]
    }
  }'

Order with prescription PDF¶

PDF_B64=$(base64 -i prescription.pdf | tr -d '\n')

curl -X POST "https://YOUR-SHOP.pharmaone.app/api/v1/external-order" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d "{
    \"external_reference\": \"TM-RX-003\",
    \"source\": \"external-telemedicine\",
    \"payload\": {
      \"customer_name\": \"Max Mustermann\",
      \"customer_email\": \"max@example.com\",
      \"shipping_option\": \"Versand\",
      \"payment_status\": \"pending\",
      \"prescription_pdf_base64\": \"$PDF_B64\",
      \"items\": [
        { \"name\": \"Cannabis flos 27/1\", \"quantity\": 10, \"price\": 5.10, \"p1_id\": \"12345\" }
      ]
    }
  }"