介接約定

寫入與重試

新增、修改、刪除／作廢、成功回執與重試規則。

寫入操作#

操作	接口行為
新增	驗證提交的欄位與關聯，建立紀錄，回傳 ID 及版本。
修改	指定紀錄 ID 與版本；定義可修改欄位、省略與清除的意義。
刪除／作廢	說明是否支援、允許的狀態、刪除或作廢方式，以及是否可復原。

每個資源列出支援的操作與狀態限制。以下是可調整的傷口評估範例；資料未通過驗證時回傳錯誤，不寫入部分紀錄。

成功回應#

201 Created · 同步寫入成功

{
  "clientRequestId": "REQ-DEMO-001",
  "recordId": "R-DEMO-001",
  "version": 1,
  "status": "committed",
  "recordState": "valid",
  "recordedAt": "2026-09-23T09:31:00+08:00"
}

recordId 用來查回紀錄；version 用於更新時比對。status 表示操作已寫入，recordState 表示紀錄有效或作廢。若採非同步處理，先回 202 與作業 ID，另提供狀態查詢；已受理不等於已寫入。

冪等性與逾時#

情況	接口行為
同 ID、同方法／路徑／內容	回原提交結果，不再執行
同 ID、方法／路徑／內容不同	`409`，回 `IDEMPOTENCY_CONFLICT`
逾時或斷線	用原 ID 查結果；需重試時保持原 ID 與內容
查不到結果	結果尚未確定；在去重有效期內以原 ID 重試，不換新 ID

GET/requests/{clientRequestId}

本例的 clientRequestId 在同一機構內唯一，至少保留 7 天；實際範圍與期限需約定。每次新操作使用新 ID，重試沿用原 ID。重送先回原回執，不能因版本已增加而誤報衝突；並行提交也只執行一次。超過去重期限先核對原結果。

版本衝突#

更正接口帶上讀取時的 version，或使用 ETag／If-Match。若資料已被修改，回 409 VERSION_CONFLICT 或 412；呼叫方重新讀取並處理衝突後再送。已簽核紀錄依院方規則更正，保留歷史。

修改範例#

PATCH/wound-assessments/{recordId}

以 R-DEMO-001 為例，先讀取最新版本。本例只允許修改 careNote，其他欄位保留，且不接受 null。成功後版本由 1 增至 2。

PATCH 請求

{
  "clientRequestId": "REQ-DEMO-002",
  "version": 1,
  "changes": {
    "careNote": "本次已清潔並更換敷料，敷料固定完整。"
  }
}

200 OK

{
  "clientRequestId": "REQ-DEMO-002",
  "recordId": "R-DEMO-001",
  "version": 2,
  "status": "committed",
  "recordState": "valid",
  "recordedAt": "2026-09-23T09:40:00+08:00"
}

過期版本回 409 VERSION_CONFLICT；已作廢紀錄回 409 RECORD_STATE_CONFLICT。可修改欄位與清除規則由院方定義。

作廢範例#

POST/wound-assessments/{recordId}/void

本例採作廢，不永久刪除。接續上例，以版本 2 作廢紀錄；保留內容與原因，單筆查詢仍可取得紀錄及作廢狀態。

POST 請求

{
  "clientRequestId": "REQ-DEMO-003",
  "version": 2,
  "reason": "重複登錄"
}

200 OK

{
  "clientRequestId": "REQ-DEMO-003",
  "recordId": "R-DEMO-001",
  "version": 3,
  "status": "committed",
  "recordState": "voided",
  "recordedAt": "2026-09-23T09:45:00+08:00"
}

本例作廢後不可修改或復原；新請求再次作廢回 409，原 ID 重送仍回原成功回執。若院方支援實際刪除，需說明成功回應、刪除後查詢結果及是否可復原。

驗證錯誤#

422 Unprocessable Entity

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "請檢查欄位格式。",
    "fields": [
      {
        "path": "observedAt",
        "message": "請使用含時區的 ISO 8601 時間，例如 2026-09-23T09:30:00+08:00。"
      }
    ]
  },
  "requestId": "TRACE-DEMO-001"
}

回傳穩定錯誤碼、出錯欄位、格式提示和追蹤 ID。驗證失敗時不寫入部分紀錄，呼叫方修正後建立新一次提交。