一步发起签署

接口描述

聚合创建流程接口，一步添加待签文件、相关附件、流程基本信息、签署方。支持签署流程自动开启和结束。

【提示】

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配置的通知方式 true - 发送消息（短信+邮件+e签宝官网站内信）（如果套餐内带“分项”字样，请确保开通【电子签名流量费（分项）认证】中的子项：【短信服务】，否则短信通知收不到） false - 不发送消息
	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 腾讯云刷脸以下四种方式请联系交付顾问开通后使用： 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:签署页码超出文档页数	签署区的页码大于文档页数