getBalance 잔액 조회

getBalance는 계정의 남은 포인트(1,000포인트 = ¥1)와 개발자 수익 배분 및 추천 보상 잔액(위안)을 반환해요. 포인트가 차감되지 않아서 clientKey가 올바른지 확인할 때 자주 써요.

POSThttps://api.yescaptcha.com/getBalance글로벌 엔드포인트복사

POSThttps://cn.yescaptcha.com/getBalance중국 엔드포인트복사

요청 파라미터

필드	타입	필수	설명
clientKey	string	예	계정의 ClientKey

{
  "clientKey": "YOUR_CLIENT_KEY"
}

반환 결과

{
  "errorId": 0,
  "balance": 1071810,
  "softBalance": 36.0098,
  "inviteBalance": 0,
  "inviteBy": 0
}

필드	타입	설명
balance	integer	계정 잔액이며 단위는 포인트(1,000포인트 = ¥1)예요. 작업을 만들려면 10포인트보다 커야 해요
softBalance	number	개발자 수익 배분 잔액이며 단위는 위안이에요. 개발자 수익 배분을 참고하세요
inviteBalance	number	추천 보상 잔액이며 단위는 위안이에요. 추천 보상을 참고하세요
inviteBy	integer	나를 추천해 가입시킨 사용자의 ID이며, 없으면 0이에요
keyQuotaRemaining	integer	이 clientKey의 현재 주기에 남은 사용 한도이며 단위는 포인트예요. 한도를 설정한 clientKey에만 이 필드가 있고, 이때 balance는 계정 잔액과 남은 한도 중 작은 값이에요. 한도를 설정하지 않았다면 이 필드는 없어요

clientKey가 올바르지 않으면 ERROR_KEY_DOES_NOT_EXIST를 반환해요. clientKey에 IP 화이트리스트가 설정되어 있는데 요청을 보낸 IP가 목록에 없으면 ERROR_KEY_IP_NOT_ALLOWED를 반환해요. getBalance는 자동 일시 중지의 영향을 받아요. 일시 중지 중에는 ERROR_IP_BLOCKED_5MIN을 반환해요.

예시

curl

get-balance.sh

#!/usr/bin/env bash
# Check the balance. getBalance is free and is a quick way to verify your clientKey
set -euo pipefail
curl -s https://api.yescaptcha.com/getBalance \
  -H 'Content-Type: application/json' \
  -d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\"}"
echo

Python

get_balance.py

"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os

import requests

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]

r = requests.post(
    "https://api.yescaptcha.com/getBalance",
    json={"clientKey": CLIENT_KEY},
    timeout=30,
)
data = r.json()
if data.get("errorId"):
    # e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
    print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
    print("balance (points):", data["balance"])

Node.js

get-balance.mjs

// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;

const res = await fetch('https://api.yescaptcha.com/getBalance', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
  // e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
  console.log('error:', data.errorCode, data.errorDescription);
} else {
  console.log('balance (points):', data.balance);
}