poieti/developers
驗收

驗收案例

院方端點在正式啟用前必須通過的 44 個案例。

案例一覽#

院方在正式環境啟用前,須在測試環境通過適用的案例:Poieti 測試環境推送到院方測試端點,金鑰與名單案例以測試金鑰對 his-dev.poieti.com 執行;Poieti 依「Poieti 預期」核對結果。每個案例指定一份範例資料(可附 merge patch)、要注入的狀況、端點應有的行為,以及 Poieti 應記錄或回覆的結果。標示「院內檢查」的 13 個案例可先以檢查工具在院內執行。

範圍案例數說明
院方端點29院方端點收到 Poieti 推送時的行為。以 signature-vectors.json 驗證簽章。
金鑰與存取4金鑰、來源 IP、範圍與限流被拒時,端點應停止並通知資訊人員,不可密集重試。
病房名單上傳11PUT /his/v1/census/wards/{wardCode} 的套用、重送與拒收。需要 census 範圍的金鑰與機構的名單開關。

案例內容取自 acceptance.json(44 個案例,英文原文)。

院方端點#

院方端點收到 Poieti 推送時的行為。以 signature-vectors.json 驗證簽章。

push.signature-valid

The endpoint accepts a correctly signed request.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
無
院方應做
Verify signature vector push-delivery and accept it.
Poieti 預期
狀態:written
院內檢查
poieti-his.mjs check 會執行

push.signature-replayed

A signature replayed on another path is rejected.

測試資料
—
注入狀況
signature-replayed Send verification vector reject-replayed-path.
院方應做
Reject with 401 and write nothing.
Poieti 預期
說明:Hospital-side check; no Poieti state.
院內檢查
poieti-his.mjs check 會執行

push.signature-stale

A signature older than 300 s is rejected.

測試資料
—
注入狀況
stale-signature Send verification vector reject-stale.
院方應做
Reject with 401 and write nothing.
Poieti 預期
說明:Hospital-side check; no Poieti state.
院內檢查
poieti-his.mjs check 會執行

push.signature-rotation

During a key rotation either key verifies.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
key-rotation Send verification vector accept-rotation-previous-key to an endpoint that still holds only the previous key.
院方應做
Accept when any v1 matches any held key.
Poieti 預期
狀態:written
院內檢查
poieti-his.mjs check 會執行

push.create-written

A create is written synchronously.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
無
院方應做
Write once, store (delivery_id, his_record_id) and answer 201 {hisRecordId}.
Poieti 預期
狀態:written
嘗試次數:1
院內檢查
poieti-his.mjs check 會執行

push.timeout-after-commit

A retry after a timed-out request does not write twice.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
timeout-after-commit The HIS commits but the response arrives after Poieti's timeout; Poieti retries with the same Idempotency-Key and identical body.
院方應做
Answer the retry with 200 and the original hisRecordId (or 409 DUPLICATE_DELIVERY with hisRecordId); keep one HIS record.
Poieti 預期
狀態:written
嘗試次數:2
院內檢查
poieti-his.mjs check 會執行

push.rejection-not-stored

A rejection is not cached against the deliveryId.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
rejected-then-fixed Answer 422 PATIENT_NOT_FOUND, then fix the HIS; hospital IT retries the delivery from the console.
院方應做
Process the retried deliveryId again and answer 201 {hisRecordId}.
Poieti 預期
狀態:written

push.correction-replaces

A correction replaces the record named by supersedes.hisRecordId in full.

測試資料
delivery-correction.json(DeliveryV1)
注入狀況
無
院方應做
Find the HIS record NA-20261016-0012 and replace every mapped field with this version, even if its admission is closed; identity comes from the original record. Answer 200 {hisRecordId} with the resulting HIS record id (the same id or a new one).
Poieti 預期
狀態:written
類型:correction

push.rows-replaced

Repeatable rows replace the stored row set as a whole.

測試資料
delivery-correction.json(DeliveryV1)
RFC 7386 merge patch
{
  "fields": {
    "FAMILY": [
      {
        "REL": "02",
        "LIVES_WITH": "true"
      }
    ]
  }
}
注入狀況
rows-removed Version 1 in the HIS has two FAMILY rows; this correction has one.
院方應做
Store exactly one FAMILY row: delete the rows that are not in the delivery. Answer 200 {hisRecordId}.
Poieti 預期
狀態:written
類型:correction

push.partial-date

A partial date is stored as rendered.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
無
院方應做
Store ONSET as 2026-10 (the mapping's text rendering); never invent a day or month. Answer 200 {hisRecordId}.
Poieti 預期
狀態:written

push.attachment-verified

Attachment bytes are fetched and verified before writing.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
無
院方應做
GET /his/v1/deliveries/{deliveryId}/attachments/{attachmentId} with a deliveries key; check Content-Length = 183204 and SHA-256 = attachments[0].sha256 before writing; answer 200 {hisRecordId}.
Poieti 預期
狀態:written

push.attachment-mismatch

Attachment bytes that fail verification are not written.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
attachment-corrupted The attachment route serves bytes whose SHA-256 differs from the delivery.
院方應做
Do not write. Answer a coded 4xx with {code: "ATTACHMENT_MISMATCH", retryable: true}.
Poieti 預期
狀態:pending
錯誤碼:ATTACHMENT_MISMATCH
可重試:true
說明:Poieti posts the same body again after the backoff, with X-Poieti-Attempt: 2.

push.missing-required

missingRequired lists a hospital-required field without a value.

測試資料
delivery-correction.json(DeliveryV1)
注入狀況
無
院方應做
Apply the hospital's documented policy: write without FOOD_ALG and flag it, or answer 422 with a non-retryable code such as REQUIRED_FIELD_MISSING. Never fill in a default. notSent is informational.
Poieti 預期
狀態之一:written / failed

push.identity-rejected

The HIS does not know the patient.

測試資料
delivery-create.json(DeliveryV1)
RFC 7386 merge patch
{
  "patient": {
    "medicalRecordNumber": "DEMO-404"
  }
}
注入狀況
unknown-patient DEMO-404 does not exist in the test HIS.
院方應做
Do not write. Answer 422 {code: "PATIENT_NOT_FOUND", retryable: false}.
Poieti 預期
狀態:failed
錯誤碼:PATIENT_NOT_FOUND
可重試:false
說明:Nurses can fix the patient and resend.
院內檢查
poieti-his.mjs check 會執行

push.identity-resend

After a nurse fixes the patient, the resend arrives as a new generation.

測試資料
delivery-create.json(DeliveryV1)
RFC 7386 merge patch
{
  "deliveryId": "7c6b5a49-3827-4615-9d4c-3b2a1f0e9d8c",
  "generation": 2
}
注入狀況
nurse-resend The generation-1 delivery failed with PATIENT_NOT_FOUND and the nurse resent it.
院方應做
Treat it as a new deliveryId: look it up, write once, answer 200 {hisRecordId}.
Poieti 預期
狀態:written
代次:2

push.retryable-failure

A temporary HIS failure is retried with the same deliveryId and body.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
his-temporarily-unavailable The HIS table is locked during attempt 1.
院方應做
Answer a coded 4xx such as 423 with {code: "HIS_LOCKED", retryable: true}. When the delivery returns (X-Poieti-Attempt: 2, identical body), write it and answer 200 {hisRecordId}.
Poieti 預期
狀態:written
嘗試次數:2
說明:After the first report the delivery is pending until its backoff ends.

push.unencodable-text

Text the HIS column cannot hold is reported, never altered.

測試資料
delivery-create.json(DeliveryV1)
RFC 7386 merge patch
{
  "target": {
    "charset": "utf-8"
  },
  "fields": {
    "CARE_NOTE": "傷口周圍皮膚完整𠀋"
  }
}
注入狀況
unencodable-text The CARE_NOTE column is Big5 and cannot store U+2000B.
院方應做
Do not truncate, drop or replace characters with ?. Answer 422 {code: "VALUE_UNENCODABLE", retryable: false} (or VALUE_TOO_LONG for an over-long value).
Poieti 預期
狀態:failed
錯誤碼:VALUE_UNENCODABLE
可重試:false

push.redeliver

After hospital-side data loss a written delivery is redelivered as a new generation.

測試資料
delivery-create.json(DeliveryV1)
RFC 7386 merge patch
{
  "deliveryId": "1e0d9c8b-7a69-4f58-8e47-3d2c1b0a9f8e",
  "generation": 2
}
注入狀況
hospital-data-loss The HIS record of generation 1 was lost; hospital IT redelivered it from the console.
院方應做
Treat the new deliveryId as new: write once and answer 200 {hisRecordId}.
Poieti 預期
狀態:written
代次:2

push.accepted-202

A queued write is followed up by status polling.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
async-import Answer 202; the status route answers 202 once, then 200 {hisRecordId}.
院方應做
Serve GET /deliveries/{deliveryId}: 202 while processing, 200 with hisRecordId when written.
Poieti 預期
狀態:written
院內檢查
poieti-his.mjs check 會執行

push.accepted-then-failed

A queued write is rejected by the import job.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
staging-import-rejected Answer 202; the import job then rejects the queued write.
院方應做
Answer GET /deliveries/{deliveryId} with a coded 4xx such as 422 {code: "IMPORT_REJECTED"}.
Poieti 預期
狀態:failed
錯誤碼:IMPORT_REJECTED

push.status-unknown

A status 404 makes Poieti post the delivery again.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
status-unknown Answer 202, then lose the queued item so GET /deliveries/{deliveryId} answers 404.
院方應做
Accept the repeated POST (same key, identical body) and write once.
Poieti 預期
狀態:written
院內檢查
poieti-his.mjs check 會執行

push.coded-rejection

A coded 4xx fails the delivery with that code.

測試資料
delivery-correction.json(DeliveryV1)
注入狀況
coded-rejection Answer 422 {code: "ENCOUNTER_CLOSED", retryable: false}.
院方應做
None further.
Poieti 預期
狀態:failed
錯誤碼:ENCOUNTER_CLOSED
可重試:false

push.uncoded-rejection

An uncoded 4xx with a healthy probe fails only that delivery.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
waf-block A gateway answers 400 with an HTML body for this delivery; GET /health answers 200.
院方應做
None; hospital IT reviews the gateway rule.
Poieti 預期
狀態:failed
錯誤碼:HIS_REJECTED
斷路器:{"open":false}

push.outage

An endpoint outage pauses dispatch without failing deliveries.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
outage POST /deliveries answers 503 and GET /health fails for an hour.
院方應做
None; dispatch resumes after /health recovers.
Poieti 預期
狀態:pending
斷路器:{"open":true,"reason":"unreachable"}
說明:The attempt is not counted; one his.push.paused alert, then his.push.resumed on recovery.

push.auth-failure

401/403 pause dispatch until the endpoint token changes.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
bad-token The endpoint answers 401 to every request.
院方應做
Hospital IT and Poieti staff fix the token with set-his-endpoint.
Poieti 預期
狀態:pending
斷路器:{"open":true,"reason":"auth"}

push.health

The probe route answers a signed GET.

測試資料
—
注入狀況
無
院方應做
Verify signature vector push-health and answer 200.
Poieti 預期
說明:Used by the gateway before charging suspect responses.
院內檢查
poieti-his.mjs check 會執行

push.census-fetch

Poieti fetches a ward census.

測試資料
census-snapshot-context.json(CensusSnapshotV1)
注入狀況
無
院方應做
Answer GET /census/wards/8B with the ward's CensusSnapshotV1.
Poieti 預期
回應:{"status":200}
說明:Applied like an upload; context rows replaced per kind.
院內檢查
poieti-his.mjs check 會執行

push.oversized-response

A response body over 64 KB is endpoint-suspect.

測試資料
delivery-create.json(DeliveryV1)
注入狀況
oversized-response Answer 201 with a 70 KB body.
院方應做
Keep delivery responses small.
Poieti 預期
狀態之一:pending / failed
說明:Probe passes → failed HIS_REJECTED; probe fails → deferred and circuit opens.
院內檢查
poieti-his.mjs check 會執行

金鑰與存取#

金鑰、來源 IP、範圍與限流被拒時,端點應停止並通知資訊人員,不可密集重試。

auth.ip-not-allowed

Requests from an address outside the credential's CIDRs are refused.

測試資料
—
注入狀況
ip-not-allowed Call from an address outside allowed_cidrs.
院方應做
Stop and alert hospital IT; do not retry in a tight loop.
Poieti 預期
回應:{"status":403,"code":"HIS_IP_NOT_ALLOWED"}

auth.revoked

A revoked key stops working on the next request.

測試資料
—
注入狀況
revoked-credential Poieti staff revoke the credential.
院方應做
Stop and alert hospital IT; do not retry in a tight loop.
Poieti 預期
回應:{"status":401,"code":"HIS_UNAUTHORIZED"}

auth.scope-denied

A census-only key cannot download attachments.

測試資料
—
注入狀況
wrong-scope Download an attachment with a credential whose scopes are [census].
院方應做
Use the deliveries credential for delivery routes.
Poieti 預期
回應:{"status":403,"code":"HIS_SCOPE_DENIED"}

auth.rate-limited

Bursts above 120 requests per minute are limited.

測試資料
—
注入狀況
rate-limited Send 130 requests within a minute.
院方應做
Wait for Retry-After seconds before the next request.
Poieti 預期
回應:{"status":429,"code":"HIS_RATE_LIMITED"}

病房名單上傳#

PUT /his/v1/census/wards/{wardCode} 的套用、重送與拒收。需要 census 範圍的金鑰與機構的名單開關。

census.upload

A snapshot is applied. Before: DEMO-001 is an HIS patient of 8B, DEMO-003 an active HIS patient, DEMO-009 a manual patient with another name and no matching encounter, DEMO-007 an HIS patient of 8B; DEMO-002 is unknown.

測試資料
census-snapshot.json(CensusSnapshotV1)
注入狀況
無
院方應做
PUT /his/v1/census/wards/8B with the snapshot.
Poieti 預期
回應:{"status":200,"replayed":false}
名單結果:{"created":1,"updated":1,"discharged":1,"missing":1,"rejected":[{"medicalRecordNumber":"DEMO-009","code":"IDENTITY_CONFLICT"}]}

census.replay

The same snapshot uploaded again changes nothing.

測試資料
census-snapshot.json(CensusSnapshotV1)
注入狀況
replayed-snapshot Upload census.upload's snapshot a second time.
院方應做
None.
Poieti 預期
回應:{"status":200,"replayed":true}
名單結果:{"created":0,"updated":0,"discharged":0,"missing":0}

census.stale

An older snapshot is refused.

測試資料
census-snapshot.json(CensusSnapshotV1)
RFC 7386 merge patch
{
  "asOf": "2026-10-16T14:40:00+08:00"
}
注入狀況
stale-snapshot Upload after census.upload.
院方應做
Discard the old snapshot; send the next one with a newer asOf.
Poieti 預期
回應:{"status":409,"code":"CENSUS_STALE"}

census.same-asof-changed

A changed snapshot must carry a new asOf.

測試資料
census-snapshot.json(CensusSnapshotV1)
RFC 7386 merge patch
{
  "patients": [
    {
      "medicalRecordNumber": "DEMO-001",
      "encounterId": "A2026101601",
      "displayName": "示範病人",
      "bed": "8B-14"
    }
  ]
}
注入狀況
same-asof-changed Upload after census.upload with the same asOf and different patients.
院方應做
Take a fresh snapshot with its own asOf.
Poieti 預期
回應:{"status":409,"code":"CENSUS_STALE"}

census.missing-offset

asOf without an offset is invalid.

測試資料
census-snapshot.json(CensusSnapshotV1),契約本身即拒收的測試資料
RFC 7386 merge patch
{
  "asOf": "2026-10-16T15:40:00"
}
注入狀況
無
院方應做
Send RFC 3339 times with an offset, for example +08:00.
Poieti 預期
回應:{"status":422,"code":"HIS_CENSUS_INVALID"}

census.duplicate-chart-number

A chart number that appears twice invalidates the snapshot.

測試資料
census-snapshot.json(CensusSnapshotV1)
RFC 7386 merge patch
{
  "patients": [
    {
      "medicalRecordNumber": "DEMO-001",
      "encounterId": "A2026101601",
      "displayName": "示範病人"
    },
    {
      "medicalRecordNumber": "DEMO-001",
      "encounterId": "A2026101699",
      "displayName": "示範病人"
    }
  ]
}
注入狀況
無
院方應做
Fix the HIS query so each patient appears once.
Poieti 預期
回應:{"status":422,"code":"HIS_CENSUS_INVALID"}

census.unknown-ward

An unknown ward code is refused.

測試資料
census-snapshot.json(CensusSnapshotV1)
注入狀況
unknown-ward PUT to /his/v1/census/wards/ZZ, which no ward uses.
院方應做
Ask Poieti staff to set the ward's HIS code.
Poieti 預期
回應:{"status":404,"code":"WARD_NOT_FOUND"}

census.context-outside-push

Clinical context is refused unless the institution is in push mode.

測試資料
census-snapshot-context.json(CensusSnapshotV1)
注入狀況
context-outside-push Upload to an institution in mode off with census on.
院方應做
Send identity and admission data only.
Poieti 預期
回應:{"status":422,"code":"CENSUS_CONTEXT_DISABLED"}

census.absent-not-discharged

A patient missing from a complete snapshot is flagged, not discharged.

測試資料
census-snapshot.json(CensusSnapshotV1)
注入狀況
patient-absent DEMO-007 is an HIS patient of 8B and is not in the snapshot.
院方應做
Send discharged: true to discharge a patient.
Poieti 預期
名單結果:{"missing":1,"discharged":1}
說明:DEMO-007 stays active with census_missing_since set; only DEMO-003 is discharged.

census.ward-scope

A credential limited to other census wards cannot upload this ward.

測試資料
census-snapshot.json(CensusSnapshotV1)
注入狀況
ward-not-allowed The credential's census wards are [8A].
院方應做
Use a credential that covers the ward.
Poieti 預期
回應:{"status":403,"code":"HIS_SCOPE_DENIED"}

census.disabled

Uploads are refused while census is off for the institution.

測試資料
census-snapshot.json(CensusSnapshotV1)
注入狀況
census-disabled The institution's census switch is off.
院方應做
Stop uploading until Poieti staff enable census.
Poieti 預期
回應:{"status":409,"code":"HIS_CENSUS_DISABLED"}
Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1