人機驗證（擋註冊機器人）

這篇會帶你做到什麼

在你自己的網頁上放一個驗證元件，通過後拿到 captcha_ticket，再把 ticket 一起送進登入或註冊。

重點：驗證供應商（Turnstile／ALTCHA／Cap）由平台統一管理，你不需要申請任何第三方金鑰。

先打這 2 支就好

設定層面（要不要啟用、哪種供應商）：GET /v1/captcha/config，需要 App 金鑰。

第 1 步：問平台「我該用哪一種」

curl -s "https://api.hsystem.halphastech.com/v1/captcha/web/bootstrap?client_id=YOUR_CLIENT_ID"

回應會告訴你供應商種類與前端需要的參數（例如 site key）。不要在前端寫死供應商——換供應商時你的程式不該跟著改。

第 2 步：拿到 ticket

使用者完成元件上的驗證後，前端把供應商給的 token 換成平台的 ticket：

curl -s -X POST https://api.hsystem.halphastech.com/v1/captcha/web/verify \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "token": "供應商回傳的 token",
    "purpose": "register"
  }'

{ "ok": true, "captcha_ticket": "ct_demo_123", "score": 0.9 }

purpose 要用你真正的情境（register／login 等）。ticket 通常只能用一次、且有時效，失敗就重新驗證，不要重送同一張。

第 3 步：帶著 ticket 送出請求

把你原本的註冊／登入請求，加上 captcha_ticket 欄位即可。被擋下時的回應會是 4xx 並在 code 說明原因，對照錯誤碼處理：

• ticket 過期：重新拿一張。
• 分數太低：換一個驗證方式，或先確認是不是有自動化流量。

什麼時候會需要它

• 註冊一直被灌假帳號。
• 登入有密碼猜測攻擊。
• 寄驗證碼／簡訊的花費突然暴增（簡訊尤其貴）。

常見錯誤

• 在自己的前端接第三方金鑰：不需要，也不該；一律走 bootstrap。
• 把 ticket 存起來重複使用：不行，它是一次性的。
• 以為驗證過就等於登入：ticket 只是「這是真人」的證明，身份驗證仍然是登入流程的事。