poieti/developers
開始使用

HIS 介接指南

Poieti 確認紀錄送入院方 HIS 的方式:院方端點、簽章、附件、病房名單與共用的紀錄格式。

護理師在 Poieti 確認的紀錄可以送入醫院資訊系統(HIS)。院方建置一個 HTTPS 端點,Poieti 以簽署的請求把每筆確認的紀錄送到端點,格式為 DeliveryV1;開啟病房名單時,Poieti 也向端點讀取名單與查詢病人。Poieti 紀錄是原始資料;HIS 設定、欄位對照或身分問題不會讓確認失敗,而是成為護理師與院方資訊人員看得到、可處理的待送紀錄。

連線方式#

方向路由驗證
Poieti → 院方端點寫入紀錄 POST /deliveries、查詢狀態 GET /deliveries/{deliveryId}、健康檢查 GET /health;開啟病房名單時另有 GET /census/wards/{wardCode} 與 POST /patients/search院方以 X-Poieti-Signature 驗證(簽章驗證)
院方端點 → Poieti HIS Web Service下載附件、查詢送出狀態與核對清單、上傳病房名單(/his/v1/*)機器金鑰(連線與金鑰)

機構模式為 off(預設)時不送出,Poieti 也不連入院方;Poieti 將機構切換為 push 後才呼叫設定的端點。另有每家機構獨立的病房名單開關:開啟後 Poieti 依設定的間隔向端點讀取名單,院方也可以自行上傳;上傳的名單在任一模式都接受身分與住院資料,過敏、警示與生命徵象只在 push 接受。

安全邊界#

  • Poieti 只連到機構設定的院方端點(公開的 HTTPS 網址),每個請求都經簽署。唯一的其他對外請求是選用的告警 webhook,內容只有事件代碼與時間,目的地必須是公開的通知服務,不能是院方端點或 Poieti 的 HIS 主機。
  • 院方端點以機器金鑰呼叫 his.poieti.com(測試 his-dev.poieti.com),金鑰綁定機構、範圍、來源 IP 與期限,在資料庫逐次驗證,撤銷立即生效。
  • 送出的內容只來自紀錄欄位經欄位對照後的值;逐字稿引用、來源參照與對話 ID 永不送出。紀錄結束後依保存天數清除送出內容。
  • Poieti 日誌不記錄送出內容、病歷號、姓名、查詢字串或院方回應內容。
  • HIS 送出狀態與院方回覆文字不會進入模型上下文;模型不會宣稱已寫入院方系統。

紀錄格式#

一份確認的紀錄版本 = 一筆送出(delivery),以 deliveryId 識別,院方以它去重。同一個 deliveryId 每次嘗試的內容完全相同;次數放在內容之外(X-Poieti-Attempt 標頭)。之後確認的新版本以 correction 整筆取代原院方紀錄。詳見 DeliveryV1 與 欄位對照。

機構設定#

以下由 Poieti 人員以管理工具設定,院方提供所需資料:

設定內容院方提供
模式與暫停off/push;暫停時不送任何請求到端點,紀錄照常排隊啟用時程
院方端點base URL、Bearer token(選用)、逾時(預設 15 秒)、名單病房與讀取間隔(預設 10 分鐘,0 為不讀取)端點網址、token
簽章金鑰Poieti 產生,每個環境一把;輪替時新舊金鑰同時有效(預設 24 小時)安全的交付方式
送出的功能與欄位對照例如入院護理評估、傷口紀錄;每個範本版本一份審核過的對照欄位對照表(CSV)
身分規則是否必須有住院號、員工編號;病歷號與住院號格式;手圈條碼格式格式規則
病房代碼與員工編號Poieti 病房對應的 HIS 病房代碼;每位使用者的院內員工編號代碼表
機器憑證範圍(deliveries、census)、允許的 IP 網段、名單病房、期限端點主機的對外 IP、secret 的 SHA-256
門檻最多嘗試次數(預設 8)、accepted 保留時數(預設 24)、待送逾時告警(預設 15 分鐘)、保存天數(預設 30)需求
告警 webhook送出失敗、逾期、推送暫停與恢復等事件通知服務網址

分工#

負責方工作
院方資訊人員建置與維運院方端點(驗證簽章、寫入 HIS 並去重、下載附件、病房名單)、網路放行、在主控台處理失敗與重試
Poieti欄位對照審核與發布、機構、端點與憑證設定、HIS Web Service 與告警
護理師確認紀錄與病人身分;身分被拒時修正後重新送出
Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1