Beberapa clientKey: batas penggunaan, daftar IP yang diizinkan, dan masa berlaku

Satu akun YesCaptcha dapat memiliki hingga 20 clientKey (termasuk yang asli), yang dikelola di halaman Kunci & keamanan pada dasbor yescaptcha.com. Setiap clientKey dapat membuat tugas dan memeriksa saldo, dan semuanya memotong saldo akun yang sama. Setiap key dapat diberi batas penggunaan, daftar IP yang diizinkan, dan masa berlaku sendiri, dan perubahan berlaku dalam hitungan detik.

Cocok untuk kasus berikut: memisahkan lingkungan pengujian dan produksi atau proyek yang berbeda; membagikan key ke pelanggan hilir atau mitra, masing-masing dengan batas sendiri; dan jika satu clientKey bocor, Anda cukup menghapus key itu saja tanpa memengaruhi program lain.

Key utama dan Sub-Key

	Key utama	Sub-Key
Yang mana	clientKey asli, satu per akun	Key yang dibuat selain key utama, hingga 19
Batas, daftar IP yang diizinkan, masa berlaku	Dapat diatur	Dapat diatur
Reset	Bisa: key lama langsung tidak berlaku dan saldo berpindah ke key baru	Tidak bisa; hapus lalu buat yang baru
Hapus	Tidak bisa	Bisa: tidak berlaku dalam hitungan detik dan tidak dapat dipulihkan

• Formatnya sama: 40 karakter pertama adalah kunci rahasia, diikuti ID pengguna Anda.
• Mereset key utama tidak memengaruhi Sub-Key.
• Apa pun clientKey yang Anda gunakan untuk membuat tugas atau memeriksa saldo, API dan responsnya sama; hanya ada tambahan pemeriksaan batas, daftar IP yang diizinkan, dan masa berlaku.

Membuat clientKey

1. Masuk ke yescaptcha.com, lalu buka halaman Kunci & keamanan (yescaptcha.com/security).
2. Di “Semua Key”, klik “Sub-Key baru”. Nama (maksimal 40 karakter), batas, daftar IP yang diizinkan, dan masa berlaku boleh dikosongkan dan dapat diubah nanti.
3. Verifikasi identitas sekali lagi saat diminta. Membuat, mengubah, dan menghapus key semuanya memerlukan verifikasi ini.
4. Setelah dibuat, salin clientKey lengkap dan atur di program Anda. Nanti Anda juga dapat melihatnya lagi dengan mengklik ikon mata di daftar.

Catatan

Membuat, mengubah, dan menghapus key berlaku dalam hitungan detik. Panggilan yang dilakukan tepat setelah key dibuat mungkin mengembalikan ERROR_KEY_DOES_NOT_EXIST; tunggu beberapa detik lalu coba lagi. Selama beberapa detik setelah key dihapus atau pengaturannya diperketat, permintaan yang sedang dikirim mungkin masih diproses dengan pengaturan lama.

Batas penggunaan

Batas penggunaan membatasi jumlah poin maksimum yang dapat dipakai sebuah clientKey dalam satu periode (1,000 poin = ¥1). Batas dapat diatur dari 1 hingga 10,000,000,000 poin. Ada empat periode, direset menurut waktu Beijing (UTC+8):

Periode	Kapan direset
Per hari	Setiap hari pukul 00:00
Per minggu	Setiap Senin pukul 00:00
Per bulan	Setiap tanggal 1 pukul 00:00
Total sekali pakai	Tidak pernah direset. Setelah habis, clientKey ini tidak dapat membuat tugas lagi; naikkan batas untuk terus menggunakannya

• Dihitung berdasarkan poin yang benar-benar dipotong: poin yang dikembalikan karena pengenalan gagal atau timeout juga dikembalikan ke batas.
• Jika sisa batas pada periode saat ini tidak cukup untuk pemotongan poin tugas, createTask mengembalikan ERROR_KEY_QUOTA_EXCEEDED. Poin tidak dipotong dan tidak dihitung ke jeda otomatis.
• Daftar di dasbor menampilkan berapa yang sudah dipakai setiap clientKey pada periode ini dan kapan reset berikutnya.
• Batas bukan saldo terpisah: semua clientKey memotong saldo akun yang sama, dan jika saldo akun tidak cukup, ERROR_ZERO_BALANCE dikembalikan seperti biasa.

Jika Anda memanggil getBalance dengan clientKey yang memiliki batas, balance adalah nilai yang lebih kecil antara saldo akun dan sisa batas pada periode ini, dan ada tambahan field keyQuotaRemaining (sisa batas, dalam poin). clientKey tanpa batas tidak memiliki field ini, dan responsnya sama seperti sebelumnya.

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

Daftar IP yang diizinkan

clientKey yang memiliki daftar IP yang diizinkan hanya dapat digunakan untuk permintaan yang dikirim dari IP dalam daftar. Kosongkan untuk tanpa batasan.

• Isi dengan IP publik mesin yang memanggil API YesCaptcha (IP keluar), bukan proxy di parameter tugas. Jika memanggil dari beberapa mesin, tambahkan IP publik masing-masing.
• Satu alamat IPv4 atau IPv6, atau rentang CIDR, per baris, maksimal 50 entri. Satu alamat berarti hanya IP itu yang diizinkan.
• Tulis rentang sebagai alamat jaringan: 203.0.113.0/24 diterima, 203.0.113.5/24 tidak (bit host bukan 0).

203.0.113.10
198.51.100.0/24
2001:db8::/32

• Jika IP permintaan tidak ada dalam daftar, createTask dan getBalance mengembalikan ERROR_KEY_IP_NOT_ALLOWED. Poin tidak dipotong dan tidak dihitung ke jeda otomatis.
• Jika IP keluar Anda berubah-ubah (internet rumah, cloud function, IP keluar yang dirotasi), jangan atur daftar ini, atau izinkan seluruh rentang.

Masa berlaku

• Setiap clientKey, termasuk key utama, dapat diberi masa berlaku dalam sepuluh tahun ke depan. Anda dapat mengubah atau menghapusnya kapan saja.
• Setelah kedaluwarsa, createTask dan getBalance dengan key tersebut mengembalikan ERROR_KEY_EXPIRED dan poin tidak dipotong. Tugas yang sudah dibuat tetap dapat diambil hasilnya dengan getTaskResult.
• Jika sebuah clientKey lama tidak digunakan, sistem akan mengatur masa berlaku untuknya demi keamanan akun dan mengirim email pengingat sebelum kedaluwarsa. Masa berlaku ini tidak dapat diubah: buat ulang key utama (saldo berpindah otomatis ke yang baru) atau buat clientKey baru, lalu perbarui di program Anda.

Saldo, batas tugas bersamaan, dan jeda otomatis

• Saldo: semua clientKey memotong saldo akun yang sama. Isi saldo, bonus VIP, hadiah referral, dan bagi hasil developer semuanya dihitung per akun, apa pun clientKey yang digunakan.
• Batas tugas bersamaan: dihitung per akun; semua clientKey berbagi batas yang sama. Lihat Batas tugas bersamaan dan jeda otomatis.
• Jeda otomatis: dihitung per clientKey. Jika satu clientKey dijeda karena terlalu banyak error, key lain tidak terpengaruh.

Kode error terkait

Kode error	Kapan dikembalikan
ERROR_KEY_QUOTA_EXCEEDED	Sisa batas pada periode ini tidak cukup untuk tugas ini (createTask)
ERROR_KEY_IP_NOT_ALLOWED	IP permintaan tidak ada dalam daftar IP yang diizinkan untuk clientKey ini (createTask, getBalance)
ERROR_KEY_EXPIRED	clientKey sudah kedaluwarsa (createTask, getBalance)

Ketiganya tidak memotong poin. Cara menanganinya ada di Kode error.