模块概述
账户模块提供余额与账单查询能力，对应密钥权限范围 account.balance、account.invoices。所有接口均需携带鉴权请求头（X-Access-Key、X-Timestamp、X-Signature），下文示例中的金额等数据仅用于展示结构。
账户余额查询
| 项目 | 内容 |
|---|
| URL | https://www.dapengcloud.com/api.php/v1/account/balance |
| 权限范围 | account.balance |
| 请求方式 | GET（也接受 POST） |
| 功能说明 | 返回当前密钥所属客户的可用余额与币种 |
请求参数
无——该接口不需要业务参数，客户身份由密钥自动识别。
响应参数（data）
| 字段 | 类型 | 说明 |
|---|
| client_id | int | 客户 ID，与密钥绑定。 |
| balance | number | 账户可用余额，由余额流水汇总计算（收入为正、支出为负），最多两位小数。 |
| currency | string | 币种，固定为 CNY。 |
请求示例
GET /api.php/v1/account/balance HTTP/1.1
Host: www.dapengcloud.com
X-Access-Key: AKID8F2C4A91B7D34E6F0A1C2B3D
X-Timestamp: 1761000000
X-Signature: 9d1c0b6f3e8a4c72b5d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5
成功响应示例
{
"code": 0,
"message": "ok",
"data": {
"client_id": 1001,
"balance": 268.5,
"currency": "CNY"
}
}
失败响应示例
{
"code": 403,
"message": "This API key does not have permission to call account.balance",
"data": null,
"error": { "code": "forbidden_scope" }
}
账单列表查询
| 项目 | 内容 |
|---|
| URL | https://www.dapengcloud.com/api.php/v1/account/invoices |
| 权限范围 | account.invoices |
| 请求方式 | GET（也接受 POST） |
| 功能说明 | 按创建时间倒序分页返回当前客户的账单 |
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| page | int | 否 | 页码，默认 1。 |
| per_page | int | 否 | 每页条数，默认 20，最大 50。 |
响应参数（data）
| 字段 | 类型 | 说明 |
|---|
| list | array | 账单列表。 |
| list[].id | int | 账单 ID。 |
| list[].invoice_number | string | 账单编号，全局唯一。 |
| list[].order_id | int / null | 关联订单 ID，无关联时为 null。 |
| list[].status | string | 账单状态：unpaid 未支付、paid 已支付、cancelled 已取消、refunded 已退款。 |
| list[].subtotal | string | 小计金额，如 "99.00"。 |
| list[].total | string | 应付总额，如 "99.00"。 |
| list[].currency | string | 币种，固定为 CNY。 |
| list[].due_date | string / null | 到期日，格式 YYYY-MM-DD。 |
| list[].created_at | string | 创建时间，格式 YYYY-MM-DD HH:MM:SS。 |
| page | int | 当前页码。 |
| per_page | int | 当前每页条数。 |
请求示例
GET /api.php/v1/account/invoices?page=1&per_page=20 HTTP/1.1
Host: www.dapengcloud.com
X-Access-Key: AKID8F2C4A91B7D34E6F0A1C2B3D
X-Timestamp: 1761000000
X-Signature: 4a7f2c9e1b3d5f608a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a5c7e9b2d4f
成功响应示例
{
"code": 0,
"message": "ok",
"data": {
"list": [
{
"id": 12,
"invoice_number": "INV202610000012",
"order_id": 8,
"status": "unpaid",
"subtotal": "99.00",
"total": "99.00",
"currency": "CNY",
"due_date": "2026-10-28",
"created_at": "2026-10-21 10:12:33"
}
],
"page": 1,
"per_page": 20
}
}
失败响应示例
{
"code": 429,
"message": "Too many requests, please slow down",
"data": null,
"error": { "code": "rate_limited" }
}
