---
title: WHMCS
---

# 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`](https://dash.captcha.la) 取得您的 **App Key** + **App Secret**

## 安裝

### 1. 安裝模組

1. 從 [releases](https://github.com/Captcha-La/captchala-whmcs/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`](https://github.com/Captcha-La/captchala-whmcs)
- 問題回報 / 功能建議：請在上述儲存庫開 issue
- 相關文件：[Web SDK](/zh-TW/web-sdk) · [PHP 伺服端 SDK](/zh-TW/sdk/server-php) · [API 參考](/zh-TW/api-reference)