Externer Telemedizin-Connector¶

Bestellanfragen von externen Telemedizin- oder Rezeptplattformen über Ihre zugewiesene PharmaOne-Shop-URL einreichen.

Der Connector ist bewusst schmal: Partner erhalten nur einen API-Schlüssel und eine Shop-Basis-URL. Manager-Hostnames, JWT-Tausch, Bestandsrouten und andere PharmaOne-API-Endpunkte sind nicht nötig.

Wann diesen Connector nutzen¶

Szenario	Dieser Connector
Telemedizin-Plattform sendet Patientenbestellung + optionales Rezept-PDF	Ja
Partner soll nur die zugewiesene Shop-Domain aufrufen	Ja
Vollständiger ERP/POS-Sync (Bestellungen, Bestand, Berichte)	Nein — PharmaOne API Übersicht

Bereitstellungsmodell

Org-Owner legen einen Integrations-API-Schlüssel in Manager → Org Settings → Integrations an und teilen ihn zusammen mit der Shop-URL (z. B. https://your-shop.pharmaone.app). Der Schlüssel authentifiziert; die Shop-URL bestimmt Organisation und Shop der Bestellanfrage.

Architektur¶

sequenceDiagram
    participant TM as Telemedizin-Plattform
    participant Shop as P1 Shop (Ihre Domain)
    participant PO as PharmaOne

    TM->>Shop: POST /api/v1/external-order + apikey
    Note over Shop: Org und Shop aus zugewiesener URL
    Shop->>PO: Bestellanfrage weiterleiten
    PO-->>TM: 200 pending + Anfrage-ID
    Note over PO: Apotheken-Prüfung → Freigabe → Bestellung

Die Shop-URL bestimmt Organisation und Shop. org_id und shop_id werden nicht im Request-Body gesendet.

Endpunkt¶

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

{your-shop-domain} durch Ihre zugewiesene Shop-URL ersetzen (z. B. https://your-shop.pharmaone.app).

Authentifizierung¶

Integrations-API-Schlüssel auf eine der folgenden Arten senden:

Methode	Beispiel
Header `apikey`	`apikey: your-key-here`
Header `X-API-Key`	`X-API-Key: your-key-here`
Query-Parameter	`?apikey=your-key-here`

Status	Bedeutung
`401`	Fehlender oder ungültiger API-Schlüssel
`502`	Shop konnte PharmaOne nicht erreichen

Request-Body¶

Gleiche JSON-Hülle wie Bestellanfragen. Beim Shop-Endpunkt sind shop_id und org_id im Payload nicht erforderlich.

{
  "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"
      }
    ]
  }
}

Felder auf oberster Ebene¶

Feld	Pflicht	Beschreibung
`external_reference`	Empfohlen	Trace- / Idempotenz-Referenz
`source`	Empfohlen	Plattform-Kennung (Standard `shop:{shop_id}` wenn leer)
`payload`	Ja	Kunde, Positionen, optionale Rezeptdaten

Payload-Felder¶

Feld	Pflicht	Beschreibung
`customer_name`	Ja*	Vollständiger Name
`customer_email`	Ja*	E-Mail
`customer_id`	Nein	Bestehende PharmaOne-Kunden-ID
`address_street`	Nein	Straße
`address_city`	Nein	Stadt
`address_postal_code`	Nein	PLZ
`address_phone`	Nein	Telefon
`shipping_option`	Nein	`Abholung`, `Versand`, `Express`, `Uber Eats`
`cash_on_pickup`	Nein	Boolean (Standard `true`)
`payment_status`	Nein	`cash_on_pickup`, `paid`, `pending`
`payment_reference`	Nein	Zahlungstransaktions-ID
`total_amount`	Nein	Bestellsumme (EUR)
`prescription_pdf_base64`	Nein	Base64-Rezept-PDF
`prescription_pdf_url`	Nein	HTTPS-URL zum Rezept-PDF
`items`	Ja**	Positionen (siehe unten)

* Mindestens customer_name oder customer_email.

** Erforderlich, außer nur Rezept über prescription_pdf_base64 oder prescription_pdf_url (siehe Bestellanfragen).

Positionsfelder¶

Feld	Pflicht	Beschreibung
`name`	Ja*	Produktname
`quantity`	Ja	Ganzzahlige Menge
`price`	Ja	Stückpreis (EUR)
`p1_id`	Nein	PharmaOne-Katalog-ID
`product_id`	Nein	Alias für Produkt-ID

* Pro Position mindestens name, p1_id oder product_id.

Positionen nutzen quantity

Bestellanfragen nutzen quantity, nicht qty (beim direkten Order-Upsert).

Rezept-PDF anhängen¶

Telemedizin-Flows enthalten oft ein signiertes Rezept:

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

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

Ergebnis in payload.prescription_pdf_base64. Apotheken-Mitarbeiter können das PDF vor der Freigabe prüfen.

Erfolgsantwort — `200 OK`¶

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

Zurückgegebene id für Support und Abgleich speichern.

Fehlerantworten¶

Status	Typische Ursache
`400`	Fehlender Kundenname/E-Mail, ungültige Positionen, Shop/Org-Mismatch
`401`	Ungültiger API-Schlüssel
`500`	Serverfehler
`502`	Shop konnte PharmaOne nicht erreichen

Erfüllungsablauf¶

Einreichen — Telemedizin-Plattform POST an {shop}/api/v1/external-order.
Prüfung — Anfrage erscheint zur Mitarbeiter-Prüfung (pending).
Freigabe — Prüfung von Kundendaten, Rezept und Positionen.
Bestellung — Freigegebene Anfrage wird normale Apotheken-Bestellung.

Ausgehende order_request_submitted-Webhooks je nach Integrationsvereinbarung. Siehe Webhooks.

cURL-Beispiele¶

Minimale Bestellung (Abholung)¶

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 }
      ]
    }
  }'

Bestellung mit Rezept-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\" }
      ]
    }
  }"