一步发起签署

更新时间:2021/10/14 19:37:37

接口描述

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

开发者在发起一步签署之前,需要确认:

1、该文件是否需要签署。如果添加的文件只是给签署人阅读,不做签署,建议将该文件以附件的形式进行添加,通过字段attachments传入附件信息;

2、通过字段docs添加的签署文件,将按照正常计费模式扣除合同份额。

3、因Windows操作系统中文件名称不支持个别特殊字符,现调整businessScene、attachmentName、fileName字段不支持以下9个字符/ \ : * " < > | ?以及所有emoji表情,详见文件名称特殊字符限制

4、单个签署流程所添加的待签署文件大小总和不要超过500M,单个文件的大小不要超过20M,单个文件的单页大小不要超过9M,单个签署流程所添加的签署区不要超过300个详见文件大小规则说明

点击查看具体更新日志


API在线调试

可通过API在线调试工具使用接口功能,入口:一步发起签署


接口

/api/v2/signflows/createFlowOneStep

请求方式

POST

请求头

提供两种安全接入方式,开发者可选择其中一种方式进行对接,对应参数如何获取,参考文档【请点击】。

方式一:请求签名鉴权(优先推荐)

请求头入参示例如下:

参数名称

类型

必选

参数说明

示例值

X-Tsign-Open-App-Id

string

项目ID


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

流程基本信息


autoArchive

boolean

body

是否自动归档,默认false。

autoInitiate

boolean

body

是否自动开启,默认false。

businessScene

string

body

本次签署流程的文件主题名称

注:名称不支持以下9个字符:/ \ : * " < > | ?

contractRemind

int32

body

文件到期前,提前多少小时回调提醒续签,小时(时间区间:1小时——15天),默认不提醒

contractValidity

int64

body

文件有效截止日期,毫秒,默认不失效

flowConfigInfo

object

body

任务配置信息


noticeDeveloperUrl

string

body

通知开发者地址。

(e签宝服务器主动通过POST方式通知开发者指定服务器的页面路径(http/https))

通知说明见【通知回调】模块

noticeType

string

body

通知方式,可选择多种通知方式,逗号分割,1-短信,2-邮件。 默认1

注:短信或者邮件获取到的签署链接,有效期默认30天;如果客户需要不通知,可以设置noticeType=""

redirectUrl

string

body

签署完成重定向地址

signPlatform

string

body

签署平台,可选择多种签署平台,逗号分割,1-开放服务h5,2-支付宝签 ,默认值1,2

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组织机构法定代表人授权书签署认证

willTypes

list

body

页面指定意愿认证方式,可指定类型如下:

CODE_SMS 短信验证码

FACE_ZHIMA_XY 支付宝刷脸FACE_TECENT_CLOUD_H5 腾讯云刷脸FACE_FACE_LIVENESS_RECOGNITION e签宝刷脸

FACE_WE_CHAT_FACE 微信小程序刷脸

FACE_AUDIO_VIDEO_DUAL 智能视频认证

faceVideoTemplate

string

body

视频认证模板id,请联系交付提供


batchDropSeal

boolean

body

一键落章是否默认勾选

否-false

是-true

countdown

int32

body

签署页提交倒计时单位为秒,不传默认为0,最大999

redirectDelayTime

int

body

签署完成重定向跳转延迟时间,默认3。

0-不展示签署完成结果页,签署完成直接跳转重定向地址

3-展示签署完成结果页,倒计时3秒后,自动跳转重定向地址

注:当redirectUrl不传的情况下,该字段无需传入,默认签署完成结果页不跳转

initiatorAccountId

string

body

发起方账户id

initiatorAuthorizedAccountId

string

body

发起方主体id

signValidity

int64

body

签署有效截止时间,毫秒,默认不失效

注:超过签署有效截止时间,则无法继续签署。

signers

array

body

签署方信息

*类型为数组,多方签署建议添加多个对象

注:签署方字段设置规则【请点击


platformSign

boolean

body

是否平台自动签署,默认false

false-为对接平台的用户签署

true-平台方自动签署

signOrder

int32

body

签署方签署顺序,默认1,且不小于1,顺序越小越先处理

signerAccount

object

body

签署方账号信息(平台方自动签署时,无需传入该参数)

signerAccountId

string

body

签署操作人个人账号标识,即操作本次签署的个人

注:平台用户自动签署时,该参数需要传入签署主体账号id

authorizedAccountId

string

body

签约主体账号标识,即本次签署对应任务的归属方,默认是签署操作人个人

注:平台用户自动签署时,无需传入该参数

noticeType

string

body

通知方式,可选择多种通知方式,逗号分割,1-短信,2-邮件

注意:可以通过此字段控制单个签署方的通知方式,不同的签署方可以设置不同的通知方式

willTypes

array

body

指定该签署人的意愿认证方式

*若flowConfigInfo下也传入willTypes,以

signerAccount下该参数优先

类型如下:

CODE_SMS 短信验证码

FACE_ZHIMA_XY 支付宝刷脸FACE_TECENT_CLOUD_H5 腾讯云刷脸FACE_FACE_LIVENESS_RECOGNITION

e签宝刷脸

FACE_WE_CHAT_FACE 微信小程序刷脸

FACE_AUDIO_VIDEO_DUAL 智能视频认证

signfields

array

body

签署文件信息


assignedPosbean

boolean

body

表示签署过程中,是否固定指定的签署区位置,默认为true。

true-固定签署区位置且无法移动,

false-不固定签署区位置且签署时可自由移动

注:当signType为1或者2时,该字段才会生效

autoExecute

boolean

body

是否自动执行,默认false(如果自动签署,必须设置为true)

actorIndentityType

int32

body

机构签约类别,当签约主体为机构时必传:

2-机构盖章

注:

1、签署主体是个人时,无需传入该参数,传入会导致无法正常签署

2、签署主体是企业时,该字段必传,传入2

fileId

string

body

文件fileId

sealId

string

body

印章id

需要注意的是:如果开通了实名签,企业手动签署这种场景不支持指定印章,个人签署场景是支持的

sealType

string

body

签署方式,个人签署时支持多种签署方式,0-手绘签名  ,1-模板印章签名,多种类型时逗号分割,为空不限制

signType

int32

body

签署类型,0-不限,1-单页签署,2-骑缝签署,默认1

posBean

object

body

签署区位置信息 。

signType为0时,本参数无效; signType为1时, 页码和XY坐标不能为空,;

signType为2时, 页码和Y坐标不能为空


posPage

string

body

页码信息,当签署区signType为2时, 页码可以'-'分割指定页码范围, 其他情况只能是数字

posX

float

body

x坐标,坐标为印章中心点

注:印章图片尺寸和坐标计算方式【请点击

开放平台拖章定位工具:【请点击

根据关键字辅助定位接口【请点击

posY

float

body

y坐标,坐标为印章中心点

width

int32

body

签署区宽度(默认印章的宽度)

signDateBeanType

int 32

body

是否需要添加签署日期,0-禁止 1-必须 2-不限制,默认0

signDateBean

object

body

签署日期信息


fontSize

int32

body

签章日期字体大小

format

string

body

签章日期格式,支持的格式:

yyyyMMdd

yyyy-MM-dd

yyyy/MM/dd

posPage

int32

body

页码信息

注:autoExecute是否自动执行为true时,并且需要展示签署日期,则需要指定日期盖章页码 ,默认当前页

posX

float

body

x坐标 ,坐标点为日期左下角

注:autoExecute是否自动执行为true时,并且需要展示签署日期,则需要指定日期盖章位置 ,默认为0

posY

float

body

y坐标 ,坐标点为日期左下角

注:autoExecute是否自动执行为true时,并且需要展示签署日期,则需要指定日期盖章位置 ,默认为0

thirdOrderNo

string

body

第三方流水号

docs

array

body

待签署文件信息

fileId

string

body

待签署文件id

fileName

string


body

待签署文件名称(必须带上文件扩展名,不然会导致后续发起流程校验过不去 示例:合同.pdf );

注意:

(1)该字段的文件后缀名称和真实的文件后缀需要一致。比如上传的文件类型是word文件,那该参数需要传“xxx.docx”,不能是“xxx.pdf”

(2)文件名称不支持以下9个字符:/ \ : * " < > | ?

encryption

int32

body

是否加密,0-不加密,1-加密,默认0注意:只支持编辑加密的PDF文件,且签署区设置的时候只有平台自动签署和签署方自动签署场景支持对加密文件盖章,手动签署区不支持


filePassword

string

body

文件密码, 如果encryption值为1, 文件密码不能为空,默认没有密码

attachments

array

body

附件信息(仅用于查看,不需要签署的文档)


fileId

string

body

附件Id

attachmentName

string

body

附件名称

注:文件名称不支持以下9个字符:

/ \ : * " < > | ?

copiers

array

body

抄送人列表

注:

抄送人指不参与签署但需要查看签署文件的人,

签署流程归档后抄送人收到通知。


copierAccountId

string

body

抄送人accountId

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":"ef08e9016806421e94f831a9d7012cb4"
        }
    ],
  "docs": [
    {

      "fileId": "ef08e9016806421e94f831a9d7012cb4",
      "fileName": "个人借贷合同.pdf"

    }
  ],
  "copiers": [
    {
      "copierAccountId": "93659d99bdbf4ca4a019c61cab3e4eab",
      "copierIdentityAccountId": "93659d99bdbf4ca4a019c61cab3e4eab",
      "copierIdentityAccountType": 0
    }
  ],  
  "flowInfo": {
    "autoArchive": true,
    "autoInitiate": true,
    "businessScene": "创建签署流程样例",
    "contractRemind": 1,
    "contractValidity": 1601049600000,
    "flowConfigInfo": {
      "noticeDeveloperUrl": "http://101.37.27.38:1110/notice/signature",
      "noticeType": "1,2,3",
      "redirectUrl": "",
      "signPlatform": "1,2",
      "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": "ef08e9016806421e94f831a9d7012cb4",
          "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": "bd465171b2a84434ad80bf416957c9aa"
    }
}

错误码

错误码

错误描述

解决方案

1437511

文档不存在,fileId:XXX

签署区里的fileId为空或fileId无效

1437306

XXXX:签署页码超出文档页数

签署区的页码大于文档页数

401


1.token过期了

2.header请求头不正确

3.apiurl和应用ID环境不对应,例如apiurl是模拟环境,应用ID是正式环境的