账户与财务 > 使用文档 > 财务对外 API 文档

财务对外 API 文档

最近更新时间：2022-03-07 10:36:07

更新日志

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": "其它地区"
            },
        }
}

以上内容是否对您有帮助？

账户财务

财务对外 API 文档

更新日志

概述

注意事项

接口域名

接口列表

API签名

错误码

月结算单概览接口

描述

请求

请求语法

请求参数

请求头

请求内容

响应

响应语法

响应头

响应内容

响应状态码

示例

请求示例

响应示例

账单详情接口

描述

请求

请求语法

请求参数

请求头

请求内容

响应

响应语法

响应头

响应内容

响应状态码

示例

请求示例

响应示例