---
title: Bắt đầu nhanh
---

# Bắt đầu nhanh

Hướng dẫn này sẽ giúp bạn tích hợp CaptchaLa CAPTCHA trong 5 phút.

::: tip Xem nó hoạt động trong 30 giây
[demo-v1.captcha.la](https://demo-v1.captcha.la) — HTML + PHP thuần, giấy phép MIT, có thể view-source mọi trang.

- [popup.html](https://demo-v1.captcha.la/popup.html) — chế độ popup
- [float.html](https://demo-v1.captcha.la/float.html) — widget nổi
- [bind.html](https://demo-v1.captcha.la/bind.html) — gắn vào nút
- [inline.html](https://demo-v1.captcha.la/inline.html) — nhúng trong dòng
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — token do máy chủ phát hành (chống replay)
:::


## 1. Tạo tài khoản

Đăng ký tài khoản miễn phí trong dashboard

[Đăng ký ngay →](https://dash.captcha.la/register)

## 2. Tạo ứng dụng

Tạo ứng dụng trong dashboard để lấy App Key

## 3. Cài đặt SDK

Chọn cách cài đặt bạn muốn

```html
<!-- CDN loader (recommended): auto-fallback CDN, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>
```

```bash
# or via npm
npm install captchala
```

## 4. Khởi tạo CAPTCHA

Khởi tạo thành phần CAPTCHA trong trang của bạn

```html
<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>
```

## 5. Xác minh phía server

Xác minh token trên server của bạn

```bash
POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>" }
```

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "risk_score": 12
  }
}
```

::: warning
Always check `data.valid === true` **and** `data.action` matches the scene you expected.
Pass tokens are single-use; the same `pt_xxx` cannot be validated twice.
:::

## Chế độ Token do server cấp (khuyến nghị cho production) {#server-token}

Đối với các thao tác nhạy cảm (đăng nhập, đăng ký, thanh toán), chúng tôi khuyến nghị luồng token do server cấp: backend của bạn sẽ yêu cầu một server_token có thời gian sống ngắn trước, sau đó trình duyệt dùng token đó để khởi tạo CAPTCHA. Cách này giúp ngăn lạm dụng khi app_key bị lộ.

### Khi nào nên dùng

- Khuyến nghị: đăng ký, đăng nhập, đặt lại mật khẩu, thanh toán, đổi điểm và mọi endpoint có thể bị kẻ tấn công tự động hóa bằng script.
- Tùy chọn: biểu mẫu công khai, ô tìm kiếm và các tương tác giá trị thấp nơi sự tiện lợi quan trọng hơn.

### 1. Backend cấp server_token

Gọi /v1/server/challenge/issue từ chính server của bạn, dùng header X-App-Key và X-App-Secret. Không bao giờ để lộ các header này ra trình duyệt.

```bash
# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }
```

### 2. Frontend render CaptchaLa với server_token

Truyền token vào thành phần CaptchaLa. SDK sẽ chuyển tiếp nó đến khởi tạo xác minh khi khởi tạo challenge.

```js
// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));
```

### Lưu ý bảo mật

- Không bao giờ đặt app_secret trong mã frontend, ứng dụng mobile hoặc repository công khai. Nó phải luôn nằm ở phía server.
- Bật "Require server-issued challenge token" trong dashboard để từ chối mọi challenge được thử mà không có server_token.
- Hãy giữ ttl ngắn (mặc định 300 giây, tối đa 900 giây) và ưu tiên max_uses=1 để giảm tác động nếu token bị lộ.

## Bước tiếp theo

- [Web SDK](./web-sdk)
- [Tài liệu API](./api-reference)