Аккаунт

Несколько clientKey: лимиты расходов, белый список IP и срок действия

Эта страница переведена с китайской версии машинным переводом и может содержать ошибки. Приоритет имеет китайская версия.

В одном аккаунте YesCaptcha может быть до 20 clientKey (включая исходный). Они управляются на странице «Ключи и безопасность» в Панели yescaptcha.com. Каждый clientKey может создавать задачи и запрашивать баланс, и все они списывают баллы с одного баланса аккаунта. Для каждого можно отдельно задать лимит расходов, белый список IP и срок действия, изменения вступают в силу за несколько секунд.

Типичные сценарии: разные ключи для тестового и рабочего окружения или для разных проектов; ключи для ваших клиентов или партнёров, у каждого свой лимит; если один clientKey утёк, вы удаляете только его, остальные программы не затрагиваются.

Основной и дополнительные ключи

	Основной ключ	Дополнительный ключ
Что это	Исходный `clientKey`, по одному на аккаунт	Любой ключ, созданный помимо основного, до 19
Лимит, белый список IP, срок действия	Можно задать	Можно задать
Сброс	Можно: старый сразу перестаёт работать, баланс переходит к новому	Нельзя, удалите его и создайте новый
Удаление	Нельзя	Можно: перестаёт работать за несколько секунд, восстановить нельзя

Формат у всех одинаковый: первые 40 символов — секретная часть, дальше ваш ID пользователя.
Сброс основного ключа не влияет на дополнительные.
С каким бы clientKey вы ни создавали задачи и ни запрашивали баланс, API и ответы одинаковы, добавляются только проверки лимита, белого списка IP и срока действия.

Создание clientKey

Войдите на yescaptcha.com и откройте страницу «Ключи и безопасность» (yescaptcha.com/security).
В разделе «Все ключи» нажмите «Новый доп. ключ». Название (до 40 символов), лимит, белый список IP и срок действия можно не заполнять, позже их можно изменить.
По запросу ещё раз подтвердите личность. Подтверждение нужно при создании, изменении и удалении.
После создания скопируйте полный clientKey и пропишите его в программе. Позже его можно снова посмотреть в списке, нажав на значок глаза.

Лимит расходов

Лимит ограничивает, сколько баллов clientKey может потратить за один период (1,000 баллов = ¥1). Его можно задать от 1 до 10,000,000,000 баллов. Периодов четыре, сброс происходит по пекинскому времени (UTC+8):

Период	Когда сбрасывается
День	Каждый день в 00:00
Неделя	Каждый понедельник в 00:00
Месяц	1-го числа каждого месяца в 00:00
Единоразовый	Не сбрасывается. После исчерпания этот `clientKey` больше не может создавать задачи, чтобы продолжить, увеличьте лимит

Считаются фактически списанные баллы: баллы, возвращённые за нераспознанные задачи или за таймаут, возвращаются и в лимит.
Если остатка лимита в текущем периоде не хватает на списание за задачу, createTask возвращает ERROR_KEY_QUOTA_EXCEEDED. Баллы не списываются, ошибка не учитывается в автоматической приостановке.
В списке в Панели видно, сколько каждый clientKey израсходовал в текущем периоде и когда лимит будет сброшен в следующий раз.
Лимит — это не отдельный баланс: все clientKey списывают баллы с одного баланса аккаунта, и когда на балансе аккаунта не хватает баллов, как обычно возвращается ERROR_ZERO_BALANCE.

Если вызвать getBalance с clientKey, для которого задан лимит, то balance — это меньшее из значений: баланс аккаунта и остаток лимита в текущем периоде. Дополнительно приходит поле keyQuotaRemaining (остаток лимита, в баллах). Для clientKey без лимита это поле не возвращается, ответ такой же, как раньше.

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

Белый список IP

clientKey с белым списком IP работает только для запросов с адресов из этого списка. Пустой список означает отсутствие ограничений.

Укажите публичный IP машины, которая вызывает API YesCaptcha (исходящий IP), а не прокси из параметров задачи. Если API вызывают несколько машин, добавьте публичный IP каждой.
По одному адресу IPv4 или IPv6 или диапазону CIDR в строке, не более 50 записей. Одиночный адрес разрешает только этот IP.
Диапазон нужно записывать адресом сети: 203.0.113.0/24 подойдёт, 203.0.113.5/24 нет (биты хоста не равны нулю).

203.0.113.10
198.51.100.0/24
2001:db8::/32

Если IP запроса нет в списке, createTask и getBalance возвращают ERROR_KEY_IP_NOT_ALLOWED. Баллы не списываются, ошибка не учитывается в автоматической приостановке.
Если ваш исходящий IP меняется (домашний интернет, облачные функции, ротация исходящих адресов), не задавайте список или разрешите весь диапазон.

Срок действия

Для любого clientKey, включая основной, можно задать срок действия не более чем на десять лет вперёд. Позже его можно в любой момент изменить или убрать.
После истечения срока createTask и getBalance с этим ключом возвращают ERROR_KEY_EXPIRED, баллы не списываются. Уже созданные задачи по-прежнему можно получить через getTaskResult.
Если clientKey долго не использовался, система ради безопасности аккаунта задаёт ему срок действия и перед истечением присылает напоминание на почту. Такой срок изменить нельзя: заново сгенерируйте основной ключ (баланс автоматически перейдёт к новому) или создайте новый clientKey, затем обновите его в программе.

Баланс, лимит параллельных задач и автоматическая приостановка

Баланс: все clientKey списывают баллы с одного баланса аккаунта. Пополнение, бонус за VIP, реферальное вознаграждение и доля разработчика относятся к аккаунту, независимо от того, каким clientKey вы пользуетесь.
Лимит параллельных задач: считается на аккаунт, все clientKey вместе подчиняются одному пределу, см. Лимит параллельных задач и автоматическая приостановка.
Автоматическая приостановка: считается отдельно для каждого clientKey. Если один clientKey приостановлен из-за слишком большого числа ошибок, на остальные это не влияет.

Связанные коды ошибок

Код ошибки	Когда возвращается
`ERROR_KEY_QUOTA_EXCEEDED`	Остатка лимита в текущем периоде не хватает на эту задачу (`createTask`)
`ERROR_KEY_IP_NOT_ALLOWED`	IP запроса нет в белом списке IP этого `clientKey` (`createTask`, `getBalance`)
`ERROR_KEY_EXPIRED`	Срок действия `clientKey` истёк (`createTask`, `getBalance`)

Ни в одном из этих случаев баллы не списываются. Что делать, см. в разделе Коды ошибок.