一步发起备注签署

更新时间:2023-08-24 16:35:17

接口描述

此接口支持同时添加普通签署区和指定备注签署区,让用户在签章过程中还可以添加备注文字信息。

典型应用场景

1. 医疗行业:病历单、处方单、告知书等签署时,需要填写一段文字用于表明患者(患者家属)已知晓所签内容及风险,如“我已经阅读并悉知”,然后签字提交签署。

2. 保险行业:签署保单时,需要投保人抄录风险提示语,确保消费者对保险保障、收益的知情权,防止销售误导投保人。如:“本人已阅读保险条款、产品说明书和投保提示书,了解本产品的特点和保单利益的不确定性”。

3. 物流行业:在物流清单上备注清点信息,如“应收XX箱货物,实收XX箱”。

<备注签署区>参数释义

通过接口参数 signfields 中的 fieldType 可控制是否需要在签署流程中添加备注签署区,fieldType参数值填写为固定值2时添加备注签署区。

备注签署区关键参数:

1. 待签署文件:fileId

2. 备注签署区选项:remarkFieldConfig参数控制备注签署区具体的信息,包括备注签署区尺寸、备注文字的输入方式、预设待抄录信息、是否开启 AI 手写抄录校验等。

【注意事项】

(1)关于参数限制

1. 备注签署区的签署类型(signType)仅限传 1-单页签署,不支持传入0-不限、2-骑缝章;

2. 备注签署区内不能盖印章,传入的印章id、sealType等相关配置将失效;

3. 备注签署区不支持自动签署,设置的自动签署 autoExecute 相关参数将失效;

(2)签署区配置参数

1. 指定了输入方式 inputType 为 2 - 键盘自由输入时,无法对输入的备注文字内容进行 AI 校验;

2. 是否开启 AI 手写抄录校验(aicheck)参数解释:

--传入值为 0 代表不开启校验;

--传入值为 1 时,开启 AI 手写抄录校验,连续3次校验不通过将弹窗提醒“监测到多次识别未通过,是否直接使用当前手写笔迹?”,确定后跳过该字的校验,下一个字继续执行 AI 校验;

--传入值为 2 时,强制 AI 手绘校验,若校验不通过,则会一直提示“识别失败,请重新书写”,直至校验通 过。

3. 指定备注签署区坐标位置的与其他签署区规则相同,即根据posBean中的posX和posY的值决定,备注签署区的尺寸则是由 remarkFieldWidth(宽度)和 remarkFieldHeight(高度)决定,width参数不生效。

(3)流程中添加多个签署区

一个流程中支持添加多个数组对象的签署区,根据 fieldType 区分,传入值为2代表添加备注签署区,印章等其他签署区无需传入该参数。

接口

/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 支付宝智能视频认证

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

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 支付宝智能视频认证

VIDEO_WE_CHAT_VIDEO_DUAL 微信智能视频认证

signfields

array

body

签署方的签署区列表数据

fieldType

int32

body

签署区类型,默认值为0

0 - 普通签署区

2 - 备注签署区

需要添加备注文字时请填写2

需要普通签章时请填写0或不传此参数

remarkFieldConfig

object

body

备注签署区配置项

注:仅fieldType=2时才需要传此参数

inputType

int32

body

备注文字输入方式

1 - 手写抄录输入

2 - 键盘自由输入

注:inputType=2时aiCheck和remarkContent参数值不生效

aiCheck

int32

body

是否开启 AI 手写抄录校验,

0 - 不开启

1 - 开启 AI 校验

2 - 强制 AI 校验

注:inputType=1时此参数必须传值

remarkContent

string

body

预设待抄录信息,

最多支持100个汉字(含标点符号),

支持传换行符 \n

注:inputType=1时此参数必须传值

remarkFieldWidth

int32

body

备注签署区的宽度

remarkFieldHeight

int32

body

备注签署区的高度

remarkFontSize

int32

body

备注文字字号,默认值11

fileId

string

body

文件fileId

assignedPosbean

boolean

body

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

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

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

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

autoExecute

boolean

body

是否自动执行,默认false

(如果自动签署,必须设置为true)

注:

1、平台方自动签署时,该字段必传,传入true;

2、fieldType=2时,不支持自动签署

actorIndentityType

int32

body

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

2-机构盖章

注:

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

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

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时, 页码可以'-'分割指定页码范围, 传all代表全部页码。

其他情况只能是数字

posX

float

body

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

控制普通签署区和备注签署区的落章位置。

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

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

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

posY

float

body

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

控制普通签署区和备注签署区的落章位置。

width

int32

body

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

注:fieldType=2时此参数值不生效。

将以remarkFieldWidth或remarkFieldHeight为准

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": "xx附件.pdf",
            "fileId": "ueywe76ejffa640fbaxx"
        }
    ],
    "docs": [
        {
            "fileId": "a5404c6b3ea640fbaexx",
            "fileName": "xx告知书.pdf"
        }
    ],
    "copiers": [
        {
            "copierAccountId": "ddd8a147f45c4d2085de8axx",
            "copierIdentityAccountId": "ddd8a147f45c4d2085de8a87xx",
            "copierIdentityAccountType": 0
        }
    ],
    "flowInfo": {
        "autoArchive": true,
        "autoInitiate": true,
        "businessScene": "添加备注签署区",
        "contractRemind": 1,
        "contractValidity": 1671082947000,
        "flowConfigInfo": {
            "noticeDeveloperUrl": "http://xx.xx.xx.xxx:8082/Notify/xx",
            "noticeType": "1,2",
            "redirectUrl": "",
            "signPlatform": "1,2",
            "willTypes": [
                "FACE_ZHIMA_XY"
            ],
            "personAvailableAuthTypes": [
                "PSN_FACEAUTH_BYURL",
                "PSN_TELECOM_AUTHCODE"
            ],
            "batchDropSeal": true,
            "orgAvailableAuthTypes": [
                "ORG_BANK_TRANSFER"
            ],
            "personAuthAdvancedEnabled": [
                "PSN_BANK4_AUTHCODE"
            ],
            "countdown": 5
        },
        "signValidity": 1671082947000
    },
    "signers": [
        {
            "platformSign": false,
            "signOrder": 1,
            "signerAccount": {
                "signerAccountId": "c871b4d01cae4b95b5e15fb4xxx"
            },
            "signfields": [
                {
                    "fieldType": "2",
                    "remarkFieldConfig": {
                        "inputType": "1",
                        "remarkContent": "我已经阅读并悉知",
                        "remarkFieldWidth": "300",
                        "remarkFieldHeight": "100",
                        "aiCheck": "1"
                    },
                    "fileId": "a5404c6b3ea640fbaeb8axxx",
                    "posBean": {
                        "posPage": "1",
                        "posX": 440,
                        "posY": 440
                    },
                    "sealType": "",
                    "signType": 1
                }
            ],
            "thirdOrderNo": "111"
        }
    ]
}

响应示例

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

错误码

错误码

错误描述

解决方案

1437511

文档不存在,fileId:XXX

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

1437306

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

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

401

1.token过期了

2.header请求头不正确

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

我要纠错