签署流程创建

更新时间:2021/09/10 09:24:04

接口描述

创建签署流程

注意:

(1)一个签署流程目前最多只支持添加300个签署区

(2)因Windows操作系统中文件名称不支持个别特殊字符,现调整businessScene字段不支持以下9个字符

/ \ : * " < > | ?以及所有emoji表情,详见文件名称特殊字符限制

点击查看具体更新日志


接口

 /v1/signflows

请求方式

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


请求参数

参数名称

类型

必选

类型

参数说明

示例值

autoArchive

boolean

body

是否自动归档,默认false;

如设置为true,则在调用签署流程开启后,当所有签署人签署完毕,系统自动将流程归档,状态变为“已完成”状态

如设置为false,则在调用流程开启后,需主动调用签署流程归档接口,将流程状态变更为“已完成”;已完成的流程才可下载签署后的文件


businessScene

string

body

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

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


configInfo

object

body

任务配置信息







noticeDeveloperUrl

string

body

回调通知地址


noticeType

string

body

通知方式,逗号分割,1-短信,2-邮件 。默认值1,请务必请选择一个通知方式,否则客户将接收不到流程的签署通知和审批通知,如果流程需要审批,将导致审批无法完成;如果客户需要不通知,可以设置noticeType=""

注:短信或者邮件获取到的签署链接,有效期默认30天


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不传的情况下,该字段无需传入,默认签署完成结果页不跳转


contractValidity

int64

body

文件有效截止日期,毫秒,默认不失效;若时间到了该参数设置的时间,则会触发【流程文件过期通知


contractRemind

int32

body

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

若时间到了该参数设置的时间,则会触发【流程文件过期前通知


signValidity

int64

body

签署有效截止日期,毫秒,默认不失效;

注:超过签署有效截止时间,则无法继续签署。
若时间到了该参数设置的时间,则会触发【流程结束回调通知


initiatorAccountId

string

body

发起人账户id,即发起本次签署的操作人个人账号id;如不传,默认由对接平台发起


initiatorAuthorizedAccountId

string

body

发起方主体id,如存在个人代机构发起签约,则需传入机构id;如不传,则默认是对接平台


公共响应参数

参数名称

类型

必选

参数说明

示例值

code

int

业务码,0表示成功


message

string

信息


data

object

业务信息


响应参数

参数名称

类型

必选

参数说明

示例值

flowId

string

流程id


请求示例  

POST https://openapi.esign.cn/v1/signflows


{
    "autoArchive":false,
    "businessScene":"合同名称",
    "configInfo":{
        "noticeDeveloperUrl":"http://127.0.0.1:9110/notice",
        "noticeType":"1,2",
        "redirectUrl":"http://127.0.0.1:8110/h5/forword",
        "signPlatform":"1",
        "willTypes":["FACE_ZHIMA_XY"],
        "personAvailableAuthTypes":["PSN_FACEAUTH_BYURL"],
        "batchDropSeal":true,
        "orgAvailableAuthTypes":["ORG_BANK_TRANSFER"],
        "personAuthAdvancedEnabled":["PSN_BANK4_AUTHCODE"],
        "countdown":5
    },
    "contractRemind":360,
    "contractValidity":1592386042000,
    "signValidity":1592386042000,
    "initiatorAccountId":"40eb61714d9e49088bac7a3c56d69d66",
    "initiatorAuthorizedAccountId":"40eb61714d9e49088bac7a3c56d69d66"
}

响应示例

{
    "code":0,
    "message":"成功",
    "data":{
        "flowId":"429b1d3038854cabbcdac0a63d7e4c0d"
    }
}

错误码

错误码

错误描述

解决方案

401


1.token过期了

2.header请求头不正确

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