请输入
菜单

证书开放接口文档

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

一、概述

1.1 文档说明

本文档描述证书相关的开放 API 接口，包括证书详情查询、证书上传、删除证书等功能。所有接口均需通过协会易分发的 appId 和 secret 进行鉴权。

1.2 基础信息

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

1.3 统一响应格式

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

二、接口列表

序号 接口名称 请求方式 路径 说明
1 证书详情 GET /open/cert/detail 获取颁发证书的详情及字段信息
2 证书上传 POST /open/cert/certUpload 给用户颁发证书
3 删除证书 POST /open/cert/certDelete 删除已上传的证书

三、接口详情

3.1 证书详情

3.1.1 接口说明

允许第三方通过此接口获取颁发证书的详情，返回证书的字段信息及等级选项等。

3.1.2 请求信息

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

3.1.3 请求参数

参数名 类型 必填 说明
certId int 是 对应协会易后台证书模板的 id
appId string 是 开放平台应用ID
secret string 是 开放平台密钥

3.1.4 请求示例

复制代码 
GET https://www.shanghuiyi.com/open/cert/detail?certId={certId}&appId={your_appId}&secret={your_secret}

3.1.5 响应参数

参数名 类型 说明
errno int 状态码，0 表示成功
errmsg string 状态描述
data array 证书字段信息列表

data 中元素结构：

属性 类型 说明
id string 证书字段的 id
name string 证书字段的名字（中文）
levels array 仅「证书等级」字段携带，含所有等级的数组

levels 中元素结构（证书等级字段专用）：

属性 类型 说明
levelName string 等级名称
levelValue int 等级值，值越大代表等级越高

说明：可根据用户信息接口中的 certLevel 获取当前用户晋级后的等级，取下一顺位即可。其他字段含义可参见系统硬编码。

3.1.6 响应示例

成功：

json 复制代码 
{
  "errno": 0,
  "errmsg": "成功",
  "data": [
    {
      "id": "6551427978502144",
      "name": "证书编号"
    },
    {
      "id": "6551427978633222",
      "name": "证书等级",
      "levels": [
        { "levelName": "无等级", "levelValue": 1 },
        { "levelName": "十六级棋士", "levelValue": 2 },
        { "levelName": "十五级棋士", "levelValue": 3 },
        { "levelName": "一级棋士", "levelValue": 17 },
        { "levelName": "棋协大师", "levelValue": 19 },
        { "levelName": "特级大师", "levelValue": 21 }
      ]
    },
    {
      "id": "6551427978502145",
      "name": "姓名"
    },
    {
      "id": "6551427978502146",
      "name": "性别"
    },
    {
      "id": "6551427978502147",
      "name": "个人证件照"
    },
    {
      "id": "6551427978633216",
      "name": "身份证号"
    },
    {
      "id": "6551427978633217",
      "name": "发证机关"
    },
    {
      "id": "6551427978633218",
      "name": "发证日期"
    },
    {
      "id": "6551427978633220",
      "name": "证书图片"
    }
  ]
}

失败：

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

3.2 证书上传

3.2.1 接口说明

允许第三方通过此接口给用户颁发证书。

3.2.2 请求信息

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

3.2.3 请求参数

Query 参数：

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

Body 参数：

参数名 类型 必填 说明
certId int 是 证书模板 id，如固定值 392
certInfos array 是 证书字段值对象数组

certInfos 中元素结构：

属性 类型 说明
title string 证书字段名
value string 证书字段对应的值

3.2.4 请求示例

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

{
  "certId": 392,
  "certInfos": [
    { "title": "证书编号", "value": "C20250001" },
    { "title": "姓名", "value": "张三" },
    { "title": "性别", "value": "男" },
    { "title": "证书等级", "value": "10" },
    { "title": "发证日期", "value": "2025-03-11" }
  ]
}

3.2.5 响应参数

参数名 类型 说明
errno int 状态码，0 表示成功
errmsg string 状态描述

3.2.6 响应示例

成功：

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

失败：

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

3.3 删除证书

3.3.1 接口说明

通过此接口可删除已上传的证书。

3.3.2 请求信息

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

3.3.3 请求参数

参数名 类型 必填 说明
certId int 是 对应协会易系统内证书模板 id
certNo string 是 证书编号
appId string 是 开放平台应用ID
secret string 是 开放平台密钥

3.3.4 请求示例

复制代码 
POST https://www.shanghuiyi.com/open/cert/certDelete?certId={certId}&certNo={certNo}&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
上一个
活动开放接口文档
下一个
文章开放接口文档
最近修改: 2026-03-11Powered by