接入说明

账单下载采用的调用方主动请求生成账单的形式实现，需要调用两个接口实现：
- 创建账单下载任务：业务主动请求创建账单下载任务，接口返回任务ID，并后台异步进行账单生成
- 获取账单下载链接：业务再次请求获取账单下载链接，如果账单已生成准备好，则返回对应的账单下载链接；如果账单未准备好，则返回错误提示稍后重试

账单下载内容：
- 账单下载文件以压缩包(*.gz)的形式进行传输，节省流量和存储应对将来数据量的剧增。解压后文件以csv格式展示，具体期望内容要求可进行申请沟通

接入准备：
- 接入方需要提供微信开放平台的AppID和负责人（用于申请互转权限时作为审批人），或者QQ互联的AppID，由公益侧提交互转权限的申请，微信/QQ审批通过后，才能使用。注意：如果是微信游戏，则需要通过微信帐号托管平台做接入，参考微信游戏帐号托管
- 接口使用签名方式，如何生成签名以及用户信息的传递参考接口调用凭证
- 以上方式涉及业务侧帐号与公益帐号的转换，需要满足以下条件：
  - 腾讯内部已开通帐号互转权限的业务（仅限微信或QQ帐号体系）
  - 外部已开通帐号互转权限的业务（仅限QQ帐号体系）

账单字段说明

数据格式： csv文件

支持字段： 如下表所示

字段名	类型	含义	举例
transcode	string	公益的支付单号	e.g. 1465188602202211011900000125
bt	string	业务类型	e.g. AXC, IOT
pid	string	项目id	e.g. 237449
money	string	金额，单位：分	e.g. 100
trans_time	string	捐款(支付)时间	e.g. 2022-11-01 04:06:29
pay_platform_info.transaction_id	string	第三方接入支付的单号	e.g. 16685929251181481715adfAiNeuCux
pay_platform_info.type	string	支付平台（wx/qq）	e.g. wx
busi_code	string	业务携带透传过来的字段(原含义为一起捐id)	e.g. 1593097381202212184800001792

特殊支持字段： 如下表所示

字段名	类型	含义	举例
refund_time	string	退款时间	e.g. 2024-05-13 13:41:10
refund_wx_code	string	退款订单号(微信支付)	e.g. 50303009432024051375404914032
refund_money	string	退款金额	e.g. 100

特殊说明：该表为特殊支持字段，只提供给有必要拉取的第三方下载（非必要不申请）。该表字段不为空时表示退款订单，提供公益订单相应的退款信息。

接口协议

创建账单下载任务

使用场景： 用于与腾讯公益合作的业务下载隔日账单进行对账，由于公益内部也需要进行初步的对账处理，所以建议业务于隔日的下午3点之后进行尝试请求拉取账单。

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/bill_download/CreateBillDownloadTask

请求参数：

参数	类型	必填	说明
start_at	string	是	数据导出周期开始时间
end_at	string	是	数据导出周期结束时间

请求示例

{
  "start_at": "2023-09-17 00:00:00", 
  "end_at": "2023-09-18 00:00:00"
}

返回参数：

参数	类型	说明
code	int	返回码：0表示成功，其他值表示错误，请参考错误码说明
msg	string	错误信息
data	object	返回数据
task_id	string	离线任务 ID, 32位长度字符

返回示例：

{
    "code": 0,
    "data": {
        "task_id": "a0e1be2e78ee496b56ff2bd9d32ffa5a"
    },
    "msg": "",
    "op_time": 1695028171,
    "trace_id": "41ec2010a17242c08a0208c5b040afb6"
}

获取账单下载链接

使用场景： 首次请求完创建账单下载任务接口，间隔等待后台账单生成后(建议间隔不少于2分钟)，再进行请求获取账单下载链接接口。如果账单已生成准备好，接口则返回成功；如若报错提示账单未准备好，可以进行重试请求该接口