WHMCS

CaptchaLa 官方 WHMCS 外掛模組。無需撰寫任何程式碼，即可為 WHMCS 客戶區加上 CAPTCHA 驗證 —— 登入、註冊、重設密碼、聯絡表單、工單送出與購物車結帳。

不同於單純的 site-key 元件，每一次挑戰皆以伺服端簽發、單次使用的權杖（防重放）為後盾，且不會載入任何第三方追蹤器。

涵蓋範圍

下列每一項在模組設定中皆為獨立的開關 —— 只啟用您想保護的入口即可。

• 登入
• 註冊
• 重設密碼
• 聯絡表單
• 工單送出
• 購物車結帳

系統需求

• WHMCS 8.x 與 9.x（已在 8.3 與 9.0 客戶區測試；相容 six 與 twenty-one 兩種主題，無論是否啟用 Friendly URLs）
• PHP 8.0+（WHMCS 9.0 本身需要 PHP 8.2+）
• 一個 CaptchaLa 帳號 —— 於 dash.captcha.la 取得您的 App Key + App Secret

安裝

1. 安裝模組

1. 從 releases 下載最新的 whmcs-x.y.z.zip。
2. 解壓縮至您的 WHMCS 根目錄。這會新增 modules/addons/captchala/。
3. 於 WHMCS 後台前往 Setup → Addon Modules，找到 CaptchaLa，點擊 Activate。

2. 設定

點擊 Configure，然後：

1. 貼上您的 App Key 與 App Secret。
2. 選擇 Widget mode 與 Theme。
3. 開啟您想保護的表單。
4. 點擊 Save Changes。

開啟後台側邊欄的 CaptchaLa 頁面，可對控制台執行即時連線測試。

TIP

啟用後若元件未顯示，請重新儲存一次模組設定 —— WHMCS 僅在模組（重新）啟用／儲存時才會註冊該模組的 hooks.php。

設定項目

所有設定皆位於 Setup → Addon Modules → CaptchaLa → Configure。

設定項目	型別	預設值	說明
App Key	string	—	來自 CaptchaLa 控制台的公開金鑰。必填。
App Secret	string	—	伺服端密鑰，用於簽發與驗證權杖。必填；絕不暴露給瀏覽器。
Widget mode	enum	popup	popup（觸發列 → 全螢幕挑戰）、float（內嵌面板）、embed（內嵌核取方塊）、bind（隱形，攔截送出）。
Theme	enum	default	配色預設：default、dark、slate、emerald、amber、rose。
Language	string	auto	BCP-47 代碼（例如 en、zh、de）或 auto（跟隨瀏覽器）。
Protect login	bool	on	對客戶區登入加上挑戰。
Protect registration	bool	on	對新帳號註冊加上挑戰。
Protect password reset	bool	on	對重設密碼表單加上挑戰。
Protect contact form	bool	off	對聯絡表單加上挑戰。
Protect ticket submission	bool	off	對工單送出的最終步驟加上挑戰。
Protect cart checkout	bool	off	對購物車結帳加上挑戰。
Skip for logged-in users	bool	on	不對已具備客戶連線階段的訪客加上挑戰。
Failure message	string	—	驗證失敗時顯示的訊息。

運作方式

在每個受保護的表單頁面上，模組會從控制台簽發一個全新的伺服端權杖（sct_），其作用範圍綁定該表單的 action，並渲染與其綁定的元件。訪客解開挑戰後，SDK 會在表單中寫入一個單次使用的通行權杖（pt_）。送出時，模組會在 WHMCS 處理表單之前於伺服端驗證該 pt_；重放與 action 不符皆會被拒絕。

若控制台暫時無法連線，模組會故障開放（放行該次送出），讓您的客戶區永遠不會因上游瞬斷而被鎖死。

常見問題

模組是免費的嗎？

是的。模組本身免費。CaptchaLa 免費方案包含每月 10,000 次驗證 —— 僅在需要更高用量時才會涉及付費方案。

在 WHMCS 8 與 9 上都能運作嗎？

可以 —— 已在 8.3 與 9.0 客戶區測試，相容 six 與 twenty-one 主題，無論是否啟用 Friendly URLs。

元件沒有顯示出來。

請重新儲存一次模組設定（Configure → Save Changes）。WHMCS 僅在模組（重新）啟用／儲存時才會註冊 hooks.php。

原始碼

• 模組儲存庫：github.com/Captcha-La/captchala-whmcs
• 問題回報 / 功能建議：請在上述儲存庫開 issue
• 相關文件：Web SDK · PHP 伺服端 SDK · API 參考