帳戶餘額查詢 API

為方便您即時掌握 PaaSoo 帳戶的剩餘餘額狀況，PaaSoo 提供了可直接查詢帳戶餘額的介面。透過此介面，您可以在任何時候查詢自己帳號的可用餘額，及時應對簡訊業務的資金管控、儲值或帳務結算需求。

1. 呼叫說明

呼叫方式

• HTTP Method：GET
• 請求地址：https://api.paasoo.com.tw/balance
• 使用場景：當您需要在簡訊發送前、中或後任何階段，取得當前帳戶或子帳戶（若有分級）餘額以評估是否滿足繼續發送需求時，可呼叫此介面。

---

2. 請求範例

GET https://api.paasoo.com.tw/balance?key=API_KEY&secret=API_SECRET

---

3. 請求參數說明

參數	類型	必填	描述	範例
key	string	是	API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。	Abcdefgh
secret	string	是	API Secret（字母或數字構成，共 8 位），與 key 配合使用以進行身分驗證。可在 PaaSoo 用戶端後台取得。	Abc123EF

---

4. 回應範例

當查詢成功時，您將收到帳戶當前餘額及貨幣單位；若查詢失敗，則會返回錯誤碼及相應提示。

4.1 回應參數說明

參數	類型	描述	範例
code	integer	回應狀態。提交至 PaaSoo 雲通訊平台的回應狀態碼。一般來說，0 代表成功。	0
descr	string	對應 code 的狀態描述資訊，用於說明錯誤原因或詳細狀態。	Missing parameters
balance	string	當前帳戶餘額。此值可能包含小數部分，具體精度與帳戶類型或貨幣單位相關。	1234.56
creditLimit	string	當前帳戶信用額度。此值可能包含小數部分，具體精度與帳戶類型或貨幣單位相關。	0
currency	string	帳戶餘額所對應的貨幣單位或符號，如 USD、SGD、TWD 等。	USD

4.2 成功回應範例

{
    "balance": "9999.99999",
    "creditLimit": "-1000",
    "currency": "EUR"
}

4.3 失敗回應範例

{
    "code": 4,
    "descr": "Invalid credentials"
}

---

5. 介面狀態碼列表

• 0 - success: 成功
• 2 - Missing parameters: 缺少必要參數
• 3 - Invalid parameters: 參數格式錯誤
• 4 - Invalid credentials: Key 或 Secret 錯誤
• 5 - Unauthorized IP: IP 限制
• 11 - System error: 系統錯誤

---

6. 最佳實踐與注意事項

1. 呼叫頻率：
   • 請根據業務量設計合理的查詢頻率，以避免對伺服器造成過大壓力。過於頻繁的查詢可能會觸發速率限制（限速）。
2. 安全性：
   • 確保在 HTTPS 通道下呼叫此介面，防止 key 和 secret 等敏感資訊被竊取。
   • 可考慮針對 IP 白名單做存取限制，進一步提升安全級別。
3. 額度監控：
   • 在大規模簡訊發送或週期性發送前，可在內部系統中整合此介面進行餘額檢查，並在不足時做提醒或自動儲值。
4. 同時查詢：
   • 如您有子帳戶或多個業務模組共用同一帳戶，務必做好查詢頻率控制與餘額使用預估，避免因超額或爭用導致發送失敗。

---

7. 總結

透過此帳戶餘額即時查詢 API，您可隨時取得當下可用餘額及其貨幣類型，無需手動登入管理後台，也不必等待每日或週期性的對帳通知。 結合 PaaSoo 其他簡訊 API、批次查詢 API 以及 DLR 回呼，您可以在簡訊全流程中實現自動化、精細化的監控與管理。

技術支援

如在 API 對接過程中遇到任何技術問題或業務疑問，歡迎隨時聯絡我們的開發者支援團隊：support@paasoo.com。我們將竭誠為您提供技術協助。