接入说明

业务需要跳到腾讯公益来完成领花

• 业务侧按应用接入流程申请注册应用信息和申请接口权限

• 业务侧可选提供领花页的配置信息，展示定制领花页

• 接口使用签名方式，如何生成签名参考接口调用凭证

业务流程

• 关键流程：
  • 使用“判断用户当前能否领花”接口，决定是否在业务前端展示领花按钮，因为用户在业务周期内（1 天/1 周/1 月）内会有领花上限限制，需要调用接口判断能否领花
  • 用户点击领花时，使用“获取预发花订单 ID”接口，获取预发花订单 ID，并且拼接跳转参数，跳转到公益领花页

调用接口

判断用户当前能否领花

使用场景： 发花前判断用户能否领花

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/xhh_third_service/CheckXhh

请求参数：

• 请求示例

{
  "open_id": "abce0001",
  "trans_date": "20220516",
  "xhh_num": 1
}

返回参数：

返回示例：

{
  "code": 0,
  "msg": "Success",
  "op_time": 1650812345,
  "trace_id": "1a2b3c4d5e6f7g8h1a2b3c4d5e6f7g8h",
  "data": {
    "attach": ""
  }
}

获取预发花订单 ID

使用场景： 判断用户能领花后，生成预发花订单

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/xhh_third_service/PreTry

请求参数：

• 请求示例

{
  "open_id": "test1234",
  "trans_code": "202205160001",
  "time_start": "2022-05-16 11:00:00",
  "time_expire": "2022-05-16 11:10:00",
  "num": 2,
  "xhh_num": 1,
  "attach": "",
  "proj_name": "社区志愿服务",
  "proj_time": "2022-05-16 14:00:00",
  "proj_locale": "人才公园",
  "gy_proj_id": "1002"
}

返回参数：

返回示例：

{
  "code": 0,
  "msg": "Success",
  "op_time": 1650812345,
  "trace_id": "1a2b3c4d5e6f7g8h1a2b3c4d5e6f7g8h",
  "data": {
    "attach": "",
    "exchange_id": "gytest0001"
  }
}

查询业务订单状态

使用场景： 对于 1 天可以领取多朵花的业务，通过此接口判断订单是否已使用，决定是否展示领花选项

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/xhh_third_service/CheckIsTransExist

请求参数：

• 请求示例

{
  "open_id": "test0001",
  "trans_code": "202205160001"
}

返回参数：

• 说明
  • 仅 7 天内可查询到预发花订单 ID
  • 如果 xhh_code 不为空，表示订单已被使用；如果 exchange_id 不为空，表示已换取过 exchange_id，可以使用该 exchange_id 来跳转领花；如果 xhh_code 和 exchange_id 都为空，表示无该订单记录

返回示例：

{
  "code": 0,
  "msg": "Success",
  "op_time": 1650812345,
  "trace_id": "1a2b3c4d5e6f7g8h1a2b3c4d5e6f7g8h",
  "data": {
    "trans_time": "2022-05-16 11:00:00",
    "xhh_code": "XHHTTZHS202205161",
    "xhh_num": 1,
    "exchange_id": "gytest0001"
  }
}

查询用户累计获取小红花数

使用场景： 可用于在业务侧展示用户的小红花累计总数(注意: 不是指用户在业务侧获得的小红花数量, 是用户总的数量)

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/xhh_third_service/QueryUserXhh

请求参数：

• 请求示例

{
  "open_id": "test0001"
}

返回参数：

• 说明
  • 返回 30130028 表示用户未通过领花页领取业务的小红花，因此无法查询用户在公益侧的小红花数量

返回示例：

{
  "code": 0,
  "msg": "Success",
  "op_time": 1650812345,
  "trace_id": "1a2b3c4d5e6f7g8h1a2b3c4d5e6f7g8h",
  "data": {
    "history_xhh": 456
  }
}

跳转领花页发花

• 跳转领花页时，需要在链接中带上领花参数以及签名，该信息由业务后台计算，由业务前端跳转时带上。
• 由于是携带参数跳转到领花页，由前端发起请求，从安全性考虑，计算签名时是对包体进行签名

跳转 Query 参数

H5 跳转

• 示例： https://ssl.gongyi.qq.com/flower-integral/getFlowers.html?appid=gy_c1ujie9cvmieripmes0g&timestamp=1600110010&nonce=abcde1234&trans_code=202205160000001&exchange_id=gytest10001&sign=ABCDEF0123456789&spmet=test

小程序跳转链接

• AppID：wxfdcee92a299bcaf1（小程序跳小程序）
• 原始 ID：gh_3f146c2a1401（H5开放标签跳小程序）
• 路径：pages/flower-integral/get-flowers/main?appid=gy_c1ujie9cvmieripmes0g&timestamp=1600110010&nonce=abcde1234&trans_code=202205160000001&exchange_id=gytest10001&sign=ABCDEF0123456789&spmet=test

测试环境调试

• 推荐先使用跳转 H5 的方式来调试，方便查看接口返回，H5 测试环境链接示例：

  https://devssl.gongyi.qq.com/flower-integral/getFlowers.html?cgi=gray + 拼接参数

• H5 测试环境链接访问限制：

  1. 公司内网可直接访问
  2. 公司外网络 + 企微登录/MOA 登录
  3. 公司外网络 + token，联系 christyma 生成 token, 在 tde 面板输入生成的 token 可直接访问

  
  

• 小程序没有测试环境, 如果业务必须使用小程序才能跑通流程，可以临时使用 webview 来走测试流程：

  pages/webview/main?link=${encodeURIComponent(H5 测试环境链接)}

  后期上线前必须替换为小程序正式路径：

  pages/flower-integral/get-flowers/main? + 拼接参数

跳转方式的选择

• 小程序：推荐使用半屏小程序的方式，优化用户体验（详情见半屏小程序文档）

• 申请半屏小程序权限：小程序管理后台「设置」-「第三方设置」-「半屏小程序管理」 - 「我调用的」- 输入< wxfdcee92a299bcaf1> 发起申请；

• 小程序 2.23.1 版本以下基础库，被半屏打开的小程序需要在 app.json 的 embeddedAppIdList 字段中声明，2.23.1 版本以上不需要；

{
    "embeddedAppIdList": ["wxfdcee92a299bcaf1"]
}

1. 当前小程序需为竖屏；
2. 调用半屏小程序相关代码：

wx.openEmbeddedMiniProgram({
   appId: 'wxfdcee92a299bcaf1',
   path: 'pages/flower-integral/get-flowers/main?appid=gy_c1ujie9cvmieripmes0g&timestamp=1600110010&nonce=abcde1234&trans_code=202205160000001&exchange_id=gytest10001&sign=ABCDEF0123456789&spmet=test'
})

• 公众号 H5：推荐使用 H5 的跳转方式
• QQ：推荐使用 H5 的跳转方式
• APP 端：推荐使用小程序的跳转方式，详细规则见《微信官方文档》： https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Launching_a_Mini_Program/Launching_a_Mini_Program.html
• 非移动端：推荐使用 H5 方式

错误码