接入说明

无感发花接入：针对用户的指腾讯内部已开通用户账号互转权限的业务（微信和QQ账号），外部已开通账号互转权限的业务（QQ账号体系）接入，调用接口时即发花

以上方式涉及业务侧帐号与公益帐号的转换，需要满足以下条件：

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

业务流程

• 以下是基本的业务使用流程

  无感发花

  sequenceDiagram participant fr as 业务前端 participant ba as 业务后端 participant op as 公益开放平台 participant ob as 公益领花页 fr ->> ba: 用户是否能领花 ba ->> ba: 判断业务自身领花资格 ba ->> op: 调用判断用户当前能否领花(无感发花)接口 op -->> ba: 返回能否领花 ba -->> fr: 返回结果 fr -->> fr: 用户能领花 fr ->> ba: 领花 ba ->> op: 调用无感发花接口 op -->> ba: 返回发花结果 ba ->> ba: 业务自身逻辑处理 ba -->> fr: 返回结果 alt 需要到公益页面设置微信状态 fr ->> ob: 使用领花参数跳转公益页面（参考文档：合作活动领特殊微信状态） else 不设置微信状态 fr ->> fr: 展示业务自定义领花结果页 end

领花后跳转设置微信状态

如果需要跳转至公益设置微信状态，需要再领花后跳转至公益小程序，跳转路径及参数请参考合作活动领特殊微信状态

调用接口

判断用户当前能否领花

使用场景： 发花前判断用户能否领花，一般用于业务需要在前端置灰领花按钮时使用。这里的判断是业务侧在公益侧申请的领花配置（比如1天1朵、1天3朵等）。如果业务侧本身有做领花数的记录，也可以不需要调用该接口。

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数：

• 请求示例

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

返回参数：

返回示例：

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

无感发花

使用场景： 无感发花，业务侧直接给某个用户的公益帐号发放指定数量的小红花

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数：

• 说明:

  • 一般只需要trans_code和xhh_num两个参数， proj相关的是小红花侧有要求时才需要填写

• 请求示例

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

返回参数：

• 说明
  • 发花失败时，部分错误码attach字段会携带原因，比如30110501用户被风控，会返回反馈链接，30110502，会返回达到领花上限的原因

返回示例：

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

查询业务订单状态

使用场景： 对于1天可以领取多朵花的业务，通过此接口判断订单是否已使用，决定是否展示领花选项。如果是1天1朵的业务，一般用判断用户当前能否领花即可。

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数：

• 请求示例

  {
    "trans_code":"202205160001"
  }
  

返回参数：

• 说明
  • 如果xhh_code为空，表示订单未被使用，如果用户当天仍能领取小红花，业务侧可以继续用该订单（7天内）或生成新订单来给用户发花

返回示例：

{
    "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
    }
}

查询用户小红花总数

使用场景： 可请求累计小红花数，或者当前小红花数。用户累计小红花数一般用于展示在用户个人信息页，与公益侧的小红花展示维度保持一致。

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数：

• 请求示例

  {
    "need_history": 1,
    "need_current": 1
  }
  

返回参数：

返回示例：

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

查询聚合业务用户小红花总数

使用场景： 用于查询用户在业务下所有可见业务的小红花统计。

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数： 无

返回参数：

返回示例：

{
  "code": 0,
  "msg": "",
  "op_time": 1657024756,
  "trace_id": "c8fc7e73a941782737d9f217391b5a57",
  "data": {
    "list": [
      {
        "appid": "gy_xxx",
        "history_xhh": 100
      }
    ]
  }
}

查询聚合业务用户小红花流水

使用场景： 用于查询用户在业务下所有可见业务的小红花流水。

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数：

返回参数：

返回示例：

{
  "code": 0,
  "msg": "",
  "op_time": 1657024756,
  "trace_id": "c8fc7e73a941782737d9f217391b5a57",
  "data": {
    "list": [
      {
        "desc":"",
        "num":"10",
        "appid": "gy_xxxxx",
        "op_type":"ADD",
        "time_sort":"1719544442260774490",
        "trans_code":"XHHMONTH2023109"
      }
    ]
  }
}

查询聚合业务用户小红花用户参与项目

使用场景： 用于查询用户在业务下所有可见业务的小红花支持的项目。

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数：

返回参数：

返回示例：

{
  "code": 0,
  "msg": "",
  "op_time": 1657024756,
  "trace_id": "c8fc7e73a941782737d9f217391b5a57",
  "data": {
    "list": [
      {
        "desc":"",
        "num":"10",
        "appid": "gy_xxxxx",
        "op_type":"ADD",
        "time_sort":"1719544442260774490",
        "trans_code":"XHHMONTH2023109"
      }
    ]
  }
}

错误码