--- title: WHMCS --- # WHMCS Module addon WHMCS chính thức của CaptchaLa. Thêm xác minh CAPTCHA cho khu vực khách hàng của WHMCS — đăng nhập, đăng ký, đặt lại mật khẩu, biểu mẫu liên hệ, gửi ticket và thanh toán giỏ hàng — mà không cần viết bất kỳ dòng mã nào. Khác với một widget site-key đơn thuần, mọi thử thách đều được hậu thuẫn bởi một **token dùng một lần do máy chủ phát hành** (chống phát lại), và không nạp bất kỳ trình theo dõi bên thứ ba nào. ## Phạm vi bảo vệ Mỗi mục dưới đây là một toggle độc lập trong cài đặt của module — chỉ bật những điểm vào bạn muốn bảo vệ. - Đăng nhập - Đăng ký - Đặt lại mật khẩu - Biểu mẫu liên hệ - Gửi ticket - Thanh toán giỏ hàng ## Yêu cầu - WHMCS 8.x và 9.x (đã kiểm thử trên khu vực khách hàng 8.3 và 9.0; hoạt động với cả hai theme `six` và `twenty-one`, có hoặc không bật Friendly URLs) - PHP 8.0+ (bản thân WHMCS 9.0 yêu cầu PHP 8.2+) - Một tài khoản CaptchaLa — lấy **App Key** + **App Secret** của bạn tại [`dash.captcha.la`](https://dash.captcha.la) ## Cài đặt ### 1. Cài module 1. Tải `whmcs-x.y.z.zip` mới nhất từ [releases](https://github.com/Captcha-La/captchala-whmcs/releases). 2. Giải nén vào thư mục **gốc WHMCS** của bạn. Việc này thêm `modules/addons/captchala/`. 3. Trong quản trị WHMCS, vào **Setup → Addon Modules**, tìm **CaptchaLa**, và nhấn **Activate**. ### 2. Cấu hình Nhấn **Configure**, rồi: 1. Dán **App Key** và **App Secret** của bạn. 2. Chọn một **Widget mode** và **Theme**. 3. Bật các biểu mẫu bạn muốn bảo vệ. 4. Nhấn **Save Changes**. Mở trang **CaptchaLa** ở thanh bên quản trị để chạy thử nghiệm kết nối trực tiếp tới bảng điều khiển. ::: tip Sau khi kích hoạt, nếu widget không xuất hiện, hãy lưu lại cài đặt module một lần — WHMCS chỉ đăng ký `hooks.php` của module khi module được (tái) kích hoạt/lưu. ::: ## Cấu hình Mọi cài đặt nằm tại **Setup → Addon Modules → CaptchaLa → Configure**. | Cài đặt | Kiểu | Mặc định | Mô tả | | --- | --- | --- | --- | | App Key | string | — | Khóa công khai từ bảng điều khiển CaptchaLa. Bắt buộc. | | App Secret | string | — | Bí mật máy chủ, dùng để phát hành và xác thực token. Bắt buộc; không bao giờ lộ ra trình duyệt. | | Widget mode | enum | `popup` | `popup` (thanh kích hoạt → thử thách toàn màn hình), `float` (bảng nội tuyến), `embed` (hộp kiểm nội tuyến), `bind` (vô hình, chặn việc gửi). | | Theme | enum | `default` | Bộ màu định sẵn: `default`, `dark`, `slate`, `emerald`, `amber`, `rose`. | | Language | string | `auto` | Mã BCP-47 (ví dụ `en`, `zh`, `de`) hoặc `auto` để theo trình duyệt. | | Protect login | bool | on | Áp thử thách cho đăng nhập khu vực khách hàng. | | Protect registration | bool | on | Áp thử thách cho đăng ký tài khoản mới. | | Protect password reset | bool | on | Áp thử thách cho biểu mẫu đặt lại mật khẩu. | | Protect contact form | bool | off | Áp thử thách cho biểu mẫu liên hệ. | | Protect ticket submission | bool | off | Áp thử thách cho bước gửi ticket cuối cùng. | | Protect cart checkout | bool | off | Áp thử thách cho thanh toán giỏ hàng. | | Skip for logged-in users | bool | on | Không áp thử thách cho khách đã có phiên đăng nhập khách hàng. | | Failure message | string | — | Thông báo hiển thị khi xác minh thất bại. | ## Cách hoạt động Trên mỗi trang biểu mẫu được bảo vệ, module phát hành một **token máy chủ (`sct_`)** mới từ bảng điều khiển, được giới hạn theo action của biểu mẫu đó, và hiển thị widget gắn với nó. Sau khi khách giải xong thử thách, SDK ghi một **token vượt qua dùng một lần (`pt_`)** vào biểu mẫu. Khi gửi, module xác thực `pt_` đó ở phía máy chủ trước khi WHMCS xử lý biểu mẫu; các trường hợp phát lại và action không khớp đều bị từ chối. Nếu bảng điều khiển tạm thời không truy cập được, module sẽ **fail open** (cho phép việc gửi đi qua) để khu vực khách hàng của bạn không bao giờ bị khóa do sự cố nhất thời ở thượng nguồn. ## Câu hỏi thường gặp **Module có miễn phí không?** Có. Module là miễn phí. Gói miễn phí của CaptchaLa bao gồm 10,000 lượt xác minh mỗi tháng — gói trả phí chỉ áp dụng khi bạn cần lưu lượng cao hơn. **Nó có hoạt động trên cả WHMCS 8 và 9 không?** Có — đã kiểm thử trên khu vực khách hàng 8.3 và 9.0, với theme `six` và `twenty-one`, có hoặc không bật Friendly URLs. **Widget không hiển thị.** Hãy lưu lại cài đặt module một lần (Configure → Save Changes). WHMCS chỉ đăng ký `hooks.php` khi module được (tái) kích hoạt/lưu. ## Mã nguồn - Kho module: [`github.com/Captcha-La/captchala-whmcs`](https://github.com/Captcha-La/captchala-whmcs) - Lỗi / yêu cầu tính năng: gửi vào kho ở trên - Liên quan: [Web SDK](/vi/web-sdk) · [PHP Máy chủ SDK](/vi/sdk/server-php) · [Tham chiếu API](/vi/api-reference)