Varios ClientKey: límites de gasto, lista blanca de IP y vencimiento

Una cuenta de YesCaptcha puede tener hasta 20 clientKey (incluida la original), que se administran en la página «Claves y seguridad» del panel de yescaptcha.com. Cada clientKey puede crear tareas y consultar el saldo, y todas descuentan del mismo saldo de la cuenta. Cada una puede tener su propio límite de gasto, lista blanca de IP y vencimiento, y los cambios surten efecto en pocos segundos.

Casos de uso habituales: separar los entornos de prueba y producción o los distintos proyectos; entregar claves a tus clientes o socios, cada uno con su propio límite; y, si una clientKey se filtra, eliminar solo esa sin afectar a los demás programas.

Key principal y SubKey

	Key principal	SubKey
Qué es	La clientKey original; una por cuenta	Las que se crean además de la Key principal; hasta 19
Límite, lista blanca de IP, vencimiento	Se pueden configurar	Se pueden configurar
Restablecer	Sí: la anterior deja de funcionar de inmediato y el saldo pasa a la nueva	No se puede; elimínala y crea otra
Eliminar	No	Sí: deja de funcionar en pocos segundos y no se puede recuperar

• Todas tienen el mismo formato: los primeros 40 caracteres son la clave y después va tu ID de usuario.
• Restablecer la Key principal no afecta a las SubKey.
• Uses la clientKey que uses para crear tareas o consultar el saldo, la API y las respuestas son iguales; la única diferencia son las comprobaciones adicionales de límite, lista blanca de IP y vencimiento.

Crear una clientKey

1. Inicia sesión en yescaptcha.com y abre la página «Claves y seguridad» (yescaptcha.com/security).
2. En «Todas las Keys», haz clic en «Nueva subKey». El nombre (hasta 40 caracteres), el límite, la lista blanca de IP y el vencimiento son opcionales y se pueden cambiar después.
3. Confirma tu identidad de nuevo cuando se te pida. Crear, modificar y eliminar requieren esta confirmación.
4. Tras crearla, copia la clientKey completa y configúrala en tu programa. También puedes volver a verla después con el icono del ojo en la lista.

Nota

Crear, modificar y eliminar surten efecto en pocos segundos. Si llamas justo después de crear una clave, puede devolver ERROR_KEY_DOES_NOT_EXIST; espera unos segundos y vuelve a intentarlo. Durante unos segundos después de eliminar una clave o de endurecer su configuración, las solicitudes que ya están en curso pueden procesarse con la configuración anterior.

Límite de gasto

El límite fija cuántos puntos puede gastar una clientKey en un periodo (1,000 puntos = ¥1), entre 1 y 10,000,000,000 puntos. Hay cuatro periodos, con reinicio en hora de Beijing (UTC+8):

Periodo	Cuándo se reinicia
Diario	Todos los días a las 00:00
Semanal	Todos los lunes a las 00:00
Mensual	El día 1 de cada mes a las 00:00
Total único	No se reinicia. Cuando se agota, esta clientKey ya no puede crear tareas; sube el límite para seguir usándola

• Se cuentan los puntos realmente cobrados: los puntos reembolsados por tareas fallidas o con tiempo agotado también vuelven al límite.
• Si el límite que queda en el periodo actual no alcanza para el cobro de puntos de la tarea, createTask devuelve ERROR_KEY_QUOTA_EXCEEDED. No se cobran puntos y no cuenta para la pausa automática.
• La lista del panel muestra cuánto ha usado cada clientKey en el periodo actual y cuándo se reinicia.
• El límite no es un saldo aparte: todas las clientKey descuentan del mismo saldo de la cuenta, y cuando el saldo de la cuenta no alcanza se devuelve ERROR_ZERO_BALANCE como siempre.

Si llamas a getBalance con una clientKey que tiene límite, balance es el menor entre el saldo de la cuenta y el límite restante del periodo actual, y se añade el campo keyQuotaRemaining (límite restante, en puntos). Una clientKey sin límite no incluye este campo y la respuesta es igual que antes.

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

Lista blanca de IP

Una clientKey con lista blanca de IP solo funciona para solicitudes enviadas desde las IP de la lista. Déjala vacía para no restringir.

• Escribe la IP pública de la máquina que llama a la API de YesCaptcha (su IP de salida), no el proxy de los parámetros de la tarea. Si llamas desde varias máquinas, añade la IP pública de cada una.
• Una dirección IPv4 o IPv6, o un rango CIDR, por línea, hasta 50 entradas. Una dirección sola permite únicamente esa IP.
• Escribe los rangos como dirección de red: 203.0.113.0/24 es válido, 203.0.113.5/24 no (los bits de host no son 0).

203.0.113.10
198.51.100.0/24
2001:db8::/32

• Si la IP de la solicitud no está en la lista, createTask y getBalance devuelven ERROR_KEY_IP_NOT_ALLOWED. No se cobran puntos y no cuenta para la pausa automática.
• Si tu IP de salida cambia (banda ancha doméstica, funciones en la nube, salidas rotativas), no configures la lista, o permite el rango completo.

Vencimiento

• Cualquier clientKey, incluida la Key principal, puede tener una fecha de vencimiento dentro de los próximos diez años; después puedes modificarla o quitarla en cualquier momento.
• Una vez vencida, createTask y getBalance con esa clave devuelven ERROR_KEY_EXPIRED y no se cobran puntos. Las tareas ya creadas se pueden seguir consultando con getTaskResult.
• Si una clientKey lleva mucho tiempo sin usarse, el sistema le asigna una fecha de vencimiento para proteger tu cuenta y te envía un correo antes de que venza. Ese vencimiento no se puede modificar: genera de nuevo la Key principal (el saldo pasa a la nueva automáticamente) o crea otra clientKey, y actualiza tu programa.

Saldo, límite de tareas simultáneas y pausa automática

• Saldo: todas las clientKey descuentan del mismo saldo de la cuenta. Las recargas, los bonos VIP, las recompensas por referidos y la participación del desarrollador pertenecen a la cuenta, sin importar qué clientKey uses.
• Límite de tareas simultáneas: se cuenta por cuenta; todas tus clientKey comparten el mismo tope. Consulta Límite de tareas simultáneas y pausa automática.
• Pausa automática: se cuenta por clientKey. Si una clientKey se pausa por demasiados errores, las demás no se ven afectadas.

Códigos de error relacionados

Código de error	Cuándo se devuelve
ERROR_KEY_QUOTA_EXCEEDED	El límite que queda en el periodo actual no alcanza para esta tarea (createTask)
ERROR_KEY_IP_NOT_ALLOWED	La IP de la solicitud no está en la lista blanca de IP de esta clientKey (createTask, getBalance)
ERROR_KEY_EXPIRED	La clientKey ha vencido (createTask, getBalance)

Ninguno de estos cobra puntos. Consulta Códigos de error para saber qué hacer.