---
title: WHMCS
---

# WHMCS

Modul addon WHMCS rasmi CaptchaLa. Menambah pengesahan CAPTCHA ke kawasan klien WHMCS — log masuk, pendaftaran, reset kata laluan, borang hubungan, penghantaran tiket dan pembayaran troli — tanpa menulis sebarang kod.

Tidak seperti widget site-key biasa, setiap cabaran disokong oleh **token sekali guna yang dikeluarkan pelayan** (anti-replay), dan tiada penjejak pihak ketiga dimuatkan.

## Apa yang dilindungi

Setiap permukaan di bawah ialah togol berasingan dalam tetapan modul — aktifkan hanya yang anda mahu lindungi.

- Log masuk
- Pendaftaran
- Reset kata laluan
- Borang hubungan
- Penghantaran tiket
- Pembayaran troli

## Keperluan

- WHMCS 8.x dan 9.x (diuji terhadap kawasan klien 8.3 dan 9.0; berfungsi dengan tema `six` dan `twenty-one`, dengan atau tanpa Friendly URLs)
- PHP 8.0+ (WHMCS 9.0 sendiri memerlukan PHP 8.2+)
- Akaun CaptchaLa — dapatkan **App Key** + **App Secret** anda di [`dash.captcha.la`](https://dash.captcha.la)

## Pasang

### 1. Pasang modul

1. Muat turun `whmcs-x.y.z.zip` terkini dari [releases](https://github.com/Captcha-La/captchala-whmcs/releases).
2. Ekstrak ke dalam direktori **root WHMCS** anda. Ini menambah `modules/addons/captchala/`.
3. Dalam admin WHMCS, pergi ke **Setup → Addon Modules**, cari **CaptchaLa**, dan klik **Activate**.

### 2. Konfigurasi

Klik **Configure**, kemudian:

1. Tampal **App Key** dan **App Secret** anda.
2. Pilih **Widget mode** dan **Theme**.
3. Aktifkan borang yang mahu dilindungi.
4. Klik **Save Changes**.

Buka halaman **CaptchaLa** di bar sisi admin untuk menjalankan ujian sambungan langsung terhadap papan pemuka.

::: tip
Selepas mengaktifkan, jika widget tidak muncul, simpan semula tetapan modul sekali — WHMCS hanya mendaftarkan `hooks.php` modul apabila modul diaktif/disimpan (semula).
:::

## Konfigurasi

Semua tetapan berada di bawah **Setup → Addon Modules → CaptchaLa → Configure**.

| Tetapan | Jenis | Lalai | Penerangan |
| --- | --- | --- | --- |
| App Key | string | — | Kunci awam dari papan pemuka CaptchaLa. Wajib. |
| App Secret | string | — | Rahsia pelayan, digunakan untuk mengeluarkan dan mengesahkan token. Wajib; tidak pernah didedahkan kepada pelayar. |
| Widget mode | enum | `popup` | `popup` (bar pencetus → cabaran skrin penuh), `float` (panel sebaris), `embed` (kotak pilihan sebaris), `bind` (halimunan, memintas penghantaran). |
| Theme | enum | `default` | Pratetap warna: `default`, `dark`, `slate`, `emerald`, `amber`, `rose`. |
| Language | string | `auto` | Kod BCP-47 (cth. `en`, `zh`, `de`) atau `auto` untuk mengikut pelayar. |
| Protect login | bool | on | Cabaran log masuk kawasan klien. |
| Protect registration | bool | on | Cabaran pendaftaran akaun baharu. |
| Protect password reset | bool | on | Cabaran borang reset kata laluan. |
| Protect contact form | bool | off | Cabaran borang hubungan. |
| Protect ticket submission | bool | off | Cabaran langkah penghantaran tiket terakhir. |
| Protect cart checkout | bool | off | Cabaran pembayaran troli. |
| Skip for logged-in users | bool | on | Jangan cabar pelawat yang sudah mempunyai sesi klien. |
| Failure message | string | — | Mesej yang dipaparkan apabila pengesahan gagal. |

## Cara ia berfungsi

Pada setiap halaman borang yang dilindungi, modul mengeluarkan **token pelayan (`sct_`)** baharu dari papan pemuka, diskopkan kepada action borang itu, dan memaparkan widget yang terikat kepadanya. Selepas pelawat menyelesaikan cabaran, SDK menulis **token lulus sekali guna (`pt_`)** ke dalam borang. Semasa penghantaran, modul mengesahkan `pt_` itu di sebelah pelayan sebelum WHMCS memproses borang; ulangan dan ketidakpadanan action ditolak.

Jika papan pemuka sementara tidak dapat dicapai, modul **fails open** (membenarkan penghantaran lalu) supaya kawasan klien anda tidak pernah terkunci akibat gangguan huluan.

## Soalan lazim

**Adakah modul ini percuma?**

Ya. Modul ini percuma. Pelan percuma CaptchaLa merangkumi 10,000 pengesahan sebulan — pelan berbayar hanya berkenaan jika anda perlukan volum lebih tinggi.

**Adakah ia berfungsi pada WHMCS 8 dan 9?**

Ya — diuji pada kawasan klien 8.3 dan 9.0, dengan tema `six` dan `twenty-one`, dengan atau tanpa Friendly URLs.

**Widget tidak muncul.**

Simpan semula tetapan modul sekali (Configure → Save Changes). WHMCS hanya mendaftarkan `hooks.php` apabila modul diaktif/disimpan (semula).

## Sumber

- Repositori modul: [`github.com/Captcha-La/captchala-whmcs`](https://github.com/Captcha-La/captchala-whmcs)
- Isu / permintaan ciri: fail terhadap repositori di atas
- Berkaitan: [Web SDK](/ms/web-sdk) · [PHP Pelayan SDK](/ms/sdk/server-php) · [Rujukan API](/ms/api-reference)