Poieti HIS Web Service
連線與金鑰
院方端點呼叫的 HIS Web Service:主機、機器金鑰格式、IP 限制、範圍與限流。
本頁內容與 contracts/his v1.0.0 及 Poieti 伺服器實作一致。
主機#
| 環境 | Base URL | 金鑰 |
|---|---|---|
| 正式 | https://his.poieti.com/his/v1 | phis.prod.… |
| 測試(驗收) | https://his-dev.poieti.com/his/v1 | phis.dev.… |
這兩個主機只回應 /his/v1/* 與未驗證的 GET /health。用另一個環境的金鑰會得到 401。請以主機名稱放行對外 443(沒有固定 IP),並排除於 TLS 檢查;無法排除時,檢查用根憑證需在系統憑證庫或 NODE_EXTRA_CA_CERTS。所有回應帶 Cache-Control: no-store。
機器金鑰#
請求標頭
Authorization: Bearer phis.<env>.<hospitalId>.<credentialId>.<secret>| 部分 | 格式 |
|---|---|
env | dev 或 prod |
hospitalId | Poieti 機構代碼 |
credentialId | 16 個小寫 RFC 4648 base32 字元 |
secret | 32 個隨機位元組,unpadded base64url(43 字元) |
Poieti 只保存 secret ASCII 文字的 SHA-256,因此院方可以自行產生 secret(檢查工具的 keygen),只交出雜湊。金鑰放在環境變數或權限受限的檔案,不可放在命令列參數或設定檔。
憑證範圍與限制#
| 項目 | 說明 |
|---|---|
| 範圍 | deliveries(附件、送出狀態、核對清單)、census(名單上傳);可分開核發 |
| 來源 IP | 1–32 個 CIDR 網段,或明確允許任何來源;不符回 403 HIS_IP_NOT_ALLOWED |
| 名單病房 | census 範圍可限定 HIS 病房代碼;不符回 403 HIS_SCOPE_DENIED |
| 期限與撤銷 | 到期或撤銷後下一個請求即回 401 HIS_UNAUTHORIZED |
| 限流 | 每個憑證每分鐘 120 次;超過回 429 HIS_RATE_LIMITED 與 Retry-After。金鑰錯誤或來源位址不允許的請求不計入,但同一位址每分鐘超過 20 次同樣回 429 |
測試連線#
用 cURL 測試時,先把標頭寫入只有自己可讀的檔案,避免金鑰出現在命令列:
準備標頭檔
printf 'Authorization: Bearer %s\n' "$(cat poieti-his.key)" > auth-header.txt
chmod 600 auth-header.txtGET /his/v1/integration
curl -sS https://his-dev.poieti.com/his/v1/integration -H @auth-header.txt200 OK
{
"institutionId": "demo-hospital",
"mode": "push",
"paused": false,
"features": [
"nursing-admission",
"wound-record"
],
"mappings": [
{
"featureId": "nursing-admission",
"templateVersion": 1,
"mappingId": "demo-hospital",
"version": 1
},
{
"featureId": "wound-record",
"templateVersion": 1,
"mappingId": "demo-hospital-wound",
"version": 1
}
],
"census": true,
"serverTime": "2026-10-16T07:42:30.512Z"
}serverTime 可用來檢查本機時鐘誤差;mode 為 push 時 Poieti 才會推送;paused 時 Poieti 不送任何請求到端點。
錯誤格式#
錯誤回應
{
"error": "Attachment not found.",
"code": "HIS_ATTACHMENT_NOT_FOUND",
"requestId": "8c1f0a5e2b7d4c39a6e1"
}行為只依 code 判斷,不要比對 error 文字。聯絡 Poieti 時提供 requestId。完整列表見錯誤碼。送給 Poieti 的內容是封閉的:多出的欄位會回 422。