Conta

Várias clientKeys: limite de gastos, IPs permitidos e expiração

Esta página foi traduzida automaticamente da versão em chinês e pode conter erros. Prevalece a versão em chinês.

Uma conta YesCaptcha pode ter até 20 clientKeys (incluindo a original), gerenciadas na página Chaves e segurança do Painel em yescaptcha.com. Toda clientKey pode criar tarefas e consultar o saldo, e todas usam o mesmo saldo da conta. Cada uma pode ter seu próprio limite de gastos, IPs permitidos e data de expiração, e as alterações entram em vigor em poucos segundos.

Usos típicos: separar ambiente de teste e de produção, ou projetos diferentes; repassar chaves a clientes ou parceiros seus, cada um com seu limite; e, se uma clientKey vazar, excluir apenas essa, sem afetar os outros programas.

Chave principal e subchaves

	Chave principal	Subchave
O que é	A `clientKey` original, uma por conta	Qualquer chave criada além da principal; até 19
Limite, IPs permitidos, expiração	Pode definir	Pode definir
Redefinir	Sim: a antiga deixa de funcionar na hora e o saldo passa para a nova	Não; exclua e crie outra
Excluir	Não	Sim: deixa de funcionar em poucos segundos e não pode ser restaurada

Todas têm o mesmo formato: os primeiros 40 caracteres são a chave secreta, seguidos do seu ID de usuário.
Redefinir a chave principal não afeta as subchaves.
Seja qual for a clientKey usada para criar tarefas ou consultar o saldo, a API e as respostas são as mesmas; a única diferença são as verificações adicionais de limite, IPs permitidos e expiração.

Criar uma clientKey

Faça login em yescaptcha.com e abra a página Chaves e segurança (yescaptcha.com/security).
Em “Todas as chaves”, clique em “Nova subchave”. Nome (até 40 caracteres), limite, IPs permitidos e expiração são opcionais e podem ser alterados depois.
Verifique sua identidade novamente quando solicitado. Criar, alterar e excluir exigem essa verificação.
Depois de criada, copie a clientKey completa e configure-a no seu programa. Você também pode vê-la novamente depois, clicando no ícone de olho na lista.

Limite de gastos

O limite define quantos pontos uma clientKey pode gastar em um período (1,000 pontos = ¥1), de 1 a 10,000,000,000 pontos. Há quatro períodos, zerados no horário de Pequim (UTC+8):

Período	Quando zera
Por dia	Todo dia às 00:00
Por semana	Toda segunda-feira às 00:00
Por mês	Todo dia 1 às 00:00
Total único	Nunca zera. Depois de esgotado, esta `clientKey` não pode mais criar tarefas; aumente o limite para continuar usando

Conta os pontos efetivamente cobrados: os pontos devolvidos por falha de reconhecimento ou timeout também voltam ao limite.
Se o que resta do limite no período atual não cobre a cobrança de pontos da tarefa, createTask retorna ERROR_KEY_QUOTA_EXCEEDED, sem cobrar pontos e sem contar para a pausa automática.
A lista no Painel mostra quanto cada clientKey já usou no período atual e quando será zerada novamente.
O limite não é um saldo separado: todas as clientKeys usam o mesmo saldo da conta, e quando o saldo da conta acaba você recebe ERROR_ZERO_BALANCE, como de costume.

Ao chamar getBalance com uma clientKey que tem limite, balance é o menor valor entre o saldo da conta e o que resta do limite no período atual, e há um campo extra keyQuotaRemaining (limite restante, em pontos). Uma clientKey sem limite não recebe esse campo, e a resposta é igual à de antes.

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

IPs permitidos

Uma clientKey com IPs permitidos só funciona para requisições enviadas dos IPs da lista. Deixe em branco para não restringir.

Informe o IP público da máquina que chama a API do YesCaptcha (o IP de saída), não o proxy dos parâmetros da tarefa. Se várias máquinas fazem chamadas, adicione o IP público de cada uma.
Um endereço IPv4 ou IPv6, ou faixa CIDR, por linha, até 50 entradas. Um endereço isolado permite somente esse IP.
Escreva as faixas com o endereço de rede: 203.0.113.0/24 é aceito, 203.0.113.5/24 não (os bits de host não são zero).

203.0.113.10
198.51.100.0/24
2001:db8::/32

Se o IP da requisição não estiver na lista, createTask e getBalance retornam ERROR_KEY_IP_NOT_ALLOWED, sem cobrar pontos e sem contar para a pausa automática.
Se o seu IP de saída muda (banda larga residencial, funções em nuvem, saída rotativa), não defina a lista ou permita a faixa inteira.

Expiração

Qualquer clientKey, inclusive a chave principal, pode ter uma data de expiração dentro de dez anos; depois você pode alterá-la ou removê-la a qualquer momento.
Depois de expirada, createTask e getBalance com essa chave retornam ERROR_KEY_EXPIRED, sem cobrar pontos. Tarefas já criadas ainda podem ter o resultado obtido com getTaskResult.
Se uma clientKey fica muito tempo sem uso, o sistema define uma data de expiração para proteger a conta e envia um e-mail antes do vencimento. Essa expiração não pode ser alterada: gere uma nova chave principal (o saldo passa para ela automaticamente) ou crie outra clientKey, e atualize o seu programa.

Saldo, limite de tarefas simultâneas e pausa automática

Saldo: todas as clientKeys usam o mesmo saldo da conta. Recarga, bônus de VIP, recompensa por indicação e participação do desenvolvedor pertencem à conta, seja qual for a clientKey usada.
Limite de tarefas simultâneas: contado por conta; todas as clientKeys juntas compartilham o mesmo limite. Veja Limite de tarefas simultâneas e pausa automática.
Pausa automática: contada por clientKey. Se uma clientKey for pausada por erros demais, as outras não são afetadas.

Códigos de erro relacionados

Código de erro	Quando é retornado
`ERROR_KEY_QUOTA_EXCEEDED`	O que resta do limite no período atual não cobre esta tarefa (`createTask`)
`ERROR_KEY_IP_NOT_ALLOWED`	O IP da requisição não está nos IPs permitidos desta `clientKey` (`createTask`, `getBalance`)
`ERROR_KEY_EXPIRED`	A `clientKey` expirou (`createTask`, `getBalance`)

Nenhum destes cobra pontos. Veja Códigos de erro para saber o que fazer.