财务对外 API 文档
更新日志
- 2022/01/04 v1.0 月结算单概览接口对外文档
- 2022/03/03 v1.1 增加账单详情接口
概述
财务对外 API 为七牛用户提供更加灵活的财务管理方式。作为对财务中心管理系统的补充,可查看用户在某个账期内各产品的消费情况。
注意事项
按量计费的账单每月4号出账,为保数据的完整性,请在5号后查看上月账单。如2021年6月账单应在7月5号后查看。
接口支持查询近24个月的数据。
接口域名
https://api.qiniu.com/
接口列表
- 月结算单概览接口
- 账单详情接口
API签名
错误码
错误码 | 错误消息 | 错误说明 |
---|---|---|
1000 | InvalidParameter | 请求参数不正确 |
1001 | BaseBillGetFaild | 账单数据获取失败 |
1002 | CustomBillGetFailed | 自定义账单数据获取失败 |
1003 | OrderGetFailed | 订单数据获取失败 |
1004 | MonthStatementGetFailed | 月结算单获取失败 |
1005 | QueryTimeExceeded | 请求的时间不正确 |
1006 | TransactionGetFailed | 流水数据获取失败 |
1007 | CouponUsageGetFailed | 优惠券使用量获取失败 |
月结算单概览接口
描述
本接口作 GET 请求用来获取请求拥有的所有月结算单的概览列表,该接口需要您使用带 Authorization 签名认证的请求,如果使用匿名请求无法获取月结算单概览。
请求
请求语法
GET /billing-api/v1/bill/overview?start=<StartTime>&end=<EndTime> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
请求参数
字段名称 | 类型 | 是否必须 | 示例 | 说明 |
---|---|---|---|---|
start | string | 是 | 2021-09-01T00:00:00 | 开始时间(东八区时间),目前只支持按月查询 |
end | string | 是 | 2021-10-01T00:00:00 | 结束时间(东八区时间),时间范围支持左闭右开 |
请求头
该请求操作的实现使用了所有操作的公共请求头。有关详细信息,请查阅公共请求头。
请求内容
该请求操作的请求体为空
响应
响应语法
HTTP/1.1 200 OK
ContentType: application/json
{
"code": <ErrorCode>,
"data": <Data>,
"message": <Message>
}
响应头
该请求操作的实现使用了所有操作的公共响应头。有关详细信息,请查阅公共响应头。
响应内容
字段名称 | 类型 | 示例 | 描述 |
---|---|---|---|
start | string | 2021-09-01T00:00:00 | 账单开始时间(东八区时间) |
end | string | 2021-10-01T00:00:00 | 账单结束时间(东八区时间),左闭右开 |
billID | string | 3489e21b4a1240d61d45c38e40f376a8 | 账单或者订单编号 |
type | string | bill | 账单类型有:bill|order,分别表示:账单,订单 |
payStatus | string | paid | 支付状态有: unpaid|paid|refunded|postpaid,分别表示:未支付,已支付,已退款,后付费(订单) |
product | string | SSL证书 | 产品名称 |
itemDesc | string | Geotrust 企业型SSL证书 | 订单显示商品名,账单显示计费项名 |
fee | integer | 1995000000 | 支付总金额,精确到小数点后8位,示例值为19.95元 |
couponFee | integer | 0 | 优惠券金额,精确到小数点后8位 |
presentFee | integer | 0 | 赠送金支付金额,精确到小数点后8位 |
cashFee | integer | 0 | 现金支付金额,精确到小数点后8位 |
currency | string | CNY | 币种 |
响应状态码
该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息,请查阅错误码。
示例
请求示例
GET /billing-api/v1/bill/overview?start=2021-11-01T00:00:00&end=2021-12-01T00:00:00
Host: api.qiniu.com
User-Agent: Go-http-client/1.1
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
注:要在 Authorization 头部的 AccessToken 前添加 Qiniu 和半角空格。
响应示例
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW
{"code": 0,
"message": "Success",
"data": [{"start": "2021-12-01T00:00:00",
"end": "2022-01-01T00:00:00",
"billID": "61d085825e65d175d97c8efb",
"type": "bill",
"payStatus": "paid",
"product": "对象存储",
"itemDesc": "存储空间-华北",
"fee": 0,
"couponFee": 0,
"presentFee": 0,
"cashFee": 0,
"currency": "CNY"},
{"start": "2021-12-01T00:00:00",
"end": "2022-01-01T00:00:00",
"billID": "61d08582722bbb5ef2fb22f7",
"type": "bill",
"payStatus": "unpaid",
"product": "对象存储",
"itemDesc": "存储空间-华东",
"fee": 7329416000000,
"couponFee": 0,
"presentFee": 0,
"cashFee": 0,
"currency": "CNY"},
...
]}
账单详情接口
描述
本接口使用 GET 请求用来获取请求拥有的所有账单详情的列表。该接口需要您使用带 Authorization 签名认证的请求,如果使用匿名请求无法获取账单详情。
请求
请求语法
GET /billing-api/v1/bill/detail?start=<StartTime>&end=<EndTime> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
请求参数
字段名称 | 类型 | 是否必须 | 示例 | 说明 |
---|---|---|---|---|
start | string | 是 | 2021-09-01T00:00:00 | 开始时间(东八区时间),目前只支持按月查询 |
end | string | 是 | 2021-10-01T00:00:00 | 结束时间(东八区时间),时间范围支持左闭右开 |
请求头
该请求操作的实现使用了所有操作的公共请求头。有关详细信息,请查阅公共请求头。
请求内容
该请求操作的请求体为空
响应
响应语法
HTTP/1.1 200 OK
ContentType: application/json
{
"code": <ErrorCode>,
"data": <Data>,
"message": <Message>
}
响应头
该请求操作的实现使用了所有操作的公共响应头。有关详细信息,请查阅公共响应头。
响应内容
字段名称 | 类型 | 示例 | 描述 |
---|---|---|---|
currency | string | CNY | 币种 |
total_money | int64 | 538323000000 | 总费用,精确到小数点后面8位 |
list | List |
详情列表 |
List
字段名称 | 类型 | 示例 | 描述 |
---|---|---|---|
start | string | 2021-09-01T00:00:00 | 账单开始时间(东八区时间) |
end | string | 2021-10-01T00:00:00 | 账单结束时间(东八区时间),左闭右开 |
product | string | CDN加速 | 产品名称 |
item | string | 动态加速-动态请求次数-华东 | 计费项描述 |
zone | string | 华东 | 地区 |
bill_period | string | 月出账单 | 账单周期 |
package_usage | int64 | 0 | 免费额度使用量 |
respack_usage | int64 | 0 | 资源包抵扣量 |
total_usage | int64 | 7015066 | 总用量,计量原始量 |
usage_coefficient | int64 | 1073741824 | 计量转化系数,从原始量单位到价格阶梯单位的转换,原始量除以此系数即为计量单位量 |
usage_unit | string | GB | 计量单位 |
price_type | string | 各阶梯单价 | 计费方式 |
price_unit | string | CNY/GB | 价格单位 |
item_money | int64 | 13233000000 | 计费项费用,此金额已经计算减免以及抵扣的费用 |
discount_money | int64 | -13225000000 | 减免金额 |
rebate_money | int64 | 0 | 折扣金额 |
currency | string | CNY | 币种 |
usage_cost | List |
各价格阶梯用量与费用 |
UsageCost
字段名称 | 类型 | 示例 | 描述 |
---|---|---|---|
is_guaranteed_price | Boolean | false | 是否是阶梯保底价格 |
money | int64 | 0 | 此价格阶梯产生的费用 |
price | int64 | 112000000 | 价格,加上 price_unit 是单价 |
usage | int64 | 7015066 | 使用量,计量原始量,根据 usage_coefficient 进行换算 |
usage_from | int64 | 0 | 价格阶梯起始量,计量原始量 |
usage_to | int64 | 1024 | 价格阶梯结束量,计量原始量,-1 表示无穷大 |
响应状态码
该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息,请查阅错误码。
示例
请求示例
GET /billing-api/v1/bill/detail?start=2021-11-01T00:00:00&end=2021-12-01T00:00:00
Host: api.qiniu.com
User-Agent: Go-http-client/1.1
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
注:要在 Authorization 头部的 AccessToken 前添加 Qiniu 和半角空格。
响应示例
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Thu, 24 Feb 2022 08:29:17 GMT
X-Reqid: 2ZUBFPIhD-akXtYW
{
"code": 0,
"message": "Success",
"data": {
"currency": "CNY",
"total_money": 538323000000,
"list": [
{
"currency": "CNY",
"discount_money": 0,
"end": "2022-03-01T00:00:00",
"item": "CDN-HTTPS 流量-其它地区",
"item_money": 0,
"package_usage": 0,
"price_type": "各阶梯单价",
"price_unit": "CNY/GB",
"product": "CDN加速",
"rebate_money": 0,
"respack_usage": 0,
"start": "2022-02-01T00:00:00",
"total_usage": 7015066,
"usage_coefficient": 1073741824,
"usage_cost": [
{
"is_guaranteed_price": false,
"money": 0,
"price": 112000000,
"usage": 7015066,
"usage_from": 0,
"usage_to": 10995116277760
},
{
"is_guaranteed_price": false,
"money": 0,
"price": 98000000,
"usage": 0,
"usage_from": 10995116277760,
"usage_to": 54975581388800
},
{
"is_guaranteed_price": false,
"money": 0,
"price": 85000000,
"usage": 0,
"usage_from": 54975581388800,
"usage_to": 109951162777600
},
{
"is_guaranteed_price": false,
"money": 0,
"price": 85000000,
"usage": 0,
"usage_from": 109951162777600,
"usage_to": 109951162777600
}
],
"usage_unit": "GB",
"zone": "其它地区"
},
}
}
文档反馈
(如有产品使用问题,请提交工单)