getBalance - Truy vấn số dư

getBalance trả về số điểm còn lại của tài khoản (1,000 điểm = ¥1), cùng số dư chia sẻ doanh thu cho nhà phát triển và thưởng giới thiệu (đơn vị: nhân dân tệ). Không trừ điểm, thường dùng để xác nhận clientKey có đúng hay không.

POSThttps://api.yescaptcha.com/getBalanceEndpoint quốc tếSao chép

POSThttps://cn.yescaptcha.com/getBalanceEndpoint Trung QuốcSao chép

Tham số yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
clientKey	string	Có	ClientKey của tài khoản

{
  "clientKey": "YOUR_CLIENT_KEY"
}

Kết quả trả về

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

Trường	Kiểu	Mô tả
balance	integer	Số dư tài khoản, đơn vị là điểm (1,000 điểm = ¥1). Phải lớn hơn 10 điểm mới tạo được tác vụ
softBalance	number	Số dư chia sẻ doanh thu cho nhà phát triển, đơn vị là nhân dân tệ, xem Chia sẻ doanh thu cho nhà phát triển
inviteBalance	number	Số dư thưởng giới thiệu, đơn vị là nhân dân tệ, xem Thưởng giới thiệu
inviteBy	integer	ID người dùng của người đã mời bạn đăng ký, bằng 0 nếu không có
keyQuotaRemaining	integer	Hạn mức chi tiêu còn lại của clientKey này trong chu kỳ hiện tại, đơn vị là điểm. Chỉ có trường này khi clientKey được đặt hạn mức; lúc đó balance là giá trị nhỏ hơn giữa số dư tài khoản và hạn mức còn lại. clientKey không đặt hạn mức thì không có trường này

Khi clientKey sai, API trả về ERROR_KEY_DOES_NOT_EXIST; khi clientKey có đặt danh sách IP cho phép mà IP gửi yêu cầu không nằm trong danh sách, API trả về ERROR_KEY_IP_NOT_ALLOWED. getBalance chịu ảnh hưởng của tự động tạm dừng: trong thời gian tạm dừng, API trả về ERROR_IP_BLOCKED_5MIN.

Ví dụ

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);
}