開放平台餘額

介面描述

查詢當前開放平台帳戶的可用點數餘額，可用於設定餘額預警。

資料說明：餘額資料可能存在短暫延遲，請以介面實際回傳為準。

請求 URL

• 方法：GET
• 路徑：/open/v1/credit/balance

點數消耗

• 消耗點數：0

前置條件

• 使用有效的 API Key。
• 請求頭攜帶 X-API-KEY、X-TIMESTAMP、X-SIGN。
• GET 請求沒有請求體，簽名原文為 X-TIMESTAMP 與空字串拼接。

請求參數

無路徑參數、查詢參數或請求體。

請求頭

請求頭	必需	描述
X-API-KEY	是	您的 API Key
X-TIMESTAMP	是	當前 13 位毫秒時間戳，與伺服器時間差不得超過 5 分鐘
X-SIGN	是	使用應用 Secret 對 X-TIMESTAMP + 空請求體 生成的 HMAC-SHA256 簽名

完整簽名規則請參考「身分驗證 / 呼叫全流程」。

回應欄位

僅展示 data 物件的欄位結構：

欄位	類型	實際回傳類型	描述
balance	long	string	當前可用總點數
buyBalance	long	string	購買獲得的可用點數
giveBalance	long	string	贈送獲得的可用點數
recentExpireTime	date	number / null	最近一批點數的過期時間，毫秒時間戳；無可用點數時為 null
recentBalance	long	string	最近一批將過期的點數；無可用點數時為 "0"

欄位關係

• balance = buyBalance + giveBalance。
• recentExpireTime 和 recentBalance 用於判斷最近一批點數的到期時間與數量。
• 無可用點數時，balance、buyBalance、giveBalance、recentBalance 均為 "0"，recentExpireTime 為 null。

cURL 範例（Linux/macOS）

curl --location --request GET 'https://api.valuescan.ai/api/open/v1/credit/balance' \
--header 'X-API-KEY: your-api-key' \
--header 'X-TIMESTAMP: 1785110400000' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: application/json'

cURL 範例（Windows CMD）

curl --location --request GET "https://api.valuescan.ai/api/open/v1/credit/balance" ^
--header "X-API-KEY: your-api-key" ^
--header "X-TIMESTAMP: 1785110400000" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: application/json"

成功回應範例

{
    "code": 200,
    "message": "success",
    "data": {
        "balance": "15000",
        "recentExpireTime": 1785513600000,
        "recentBalance": "3000",
        "buyBalance": "10000",
        "giveBalance": "5000"
    },
    "requestId": "xxx-xxx-xxx"
}

無有效餘額回應範例

{
    "code": 200,
    "message": "success",
    "data": {
        "balance": "0",
        "recentExpireTime": null,
        "recentBalance": "0",
        "buyBalance": "0",
        "giveBalance": "0"
    },
    "requestId": "xxx-xxx-xxx"
}

常見錯誤

錯誤碼	說明
20001	缺少 API Key
20012	請求時間戳已過期
20021	簽名驗證失敗
60001	呼叫頻率超限
70002	當前用戶的 OpenAPI 存取已被停用