接入说明

• 无感发花是指无需跳转领花页，直接在业务侧操作而实现发放小红花到用户对应公益帐号中的发花方式
• 无感捐花是指无需跳转到腾讯公益梦想页/项目页，直接在业务侧操作而实现用户捐赠小红花

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

• 腾讯内部已开通帐号互转权限的业务（仅限微信或QQ帐号体系）
• 外部已开通帐号互转权限的业务（仅限QQ帐号体系）

• 已通过开放平台绑定用户帐号的业务（任意帐号体系，暂未支持）

• 接入方需要提供微信开放平台的AppID和负责人（用于申请互转权限时作为审批人），或者QQ互联的AppID，由公益侧提交互转权限的申请，微信/QQ审批通过后，才能使用。注意：如果是微信游戏，则需要通过微信帐号托管平台做接入，参考微信游戏帐号托管

• 接口使用签名方式，如何生成签名以及用户信息的传递参考接口调用凭证

业务流程

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

  无感发花

  sequenceDiagram participant fr as 业务前端 participant ba as 业务后端 participant op as 公益开放平台 fr ->> ba: 用户是否能领花 ba ->> ba: 判断业务自身领花资格 ba ->> op: 调用判断用户当前能否领花(无感发花)接口 op -->> ba: 返回能否领花 ba -->> fr: 返回结果 fr -->> fr: 用户能领花 fr ->> ba: 领花 ba ->> op: 调用无感发花接口 op -->> ba: 返回发花结果 ba ->> ba: 业务自身逻辑处理 ba -->> fr: 返回结果 fr ->> fr: 展示业务自定义领花结果页

无感捐花

调用接口

判断用户当前能否领花

使用场景： 发花前判断用户能否领花，一般用于业务需要在前端置灰领花按钮时使用。这里的判断是业务侧在公益侧申请的领花配置（比如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_current参数，来请求用户当前可用小红花数量即可，用于捐花展示及捐花参数限制

• 请求示例

  {
    "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/SilenceDonateXhh

请求参数：

• 说明：

  • 一般业务需要先查询用户当前可用小红花数量，再调用该接口来捐花

• 请求示例

  {
  "trans_code": "WZRY202207010000001",
  "donate_id": "5",
  "donate_type": 0,
  "xhh_num": 10
  }
  

返回参数：

• 说明：
  • 返回30130030表示用户当天在业务侧捐花超限，或者是单次捐花超限，需要跳转到公益的H5或小程序中完成相应的捐花操作
  • 其中H5会返回完整的链接，小程序返回路径
  • 小程序AppID：wxfdcee92a299bcaf1
  • 小程序原始ID：gh_3f146c2a1401

返回示例：

{
  "code": 0,
  "msg": "",
  "op_time": 1657024756,
  "trace_id": "c8fc7e73a941782737d9f217391b5a57",
  "data": {
    "trans_code": "fakfkda-sdkds-saieo-00",
    "day_user_xhh_num": 10,
    "h5_url": "https://ssl.gongyi.qq.com/flower-integral/project/detail.html?pid=1&et=XHH",
    "mp_url": "pages/webview/main?link=https%%3A%%2F%%2Fssl.gongyi.qq.com%%2Fflower-integral%%2Fproject%%2Fdetail.html%%3Fpid%%3D1%%26et%%3DXHH",
    "day_xhh_num": 1000,
    "total_xhh_num": 10000
  }
}

查询捐花项目/梦想进度

使用场景： 用于业务侧展示整体的梦想进度，由于是全局数据，建议业务侧做秒级的缓存，不需要每次用户打开页面都来查一次，每秒请求1次即可。

调用凭证： 应用签名

请求方式： POST（HTTPS）

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

请求参数：

• 请求示例

  {
  "donate_ids": [
    "10"
  ]
  }
  

返回参数：

返回示例：

{
  "code": 0,
  "msg": "",
  "op_time": 1657024756,
  "trace_id": "c8fc7e73a941782737d9f217391b5a57",
  "data": {
    "donate_infos": [
      {
        "current_total_num": 20,
        "donate_id": "10",
        "donate_mt": 20,
        "donate_name": "腾讯公益项目",
        "limit_type": 0,
        "object_xhh_num": 2,
        "target_total_num": 1000,
        "start_time": "2022-07-20 11:30:00",
        "end_time": "2022-08-31 00:00:00"
      }
    ]
  }
}

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

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

调用凭证： 应用签名

请求方式： 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"
      }
    ]
  }
}

错误码