院方 API
院方實作、由 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 小時)。
寫入紀錄#
/deliveries| 標頭 | 值 |
|---|---|
Idempotency-Key | deliveryId(每次嘗試與重試都相同) |
X-Poieti-Delivery | deliveryId |
X-Poieti-Attempt | 嘗試次數(不在內容中,內容永遠相同) |
X-Poieti-Signature | 見簽章驗證 |
Authorization | Bearer token(設定為 bearer 時) |
User-Agent | Poieti-HIS/1 |
內容為標準化 JSON(RFC 8785:鍵排序、無空白)的 DeliveryV1,同一 deliveryId 每次位元組完全相同。
{
"hisRecordId": "WD-20261016-0031"
}{
"code": "DUPLICATE_DELIVERY",
"hisRecordId": "WD-20261016-0031",
"message": "deliveryId already written"
}{
"code": "ENCOUNTER_CLOSED",
"message": "住院號已結帳,請資訊室處理",
"retryable": false
}- 以 deliveryId 去重:寫入 HIS 與記下
(deliveryId, hisRecordId)在同一個 HIS 交易中完成;已寫入的 deliveryId 再次送來時回 200 與原hisRecordId(或 409DUPLICATE_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 保留這筆,之後查詢狀態 |
2XX | PushWriteResponse | 已寫入:Poieti 記為 written |
409 | PushDuplicateDelivery | 已寫入: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 察覺時(下一筆送出通知或每小時核對)就立即重新探測,不等排定的時間。
查詢狀態#
/deliveries/{deliveryId}| HTTP 狀態 | 內容 | Poieti 判斷 |
|---|---|---|
200 | PushWriteResponse | 已寫入: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)。
健康檢查#
/health與其他請求一樣簽署。任何 200 回應都算通過,內容會被忽略。Poieti 在判斷可疑回應前與暫停期間探測此路由。
病房名單#
/census/wards/{wardCode}開啟名單時,Poieti 依讀取間隔(預設 10 分鐘)擷取每個設定的病房,回應為 CensusSnapshotV1,可含過敏、警示與生命徵象(每種各自取代;[] 表示沒有,省略表示未提供)。每份合格的名單都會套用,只寫入有變化的部分。驗證與套用規則同病房名單上傳。
{
"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": []
}
]
}病人查詢#
/patients/search{
"schema": "poieti.his.patient-search/1",
"medicalRecordNumber": "DEMO-002",
"wardCode": "8B",
"requestedBy": {
"poietiUserId": "user_2pR6sU9wY2bD5gJ8mP1tV4xA7c",
"staffNumber": "N10871"
}
}{
"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.overdue | accepted 保留期滿未有結果,或待送超過逾時門檻 | 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"
}
}