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"
}
]
}| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
asOf | string (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. |
complete | true | 是 | The snapshot lists every current patient of the ward. |
patients | object[] | 是 | Chart numbers and encounter ids must not repeat. |
patients[].medicalRecordNumber | string | 是 | 病歷號; Poieti normalizes (NFKC, trim, upper-case) and checks the institution's pattern. |
patients[].encounterId | string | 是 | 住院號 of the current admission. |
patients[].hisPatientId | string | ||
patients[].displayName | string | 是 | |
patients[].wardCode | string | HIS ward code (wards.his_code). . and .. are not ward codes. | |
patients[].bed | string | Sent when the HIS manages beds; Poieti then treats the bed as HIS-managed. | |
patients[].admittedAt | string (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[].discharged | boolean | Explicit discharge. Absence from a snapshot never discharges. | |
patients[].allergies | object[] | Push mode only. Absent: not provided (stored rows kept). []: the HIS has none. | |
patients[].allergies[].code | string | 是 | Unique per patient and kind. |
patients[].allergies[].label | string | 是 | |
patients[].allergies[].text | string | ||
patients[].allergies[].value | number | ||
patients[].allergies[].unit | string | ||
patients[].allergies[].observedAt | string (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[].alerts | object[] | Push mode only; same semantics as allergies. | |
patients[].alerts[].code | string | 是 | Unique per patient and kind. |
patients[].alerts[].label | string | 是 | |
patients[].alerts[].text | string | ||
patients[].alerts[].value | number | ||
patients[].alerts[].unit | string | ||
patients[].alerts[].observedAt | string (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[].vitals | any[] | Push mode only; same semantics as allergies. Each vital carries its observation time. | |
patients[].vitals[].code | string | Unique per patient and kind. | |
patients[].vitals[].label | string | ||
patients[].vitals[].text | string | ||
patients[].vitals[].value | number | ||
patients[].vitals[].unit | string | ||
patients[].vitals[].observedAt | string (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. |
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
medicalRecordNumber | string | 是 | 病歷號; Poieti normalizes (NFKC, trim, upper-case) and checks the institution's pattern. |
encounterId | string | 是 | 住院號 of the current admission. |
hisPatientId | string | ||
displayName | string | 是 | |
wardCode | string | HIS ward code (wards.his_code). . and .. are not ward codes. | |
bed | string | Sent when the HIS manages beds; Poieti then treats the bed as HIS-managed. | |
admittedAt | string (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. | |
discharged | boolean | Explicit discharge. Absence from a snapshot never discharges. | |
allergies | object[] | Push mode only. Absent: not provided (stored rows kept). []: the HIS has none. | |
allergies[].code | string | 是 | Unique per patient and kind. |
allergies[].label | string | 是 | |
allergies[].text | string | ||
allergies[].value | number | ||
allergies[].unit | string | ||
allergies[].observedAt | string (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. | |
alerts | object[] | Push mode only; same semantics as allergies. | |
alerts[].code | string | 是 | Unique per patient and kind. |
alerts[].label | string | 是 | |
alerts[].text | string | ||
alerts[].value | number | ||
alerts[].unit | string | ||
alerts[].observedAt | string (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. | |
vitals | any[] | Push mode only; same semantics as allergies. Each vital carries its observation time. | |
vitals[].code | string | Unique per patient and kind. | |
vitals[].label | string | ||
vitals[].text | string | ||
vitals[].value | number | ||
vitals[].unit | string | ||
vitals[].observedAt | string (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 無法修改。護理師仍可手動新增病人,下一份名單會依上述規則納入。