上海交通大学开发者平台

# 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，表示每个数据项表示签章在指定页面上的放置位置，需要指定签章位置时传入此参数
qrCodeLocations [] N 验证二维码坐标，json数组，CONTENT TYPE 为application/json，表示每个数据项表示验证二维码在指定页面上的放置位置，需要在指定位置显示验证二维码时传入此参数

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

# 响应参数

响应为文件二进制流。

# 请求示例

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

← API SDK →