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 必填：對民眾（patient）與對醫事人員（clinician）判定標準不同（例：對民眾未揭露 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，背後是同一個服務與同一份稽核/配額。

有問題或要調整配額/版本/關卡設定，請聯絡我們。