poieti/developers
Poieti HIS Web Service

連線與金鑰

院方端點呼叫的 HIS Web Service:主機、機器金鑰格式、IP 限制、範圍與限流。

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

主機#

環境Base URL金鑰
正式https://his.poieti.com/his/v1phis.prod.…
測試(驗收)https://his-dev.poieti.com/his/v1phis.dev.…

這兩個主機只回應 /his/v1/* 與未驗證的 GET /health。用另一個環境的金鑰會得到 401。請以主機名稱放行對外 443(沒有固定 IP),並排除於 TLS 檢查;無法排除時,檢查用根憑證需在系統憑證庫或 NODE_EXTRA_CA_CERTS。所有回應帶 Cache-Control: no-store。

機器金鑰#

請求標頭
Authorization: Bearer phis.<env>.<hospitalId>.<credentialId>.<secret>
部分格式
envdev 或 prod
hospitalIdPoieti 機構代碼
credentialId16 個小寫 RFC 4648 base32 字元
secret32 個隨機位元組,unpadded base64url(43 字元)

Poieti 只保存 secret ASCII 文字的 SHA-256,因此院方可以自行產生 secret(檢查工具的 keygen),只交出雜湊。金鑰放在環境變數或權限受限的檔案,不可放在命令列參數或設定檔。

憑證範圍與限制#

項目說明
範圍deliveries(附件、送出狀態、核對清單)、census(名單上傳);可分開核發
來源 IP1–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.txt
GET /his/v1/integration
curl -sS https://his-dev.poieti.com/his/v1/integration -H @auth-header.txt
200 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。

Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1