診所資訊系統串接說明

取得目前授權給診所的病患清單。建議第一次同步與每日 reconciliation 使用。

GET /api/clinic/v1/authorized-patients?limit=100

可選參數：

Response 範例

{
  "data": [
    {
      "patientHandle": "pt_exampleHandleABCDEFGH",
      "patientId": null,
      "authorizedScopes": {
        "vitals": true,
        "reports": true,
        "history": true
      },
      "grantId": "grant_example",
      "status": "active"
    }
  ],
  "page": {
    "limit": 100,
    "nextCursor": null
  },
  "requestId": "clinic-sync-001"
}

依 patientHandle 或診所端病歷號 patientId 讀取檢測紀錄。建議優先使用 patientHandle。

GET /api/clinic/v1/records?patientHandle=pt_exampleHandleABCDEFGH&limit=100

常用參數：

若診所系統已保存 recordId，可直接回查單筆紀錄。

GET /api/clinic/v1/records/sample-record-001?format=json

紀錄不存在、病患未授權，或紀錄不屬於該診所授權範圍時，都會回 404 not_found。請不要用 404 結果推測紀錄或病患是否存在。

{
  "data": [
    {
      "recordId": "sample-record-001",
      "patientId": "TEST-001",
      "patientName": null,
      "deviceType": "urine_analysis",
      "scopeCategory": "reports",
      "timestamp": "2026-05-19T17:19:00.000Z",
      "updatedAt": "2026-05-22T02:54:12.835Z",
      "measurements": [
        { "name": "SG", "value": "1.020", "unit": "" },
        { "name": "pH", "value": "6", "unit": "" },
        { "name": "LEU", "value": "neg", "unit": "" }
      ],
      "reviewStatus": "pending",
      "reviewedAt": null,
      "hisSentStatus": "not_sent",
      "isRejected": false
    }
  ],
  "page": {
    "limit": 100,
    "nextCursor": null
  },
  "requestId": "clinic-sync-001"
}

臨床安全提醒：pending 資料尚未完成醫護確認，診所系統若要顯示給臨床人員，應明確標示為未審閱/暫定資料。

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Observation",
        "id": "sample-record-001",
        "status": "preliminary",
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                "code": "laboratory",
                "display": "Laboratory"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "24356-8",
              "display": "Urinalysis complete panel"
            }
          ],
          "text": "Urinalysis complete panel"
        },
        "subject": {
          "identifier": {
            "system": "https://ai.winefont.net/fhir/identifier/patient-id",
            "value": "TEST-001"
          }
        },
        "effectiveDateTime": "2026-05-19T17:19:00.000Z",
        "component": [
          {
            "code": { "text": "Specific gravity of Urine by Test strip" },
            "valueQuantity": { "value": 1.02, "unit": "" }
          }
        ]
      }
    }
  ]
}

血壓等生命徵象資料會使用 vital-signs category。一般檢驗報告多為 laboratory category。

{
  "deviceType": "metabolic_health",
  "scopeCategory": "reports",
  "measurements": [
    { "name": "HbA1c", "value": "6.5", "unit": "%" },
    { "name": "TC", "value": "180", "unit": "mg/dL" },
    { "name": "HDL", "value": "52", "unit": "mg/dL" },
    { "name": "LDL", "value": "105", "unit": "mg/dL" },
    { "name": "TG", "value": "120", "unit": "mg/dL" }
  ]
}

{
  "deviceType": "urine_analysis",
  "scopeCategory": "reports",
  "measurements": [
    { "name": "SG", "value": "1.020", "unit": "" },
    { "name": "pH", "value": "6", "unit": "" },
    { "name": "LEU", "value": "neg", "unit": "" },
    { "name": "NIT", "value": "neg", "unit": "" },
    { "name": "PRO", "value": "neg", "unit": "" },
    { "name": "GLU", "value": "norm", "unit": "" },
    { "name": "KET", "value": "neg", "unit": "" },
    { "name": "UBG", "value": "norm", "unit": "" },
    { "name": "BIL", "value": "neg", "unit": "" },
    { "name": "ERY", "value": "neg", "unit": "" }
  ]
}

{
  "deviceType": "coagulation_factors",
  "scopeCategory": "reports",
  "measurements": [
    { "name": "PT", "value": "12.4", "unit": "sec" },
    { "name": "INR", "value": "1.1", "unit": "" },
    { "name": "aPTT", "value": "31", "unit": "sec" }
  ]
}

{
  "deviceType": "blood_pressure_monitor",
  "scopeCategory": "vitals",
  "measurements": [
    { "name": "SYS", "value": "120", "unit": "mmHg" },
    { "name": "DIA", "value": "80", "unit": "mmHg" },
    { "name": "Pulse", "value": "72", "unit": "bpm" }
  ]
}

FHIR category 會是 vital-signs。

{
  "deviceType": "blood_glucose_meter",
  "scopeCategory": "vitals",
  "measurements": [
    { "name": "BG", "value": "110", "unit": "mg/dL" }
  ]
}

full_report 用於完整檢驗報告或多項目報告。v1 API 只回傳結構化數值，不回傳報告圖片或檔案下載連結。

{
  "deviceType": "full_report",
  "scopeCategory": "reports",
  "measurements": [
    { "name": "WBC", "value": "6.2", "unit": "10^3/uL" },
    { "name": "RBC", "value": "4.8", "unit": "10^6/uL" },
    { "name": "Hb", "value": "14.1", "unit": "g/dL" },
    { "name": "PLT", "value": "220", "unit": "10^3/uL" }
  ]
}