接口描述
聚合创建流程接口,一步添加待签文件、相关附件、流程基本信息、签署方。支持签署流程自动开启和结束。
【提示】
1、该文件是否需要签署。如果添加的文件只是给签署人阅读,不做签署,建议将该文件以附件的形式进行添加,通过字段attachments
传入附件信息;
2、通过字段docs
添加的签署文件,将按照正常计费模式扣除合同份额。
3、因Windows操作系统中文件名称不支持个别特殊字符,现调整businessScene、attachmentName、fileName字段不支持以下9个字符/ \ : * " < > | ?以及所有emoji表情,详见文件名称特殊字符限制
4、单个签署流程所添加的待签署文件大小总和不要超过500M,待签署文件个数不超过50个,单个文件的大小不要超过20M,单个文件的单页大小不要超过9M,单个签署流程所添加的签署区不要超过300个,详见文件大小规则说明
点击查看具体更新日志
5、签署过程中除了印章使用员和印章审批员之外的企业用户,在使用企业印章时,都会触发用印审批。
API在线调试
可通过API在线调试工具使用接口功能,入口:一步发起签署
接口
/api/v2/signflows/createFlowOneStep
请求方式
POST
请求头
提供两种安全接入方式,开发者可选择其中一种方式进行对接,对应参数如何获取,参考文档【请点击】。
方式一:请求签名鉴权(优先推荐)
请求头入参示例如下:
参数名称 | 类型 | 必选 | 参数说明 |
X-Tsign-Open-App-Id | string | 是 | 应用AppId |
Content-Type | string | 是 | application/json;charset=UTF-8 |
X-Tsign-Open-Ca-Timestamp | string | 是 | API 调用者传递时间戳,值为当前时间的毫秒数,也就是从1970年1月1日起至今的时间转换为毫秒,时间戳有效时间为15分钟,为了防重放攻击 |
Accept | string | 是 | 建议统一填写 */* |
X-Tsign-Open-Ca-Signature | string | 是 | 签名字符串 |
Content-MD5 | string | 是 | 当请求 Body 非 Form 表单时,可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。建议当请求 Body 非 Form 表单时,加上此请求头。 |
X-Tsign-Open-Auth-Mode | string | 是 | 选择请求方式进行鉴权,固定值,Signature |
方式二:OAuth2.0鉴权(不推荐使用)
当安全接入选择OAuth2.0鉴权方式,请点击查阅详情,请求头入参示例如下:
参数名称 | 类型 | 必选 | 参数说明 |
X-Tsign-Open-App-Id | string | 是 | 应用ID |
X-Tsign-Open-Token | string | 是 | 通过获取鉴权Token接口返回 |
Content-Type | string | 是 | application/json; charset=UTF-8 |
请求参数
展开全部参数参数名称 | 类型 | 必选 | 参数 类型 | 参数说明 | |||
flowInfo | object | 是 | body | 本次签署流程的基本信息 | |||
businessScene | string | 是 | body | 本次签署流程的文件主题名称 注:不可含有以下9个特殊字符:/ \ : * " < > | ?以及所有emoji表情 | |||
autoArchive | boolean | 否 | body | 全部签章后流程自动结束,默认false。 true - 自动结束,false - 非自动结束 false时需要开发者调用【签署流程结束】接口结束流程 | |||
autoInitiate | boolean | 否 | body | 是否自动开启,默认false。 | |||
signValidity | int64 | 否 | body | 本次签署流程的截止时间。时间戳格式,单位:毫秒,默认永久有效。 注:超过签署有效截止时间,则无法继续签署。 | |||
contractValidity | int64 | 否 | body | 本次签署文件的到期时间。时间戳格式,单位:毫秒,默认永久有效。 注:只有设置了contractValidity,才能设置续签提醒时间contractRemind。 | |||
contractRemind | int32 | 否 | body | 本次签署的续签提醒时间。单位:小时,默认不提前提醒。 注:时间区间[1-360],可通过异步通知方式触发续签通知 | |||
initiatorAccountId | string | 否 | body | 发起人账户id,发起本次签署的操作人个人账号id;如不传,默认由对接平台发起 | |||
initiatorAuthorizedAccountId | string | 否 | body | 发起方主体id,如存在个人代机构发起签约,则需传入机构id;如不传,则默认是对接平台 | |||
flowConfigInfo | object | 否 | body | 本次签署流程的任务信息配置 | |||
noticeDeveloperUrl | string | 否 | body | 通知开发者地址。 (e签宝服务器主动通过POST方式通知开发者指定服务器的页面路径(http/https))通知说明见【通知回调】模块 | |||
noticeType | string | 否 | body | 签署通知方式, 默认方式:1。同时支持多种通知方式,用逗号分割。 1-短信,2-邮件。 (如果套餐内带“分项”字样,请确保开通【电子签名流量费(分项)认证】中的子项:【短信服务】,否则短信通知收不到) 注:短信或者邮件获取到的签署链接,有效期默认30天;如果客户需要不通知,可以设置noticeType="",详细规则【请点击】 | |||
examineNotice | boolean | 否 | body | 通知给企业印章用印审批人员的通知类型,按照账号中的手机号或邮箱的填写情况进行通知。 不传值默认取noticeType配置的通知方式 (如果套餐内带“分项”字样,请确保开通【电子签名流量费(分项)认证】中的子项:【短信服务】,否则短信通知收不到) | |||
redirectUrl | string | 否 | body | 签署完成后,重定向跳转地址(http/https) | |||
signPlatform | string | 否 | body | 签署平台,默认值1,2。 可选择多种签署平台,逗号分割。 1-H5网页版方式进行签署; 2-跳转支付宝(移动端)或支付宝扫码进行签署(PC端)。 | |||
personAvailableAuthTypes | list | 否 | body | 个人页面显示实名认证方式 PSN_BANK4_AUTHCODE - 个人银行卡四要素认证 PSN_TELECOM_AUTHCODE -个人运营商三要素认证 PSN_FACEAUTH_BYURL -个人刷脸认证 | |||
personAuthAdvancedEnabled | list | 否 | body | 指定通过银行卡认证或运营商认证方式时,是否使用详情版,如指定则核验失败可返回具体不匹配信息,传空默认为普通版。 PSN_BANK4_AUTHCODE-个人银行卡四要素认证 PSN_TELECOM_AUTHCODE -个人运营商三要素认证 注:详情版,需要单独购买,具体购买方式请咨询e签宝工作人员; 普通版,信息比对核验失败,不会返回具体的不匹配信息 | |||
orgAvailableAuthTypes | list | 否 | body | 企业页面显示实名认证方式 ORG_BANK_TRANSFER 组织机构对公账户打款认证 ORG_ZM_AUTHORIZE 企业芝麻认证 ORG_LEGAL_AUTHORIZE 组织机构法定代表人授权书签署认证 LEGAL_REP_AUTH 法定代表人认证 注: (1)法定代表人本人认证的方式默认都是在页面存在的,无法去掉 (2)当只希望用户选择【法定代表人认证】一种方式时,此参数仅传入 LEGAL_REP_AUTH 即可 | |||
willTypes | list | 否 | body | 页面指定意愿认证方式,可指定类型如 CODE_SMS 短信验证码 FACE_ZHIMA_XY 支付宝刷脸 FACE_TECENT_CLOUD_H5 腾讯云刷脸 SIGN_PWD 签署密码 以下四种方式请联系交付顾问开通后使用: FACE_FACE_LIVENESS_RECOGNITION 快捷刷脸 FACE_WE_CHAT_FACE 微信小程序刷脸 FACE_AUDIO_VIDEO_DUAL 支付宝智能视频认证 VIDEO_WE_CHAT_VIDEO_DUAL 微信智能视频认证 | |||
faceVideoTemplate | string | 否 | body | 视频认证模板id,请联系交付顾问提供 | |||
batchDropSeal | boolean | 否 | body | 签署页是否显示“一键落章”按钮,默认显示。 关闭显示 - false 显示 - true | |||
countdown | int32 | 否 | body | 签署页提交倒计时,单位为秒, 不传默认为0,最大999 | |||
redirectDelayTime | int | 否 | body | 签署完成重定向跳转延迟时间,默认3。 0-不展示签署完成结果页,签署完成直接跳转重定向地址 3-展示签署完成结果页,倒计时3秒后,自动跳转重定向地址 注:当redirectUrl不传的情况下,该字段无需传入,默认签署完成结果页不跳转 | |||
mobileShieldWay | string | 否 | body | 是否使用e签盾签署,默认为1. 1-不使用e签盾,2-使用e签盾 注:使用e签盾签署后,签署平台默认提示跳转e签宝app进行签署更新日志:点此了解 | |||
signers | array | 是 | body | 签署方信息 多方签署建议添加多个对象 注:签署方中具体字段,设置规则【请点击】 | |||
platformSign | boolean | 否 | body | 是否平台方自动签署,默认false true -平台方自动签署 false -平台用户签署 | |||
signOrder | int32 | 否 | body | 签署顺序,默认1,且不小于1。顺序越小越先处理 | |||
signerAccount | object | 否 | body | 签署方账号信息(平台方自动签署时,无需传入该参数) | |||
signerAccountId | string | 否 | body | 签署操作人个人账号标识,即操作本次签署的个人 注:个人/企业用户手动签署时,需传入签署的个人/经办人的签署账号ID(【创建个人签署账号】接口获取) | |||
authorizedAccountId | string | 否 | body | 签约主体账号标识,即本次签署对应任务的归属方,默认是签署操作人个人 注:企业用户手动签署时,需传入签署的机构的签署账号ID(【创建机构签署账号】接口获取) | |||
noticeType | string | 否 | body | 通知方式,可选择多种通知方式,逗号分割,默认值为1 1-短信,2-邮件,""不通知(传空字符串) (如果套餐内带“分项”字样,请确保开通【电子签名流量费(分项)认证】中的子项:【短信服务】,否则短信通知收不到) 注:可以通过此字段控制单个签署方的通知方式,不同的签署方可以设置不同的通知方式 | |||
willTypes | array | 否 | body | 指定该签署人的意愿认证方式 若flowConfigInfo下也传入willTypes,以signerAccount下该参数优先 类型如下: CODE_SMS 短信验证码 FACE_ZHIMA_XY 支付宝刷脸 FACE_TECENT_CLOUD_H5 腾讯云刷脸 以下四种方式请联系交付顾问开通后使用: FACE_FACE_LIVENESS_RECOGNITION 快捷刷脸 FACE_WE_CHAT_FACE 微信小程序刷脸 FACE_AUDIO_VIDEO_DUAL 支付宝智能视频认证 VIDEO_WE_CHAT_VIDEO_DUAL 微信智能视频认证 | |||
signfields | array | 是 | body | 签署方的签署区列表数据 | |||
assignedPosbean | boolean | 否 | body | 表示签署过程中,是否固定指定的签署区位置,默认为true。 true-固定签署区位置且无法移动, false-不固定签署区位置且签署时可自由移动 注:当signType为1或者2时,该字段才会生效 | |||
autoExecute | boolean | 否 | body | 是否自动执行签署,默认false true-自动签署, false-手动签署。 注: 1、平台方自动签署时,该字段必传,传入true; 2、SaaS API标准版产品,平台用户不支持自动签署 | |||
actorIndentityType | int32 | 否 | body | 企业主体签约类型:0-个人盖章,2-机构盖章; 默认是0 注: 1、签署主体是个人时,无需传入该参数,或者传0 2、签署主体是企业时,该字段必传,传入2 | |||
fileId | string | 是 | body | 文件fileId | |||
sealIds | list | 否 | body | 印章ids,用于手动签署时,指定企业印章进行展示,实现手动选择印章进行签署 1、只支持签约主体为企业时指定印章,通过e签宝官网获取对应实名主体下的印章编号。 2、支持传入多个印章id,入参格式:sealIds:["印章id1","印章id2",....] | |||
sealId | string | 否 | body | 印章ID,通过e签宝官网获取对应实名主体下的印章编号。 注: (1) 当印章ID为空时,取appId对应企业的默认印章; (2) 平台方自动盖章签署时,仅限传入企业章,不支持指定企业法定代表人印章; (3) 平台方自动盖章签署时,如果指定企业授权印章,签署后的签名信息,印章样式和数字证书均为授权企业主体所有,详细参考【印章授权说明】 | |||
sealBizTypes | string | 否 | body | 指定业务印章类型(仅支持签约主体为企业时指定, 允许指定多个印章类型,英文逗号分隔) ALL -不指定印章类型, COMMON -无业务类型(其他), CONTRACT -合同专用章, FINANCE -财务章, PERSONNEL -人事专用章, PUBLIC -公章 | |||
sealType | string | 否 | body | 签署方式,个人签署时支持多种签署方式 0-手绘签名, 1-模板印章签名, 多种类型时逗号分割,为空不限制 | |||
handDrawnWay | string | 否 | body | 手绘签名方式 0-普通手绘签名 1-AI校验手绘签名 多种类型时逗号分割,为空只有普通手绘签名 | |||
signType | int32 | 否 | body | 签署类型,0-不限,1-单页签署,2-骑缝签署 默认1 | |||
posBean | object | 否 | body | 签署区位置信息 。 signType为0时,本参数无效; signType为1时, 页码和XY坐标不能为空; signType为2时, 页码和Y坐标不能为空 | |||
posPage | string | 否 | body | 页码信息, 当签署区signType为2时, 页码可以'-'分割指定页码范围, 传all代表全部页码。 其他情况只能是数字 | |||
posX | float | 否 | body | x坐标,坐标为印章中心点 注:印章图片尺寸和坐标计算方式【请点击】 开放平台拖章定位工具:【请点击】 根据关键字辅助定位接口【请点击】 | |||
posY | float | 否 | body | y坐标,坐标为印章中心点 | |||
width | int32 | 否 | body | 指定签署区的宽度,单位px像素。默认取印章大小(个人印章96px,企业印章159px)。 不建议设置为0,会造成页面看不到印章图片。 不需指定宽度时,可不传width参数。 | |||
signDateBeanType | int 32 | 否 | body | 是否需要添加签署日期, 0-禁止 1-必须 2-不限制,默认0 | |||
signDateBean | object | 否 | body | 签署日期信息 | |||
fontSize | int32 | 否 | body | 签章日期字体大小(默认值12px) | |||
format | string | 否 | body | 签章日期格式,支持的格式: yyyy年MM月dd日(默认值) yyyy-MM-dd yyyy/MM/dd yyyy-MM-dd HH:mm:ss | |||
posPage | int32 | 否 | body | 页码信息 注:autoExecute是否自动执行为true时,并且需要展示签署日期,则需要指定日期盖章页码 ,默认当前页 | |||
posX | float | 否 | body | x坐标 ,坐标原点为页面左下角 注: (1)autoExecute是否自动执行为true时, 且必须添加签署日期,若需指定日期位置,可传入x坐标值,不传x坐标值默认为0; (2)autoExecute是否自动执行为false时(页面手动签署),若需指定日期位置,posPage需与posX、posY三个参数同时传入,坐标值才会生效。 | |||
posY | float | 否 | body | y坐标 ,坐标原点为页面左下角 注: (1)autoExecute是否自动执行为true时, 且必须添加签署日期,若需指定日期位置,可传入y坐标值,不传y坐标值默认为0; (2)autoExecute是否自动执行为false时(页面手动签署),若需指定日期位置,posPage需与posX、posY三个参数同时传入,坐标值才会生效。 | |||
fieldType | int32 | 否 | body | 签署区类型,默认值为0 0 - 普通签署区,2 - 备注签署区 当用于添加备注自定义文字时请填写2,普通签章/签名时请填写0或不传此参数 | |||
remarkFieldConfig | object | 否 | body | 备注签署区专用参数 注:仅fieldType=2时传此参数,签章/签名无需传此参数 | |||
inputType | int32 | 是 | body | 备注文字输入方式 注:inputType=2时aiCheck和remarkContent参数值不生效 1 - 手写抄录输入 2 - 键盘自由输入 | |||
aiCheck | int32 | 否 | body | 是否开启 AI 手写抄录校验,注:inputType=1时此参数必须传值 0 - 不开启 1 - 开启 AI 校验 2 - 强制 AI 校验 | |||
remarkContent | string | 否 | body | 预设待抄录信息,注:inputType=1时此参数必须传值 最多支持50个汉字(含标点符号),支持传换行符 \n | |||
remarkFieldWidth | int32 | 是 | body | 备注签署区的宽度 | |||
remarkFieldHeight | int32 | 是 | body | 备注签署区的高度 | |||
remarkFontSize | int32 | 否 | body | 备注文字字号,默认值11 | |||
thirdOrderNo | string | 否 | body | 第三方流水号 | |||
docs | array | 是 | body | 待签署文件信息 | |||
fileId | string | 是 | body | 待签署文件id | |||
fileName | string | 否 | body | 文件名称 (签署界面展示的文件名称与下载时的文件名称) (1)名称不传扩展名时,例如传:xx,默认展示的文件名为 xx,下载时自动添加后缀 xx.pdf。 (2)文件扩展名仅限传pdf格式,例如传 xx.pdf,展示的文件名即为所传值 xx.pdf,下载文件也为xx.pdf。 (3)传入空值,取文件的原始名称,扩展名皆为.pdf。 (4)文件名称不可含有以下9个特殊字符:/ \ : * " < > | ?以及所有emoji表情 该参数控制下图所示位置 ![]() | |||
encryption | int32 | 否 | body | 文档是否设置编辑密码 0-未设置,1-已设置,默认值为0 注: (1)设置编辑密码的PDF文件需要输入密码才有权限进行盖章操作。 (2)encryption填写1时,同时需要向filePassword参数填写编辑密码。 (3)支持自动盖章场景。 (4)不支持手动盖章场景。 ![]() | |||
filePassword | string | 否 | body | 文档密码, 如果encryption值为1, 文档密码不能为空,默认没有密码 | |||
attachments | array | 否 | body | 附件信息(仅用于查看,不需要签署的文档) | |||
fileId | string | 是 | body | 附件Id | |||
attachmentName | string | 是 | body | 附件名称 注:不可含有以下9个特殊字符:/ \ : * " < > | ?以及所有emoji表情 | |||
copiers | array | 否 | body | 抄送人列表 注: 抄送人指不参与签署但需要查看签署文件的人 | |||
copierAccountId | string | 是 | body | 抄送人account id | |||
copierIdentityAccountType | int32 | 是 | body | 抄送主体类型, 0-个人, 1-企业 | |||
copierIdentityAccountId | string | 否 | body | 抄送主体账号id |
公共响应参数
参数名称 | 类型 | 必选 | 参数说明 |
code | int | 是 | 业务码,0表示成功 |
message | string | 否 | 信息 |
data | object | 否 | 业务信息 |
响应参数
参数名称 | 类型 | 必选 | 参数说明 |
flowId | string | 否 | 流程id |
请求示例
参数示例仅供参考,请根据实际情况传参
POST https://openapi.esign.cn/api/v2/signflows/createFlowOneStep
{
"attachments":[
{
"attachmentName":"1",
"fileId":"ef08e9016806421e94f831a9d701xxx"
}
],
"docs": [
{
"fileId": "ef08e9016806421e94f831a9d701xxx",
"fileName": "个人借贷合同.pdf"
}
],
"copiers": [
{
"copierAccountId": "93659d99bdbf4ca4a019c61cab3exxx",
"copierIdentityAccountId": "93659d99bdbf4ca4a019c61cab3exxx",
"copierIdentityAccountType": 0
}
],
"flowInfo": {
"autoArchive": true,
"autoInitiate": true,
"businessScene": "创建签署流程样例",
"contractRemind": 1,
"contractValidity": 1601049600000,
"flowConfigInfo": {
"noticeDeveloperUrl": "http://172.10.XX.XX:8080/notify/esign",
"noticeType": "1,2,3",
"redirectUrl": "https://www.xx.com",
"signPlatform": "1,2",
"mobileShieldWay":"1",
"redirectDelayTime":3,
"willTypes":["FACE_ZHIMA_XY"],
"personAvailableAuthTypes":["PSN_FACEAUTH_BYURL"],
"batchDropSeal":true,
"orgAvailableAuthTypes":["ORG_BANK_TRANSFER"],
"personAuthAdvancedEnabled":["PSN_BANK4_AUTHCODE"],
"countdown":5
},
"signValidity": 1601049600000
},
"signers": [
{
"platformSign": true,
"signOrder": 1,
"signfields": [
{
"autoExecute": true,
"actorIndentityType":2,
"fileId": "ef08e9016806421e94f831a9d701xxx",
"posBean": {
"posPage": "1",
"posX": 440,
"posY": 440
},
"sealType": "",
"signDateBean": {
"fontSize": 12,
"format": "yyyy年MM月dd日"
},
"signType": 1,
"width": 150
}
],
"thirdOrderNo": "111"
}
]
}
响应示例
{
"code": 0,
"message": "成功",
"data": {
"flowId": "bd465171b2a84434ad80bf416957xxx"
}
}
错误码
错误码 | 错误描述 | 解决方案 |
1437511 | 文档不存在,fileId:XXX | 签署区里的fileId为空或fileId无效 |
1437306 | XXXX:签署页码超出文档页数 | 签署区的页码大于文档页数 |