# Nhiều clientKey: hạn mức, IP cho phép và thời gian hết hạn

> Một tài khoản YesCaptcha có tối đa 20 clientKey, cùng trừ vào một số dư tài khoản. Mỗi clientKey có thể đặt riêng hạn mức chi tiêu (theo ngày, tuần, tháng hoặc tổng một lần, đặt lại theo giờ Bắc Kinh), IP cho phép và thời gian hết hạn, có hiệu lực trong vài giây.

Source: https://docs.yescaptcha.com/vi/account/client-keys/ · Last verified: 2026-10-29

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/client-keys/

Một tài khoản YesCaptcha có tối đa 20 `clientKey` (gồm cả key ban đầu), quản lý tại trang “Khóa và bảo mật” trong bảng điều khiển [yescaptcha.com](https://yescaptcha.com/security). Mỗi `clientKey` đều có thể tạo tác vụ và truy vấn số dư, và đều trừ vào cùng một số dư tài khoản. Mỗi key có thể đặt riêng hạn mức chi tiêu, IP cho phép và thời gian hết hạn, có hiệu lực trong vài giây.

Phù hợp với các trường hợp: tách key cho môi trường thử nghiệm và môi trường production, hoặc cho từng dự án; cấp key cho khách hàng hạ nguồn hoặc đối tác, mỗi bên một hạn mức; khi một `clientKey` bị lộ, chỉ cần xóa đúng key đó, các chương trình khác không bị ảnh hưởng.

## Key chính và Key phụ

|  | Key chính | Key phụ |
| --- | --- | --- |
| Là key nào | `clientKey` ban đầu, mỗi tài khoản có một | Key tạo thêm ngoài Key chính, tối đa 19 |
| Hạn mức, IP cho phép, thời gian hết hạn | Có thể đặt | Có thể đặt |
| Đặt lại | Có: key cũ mất hiệu lực ngay, số dư chuyển sang key mới | Không thể đặt lại, hãy xóa rồi tạo key khác |
| Xóa | Không | Có: mất hiệu lực trong vài giây, không thể khôi phục |

-   Định dạng đều giống nhau: 40 ký tự đầu là khóa bí mật, phần sau là ID người dùng của bạn.
-   Đặt lại Key chính không ảnh hưởng đến Key phụ.
-   Dùng `clientKey` nào để tạo tác vụ hay truy vấn số dư thì giao diện API và kết quả trả về đều như nhau, chỉ thêm các bước kiểm tra hạn mức, IP cho phép và thời gian hết hạn.

## Tạo clientKey

1.  Đăng nhập [yescaptcha.com](https://yescaptcha.com/), mở trang “Khóa và bảo mật” ([yescaptcha.com/security](https://yescaptcha.com/security)).
2.  Trong “Tất cả Key”, bấm “Tạo Key phụ”. Tên (tối đa 40 ký tự), hạn mức, IP cho phép và thời gian hết hạn đều có thể để trống, sau này vẫn sửa được.
3.  Xác minh danh tính thêm một lần theo hướng dẫn. Tạo, sửa và xóa đều cần xác minh.
4.  Sau khi tạo, sao chép `clientKey` đầy đủ và cấu hình vào chương trình. Sau này cũng có thể bấm biểu tượng con mắt trong danh sách để xem lại.

> **Ghi chú:** Tạo, sửa và xóa đều có hiệu lực trong vài giây. Nếu gọi ngay sau khi vừa tạo, có thể nhận `ERROR_KEY_DOES_NOT_EXIST`, hãy đợi vài giây rồi thử lại; trong vài giây sau khi xóa hoặc siết chặt cài đặt, các yêu cầu đang được gửi đi vẫn có thể được xử lý theo cài đặt cũ.

## Hạn mức chi tiêu

Hạn mức giới hạn một `clientKey` được tiêu tối đa bao nhiêu điểm trong một chu kỳ (1,000 điểm = ¥1), có thể đặt từ 1 đến 10,000,000,000 điểm. Có bốn chu kỳ, đặt lại theo giờ Bắc Kinh (UTC+8):

| Chu kỳ | Khi nào đặt lại |
| --- | --- |
| Mỗi ngày | 0 giờ mỗi ngày |
| Mỗi tuần | 0 giờ thứ Hai hàng tuần |
| Mỗi tháng | 0 giờ ngày 1 hàng tháng |
| Tổng một lần | Không đặt lại. Dùng hết thì `clientKey` này không thể tạo tác vụ nữa, muốn tiếp tục dùng hãy tăng hạn mức |

-   Tính theo số điểm thực tế đã trừ: điểm được hoàn lại do nhận dạng thất bại hoặc hết thời gian chờ cũng được hoàn lại vào hạn mức.
-   Khi hạn mức còn lại của chu kỳ hiện tại không đủ để trừ điểm cho tác vụ này, `createTask` trả về [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED), không trừ điểm và không tính vào [tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md).
-   Trong danh sách ở bảng điều khiển có thể xem mỗi `clientKey` đã dùng bao nhiêu trong chu kỳ hiện tại và khi nào đặt lại tiếp theo.
-   Hạn mức không phải số dư riêng: mọi `clientKey` đều trừ vào cùng một số dư tài khoản, khi số dư tài khoản không đủ vẫn trả về `ERROR_ZERO_BALANCE` như bình thường.

Khi gọi [`getBalance`](https://docs.yescaptcha.com/vi/api/get-balance.md) bằng `clientKey` có đặt hạn mức, `balance` là giá trị nhỏ hơn giữa số dư tài khoản và hạn mức còn lại của chu kỳ hiện tại, ngoài ra có thêm trường `keyQuotaRemaining` (hạn mức còn lại, tính bằng điểm). `clientKey` không đặt hạn mức không có trường này, kết quả trả về giống như trước.

```json
{
  "errorId": 0,
  "balance": 20000,
  "softBalance": 0,
  "inviteBalance": 0,
  "inviteBy": 0,
  "keyQuotaRemaining": 20000
}
```

## IP cho phép

`clientKey` có đặt IP cho phép chỉ dùng được với các yêu cầu gửi từ IP trong danh sách. Để trống nghĩa là không giới hạn.

-   Điền **IP công khai của máy gọi API YesCaptcha** (IP đầu ra), không phải proxy trong tham số tác vụ. Nếu gọi từ nhiều máy, phải thêm IP công khai của từng máy.
-   Mỗi dòng một địa chỉ IPv4 hoặc IPv6, hoặc dải CIDR, tối đa 50 mục. Một địa chỉ đơn nghĩa là chỉ cho phép đúng IP đó.
-   Dải mạng phải viết ở dạng địa chỉ mạng: `203.0.113.0/24` được, `203.0.113.5/24` không được (các bit máy chủ không bằng 0).

```text
203.0.113.10
198.51.100.0/24
2001:db8::/32
```

-   Khi IP của yêu cầu không có trong danh sách, `createTask` và `getBalance` trả về [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED), không trừ điểm và không tính vào tự động tạm dừng.
-   Nếu IP đầu ra thay đổi (mạng gia đình, cloud function, đầu ra luân phiên) thì đừng đặt, hoặc đặt thành cả dải mạng.

## Thời gian hết hạn

-   Mọi `clientKey` (kể cả Key chính) đều có thể đặt thời gian hết hạn, trong vòng mười năm; sau đó có thể sửa hoặc bỏ bất cứ lúc nào.
-   Sau khi hết hạn, gọi `createTask` và `getBalance` bằng key đó sẽ trả về [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_EXPIRED), không trừ điểm. Các tác vụ đã tạo vẫn lấy được kết quả bằng `getTaskResult` như bình thường.
-   Với `clientKey` lâu không sử dụng, hệ thống sẽ đặt thời gian hết hạn để bảo vệ an toàn tài khoản và gửi email nhắc trước khi hết hạn. Thời gian hết hạn này không thể sửa: hãy tạo lại Key chính (số dư tự động chuyển sang key mới) hoặc tạo một `clientKey` mới, rồi cập nhật vào chương trình.

## Số dư, giới hạn đồng thời và tự động tạm dừng

-   **Số dư**: mọi `clientKey` đều trừ vào cùng một số dư tài khoản. Nạp tiền, điểm thưởng khi nạp của VIP, thưởng giới thiệu và chia sẻ doanh thu cho nhà phát triển đều tính theo tài khoản, không phụ thuộc vào việc dùng `clientKey` nào.
-   **Giới hạn đồng thời**: tính theo tài khoản, tất cả `clientKey` cộng lại chịu chung một mức trần, xem [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md).
-   **Tự động tạm dừng**: tính riêng cho từng `clientKey`, một `clientKey` gặp quá nhiều lỗi bị tạm dừng thì không ảnh hưởng đến các key khác.

## Mã lỗi liên quan

| Mã lỗi | Khi nào trả về |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | Hạn mức còn lại của chu kỳ hiện tại không đủ cho tác vụ này (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | IP của yêu cầu không có trong danh sách IP cho phép của `clientKey` này (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/vi/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey` đã hết hạn (`createTask`, `getBalance`) |

Cả ba mã này đều không trừ điểm. Cách xử lý xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).