poieti/developers
Poieti HIS Web Service

病房名單上傳

上傳病房病人名單,讓護理師的病人清單與 HIS 一致。

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

上傳#

PUT/his/v1/census/wards/{wardCode}

開啟名單後,Poieti 依讀取間隔向院方端點擷取名單(見院方 API);院方也可以用此路由上傳,例如在 ADT 異動後,或讀取間隔設為 0 時。兩種來源套用相同的規則。

一次一個病房,內容為該病房目前所有病人(complete: true),最多 500 人、2 MB。需要 census 範圍的憑證與機構的名單開關;病房代碼由 Poieti 設定(HIS 病房代碼)。憑證限定病房時,只能上傳那些病房,也只會變更新病人或已在那些病房的病人:名單列出其他病房的病人(或住院號被其他病房病人使用)時回報 OUT_OF_SCOPE,不做任何變更,因此跨病房轉床需要涵蓋兩個病房、或不限病房的憑證。只靠上傳時,建議每 10 分鐘上傳一次,並在 ADT 異動後上傳。

CensusSnapshotV1
{
  "asOf": "2026-10-16T15:40: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"
    },
    {
      "medicalRecordNumber": "DEMO-002",
      "encounterId": "A2026101502",
      "hisPatientId": "P000456",
      "displayName": "測試陳小姐",
      "bed": "8B-07",
      "admittedAt": "2026-10-15T16:05:00+08:00"
    },
    {
      "medicalRecordNumber": "DEMO-003",
      "encounterId": "A2026100903",
      "displayName": "測試林先生",
      "discharged": true
    },
    {
      "medicalRecordNumber": "DEMO-009",
      "encounterId": "A2026101609",
      "displayName": "測試張先生",
      "bed": "8B-15"
    }
  ]
}
欄位型別必填說明
asOfstring (RFC 3339)是When the HIS took the snapshot. Must carry an offset, be at most 5 minutes ahead of server time and at most 24 hours old.
completetrue是The snapshot lists every current patient of the ward.
patientsobject[]是Chart numbers and encounter ids must not repeat.
patients[].medicalRecordNumberstring是病歷號; Poieti normalizes (NFKC, trim, upper-case) and checks the institution's pattern.
patients[].encounterIdstring是住院號 of the current admission.
patients[].hisPatientIdstring
patients[].displayNamestring是
patients[].wardCodestringHIS ward code (wards.his_code). . and .. are not ward codes.
patients[].bedstringSent when the HIS manages beds; Poieti then treats the bed as HIS-managed.
patients[].admittedAtstring (RFC 3339)RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.
patients[].dischargedbooleanExplicit discharge. Absence from a snapshot never discharges.
patients[].allergiesobject[]Push mode only. Absent: not provided (stored rows kept). []: the HIS has none.
patients[].allergies[].codestring是Unique per patient and kind.
patients[].allergies[].labelstring是
patients[].allergies[].textstring
patients[].allergies[].valuenumber
patients[].allergies[].unitstring
patients[].allergies[].observedAtstring (RFC 3339)RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.
patients[].alertsobject[]Push mode only; same semantics as allergies.
patients[].alerts[].codestring是Unique per patient and kind.
patients[].alerts[].labelstring是
patients[].alerts[].textstring
patients[].alerts[].valuenumber
patients[].alerts[].unitstring
patients[].alerts[].observedAtstring (RFC 3339)RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.
patients[].vitalsany[]Push mode only; same semantics as allergies. Each vital carries its observation time.
patients[].vitals[].codestringUnique per patient and kind.
patients[].vitals[].labelstring
patients[].vitals[].textstring
patients[].vitals[].valuenumber
patients[].vitals[].unitstring
patients[].vitals[].observedAtstring (RFC 3339)是RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.
欄位型別必填說明
medicalRecordNumberstring是病歷號; Poieti normalizes (NFKC, trim, upper-case) and checks the institution's pattern.
encounterIdstring是住院號 of the current admission.
hisPatientIdstring
displayNamestring是
wardCodestringHIS ward code (wards.his_code). . and .. are not ward codes.
bedstringSent when the HIS manages beds; Poieti then treats the bed as HIS-managed.
admittedAtstring (RFC 3339)RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.
dischargedbooleanExplicit discharge. Absence from a snapshot never discharges.
allergiesobject[]Push mode only. Absent: not provided (stored rows kept). []: the HIS has none.
allergies[].codestring是Unique per patient and kind.
allergies[].labelstring是
allergies[].textstring
allergies[].valuenumber
allergies[].unitstring
allergies[].observedAtstring (RFC 3339)RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.
alertsobject[]Push mode only; same semantics as allergies.
alerts[].codestring是Unique per patient and kind.
alerts[].labelstring是
alerts[].textstring
alerts[].valuenumber
alerts[].unitstring
alerts[].observedAtstring (RFC 3339)RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.
vitalsany[]Push mode only; same semantics as allergies. Each vital carries its observation time.
vitals[].codestringUnique per patient and kind.
vitals[].labelstring
vitals[].textstring
vitals[].valuenumber
vitals[].unitstring
vitals[].observedAtstring (RFC 3339)是RFC 3339 date-time with an explicit offset. Metadata times from Poieti are UTC (Z, millisecond precision); record times in DeliveryV1 use the mapping timezone (default Asia/Taipei, +08:00). Times sent to Poieti must carry an offset.

驗證與套用#

  • asOf 為取得名單的時間,必須有時區,且不可超前 Poieti 時間 5 分鐘、不可早於 24 小時;同一名單內病歷號與住院號不可重複,否則 422 HIS_CENSUS_INVALID。
  • asOf 早於上次套用的名單 → 409 CENSUS_STALE;相同 asOf 與相同內容視為重送(計數為 0、replayed: true);相同 asOf 但內容不同也是 CENSUS_STALE。
  • 病歷號以 NFKC、去空白、英文大寫比對,並檢查機構的格式規則。
  • 新病人以 HIS 病人建立;HIS 病人依較新的名單更新姓名、住院號、病房(轉床)與床號(有送才更新);出院後再出現視為再住院。
  • 護理師手動新增的病人:住院號相同,或沒有住院號且姓名相符時納入 HIS 管理(adopted);否則回報 IDENTITY_CONFLICT,不改任何資料,護理長會看到「院方資料不符」,直到提出此衝突的病房名單不再列出該病歷號。
  • 只有 discharged: true 才會出院;沒有出現在名單的 HIS 病人只標記「未出現在院方名單」(missing),不會出院。
  • 名單不會放行任何待送紀錄,也不會改動既有紀錄的住院歸屬。
  • 上傳的過敏、警示與生命徵象只在機構模式為 push 時接受,否則回 422 CENSUS_CONTEXT_DISABLED。

結果#

200 OK
{
  "created": 1,
  "updated": 1,
  "adopted": 0,
  "transferred": 0,
  "readmitted": 0,
  "discharged": 1,
  "unchanged": 0,
  "missing": 1,
  "rejected": [
    {
      "medicalRecordNumber": "DEMO-009",
      "code": "IDENTITY_CONFLICT"
    }
  ],
  "replayed": false
}
計數意思
created新建立的 HIS 病人
updated資料有變更
adopted手動新增的病人改由 HIS 管理
transferred轉入此病房
readmitted出院後再住院
discharged明確出院
unchanged無變更
missing此病房的 HIS 病人未出現在名單
rejected逐筆拒收:IDENTITY_CONFLICT、CHART_NUMBER_INVALID、ENCOUNTER_INVALID、ENCOUNTER_IN_USE、PATIENT_INVALID、OUT_OF_SCOPE(憑證限定的病房不含此病人所在的病房)

HIS 管理的欄位#

開啟名單後,HIS 病人的姓名、病房、狀態、住院號(以及 HIS 有送床號時的床號)由 HIS 管理,護理師在 Poieti 無法修改。護理師仍可手動新增病人,下一份名單會依上述規則納入。

Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1