goalkeeper 客戶 API 使用手冊（串接方）

給要串接本服務的廠商。說明開通時拿到什麼、送什麼資料、怎麼判讀回應。本服務收一段「AI 產出的醫療內容」，依台灣醫療法規回報每道檢查的符合狀態。放行與否由你自行判讀，服務不替你做整體決定。

1. 開通時會拿到什麼

項目	說明
API 金鑰（API Key）	明碼字串，格式 `<你的客戶代號>.<隨機字串>`，例如 `clinic-1.4dc5…`。只在開通時給一次，遺失只能請我們輪替重發。每次呼叫放在 `X-API-Key` 標頭。
服務網址（Base URL）	例 `https://api.<域名>/`，測試與正式不同。
租戶設定	依約定替你設好：月配額（每月可呼叫次數）、是否鎖定規範版本（確保可重現）、是否只啟用某幾道檢查。這些綁在金鑰上自動套用，你不用自己帶。

金鑰對應一個租戶帳號，用量與稽核都歸戶在此，等同你的身分，請勿外流。

2. 送什麼

主要呼叫：`POST /medical/validate`

POST /medical/validate
X-API-Key: <你的金鑰>
Content-Type: application/json

{
  "content": "要查核的 AI 產出文字內容…",   // 必填
  "audience": "patient",                      // 必填：patient（對民眾）| clinician（對醫事人員）
  "content_type": "discharge_summary",        // 選填：用途提示（影響越權判斷）
  "options": { "checks": ["disclosure", "pii"] } // 選填：只跑指定幾道（須在你被授權的範圍內）
}

content：AI 實際產出、預備給人看的內容，例如病人衛教訊息、出院摘要、衛教回覆。上限 20,000 字元，超過會以 400（格式驗證失敗）回報。不要為了塞進上限而截斷送驗，截斷會改變語意，判定也跟著失真。
audience（必填）：對民眾與對醫事人員的判定標準不同。同一段沒揭露 AI 生成的內容，對民眾是 fail，對醫事人員是 warning。不確定對象就帶 patient，那是比較嚴的一邊。
content_type：用途提示，主要影響越權診斷的判斷。不帶會偏保守。
options.checks：只想跑部分檢查時用。實際執行的是你帶的關卡與你被授權關卡的交集。

隱私：直接送原文就好。本服務會先在內部去識別化（遮罩身分證、電話這類欄位），之後全程在遮罩後文本上判定，你的原文與個資原值不會寫進稽核。

3. 收到什麼、怎麼判讀

回應範例

{
  "request_id": "req_…",
  "ruleset": "medical",
  "ruleset_version": "medical-115.05.29",     // 實際採用的規範版本
  "checks_run": ["disclosure","source_attribution","scope_boundary","pii","hallucination"],
  "checks_skipped": [],
  "checkpoints": [
    {
      "id": "disclosure",
      "name": "AI 生成揭露／免責提醒",
      "status": "fail",                        // ← 逐關卡狀態（重點）
      "engine": "rule+llm",
      "confidence": null,
      "reason": "對民眾情境未偵測到任何揭露要素",
      "citation": "醫療機構應用生成式人工智慧指引 三(三)4(1)；病人自主權利法 第5條",
      "evidence": []                           // pii 關卡會回 {type, span}（遮罩座標，無原值）
    }
    // …其餘關卡
  ],
  "summary": { "pass": 2, "warning": 1, "fail": 1, "error": 1 }
}

五道檢查

id	名稱	看什麼
`disclosure`	揭露／免責提醒	是否註明 AI 生成、可能有誤、僅供參考、必要時由醫事人員確認
`source_attribution`	來源標註	實質臨床/事實主張是否有溯源
`scope_boundary`	越權／越級診斷	是否逾越為「下確定診斷/治療指令」或冒充醫事人員親自執行
`pii`	個資外洩	是否夾帶可識別個資（身分證、電話、病歷號…）
`hallucination`	幻覺查核	編造文獻、錯誤藥物交互、與臨床指引不符（三子型）

狀態語意

status	意義	你該怎麼做
`pass`	該關卡要求達成	通過
`fail`	明確違反規範	擋下／要求修正
`warning`	模糊／部分達成／信心低	需人工覆核，不可當通過
`error`	該關卡未能查核（如 LLM 逾時、外部查核失敗）	非通過，視為需覆核或重試；該關卡的 `errorCode` 欄標根因（如 `llm_unavailable`）

判讀鐵則

服務只回各關卡狀態，不做整體放行決定，所以判讀是你的責任，要逐關卡讀。
error ≠ pass。不可只看 summary.fail === 0 就放行；warning 與 error 都算未通過／需人工覆核。
summary 只是計數方便，不能取代逐關卡判讀。
建議的放行條件：所有關卡皆 pass 才自動放行，任一 fail 擋下，任一 warning/error 轉人工。
臨床指引子型目前定位是輔助提示，多回 warning，以人工複核為準。

4. 其他端點

`GET /medical/describe`

查可帶哪些參數、有哪幾道關卡、各自依據什麼法條。不需金鑰，適合拿來自我檢查串接格式。

`GET /medical/audit?limit=&cursor=`（需金鑰）

查你自己的稽核紀錄：每次呼叫的時間、規範版本、各關卡狀態摘要，不含原文或個資。

回 { items: [...], next_cursor }。翻頁時把上一頁的 next_cursor 帶回 ?cursor=，next_cursor 為 null 表示沒有下一頁。
limit 預設 50、上限 200。
以金鑰歸戶，只看得到自己的紀錄，讀不到別人的。

5. HTTP 狀態碼

碼	意義	處理
`200`	正常（含部分關卡 error 也是 200）	逐關卡判讀
`400`	請求格式錯誤（缺 audience、JSON 壞、content 超過 20,000 字元…）；回 `{error:"invalid_request", issues}`	修正請求後重送
`401`	（僅 `/medical/audit`）未帶有效金鑰	帶正確 `X-API-Key`
`403`	你的帳號被停用（suspended）	聯絡我們
`404`	規範版本不存在	檢查路徑版本
`429`	超過月配額	看 `Retry-After`（到下月初的秒數）後再試，或洽談調額

validate 與 describe 不帶金鑰也會回 200，走匿名身分與預設設定。但正式串接請務必帶金鑰，才會套用你的配額、版本與關卡設定，也才會計入你的稽核。

6. 串接檢查清單

拿到金鑰與 Base URL。
先打 GET /medical/describe 確認格式與關卡清單。
POST /medical/validate，帶 X-API-Key、content、audience。
逐關卡讀 status，依判讀鐵則決定放行、擋下或轉人工。別只看 summary。
需要對帳時用 GET /medical/audit。
金鑰外洩或遺失就立刻聯絡我們輪替。

7. 範例（curl）

# 查核一段對民眾的衛教內容
curl -X POST "$BASE_URL/medical/validate" \
  -H "X-API-Key: $KEY" -H "content-type: application/json" \
  -d '{"content":"本內容由 AI 生成，可能有誤，僅供參考，必要時由醫事人員確認。","audience":"patient"}'

# 查自己的稽核
curl "$BASE_URL/medical/audit?limit=20" -H "X-API-Key: $KEY"

8. MCP 模式（給 AI agent 串接）

除了 REST，同一個網址也提供 MCP Server（遠端 HTTP，JSON-RPC 2.0），讓 AI agent（Claude Desktop、IDE、agent runtime…）把醫療內容合規查核當一個工具直接呼叫。兩邊同一把金鑰、同一套多租戶、配額與稽核，換的只是協定。

連線：在你的 MCP client 加一個遠端 server，URL 填 $BASE_URL/mcp，認證標頭填 Authorization: Bearer <你的金鑰>，或用 X-API-Key 也可以。

提供的工具（tools）

工具	用途	認證
`validate_medical_content`	查核一段內容，回各關卡狀態（同 REST 結果）	選填（無金鑰＝匿名共用額度）
`get_my_usage`	查當期用量 `{ period, used, quota, remaining }`	需金鑰
`list_my_audits`	分頁查自己的稽核	需金鑰

資源（resource）：goalkeeper://medical/describe，提供規範參數、關卡清單與依據法條，agent 可自讀脈絡。

判讀：validate_medical_content 的結果與 REST 完全一致，agent 一樣要逐關卡讀 status，依第 3 節的判讀鐵則決定（error/warning 都不是通過）。這裡最常見的失誤是讓模型自己「看起來沒問題就過」，等於把判讀權交回給你原本想守門的那個模型，鐵則請寫死在決策邏輯裡。

錯誤：帳號停用、超配額、audit/usage 未帶金鑰這類業務錯誤，以工具錯誤（isError）回給 agent；JSON 格式或未知方法這類協定錯誤，回 JSON-RPC error。

兩種模式可以並用：傳統系統走 REST、AI agent 走 MCP，背後是同一個服務與同一份稽核、配額。

有問題找誰

要調整配額、規範版本或啟用哪幾道檢查，寫信到 service@yao.care。