介接約定

連線與授權

連線參數、認證方式、使用者對應與權限檢查。

連線參數#

項目	請提供
測試環境	Base URL、允許的連線路徑、測試窗口
認證方式	OAuth／SSO 或服務帳號；核發、有效期限與更新方式
使用者對應	如何把登入者對應至院內帳號、機構及操作範圍
運作限制	逾時、限流及接口版本變更通知方式

不要求 HIS 公開到網際網路。連線可按院方網路政策規劃；實際憑證透過安全管道交付，不放進文件或 iOS App。

權限檢查#

從可信的認證身分取得使用者與機構，再檢查病人、紀錄及附件的操作權限。
使用服務帳號時，另行約定可驗證的操作者傳遞方式；不能只信任請求內的 userId。
寫入時留下實際操作者、時間、紀錄版本和請求追蹤 ID。

HTTP 狀態碼#

HTTP	意思	呼叫方下一步
`401`	憑證無效或過期	更新授權，再重試
`403`	已認證，但無操作權限	停止操作，檢查帳號範圍
`429`	超過限流	依 `Retry-After` 等待；寫入仍沿用原請求 ID