poieti/developers
院方端點

院方 API

院方實作、由 Poieti 呼叫的路由。

本頁內容與 contracts/his v1.0.0 及 Poieti 伺服器實作一致。

端點要求#

  • 公開的 HTTPS base URL(不含查詢字串、片段、連接埠或 IP 位址),例如 https://his.example.org/poieti/v1;由 Poieti 以管理工具設定。
  • Poieti 從 Cloudflare Workers 呼叫,沒有固定來源 IP,也無法連到私有網路:以 X-Poieti-Signature 驗證來源,可另加 Bearer token。目前不提供固定來源 IP、mTLS 或私有連線。
  • 每個請求的逾時預設 15 秒(1–30 秒),回應內容上限 64 KB(名單 2 MB)。
  • 簽署請求的金鑰由 Poieti 產生並交付(43 個 base64url 字元);輪替期間新舊金鑰同時有效(預設 24 小時)。

寫入紀錄#

POST/deliveries
標頭值
Idempotency-KeydeliveryId(每次嘗試與重試都相同)
X-Poieti-DeliverydeliveryId
X-Poieti-Attempt嘗試次數(不在內容中,內容永遠相同)
X-Poieti-Signature見簽章驗證
AuthorizationBearer token(設定為 bearer 時)
User-AgentPoieti-HIS/1

內容為標準化 JSON(RFC 8785:鍵排序、無空白)的 DeliveryV1,同一 deliveryId 每次位元組完全相同。

已寫入
{
  "hisRecordId": "WD-20261016-0031"
}
  • 以 deliveryId 去重:寫入 HIS 與記下 (deliveryId, hisRecordId) 在同一個 HIS 交易中完成;已寫入的 deliveryId 再次送來時回 200 與原 hisRecordId(或 409 DUPLICATE_DELIVERY 附 hisRecordId)。
  • 只存成功的寫入:拒收不記在該 deliveryId 上,主控台重試時要重新處理。
  • 請求只含附件的中繼資料(ID、類型、大小、SHA-256)。附件位元組以 deliveries 範圍的機器金鑰下載(見附件與送出狀態),比對大小與 SHA-256 後再寫入;不符時不要寫入,回可重試的 ATTACHMENT_MISMATCH。
  • 排入佇列時回 202,Poieti 會在 30 秒、2 分、10 分後,之後每 30 分鐘查詢狀態。
  • 401/403 只用於端點憑證問題;單筆拒收請用有代碼的 4xx(例如 422),內容為 {code, message, retryable}(retryable 預設 false)。

寫入 HIS#

情況做法
create以 medicalRecordNumber + encounterId 對應病人與本次住院;displayName、wardCode、bed 只供核對
correction以 supersedes.hisRecordId 找到原紀錄整筆取代(重複資料列整組取代),即使該次住院已結帳;身分沿用原紀錄
部分日期照對照的文字格式存(例如 2026-10),不要自行補日或月
字元放不下不截斷、不刪除、不換成 ?;回 VALUE_UNENCODABLE 或 VALUE_TOO_LONG
missingRequired依院方規則:寫入並標記,或回不可重試的 REQUIRED_FIELD_MISSING;不要填預設值
病人或住院號不符回不可重試的 PATIENT_NOT_FOUND、PATIENT_MISMATCH 或 ENCOUNTER_NOT_FOUND;護理師修正後會以新的 deliveryId 重新送出
暫時無法寫入回可重試的代碼(例如 423 HIS_LOCKED、retryable: true)

message 為純文字,會原樣顯示給護理師與資訊人員,不翻譯、不交給模型。請只寫能據以處理的說明(最多 500 字元),不要放入病人資料,或 SQL、堆疊追蹤等內部細節。這筆送出的內容清除時,message 一併清除,只留 code。

回應判斷#

HTTP 狀態內容Poieti 判斷
202任何已受理:Poieti 保留這筆,之後查詢狀態
2XXPushWriteResponse已寫入:Poieti 記為 written
409PushDuplicateDelivery已寫入:Poieti 記為 written
4XX(除了 401、403、407、408、409、425、429)PushError院方拒收:Poieti 記為 failed(body 標明 retryable 才重試)
其他任何端點可疑:不算在這筆;Poieti 先探測 /health 再決定

端點可疑的回應不會直接算在這筆送出:401/403 會暫停推送直到端點設定變更;其他情況 Poieti 先以簽署的 GET /health 探測,探測失敗就暫停推送並在 30 秒、2 分、10 分、之後每 30 分鐘重試,這段期間不計次數(/health 回 401/403 同樣視為憑證問題,暫停至端點設定變更);探測通過才算在這筆(網路錯誤、逾時、5xx、408/425/429 依 30 秒、2 分、10 分、30 分、2 小時、6 小時重試至上限後成為 HIS_UNREACHABLE,其他成為 HIS_REJECTED)。連續三筆沒有代碼的失敗也會暫停推送。暫停期間端點設定一變更(例如改用備援端點、更換權杖或輪替簽章金鑰),Poieti 察覺時(下一筆送出通知或每小時核對)就立即重新探測,不等排定的時間。

查詢狀態#

GET/deliveries/{deliveryId}
HTTP 狀態內容Poieti 判斷
200PushWriteResponse已寫入:Poieti 記為 written
202任何處理中
404任何院方不認得:Poieti 以同一 key、相同內容重新 POST
4XX(除了 401、403、407、408、409、425、429)PushError院方拒收:Poieti 記為 failed(body 標明 retryable 才重試)
其他任何端點可疑:不算在這筆;Poieti 先探測 /health 再決定

404(不論內容)表示院方不認得這個 deliveryId,Poieti 會以同一 key、相同內容重新 POST。202 之後 Poieti 保留這筆 accepted 保留時數(預設 24 小時);期滿仍未有結果時算一次嘗試,之後以相同內容重新 POST(次數用完成為 LEASE_EXPIRED)。

健康檢查#

GET/health

與其他請求一樣簽署。任何 200 回應都算通過,內容會被忽略。Poieti 在判斷可疑回應前與暫停期間探測此路由。

病房名單#

GET/census/wards/{wardCode}

開啟名單時,Poieti 依讀取間隔(預設 10 分鐘)擷取每個設定的病房,回應為 CensusSnapshotV1,可含過敏、警示與生命徵象(每種各自取代;[] 表示沒有,省略表示未提供)。每份合格的名單都會套用,只寫入有變化的部分。驗證與套用規則同病房名單上傳。

200 OK · 含臨床資料
{
  "asOf": "2026-10-16T15:50:00+08:00",
  "complete": true,
  "patients": [
    {
      "medicalRecordNumber": "DEMO-001",
      "encounterId": "A2026101601",
      "hisPatientId": "P000123",
      "displayName": "示範病人",
      "bed": "8B-12",
      "admittedAt": "2026-10-16T10:20:00+08:00",
      "allergies": [
        {
          "code": "PCN",
          "label": "Penicillin",
          "text": "皮疹"
        }
      ],
      "alerts": [
        {
          "code": "FALL_HIGH",
          "label": "跌倒高危險",
          "observedAt": "2026-10-16T11:00:00+08:00"
        }
      ],
      "vitals": [
        {
          "code": "BT",
          "label": "體溫",
          "value": 37.8,
          "unit": "°C",
          "observedAt": "2026-10-16T14:00:00+08:00"
        },
        {
          "code": "SBP",
          "label": "收縮壓",
          "value": 128,
          "unit": "mmHg",
          "observedAt": "2026-10-16T14:00:00+08:00"
        }
      ]
    },
    {
      "medicalRecordNumber": "DEMO-002",
      "encounterId": "A2026101502",
      "hisPatientId": "P000456",
      "displayName": "測試陳小姐",
      "bed": "8B-07",
      "allergies": []
    }
  ]
}
POST/patients/search
請求
{
  "schema": "poieti.his.patient-search/1",
  "medicalRecordNumber": "DEMO-002",
  "wardCode": "8B",
  "requestedBy": {
    "poietiUserId": "user_2pR6sU9wY2bD5gJ8mP1tV4xA7c",
    "staffNumber": "N10871"
  }
}
200 OK
{
  "patients": [
    {
      "medicalRecordNumber": "DEMO-002",
      "encounterId": "A2026101502",
      "hisPatientId": "P000456",
      "displayName": "測試陳小姐",
      "wardCode": "8B",
      "bed": "8B-07",
      "admittedAt": "2026-10-15T16:05:00+08:00"
    }
  ]
}

護理師在 Poieti 找不到病人時使用。病歷號以正規化後的形式放在簽署的內容中(不放在網址);requestedBy 為查詢護理師的員工編號。只回該病房的病人、每筆含 wardCode、不含臨床資料,最多 20 筆、64 KB。機構暫停或推送中斷時不會查詢,機構要求員工編號而查詢的護理師沒有員工編號時也不會查詢;每位使用者每分鐘最多 10 次。

順序#

情況Poieti 的處理
同一紀錄已有送出中的版本較新版本暫不送出,等前一筆有結果後以 correction 送出
回覆有代碼的 4xx 且 retryable: true嘗試次數未用完時依退避再送,內容與 deliveryId 不變
較舊版本以 Poieti 的代碼失敗(可能已在 HIS 中)較新版本暫不送出,直到資訊人員處理舊版本(見錯誤碼);院方的拒收代碼則不會擋住較新版本
功能不再送出(機構設定移除)未送出的紀錄停在原處、不再送出

告警#

設定了告警 webhook 時,Poieti 在下列事件送出告警。內容只有代碼、計數與時間,以告警簽章金鑰簽署(見簽章驗證)。

事件時機detail
his.delivery.failed任一送出成為 failed(超過 10 筆合併)deliveryId、featureId、errorCode、errorOrigin(hospital:院方的拒絕,即使代碼與 Poieti 的同名;poieti:Poieti 自己的失敗,可能已在 HIS 中)或 count
his.delivery.overdueaccepted 保留期滿未有結果,或待送超過逾時門檻overdue、count、oldestAt
his.push.paused推送端點中斷reason、since、nextProbeAt
his.push.resumed推送恢復since
告警內容範例
{
  "schema": "poieti.his.alert/1",
  "id": "2b1a0f9e-8d7c-4b6a-9e5d-4c3b2a1f0e9d",
  "event": "his.push.paused",
  "environment": "dev",
  "institutionId": "demo-hospital",
  "at": "2026-10-16T08:00:02.417Z",
  "text": "demo-hospital: deliveries are paused because the hospital endpoint is unreachable.",
  "detail": {
    "reason": "unreachable",
    "since": "2026-10-16T08:00:01.902Z",
    "nextProbeAt": "2026-10-16T08:00:31.902Z"
  }
}
Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1