账户余额查询 API

为方便您实时掌握 PaaSoo 账户的剩余余额状况，PaaSoo 提供了可直接查询账户余额的接口。通过此接口，您可以在任何时候查询自己账号的可用余额，及时应对短信业务的资金管控、充值或账务结算需要。

1. 调用说明

调用方式

• HTTP Method：GET
• 请求地址：https://api.paasoo.cn/balance
• 使用场景：当您需要在短信发送前、中或后任何阶段，获取当前账户或子账户（若有分级）余额以评估是否满足继续发送需求时，可调用此接口。

---

2. 请求示例

GET https://api.paasoo.cn/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、CNY 等。	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。我们将竭诚为您提供技术协助。