上海交通大学开发者平台

# Signature APIs

本组API完成电子签章功能。

# 安全策略

本API是电子签章用API，使用客户端凭据授予方式获取scope为signature的令牌即可访问。

# 签章文件

# 功能介绍

对pdf文件进行电子签章，返回该已签文件字节数组。

# 路径参数

参数名 类型 是否必填(Y/N) 说明
eSignCode String Y 电子签章编码，平台提供

# 请求参数

  • 文件参数 - file 需要签章的文件
参数名 类型 是否必填(Y/N) 说明
file MultipartFile Y pdf文件对象
  • 定位参数 - 坐标
参数名 类型 是否必填(Y/N) 说明
locations [] N 签章坐标，json数组，CONTENT TYPE 为application/json，表示每个数据项表示签章在指定页面上的放置位置，需要指定签章位置时传入此参数
  • 定位参数 - 关键字
参数名 类型 是否必填(Y/N) 说明
keyword string N 关键字，系统会在传入的文件中搜索关键字，若搜索到会在关键字上放置签章
keywordOrder int N 搜索顺序，0: 全部, 1: 正序, 2: 倒序，不传系统会默认为2
keywordSeq int N 匹配次序，即匹配搜索到的第几个关键字，不传系统会默认为1

坐标和关键字两种定位方式二选一即可，若同时传入，系统会优先取坐标定位方式作为实际有效的定位参数。

locations 的数据项格式说明

locations 的每个数据项由签章页码（表示签章在第几页）和签章位置（表示印章加盖的位置）两部分信息所组成。

在描述签章位置时有两种表达方式：

  1. 基于(x, y)，即XY坐标方式（后面称XY坐标方式）
  2. 基于(top/bottom, left/right)，即指定上/下/左/右偏移的方式（后面称偏移方式）

XY坐标方式示例：

[
  {
    "pageNo": 1,
    "x": 100,
    "y": 400
  },
  {
    "pageNo": 2,
    "x": 300,
    "y": 200
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
参数名 类型 是否必填(Y/N) 说明
pageNo int N 签章页码，表示签章在第几页
x int N x坐标，表示印章左边缘距离pdf页面左侧边界多少像素
y int N y坐标，表示印章中心点距离pdf页面底部边界多少像素

偏移方式示例：

[
  {
    "pageNo": 1,
    "top": 100,
    "left": 400
  },
  {
    "pageNo": 2,
    "bottom": 300,
    "right": 200
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
参数名 类型 是否必填(Y/N) 说明
pageNo int N 签章页码，表示印章在第几页
top/bottom/left/right int N 印章相对于页面的位置偏移多少像素，即印章上/下/左/右边缘与页面上/下/左/右边缘的间距

locations 的数据项规则说明

  • XY坐标方式优先于偏移方式，即如果在一个数据项内同时使用了这两种方式，则会使用XY坐标方式而忽略偏移方式
  • 数据项不包含 pageNo 属性时，会基于此数据项的签章位置信息为 pdf 每一页生成一个对应的数据项，即表示在 pdf 所有页面上盖章
  • 可以同时出现包含 pageNo 属性和不包含 pageNo 属性的数据项，这种情况下会为 pdf 所有页面上盖章，包含 pageNo 属性的数据项的的签章位置信息会覆盖由不包含 pageNo 属性的数据项所生成出来的数据项的签章位置信息
  • 多个数据项的 pageNo 属性相同或者均不存在时，则会进行去重，仅保留这些数据项中的第一个（结果就是该印章在某一页面中只能出现一次）
  • XY坐标方式中，如果 x 或 y 属性未指定，则会被设置默认值0
  • 偏移方式中，未给出的属性会被设置默认值0，top 和 bottom 同时出现时使用 top 忽略 bottom，left 和 right 同时出现时使用 left 忽略 right

关于验证二维码的特别说明

  • 验证二维码是指用于证明本文件签章真实性的二维码，当调用签章接口带有 qrCodeLocations 参数时会在签章后的文件上显示该二维码
  • 二维码内容为本文件的源文件在交大文件服务器上的地址，以交大域名形式确保签章文件的真实性
  • 验证二维码的坐标 qrCodeLocations 数据格式及规则同 locations
  • 验证二维码的坐标 qrCodeLocations 数据项中可以包含 width、height 两个属性，用于指定验证二维码的长度和宽度

# 请求数据格式

body form-data

# 响应参数

  1. 成功

http响应状态码为200，且返回已签文件字节数组。

  1. 失败

http响应状态码为非200，具体错误信息会以json格式返回，如：

Http Status Code: 401（验证token失败）

{
    "errno": 10007,
    "error": "ACCESS_TOKEN_EXPIRED",
    "total": 0
}
1
2
3
4
5

Http Status Code: 500（文件签章报错）

{
    "errno": -2,
    "error": "签章出错: 文件格式不支持",
    "total": 0
}
1
2
3
4
5

# 请求示例

  1. 坐标定位方式
curl -v -X POST -F file=@test.pdf -F locations="[{\"pageNo\":1,\"x\":100,\"y\":400},{\"pageNo\":2,\"x\":300,\"y\":200}];type=application/json" "https://api.sjtu.edu.cn/v1/signature/TEST?access_token=token"

POST /v1/signature/TEST?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2
3
4
  1. 关键字定位方式
curl -v -X POST -F file=@test.pdf -F keyword="上海交通大学" "https://api.sjtu.edu.cn/v1/signature/TEST?access_token=token"

POST /v1/signature/TEST?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2
3
4

← API SDK →