请输入
菜单

活动开放接口文档

文档版本：v1.0
更新日期：2024-11-13
接口模块：活动开放 API

一、概述

1.1 文档说明

本文档描述活动相关的开放 API 接口，包括获取报名用户信息、证书颁发、核销准考证等功能。所有接口均需通过协会易分发的 appId 和 secret 进行鉴权。

1.2 使用场景

场景 说明
线上 用户登录协会易后，在小程序报名活动缴费，跳转到第三方小程序并携带准考证号 ticketID，同时携带三方参数 thirdId，参数值需秘书处在协会易活动里配置
线下 用户登录协会易后，在小程序报名活动缴费，协会易告知用户准考证号 activityNumber，所需的三方参数在 getUserInfo 接口返回
信息获取 第三方通过 activityNumber 调用接口，可获取用户信息
证书颁发 用户在第三方小程序进行竞赛/考试，若考试通过，可通过上一步获取的信息调用颁发证书接口

1.3 基础信息

项目 说明
Base URL https://www.shanghuiyi.com/open/activity
鉴权方式 所有接口需在请求中携带 appId 和 secret 参数
数据格式 JSON

1.4 统一响应格式

json 复制代码 
{
  "errno": 0,
  "errmsg": "成功",
  "data": {}
}
字段 类型 说明
errno int 状态码，0 表示成功，其余为异常状态
errmsg string 状态描述，若有异常则为异常提示信息
data object/array 业务数据，成功时根据接口返回不同结构

二、接口列表

序号 接口名称 请求方式 路径 说明
1 获取报名用户信息 GET /open/activity/getUserInfo 获取当前报名用户的基本信息
2 证书颁发 POST /open/activity/certAward 给通过的用户颁发证书
3 核销准考证 POST /open/activity/checkTicket 核销用户当次报名的准考证

三、接口详情

3.1 获取报名用户信息

3.1.1 接口说明

允许第三方通过此接口获取当前报名用户的基本信息。需提供准考证号 activityNumber。

3.1.2 请求信息

项目 说明
请求方式 GET
请求路径 https://www.shanghuiyi.com/open/activity/getUserInfo

3.1.3 请求参数

参数名 类型 必填 说明
activityNumber string 是 准考证号，16 个字符
appId string 是 开放平台应用ID
secret string 是 开放平台密钥

3.1.4 请求示例

复制代码 
GET https://www.shanghuiyi.com/open/activity/getUserInfo?activityNumber={activityNumber}&appId={your_appId}&secret={your_secret}

3.1.5 响应参数

参数名 类型 说明
errno int 状态码，0 表示成功
errmsg string 状态描述
data object 用户基本信息及报名信息

data.baseInfo（用户基本信息）：

参数名 类型 说明
userId string 用户 id
certId int 证书模板 id
username string 姓名
avatar string 用户头像
region string 地区
undertaker string 活动承办方
organizersIntroduction string 主办单位
idCard string 身份证号
gender string 用户性别：0-未知，1-男，2-女

data.registerInfo（用户报名信息）：

参数名 类型 说明
registerTime string 用户报名时间，格式：yyyy-MM-dd HH:mm:ss
startTime string 比赛开始时间，格式：yyyy-MM-dd HH:mm:ss
endTime string 比赛结束时间，格式：yyyy-MM-dd HH:mm:ss
level int 用户报考等级
match string 赛事名称
formInfo array 用户填写的报名表单信息，key-value 格式

formInfo 元素结构：

属性 类型 说明
title string 秘书处配置的报名题目
answer string 用户填写的信息

data.thirdId：第三方所需参数，用于跳转或关联。

3.1.6 响应示例

成功：

json 复制代码 
{
  "errno": 0,
  "errmsg": "成功",
  "data": {
    "baseInfo": {
      "userId": "5320812425650176",
      "certId": 256,
      "username": "李②",
      "avatar": "https://thirdwx.qlogo.cn/mmopen/vi_32/xxx/132",
      "region": "",
      "undertaker": ""
    },
    "registerInfo": {
      "registerTime": "2023-01-12 17:31:27",
      "startTime": "2023-01-25 00:00:00",
      "endTime": "2023-01-31 00:00:00",
      "level": 9,
      "formInfo": [
        { "title": "姓名", "answer": "李②" },
        { "title": "联系方式", "answer": "17365365619" },
        { "title": "我的等级", "answer": "五级棋士" },
        { "title": "身份证号码", "answer": "4210811548115" },
        { "title": "备注", "answer": "" }
      ]
    },
    "thirdId": "?qipuID=136596&qipuType=1"
  }
}

失败：

json 复制代码 
{
  "errno": -1,
  "errmsg": "请求错误"
}

3.2 证书颁发

3.2.1 接口说明

允许第三方通过此接口给通过的用户颁发证书。成功后将返回证书的 H5 地址，第三方可自行渲染。

3.2.2 请求信息

项目 说明
请求方式 POST
请求路径 https://www.shanghuiyi.com/open/activity/certAward
Content-Type application/json

3.2.3 请求参数

Query 参数：

参数名 类型 必填 说明
appId string 是 开放平台应用ID
secret string 是 开放平台密钥

Body 参数：

参数名 类型 必填 说明
userId string 是 用户 id（从 getUserInfo 获取）
certId int 是 证书模板 id，固定值 392
activityNumber string 是 准考证号
certInfos array 是 证书字段值对象数组

certInfos 中元素结构：

属性 类型 说明
title string 证书字段名（见下方硬编码字段表）
value string 证书字段对应的值

3.2.4 证书字段硬编码说明

字段名 类型 说明
证书编号 string 待颁发证书的编号，例如：no887332
姓名 string 参赛人姓名
性别 string 参赛人性别，值为男或女
单位名称 string 参赛人单位
身份证号 string 参赛人身份证号码
发证机关 string 发证机关
出生日期 string 参赛人出生日期，需解析身份证号
发证日期 string 发证日期，格式：yyyy-MM-dd
赛事名称 string 参与比赛的名称
赛事成绩 string 参赛最终成绩
证书等级 string 参赛获得的称号
个人证件照 string 如果没有，可传空字符串

3.2.5 请求示例

复制代码 
POST https://www.shanghuiyi.com/open/activity/certAward?appId={your_appId}&secret={your_secret}
Content-Type: application/json

{
  "userId": "5320812425650176",
  "certId": 392,
  "activityNumber": "ACT202500012345",
  "certInfos": [
    { "title": "证书编号", "value": "no887332" },
    { "title": "姓名", "value": "李②" },
    { "title": "性别", "value": "男" },
    { "title": "单位名称", "value": "某某棋院" },
    { "title": "身份证号", "value": "4210811548115" },
    { "title": "发证机关", "value": "中国象棋协会" },
    { "title": "发证日期", "value": "2025-03-11" },
    { "title": "赛事名称", "value": "2025年春季等级赛" },
    { "title": "证书等级", "value": "五级棋士" }
  ]
}

3.2.6 响应参数

参数名 类型 说明
errno int 状态码，0 表示成功
errmsg string 状态描述
data object 证书 H5 地址

data 结构：

参数名 类型 说明
h5 string 证书 H5 地址，第三方自行渲染

3.2.7 响应示例

成功：

json 复制代码 
{
  "errno": 0,
  "errmsg": "成功",
  "data": {
    "h5": "https://www.shanghuiyi.com/wv-pdf/#/Cert?isShow=true&shId=225&memberCertId=5841334927626240"
  }
}

失败：

json 复制代码 
{
  "errno": -1,
  "errmsg": "请求错误"
}

3.3 核销准考证

3.3.1 接口说明

通过此接口可核销用户当次报名的准考证。

3.3.2 请求信息

项目 说明
请求方式 POST
请求路径 https://www.shanghuiyi.com/open/activity/checkTicket

3.3.3 请求参数

参数名 类型 必填 说明
activityNumber string 是 准考证号，16 个字符
appId string 是 开放平台应用ID
secret string 是 开放平台密钥

3.3.4 请求示例

复制代码 
POST https://www.shanghuiyi.com/open/activity/checkTicket?activityNumber={activityNumber}&appId={your_appId}&secret={your_secret}

3.3.5 响应参数

参数名 类型 说明
errno int 状态码，0 表示成功，其余为异常状态
errmsg string 状态描述，若有异常则为异常提示信息

3.3.6 响应示例

成功：

json 复制代码 
{
  "errno": 0,
  "errmsg": "成功"
}

失败：

json 复制代码 
{
  "errno": -1,
  "errmsg": "请求错误"
}

四、错误码说明

errno 说明
0 成功
-1 请求错误，请求参数非法
其他 失败，具体原因见 errmsg
上一个
微信小程序H5跳转接口文档
下一个
证书开放接口文档
最近修改: 2026-03-11Powered by