Examples¶

Request and response samples verified on dev (org1, shop1) on 2026-06-14. Customer names, emails, and addresses in JSON below are anonymized as Max Mustermann / max@example.com; field shapes and status codes match live API responses.

Host	URL
Manager (dev)	`https://manager.pharmaone.dev.secpaid.com`
Shop proxy (dev)	`https://shop1.pharmaone.dev.secpaid.com`
Manager (production)	`https://manager.prod.pharmaone.shop`

Obtain your integration API key in Manager → Org Settings → Integrations → External API keys (shown once at creation).

Setup¶

# Dev sandbox (examples below)
export BASE="https://manager.pharmaone.dev.secpaid.com"
export SHOP="https://shop1.pharmaone.dev.secpaid.com"
export ORG="org1"
export APIKEY="your-integration-api-key"

export TOKEN="$(curl -s -X POST "$BASE/api/v2/public/orgs/$ORG/auth/token" \
  -H "apikey: $APIKEY" | jq -r .access_token)"

Production: set BASE="https://manager.prod.pharmaone.shop" and your prod shop URL.

1. Exchange API key for JWT¶

RequestResponse 200Response 401 (invalid key)

POST /api/v2/public/orgs/org1/auth/token HTTP/1.1
Host: manager.pharmaone.dev.secpaid.com
apikey: <your-integration-api-key>

curl -s -X POST "$BASE/api/v2/public/orgs/$ORG/auth/token" \
  -H "apikey: $APIKEY"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdfaWQiO…",
  "expires_in": 3600,
  "token_type": "Bearer"
}

JWT claims: iss: pharmaone-integration, sub: integration, org_id: org1, scopes — see Scopes.

Kong rejects unknown keys before the backend:

{
  "message": "Unauthorized",
  "request_id": "cd736522b658367429e55f72dc5c6040"
}

2. List shops¶

RequestResponse 200

GET /api/v2/public/orgs/org1/shops HTTP/1.1
Authorization: Bearer <access_token>

{
  "data": [
    { "is_active": true, "name": "Demo Shop DEV", "shop_id": "shop1" },
    { "is_active": true, "name": "Medikamentenmanfred", "shop_id": "testtttt" },
    { "is_active": true, "name": "release23", "shop_id": "release23" },
    { "is_active": true, "name": "Weed Bank", "shop_id": "shop3" }
  ]
}

3. List orders¶

RequestResponse 200

GET /api/v2/public/orgs/org1/orders?limit=2 HTTP/1.1
Authorization: Bearer <access_token>

{
  "data": [
    {
      "id": "ORD_20260614_8v039dhnrv",
      "shop_id": "shop1",
      "customer_name": "Max Mustermann",
      "status": "awaiting_packing",
      "payment_status": "pending",
      "total_amount": 98.25,
      "created_at": "2026-06-14T10:05:55.806759Z",
      "updated_at": "2026-06-14T11:43:41.851771Z"
    },
    {
      "id": "ORD_20260613_LmOSX158ce",
      "shop_id": "shop1",
      "customer_name": "Max Mustermann",
      "status": "pending",
      "payment_status": "pending",
      "total_amount": 34.25,
      "created_at": "2026-06-13T06:18:21.998356Z",
      "updated_at": "2026-06-13T06:18:52.592746Z"
    }
  ],
  "pagination": { "limit": 2, "offset": 0, "total": 731 }
}

4. Get order by ID¶

RequestResponse 200

GET /api/v2/public/orgs/org1/orders/ORD_20260614_8v039dhnrv HTTP/1.1
Authorization: Bearer <access_token>

{
  "id": "ORD_20260614_8v039dhnrv",
  "shop_id": "shop1",
  "customer_name": "Max Mustermann",
  "customer_email": "max@example.com",
  "status": "awaiting_packing",
  "payment_status": "pending",
  "total_amount": 98.25,
  "items": [
    {
      "name": "24/1 IUVO KC OJ Zainbow",
      "quantity": 11,
      "price": 8.75,
      "p1_id": ""
    }
  ],
  "shipping_address": {
    "street": "Musterstr. 1",
    "city": "Berlin",
    "postal_code": "10115",
    "phone": "+49123456789"
  },
  "created_at": "2026-06-14T10:05:55.806759Z",
  "updated_at": "2026-06-14T11:43:41.851771Z"
}

5. Patch order status¶

RequestResponse 200

PATCH /api/v2/public/orgs/org1/orders/ORD_20260614_8v039dhnrv/status HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{"status":"awaiting_packing"}

{
  "order_id": "ORD_20260614_8v039dhnrv",
  "status": "awaiting_packing",
  "updated_at": "2026-06-14T11:44:21.735875899Z"
}

6. Submit order request (v2 + JWT)¶

RequestResponse 200

POST /api/v2/public/orgs/org1/order-requests HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "external_reference": "pos-20260614-001",
  "source": "docs-example",
  "payload": {
    "shop_id": "shop1",
    "customer_name": "Max Mustermann",
    "customer_email": "max@example.com",
    "total_amount": 19.99,
    "items": [
      { "name": "Test Item", "quantity": 1, "price": 19.99 }
    ]
  }
}

{
  "id": "08ec979e-67fc-4012-8c32-f003cb406d65",
  "status": "pending",
  "message": "Order request received.",
  "external_reference": "pos-20260614-001"
}

7. Submit order request (v1 + API key)¶

Kong validates apikey on this route. shop_id is required in the payload.

RequestResponse 200

POST /api/v1/public/orgs/org1/order-requests HTTP/1.1
apikey: <your-integration-api-key>
Content-Type: application/json

Same JSON body as §6.

{
  "id": "4ee3b265-867a-4aeb-aee1-b346b27f265f",
  "status": "pending",
  "message": "Order request received.",
  "external_reference": "pos-20260614-001-v1"
}

8. Shop proxy — external telemedicine order¶

No JWT. Shop injects shop_id and forwards to Manager. See External Telemedicine Connector.

RequestResponse 200Response 401 (missing apikey)

POST /api/v1/external-order HTTP/1.1
Host: shop1.pharmaone.dev.secpaid.com
apikey: <your-integration-api-key>
Content-Type: application/json

{
  "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": "Abholung",
    "total_amount": 25.50,
    "items": [
      { "name": "Cannabis flos 27/1", "quantity": 5, "price": 5.10 }
    ]
  }
}

curl -s -X POST "$SHOP/api/v1/external-order" \
  -H "apikey: $APIKEY" \
  -H "Content-Type: application/json" \
  -d @external-order.json

{
  "id": "5dbdd185-98ec-4973-8ab0-7033b76c9eb2",
  "status": "pending",
  "message": "Order request received.",
  "external_reference": "TM-RX-2026-0042"
}

{ "error": "Missing or invalid API key" }

9. List prescriptions¶

RequestResponse 200

GET /api/v2/public/orgs/org1/prescriptions?limit=1 HTTP/1.1
Authorization: Bearer <access_token>

{
  "data": [
    {
      "id": "org1-pq-8LLI8R",
      "shop_id": "shop1",
      "status": "new",
      "customer_email": "max@example.com",
      "order_id": "",
      "created_at": "2026-06-14T11:43:42.262149Z"
    }
  ],
  "pagination": { "limit": 1, "offset": 0 }
}

10. Ingest prescription¶

Uses Title Case keys — see Data models & schemas.

RequestResponse 200

{
  "shop_id": "shop1",
  "Customer Email": "max@example.com",
  "Customer First Name": "Max",
  "Customer Last Name": "Mustermann",
  "Order Total Amount": 42.0
}

{
  "id": "org1-pq-1AUOPV",
  "upsert": "ok"
}

11. Inventory¶

RequestResponse 200 (excerpt)

GET /api/v2/public/orgs/org1/inventory HTTP/1.1
Authorization: Bearer <access_token>

{
  "data": [
    {
      "p1_id": 57672,
      "name": "24/1 IUVO KC OJ Zainbow",
      "category": "cannabis",
      "price": 8.75,
      "stockquantity": 989,
      "log_entries": 0
    },
    {
      "p1_id": 50232,
      "name": "24/1 IUVO OC ORANGE Z",
      "category": "Cannabis",
      "price": 1,
      "stockquantity": 1,
      "log_entries": 0
    }
  ]
}

12. List products (shop catalog)¶

shop_id query parameter is required.

RequestResponse 200 (excerpt)Response 400 (missing shop_id)

GET /api/v2/public/orgs/org1/products?shop_id=shop1&limit=1 HTTP/1.1
Authorization: Bearer <access_token>

{
  "data": [
    {
      "p1_id": "57674",
      "name": "ZOIKS 31/1 MN Moonlight Nectar",
      "category": "cannabis",
      "price": 6.45,
      "stock_quantity": 991,
      "thc": 31,
      "cbd": 1,
      "available": true,
      "producer": "Vayamed"
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 42 }
}

{ "error": "shop_id query parameter is required" }

13. Reports — dashboard stats¶

RequestResponse 200 (excerpt)

GET /api/v2/public/orgs/org1/reports/stats HTTP/1.1
Authorization: Bearer <access_token>

{
  "data": {
    "prescriptions": {
      "total": 961,
      "pending": 174,
      "approved": 770,
      "completed": 730,
      "declined": 17
    },
    "shop_performance": [
      {
        "shop_id": "shop1",
        "name": "Demo Shop DEV",
        "order_count": 696,
        "total_revenue": 79782936.62,
        "unique_customers": 32
      }
    ],
    "monthly_trends": [
      { "month": "2026-06", "order_count": 34, "revenue": 1207.15 }
    ]
  }
}

14. Reports — product performance¶

RequestResponse 200 (excerpt)

GET /api/v2/public/orgs/org1/reports/product-performance HTTP/1.1
Authorization: Bearer <access_token>

{
  "data": {
    "top_by_revenue": {
      "p1_id": "50201",
      "name": "Eufloria 30/1 ITG Integrator",
      "units": 35,
      "revenue": 10500,
      "growth_rate": 1
    },
    "products": [
      {
        "p1_id": "53224",
        "name": "Materia AND 18/1 Andes",
        "units": 548,
        "revenue": 590,
        "growth_rate": 2.19
      }
    ]
  }
}

Smoke test¶

export BASE="https://manager.pharmaone.dev.secpaid.com"
export ORG="org1"
export APIKEY="your-integration-api-key"

TOKEN=$(curl -s -X POST "$BASE/api/v2/public/orgs/$ORG/auth/token" \
  -H "apikey: $APIKEY" | jq -r .access_token)

curl -s "$BASE/api/v2/public/orgs/$ORG/shops" \
  -H "Authorization: Bearer $TOKEN" | jq .

curl -s -X POST "https://shop1.pharmaone.dev.secpaid.com/api/v1/external-order" \
  -H "apikey: $APIKEY" -H "Content-Type: application/json" \
  -d '{"payload":{"customer_name":"Max Mustermann","customer_email":"max@example.com","items":[{"name":"X","quantity":1,"price":1}]}}' | jq .

Full automated smoke script: scripts/test-external-api.sh in the PharmaOne monorepo.

Postman / Insomnia¶

Import the OpenAPI spec from the Interactive API Explorer.

Variable	Example (dev)
`baseUrl`	`https://manager.pharmaone.dev.secpaid.com`
`shopUrl`	`https://shop1.pharmaone.dev.secpaid.com`
`orgId`	`org1`
`apikey`	From Manager → Integrations
`token`	From `POST …/auth/token`