账户财务

  • 账户与财务 > 使用文档 > 财务对外 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": "其它地区"
                },
            }
    } 
    
    以上内容是否对您有帮助?
  • Qvm free helper
    Close