接入说明

• 目前支持两种勋章发放方式：
  • 无感发勋章：是指无需在腾讯公益的小程序或H5环境内，由业务侧直接调用公益开放平台接口，实现发放勋章到用户对应的公益账号
  • 跳转公益页发勋章：是指业务侧调用公益开放平台接口获取勋章预发放ID后，携带参数跳转到公益勋章领取页（小程序或H5环境）完成领取

• 如何查看勋章：
  • 在腾讯公益的小程序或H5的个人中心，用户可以查看自己的所有公益勋章

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

业务流程

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

  无感发勋章

  sequenceDiagram participant fr as 业务前端 participant ba as 业务后端 participant op as 公益开放平台 fr ->> ba: 用户是否需要发勋章 ba ->> ba: 判断业务自身发勋章资格 ba ->> op: 调用查询用户勋章接口（ExternalQueryMedal） op -->> ba: 返回信息 ba -->> fr: 返回结果 fr -->> fr: 用户能领章 fr ->> ba: 领章 ba ->> op: 调用无感发勋章接口（ExternalAwardMedal） op -->> ba: 返回发勋章结果 ba ->> ba: 业务自身逻辑处理 ba -->> fr: 返回结果 fr ->> fr: 展示业务自定义领勋章结果页

跳转公益页发勋章

接口协议

查询用户已领取勋章信息

使用场景： 发勋章前判断用户是否已领过勋章，一般用于业务前端置灰领章按钮和做文字提示等。如果业务侧本身有做领取记录，也可以不用调该接口，本身发勋章接口也包含校验用户是否已领取过勋章的逻辑（如果用户已领取，发勋章接口会返回对应错误码）。

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/user_medal_rule/ExternalQueryMedal

请求参数：

• 请求示例

  {
    "medal_id":"MEDALYKZYYY",
    "third_open_id": "third_xxxxxx"
  }
  

返回参数：

返回示例：

{
    "code": 0,
    "data": {
        "list": [
            {
                "attach_info": "测试数据",
                "award_time": "2023-03-26 16:21:06",
                "medal_id": "MEDALYKZYYY",
                "medal_level": "3",
                "transcode": "20230323162106MEDALYKZYYY"
            },
            {
                "attach_info": "",
                "award_time": "2023-03-20 23:24:01",
                "medal_id": "MEDALYKZYYY",
                "medal_level": "2",
                "transcode": "20230322324010MEDALYKZYYY"
            },
            {
                "attach_info": "测试数据",
                "award_time": "2023-03-20 16:19:48",
                "medal_id": "MEDALYKZYYY",
                "medal_level": "1",
                "transcode": "20230320161948MEDALYKZYYY"
            }
        ]
    },
    "msg": "",
    "op_time": 1679844396,
    "trace_id": "ed8436c85407856b23e5ea20fa472ebc"
}

无感发勋章

使用场景： 无感发勋章，业务侧直接给某个用户的公益帐号发放勋章

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/user_medal_rule/ExternalAwardMedal

请求参数：

• 请求示例

  {
    "medal_id": "MEDALYKZYYY",
    "medal_level": "2",
    "trans_code": "20230320232401MEDALYKZYYY"
  }
  

返回参数：

返回示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "award_time": "2023-03-26 23:24:01",
        "transcode": "20230320232401MEDALYKZYYY"
    },
    "op_time": 1679844241,
    "trace_id": "0f4f9a2e9147e0c7381932b5b1271403"
}

获取勋章预领取订单ID

使用场景： 跳转公益页领勋章。判断用户能领取后，生成预领取订单ID，用于生成跳转参数

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/user_medal_rule/ExternalGetExchangeId

请求参数：

• 请求示例

  {
    "third_open_id": "third_xxxxxx",
    "medal_id": "MEDALYKZYYY",
    "medal_level": "2",
    "trans_code": "20230320232401MEDALYKZYYY"
  }
  

返回参数：

返回示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "exchange_id": "gytest0001"
    },
    "op_time": 1679844241,
    "trace_id": "0f4f9a2e9147e0c7381932b5b1271403"
}

获取聚合业务用户勋章数据

使用场景： 获取业务下授权业务用户勋章

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/user_medal_rule/ExternalQueryAggMedal

请求参数：

• 请求示例

  {
    "medal_id": "MEDALYKZYYY",
  "start_time": "2006-01-02 15:04:05",
  "end_time": "2006-01-02 15:04:05"
  }
  

返回参数：

返回示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "medal_num": 10,
         "list": [{
           "transcode": "transcode_xx",
           "medal_id": "medal_xx",
           "medal_level": "level1",
           "award_time": "2024-01-01 14:00:00",
           "attach_info": "",
           "medal_name": "medal_name",
           "medal_img": "http://xxx.jpg",
           "medal_desc": "medal_desc",
           "appid": "gy_xx",
           "app_name": "demoApp"
         }]
    },
    "op_time": 1679844241,
    "trace_id": "0f4f9a2e9147e0c7381932b5b1271403"
}

获取聚合业务用户勋章项目

使用场景： 获取业务下授权业务用户勋章参与项目

调用凭证： 应用签名

请求方式： POST（HTTPS）

请求地址： https://oapi.gongyi.qq.com/api/user_medal_rule/ExternalQueryAggMedalProj

请求参数：

• 请求示例

  {
  "start_time": "2006-01-02 15:04:05",
  "end_time": "2006-01-02 15:04:05"
  }
  

返回参数：

返回示例：

{
    "code": 0,
    "msg": "",
    "data": {
        "medal_num": 10,
         "list": [{
           "proj_id": "233777",
           "proj_name": "项目",
           "proj_img": "http://xx.jpg"
         }]
    },
    "op_time": 1679844241,
    "trace_id": "0f4f9a2e9147e0c7381932b5b1271403"
}

跳转公益页发勋章

• 跳转公益页时，需要在链接中带上勋章领取参数以及签名，该信息由业务后台计算，由业务前端跳转时带上。
• 由于是携带参数跳转到公益页，由前端发起请求，从安全性考虑，计算签名时是对包体进行签名。
• 此流程会将业务侧用户ID与公益侧ID进行绑定

跳转 Query 参数

H5 跳转

• 示例： https://ssl.gongyi.qq.com/user_center/getBadges.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/webview/main?link=${encodeURIComponent(H5链接)}&spmet=test

测试环境调试

• 测试环境接口域名：增加 test- 前缀

• H5 测试环境链接示例：https://devssl.gongyi.qq.com/user_center/getBadges.html?cgi=gray + 拼接参数

• 小程序测试环境路径：pages/webview/main?link=${encodeURIComponent(测试环境H5链接)}&spmet=test

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

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

  
  

跳转方式的选择

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

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

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

{
    "embeddedAppIdList": ["wxfdcee92a299bcaf1"]
}

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

wx.openEmbeddedMiniProgram({
   appId: 'wxfdcee92a299bcaf1',
   path: 'pages/webview/main?link=${encodeURIComponent(H5链接)}&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 方式

错误码