契约锁电子签章接口调用示例
通过调用契约锁开放平台电子签章接口，可以实现电子文件的创建、发起及签署。下面通过介绍文件的关键组成元素和示例，帮助深入理解电子签章过程。
名词解释
1 文件
文件是契约锁电子签章的基本单位，下图展示了文件的关键组成元素。
1.1 文件文档
简介：文件文档是文件的必要组成部分，在发起文件前必须指定。
生成方式：
（1）自动生成：在业务分类中配置文件模板，调用接口“创建文件草稿”时，会自动把模板转换为文件文档；
（2）主动添加：在“创建文件草稿”后、“发起文件”前，调用接口“添加文件文档”生成文件文档；
1.2 签署方
简介：签署文件的主体。按签署方属性分为公司和个人两种类型；按是否为发起方分为发起方和接收方两种类型。
生成方式：
调用接口“创建文件草稿”时传入签署方信息，生成签署方。
1.2.1 经办人
简介：签署方的联系人。文件签署流程流转到签署方时，契约锁发送消息给经办人，经办人通知实际签署人签署文件。
（1）对于个人签署方，经办人即为签署方本人。
（2）对于公司签署方，发起方无需指定经办人（经办人即为文件发起人）；接收方必须指定经办人，用于接收签署消息。
生成方式：
调用接口“创建文件草稿”时传入经办人信息。
1.2.2 签署动作
简介：签署方需要对文件进行的操作。别名有 签署流程、签署要求、签署节点。
类型：签署公章、签署法人章、经办人签署、审批、个人签名。其中“个人签名”属于个人签署方，其他四个类型属于公司签署方。
生成方式：
（1）自动生成：在业务分类中“预设签署方”（发起方需要“预设内部流程”），调用接口“创建文件草稿”时，会匹配对应的签署动作（包括其下的印章、操作人、签署位置），自动生成。
（2）主动添加：在业务分类中“不预设签署方”（发起方“不预设内部流程”），调用接口“创建文件草稿”时，传入签署动作（包括操作人、印章和签署位置等），主动生成。
1.2.2.1 操作人
简介：签署动作的执行人。只有“签署公章”、“审批”这两种签署动作可以设置操作人。所有签署动作均可登录契约锁平台执行。
以下针对不同类型签署动作，对操作人介绍：
（1）签署公章：如果指定操作人，则只有操作人可以签署文件。如果未指定操作人、指定了公章，则操作人是有公章权限的人。如果未指定操作人、未指定公章，则操作人是公章管理员。发起方可以通过接口签署公章。
（2）签署法人章：操作人是法人和有法人章使用权限的人。发起方可以通过接口签署法人章。
（3）经办人签署：操作人是经办人。
（4）审批：需要指定操作人。只有发起方可以指定此类型。发起方可以通过接口审批。
（5）个人签名：操作人是签署方本人。
1.2.2.2 印章、签署位置
简介：操作人在签署文件时的两个必需元素。印章用于指定签署外观，签署位置用于定位签署的坐标。
（下面所说的个人签名、法人章、公章均指印章）
印章：
（1）公章：如果创建文件时指定了公章，签署时只能使用此公章，如果未指定，则操作人签署时可以签所有有权限的公章。
（2）个人签名：不能指定个人签名。
（3）法人章：不能指定法人章。法人章最多只有一个。
签署位置：
（1）如果签署文件前已指定签署位置，签署时默认使用指定的签署位置；如果未指定，用户自由拖动选择签署位置。
（2）发起方通过接口签署，如果指定签署位置，默认使用指定的签署位置；如果未指定，必须传签署位置参数。
API接入示例
1 示例
签署方类型、数量不固定，无统一格式的文件文件的场景。
1.1 流程概览
该流程模拟发起一份人事文件，并完成签署。通过以下几个方面介绍该模式的实现过程：
（1）签署流程说明；
（2）实现示例；
1.2 流程说明
1.2.1 创建文件草稿
调用接口”创建文件草稿“，完成文件草稿的创建，该接口需要指定如下参数：
文件主题名称（subject）；
文件签署方（signatories）：参与文件签署的签署方、签署流程（actions）等信息，其中，签署流程中需要指定签署所用到的印章（sealId）。
是否发起文件（send），设置为不发起；
http示例：
POST /v2/contract/draft HTTP/1.1
Host: [host]
x-qys-open-timestamp: [替换为请求头生成的Timestamp]
x-qys-open-signature: [替换为请求头生成的Signature]
x-qys-open-accesstoken: [替换为请求头生成的Token]
Content-Type: application/json
{
"sn": "123321",
"subject": "V2文件",
"description": "文件描述",
"expireTime": "2019-08-25 00:00:00",
"ordinal": true,
"send": false,
"category": {
"name": "V2"
},
"creator": {
"contact": "18435186216",
"contactType": "MOBILE"
},
"signatories": [
{
"tenantType": "COMPANY",
"tenantName": "思晨教育",
"receiver": {
"contact": "10100000000",
"contactType": "MOBILE"
},
"serialNo": 1,
"actions": [
{
"type": "COMPANY",
"name": "公章签署动作",
"serialNo": 1,
"operators": [
{
"contact": "10100000000",
"contactType": "MOBILE"
}
]
},
{
"type": "AUDIT",
"name": "审批动作",
"serialNo": 3,
"operators": [
{
"contact": "10100000000",
"contactType": "MOBILE"
}
]
},
{
"type": "LP",
"name": "法人签署动作",
"serialNo": 4
}
]
},
{
"tenantType": "PERSONAL",
"tenantName": "吉哲",
"receiver": {
"contact": "10100000000",
"contactType": "MOBILE"
},
"serialNo": 2
}
]
}
1.2.2 添加文件文档
文件草稿创建成功之后，需要为文件添加待签署的文档，契约锁提供两种方式进行文件文档的上传：
调用 “用文件添加文件文档”接口，上传文件作为文件文档，并绑定文件；
调用 “用模板添加文件文档”接口，用模板转换为文件文档，并绑定文件；
“用模板添加文件文档”http示例
POST /v2/document/addbytemplate HTTP/1.1
Host: [host]
x-qys-open-timestamp: [替换为请求头生成的Timestamp]
x-qys-open-signature: [替换为请求头生成的Signature]
x-qys-open-accesstoken: [替换为请求头生成的Token]
Content-Type: application/json
{
"contractId": "2593815518218461185",
"bizId": null,
"title": "V2添加模板文档",
"templateId": "2560778409594396776",
"templateParams": [
{
"name": "乙方姓名",
"value": "张三"
}
]
}
1.2.3 指定签署位置并发起文件
完成文件文档添加之后，调用”发起文件“接口即可完成文件的发起，此处需要传递的参数有：
文件ID（contractId）;
签署位置（stampers）：若指定公司签署方的签署位置，需要传入签署动作ID（actionId）与之关联，若指定个人签署方的签署位置，需要传递签署方ID（signatoryId）与之关联。
发起文件
http示例：
POST /v2/contract/send HTTP/1.1
Host: [host]
x-qys-open-timestamp: [替换为请求头生成的Timestamp]
x-qys-open-signature: [替换为请求头生成的Signature]
x-qys-open-accesstoken: [替换为请求头生成的Token]
Content-Type: application/json
{
"contractId": "2591540368898105360",
"bizId": null,
"stampers": [{
"actionId": "2591541618892972178",
"type": "COMPANY",
"documentId": "2591542337725374704",
"sealId": "2566229349702860958",
"offsetX": "0.1",
"offsetY": "-0.1",
"keyword": "劳动",
"keywordIndex": "2"
}, {
"actionId": "2591541618892972178",
"type": "COMPANY",
"documentId": "2591542337725374704",
"sealId": "2566229349702860958",
"offsetX": "0.5",
"offsetY": "0.5",
"page": "1"
}, {
"signatoryId": "2591541619077521559",
"type": "PERSONAL",
"documentId": "2591542337725374704",
"offsetX": 0.9,
"offsetY": 0.9,
"page": 1
}]
}
1.2.4 对接方签署
1.2.4.1 签署公章
调用接口“签署公章”，完成公章签署节点，以下是需要指定的参数：
http为例：
文件ID（contractId）。
POST /v2/contract/companysign HTTP/1.1
Host: [host]
x-qys-open-timestamp: [替换为请求头生成的TimeStamp]
x-qys-open-signature: [替换为请求头生成的Signature]
x-qys-open-accesstoken: [替换为请求头生成的Token]
Content-Type: application/json
{
"contractId": "2591540368898105360",
"bizId": null,
"stampers": [
{
"type": "COMPANY",
"documentId": "2591542337725374704",
"sealId": "2566229349702860958",
"offsetX": "0.2",
"offsetY": "-0.2",
"keyword": "劳动",
"keywordIndex": "2"
},
{
"type": "TIMESTAMP",
"documentId": "2591542337725374704",
"sealId": "2566229349702860958",
"offsetX": "0.5",
"offsetY": "0.5",
"page": "1"
},
{
"type": "ACROSS_PAGE",
"documentId": "2591542337725374704",
"sealId": "2566229349702860958",
"offsetY": "0.5"
}
]
}
1.2.5 接收方签署
在对接方签署完成后，文件流转到个人接收方。个人接收方可通过以下三种方式进行签署：
登录契约锁签署
文件流转到接收方时，契约锁会给接收方发送消息，通知接收方签署文件。接收方可以登录契约锁完成文件签署（契约锁签署支持：PC端网页、移动端网页、契约锁APP等多种签署方式）。
内嵌页面签署
对接方调用“签署页面”接口，获取签署文件链接，用户打开链接即可查看、签署文件。页面支持跨哉，可以嵌入对接方的网站或APP中。
若对接方不希望用户接收短信通知，可以在“业务分类配置 -> 短信设置”中，关闭消息提醒。
JS-SDK方式签署
若对接方希望客户在其页面上完成签署操作，但无法内嵌页面，即可采用该方案，该方案需要部署JS-SDK以及请求转发接口。 若对接方不希望用户接收短信通知，可以在“业务分类配置 -> 短信设置”中，关闭消息提醒。