Compte

Plusieurs ClientKey : limites, liste blanche d'IP et expiration

Cette page a été traduite automatiquement à partir de la version chinoise et peut contenir des erreurs. La version chinoise fait foi.

Un compte YesCaptcha peut avoir jusqu’à 20 clientKey (y compris la première), gérées dans la page « Clés et sécurité » du tableau de bord yescaptcha.com. Chaque clientKey peut créer des tâches et consulter le solde, et toutes débitent le même solde du compte. Chacune peut avoir sa propre limite de dépenses, sa liste blanche d’IP et son expiration, appliquées en quelques secondes.

Cas d’usage typiques : séparer les environnements de test et de production, ou les différents projets ; confier une clé à vos clients ou partenaires, chacun avec sa propre limite ; et si une clientKey fuit, ne supprimer que celle-ci sans toucher aux autres programmes.

Clé principale et sous-clés

	Clé principale	Sous-clé
Définition	La `clientKey` d’origine, une par compte	Toute clé créée en plus de la clé principale, 19 au maximum
Limite, liste blanche d’IP, expiration	Possible	Possible
Réinitialisation	Oui : l’ancienne cesse de fonctionner immédiatement et le solde passe à la nouvelle	Non ; supprimez-la et créez-en une autre
Suppression	Non	Oui : cesse de fonctionner en quelques secondes, irréversible

Toutes ont le même format : les 40 premiers caractères forment le secret, suivis de votre ID utilisateur.
Réinitialiser la clé principale n’affecte pas les sous-clés.
Quelle que soit la clientKey utilisée pour créer des tâches ou consulter le solde, l’API et ses réponses sont identiques ; seules s’ajoutent les vérifications de limite, de liste blanche d’IP et d’expiration.

Créer une clé

Connectez-vous sur yescaptcha.com et ouvrez la page « Clés et sécurité » (yescaptcha.com/security).
Dans « Toutes les clés », cliquez sur « Nouvelle sous-clé ». Le nom (40 caractères maximum), la limite, la liste blanche d’IP et l’expiration sont facultatifs et modifiables plus tard.
Confirmez de nouveau votre identité lorsque c’est demandé. La création, la modification et la suppression l’exigent toutes.
Copiez la clientKey complète et configurez-la dans votre programme. Vous pourrez la consulter de nouveau plus tard avec l’icône en forme d’œil dans la liste.

Limite de dépenses

La limite plafonne le nombre de points qu’une clientKey peut dépenser sur une période (1,000 points = ¥1), de 1 à 10,000,000,000 points. Il existe quatre périodes, remises à zéro à l’heure de Pékin (UTC+8) :

Période	Remise à zéro
Par jour	Chaque jour à 00:00
Par semaine	Chaque lundi à 00:00
Par mois	Le 1er de chaque mois à 00:00
Total unique	Jamais. Une fois épuisée, cette `clientKey` ne peut plus créer de tâches ; augmentez la limite pour continuer à l’utiliser

Le calcul porte sur les points réellement débités : les points remboursés pour les tâches échouées ou expirées sont aussi rendus à la limite.
Si le reste de la limite de la période en cours est inférieur au coût de la tâche, createTask renvoie ERROR_KEY_QUOTA_EXCEEDED. Aucun point n’est débité et l’erreur ne compte pas pour la suspension automatique.
La liste du tableau de bord indique, pour chaque clientKey, ce qui a été utilisé sur la période en cours et la prochaine remise à zéro.
La limite n’est pas un solde distinct : toutes les clientKey débitent le même solde du compte, et quand le solde du compte est épuisé, vous obtenez ERROR_ZERO_BALANCE comme d’habitude.

Si vous appelez getBalance avec une clientKey qui a une limite, balance est la plus petite valeur entre le solde du compte et le reste de la limite de la période en cours, et un champ supplémentaire keyQuotaRemaining (limite restante, en points) est renvoyé. Une clientKey sans limite n’a pas ce champ et la réponse reste identique à avant.

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

Liste blanche d’IP

Une clientKey avec une liste blanche d’IP ne fonctionne que pour les requêtes envoyées depuis les adresses IP de la liste. Laissez-la vide pour ne mettre aucune restriction.

Saisissez l’IP publique de la machine qui appelle l’API YesCaptcha (son IP de sortie), et non le proxy indiqué dans les paramètres de la tâche. Si plusieurs machines appellent l’API, ajoutez l’IP publique de chacune.
Une adresse IPv4 ou IPv6, ou une plage CIDR, par ligne, 50 entrées au maximum. Une adresse seule n’autorise que cette IP.
Écrivez les plages avec l’adresse réseau : 203.0.113.0/24 est accepté, 203.0.113.5/24 ne l’est pas (les bits d’hôte ne sont pas à 0).

203.0.113.10
198.51.100.0/24
2001:db8::/32

Si la requête provient d’une IP absente de la liste, createTask et getBalance renvoient ERROR_KEY_IP_NOT_ALLOWED. Aucun point n’est débité et l’erreur ne compte pas pour la suspension automatique.
Si votre IP de sortie change (box domestique, fonctions cloud, sorties en rotation), ne définissez pas de liste blanche, ou autorisez toute la plage.

Expiration

Toute clientKey, clé principale comprise, peut avoir une date d’expiration dans les dix ans à venir. Vous pouvez la modifier ou la retirer à tout moment.
Après l’expiration, createTask et getBalance avec cette clé renvoient ERROR_KEY_EXPIRED et aucun point n’est débité. Les tâches déjà créées peuvent toujours être récupérées avec getTaskResult.
Si une clientKey reste inutilisée pendant longtemps, le système lui attribue une date d’expiration pour protéger votre compte et vous envoie un e-mail avant l’échéance. Cette date ne peut pas être modifiée : générez une nouvelle clé principale (le solde y est transféré automatiquement) ou créez une autre clientKey, puis mettez à jour votre programme.

Solde, limite de tâches simultanées et suspension automatique

Solde : toutes les clientKey débitent le même solde du compte. Les recharges, les bonus VIP, les récompenses de parrainage et la part développeur sont rattachés au compte, quelle que soit la clientKey utilisée.
Limite de tâches simultanées : calculée par compte ; toutes vos clientKey partagent la même limite. Voir Limite de tâches simultanées et suspension automatique.
Suspension automatique : calculée par clientKey. Si une clientKey est suspendue pour trop d’erreurs, les autres ne sont pas affectées.

Codes d’erreur associés

Code d’erreur	Quand il est renvoyé
`ERROR_KEY_QUOTA_EXCEEDED`	Le reste de la limite de la période en cours est inférieur au coût de cette tâche (`createTask`)
`ERROR_KEY_IP_NOT_ALLOWED`	L’IP de la requête n’est pas dans la liste blanche d’IP de cette `clientKey` (`createTask`, `getBalance`)
`ERROR_KEY_EXPIRED`	La `clientKey` a expiré (`createTask`, `getBalance`)

Aucun de ces codes ne débite de points. Voir Codes d’erreur pour savoir quoi faire.