Data models & schemas¶

Canonical JSON shapes for the PharmaOne API, webhooks, and the External Telemedicine Connector.

The same definitions live in two places:

Location	Use
OpenAPI spec	Machine-readable — Swagger UI, Postman, codegen
Interactive API Explorer	Browse schemas under Schemas per endpoint

Schema index¶

Common¶

Schema	Description
`Error`	API error body (`error`, optional `message`)
`TokenResponse`	JWT from `POST /auth/token`
`PaginationOffset`	`limit`, `offset`, `total`
`PaginationPage`	`page`, `pageSize`, `total`, `totalPages`

Shops & products¶

Schema	Description
`Shop`	Shop list item
`ShopProduct`	Product in shop catalog
`ProductListResponse`	Paginated product list
`ProductUpdate`	`PUT /products/{p1Id}` body
`AddToInventoryRequest`	Add catalog product to org inventory
`ShopProductAttach`	Attach product to shop
`ShopProductDetach`	Detach product from shop
`ShopProductOverrides`	Shop-specific product overrides

Inventory¶

Schema	Description
`InventoryRow`	Org inventory line
`InventoryListResponse`	`GET /inventory` wrapper
`InventoryAdjustRequest`	Stock adjustment body
`InventoryAdjustResponse`	`{ status, id }`
`InventoryLogEntry`	Single log row

Orders¶

Schema	Description
`OrderSummary`	Order list item
`OrderDetail`	Full order with items & address
`OrderItem`	Line item in order detail (`quantity`)
`OrderListResponse`	Paginated orders
`OrderUpsert`	Create/upsert order body
`OrderUpsertItem`	Line item for upsert — uses `qty`
`OrderStatusPatch`	Patch order status body
`OrderStatusPatchResponse`	Status patch result

Order requests¶

Schema	Description
`OrderRequestEnvelope`	Top-level order-request wrapper
`OrderRequestPayload`	Inner payload (requires `shop_id`)
`OrderRequestLineItem`	Line item — uses `quantity`
`OrderRequestResponse`	`{ id, status, message, external_reference }`

Prescriptions¶

Schema	Description
`Prescription`	Prescription request summary
`PrescriptionListResponse`	Paginated list
`PrescriptionIngestRequest`	Full ingest body (Title Case keys)
`PrescriptionIngestResponse`	`{ id, upsert: "ok" }`

Reports¶

Schema	Description
`ReportStatsResponse`	Dashboard stats (`data.prescriptions`, orders, customers)
`ReportPrescriptionStats`	Prescription counts by status
`ReportTopCustomer`	Top customer row
`ReportProductPerformanceResponse`	Product performance with period comparison
`ReportProductPerformanceRow`	Single product performance row
`ReportProductSalesResponse`	Sales by product and order status
`ReportProductSalesRow`	Per-product sales breakdown
`ReportProductSalesStatusRow`	Order-status counts within a product row
`ReportPharmaoneResponse`	Monthly service fee report
`ReportPharmaoneRow`	Single org/month fee row

Webhooks (outbound)¶

Schema	Description
`WebhookEvent`	Body PharmaOne POSTs to your URL

Documented path: POST /webhooks/pharmaone on your server (not Manager). See Webhooks.

External Telemedicine Connector¶

Schema	Description
`ExternalTelemedicineOrderRequest`	Shop `POST /api/v1/external-order` envelope
`ExternalOrderRequestPayload`	Inner payload — no `shop_id` required

Documented path: POST /api/v1/external-order on your shop domain. See External Telemedicine Connector.

Key field differences¶

Context	Quantity field	Shop ID
`POST /orders` (upsert)	`qty`	Required in body
`POST /order-requests`	`quantity`	Required in `payload`
Shop external-order	`quantity`	Omitted (from shop URL)

`PrescriptionIngestRequest`¶

Uses Title Case JSON keys (same format as shop prescription questionnaires). Examples:

Key	Type	Notes
`Customer Email`	string	Customer contact
`Customer First Name`	string
`Customer Last Name`	string
`Order Total Amount`	number
`Receipt Pdf Base64`	string	HTTPS URL to receipt PDF
`Id Card Front Url`	string	ID document URL
`Product 1 Pharma One Product Id`	string	Up to 3 product slots
`Questionnaire Indication`	string	Questionnaire fields
`Shop Id`	string	Optional when passed as query `shop_id`

Additional questionnaire, product, and payment fields are listed in the OpenAPI schema. Unknown keys are accepted and stored.

`WebhookEvent`¶

{
  "id": "uuid",
  "org_id": "org1",
  "event_type": "order_status_updated",
  "title": "Order status updated",
  "description": "Order ORD_… updated",
  "metadata": {
    "order_id": "ORD_…",
    "old_status": "awaiting_packing",
    "new_status": "ready_pickup"
  },
  "created_at": "2026-06-05T12:00:00Z"
}

Delivery headers: X-PharmaOne-Event, X-PharmaOne-Delivery-Id, X-PharmaOne-Signature.

`ExternalTelemedicineOrderRequest`¶

Same structure as OrderRequestEnvelope, but payload uses ExternalOrderRequestPayload (no shop_id / org_id).

{
  "external_reference": "TM-RX-2026-0042",
  "source": "external-telemedicine",
  "payload": {
    "customer_name": "Max Mustermann",
    "customer_email": "max@example.com",
    "items": [
      { "name": "Product", "quantity": 5, "price": 8.59, "p1_id": "12345" }
    ]
  }
}

Download & tooling¶

# OpenAPI YAML (all schemas under components/schemas)
curl -O https://docs.pharmaone.io/openapi/external-api.yaml

Import into Postman, Insomnia, or openapi-generator — schema names match this page and Swagger UI.