（精简版）基于文件发起签署

接口描述

开发者可基于已上传的合同文件或模板所填充生成的文件来发起签署流程。

由于《基于文件发起签署》接口参数过于繁多，开发者接入较为复杂，该文档在完整版基础上根据开发者常用参数做了精简，因此命名为（精简版）基于文件发起签署。与（完整版）基于文件发起签署 是同一个接口。

【注意事项】

1. 单个签署流程中对签署文件（docs）要求如下：

单个签署流程中所添加的文件个数不可超过50个。
单个文件大小不可超过50MB。
单个文件内单页大小不可超过20MB（文件内含图片时，需特别关注单页大小）。
单个签署流程中所添加的文件大小总和不可超过500MB。

2. 单个签署流程中一次性添加的签署方（signers）不要超过10个，如果超过10个后续可以用《追加签署区》接口追加，整个流程不能超过50个签署方。

3. 单个签署流程中所添加的签署区（signFields）总和不要超过300个。

接口地址&请求方法

点击下述蓝色字体{host}可跳转至API请求域名说明文档

接口地址：https://{host}/v3/sign-flow/create-by-file

请求方法：POST

请求头格式

具体请求头参数，请查看公共请求头格式。

请求参数

开发者可通过【签字盖章核心操作演示视频】和【发起签署参数可视化讲解页】来辅助理解签章及参数含义。

展开全部参数参数名称（点击左侧“+”一键展开参数）					参数类型	必选	参数位置	参数说明（请左右滑动查看完整描述）
docs（点击“+”展开详情）					array	否	body	设置待签署文件信息（点击了解直接上传待签署文件）流程中如需一次完成多份文件签署，可传入多个docs数组；当发起流程而相关签署需求无法确定时，允许不传docs（同时签署方参数signers也无需设置、是否自动开启autoStart必须设置为false），发起签署后再【追加签署文件】。
	fileId				string	是	body	待签署文件ID
	fileName				string	否	body	文件名称（需要添加PDF文件后缀名，“xxx.pdf”）【注】文件名称不可含有以下9个特殊字符：/ \ : * " < > \| ？以及所有emoji表情
signFlowConfig（点击“+”展开详情）					object	是	body	签署流程配置项
	signFlowTitle				string	是	body	签署流程主题（将展示在签署通知和签署页的任务信息中）【注】主题名称不可含有以下9个特殊字符：/ \ : * " < > \| ？以及所有emoji表情
	signFlowExpireTime				int64	否	body	签署截止时间， unix时间戳（毫秒）格式（点击了解指定签署截止日期）补充说明：默认在签署流程创建后的90天时截止（指定值最大不能超过90天，只能指定90天内的时间戳）。签署中如需延期请调用【延期签署截止时间】接口。
	autoFinish				boolean	否	body	所有签署方签署完成后流程自动完结，默认值 false true - 自动完结 false - 非自动完结，需调用【完结签署流程】接口完结补充说明：设置了自动完结的流程中不允许再追加签署区、抄送方，点击这里了解更多流程状态说明。
	notifyUrl				string	否	body	接收相关回调通知的Web地址，详见【签署回调通知接收说明】。
	redirectConfig				object	否	body	重定向配置项
	redirectUrl			string	否	body	签署完成后跳转页面（除app和小程序端集成外，地址需符合 https /http 协议地址）【注】贵司的重定向域名需要在e签宝提前放行，否则会报错：“您即将访问的页面可能有安全风险”。（点击跳转重定向域名配置说明）签署完成后会在贵司重定向地址上拼接签署状态等字段。（点击跳转签署页重定向跳转说明）
signers（点击“+”展开详情）					array	否	body	签署方信息（指参与签署的个人或者机构）（点击了解如何指定双方签署）单个签署方数组中，机构签署方、个人签署方二选一传入（orgSignerInfo与psnSignerInfo二选一即可）；多方签署场景，可传多个签署方数组；单个签署流程中，签署方最多不能超过10个。【注】该接口如果未添加签署方信息，则需要后续在流程中添加，调用【追加签署区】接口添加。
	signConfig				object	否	body	签署人配置项
		forcedReadingTime			int32	否	body	设置页面强制阅读倒计时时间，默认值为 0（单位：秒，最大值999）
		signOrder			int32	否	body	设置签署方的签署顺序按序签时支持传入顺序值 1 - 255（值小的先签署）同时签时，允许值重复
	noticeConfig				object	否	body	设置签署方的通知方式
		noticeTypes			string	否	body	通知类型，默认不通知（值为""空字符串），允许多种通知方式，请使用英文逗号分隔（点解了解指定e签宝短信/邮件通知签署）传空 - 不通知（默认值） 1 - 短信通知（如果套餐内带“分项”字样，请确保开通【电子签名流量费（分项）认证】中的子项：【短信服务】，否则短信通知收不到） 2 - 邮件通知补充说明：个人账号中需要绑定短信/邮件才有对应的通知方式。该通知是签署方维度的，只控制签署人的签署提醒短信，不控制流程的撤销、完成、抄送等短信通知。
	signerType				int32	是	body	签署方类型 0 - 个人，1 -企业/机构，2 - 法定代表人，3 - 经办人若指定签署方为个人，则psnSignerInfo为必传项；若指定签署方为机构或法定代表人手动签署（autoSign参数为false）时，则orgSignerInfo为必传项；若指定签署方为经办人，在同级数组内必须还有机构类型存在，且orgSignerInfo为必传项，即：指定3 - 经办人签的前提是必须同时存在1 - 企业/机构，且经办人签属于企业合同，不在个人名下。
orgSignerInfo				object	否	body	企业/机构签署方信息当签署主体为企业/机构用户、autoSign参数为false手动签章时，请必须传入此对象当企业/机构用户选择静默签署，autoSign参数为true自动落章时，建议不传此对象，e签宝后台会取默认值
	orgName			string	是	body	企业/机构名称（账号标识）【注】企业/机构用户签署时，该参数为必传项
	orgInfo			object	否	body	企业/机构签署方信息（将展示在机构认证页面）
		orgIDCardNum		string	否	body	企业/机构证件号
orgIDCardType		string	否	body	企业/机构证件类型，可选值如下： CRED_ORG_USCC - 统一社会信用代码 CRED_ORG_REGCODE - 工商注册号
transactorInfo			object	否	body	企业/机构经办人信息企业/机构手动签署（autoSign为false），经办人信息必传企业/机构自动落章（autoSign为true），请不要传该参数
		psnAccount		string	是	body	经办人账号标识，手机号或邮箱【注】指定orgName时，该参数为必传项，为了保证签署人准确，必须配合psnName（经办人姓名）传入
	psnInfo		object	否	body	经办人身份信息
	psnName	string	是	body	经办人姓名【注】传psnAccount（经办人账号标识）时，该参数为必传项
	psnIDCardNum	string	否	body	经办人证件号
	psnIDCardType	string	否	body	经办人证件类型，可选值如下： CRED_PSN_CH_IDCARD - 中国大陆居民身份证（默认值） CRED_PSN_CH_HONGKONG - 香港来往大陆通行证（回乡证） CRED_PSN_CH_MACAO - 澳门来往大陆通行证（回乡证） CRED_PSN_CH_TWCARD - 台湾来往大陆通行证（台胞证） CRED_PSN_PASSPORT - 护照【注】CRED_PSN_CH_IDCARD 类型同时兼容港澳台居住证（81、82、83开头18位证件号）、外国人永久居住证（9开头18位证件号）
psnSignerInfo				object	否	body	个人签署方信息当签署主体为个人时请传此对象
	psnAccount			string	是	body	个人账号标识（手机号或邮箱）用于登录e签宝官网的凭证【注】个人用户签署时，该参数为必传项，为了保证签署人准确，必须配合psnName（个人姓名）传入
	psnInfo			object	否	body	个人签署方身份信息补充说明：已实名用户，若传入的psnInfo与在e签宝绑定的psnAccount一致，则无需重复实名，签署页直接进行签署意愿认证；已实名用户，若传入的psnInfo与在e签宝绑定的psnAccount不一致，则接口将会报错，建议核实用户身份信息后重新发起流程；未实名用户，签署页将根据传入的身份信息进行用户实名认证。
	psnName		string	是	body	个人姓名【注】传psnAccount（个人账号标识）时，该参数为必传项
	psnIDCardNum		string	否	body	个人证件号
	psnIDCardType		string	否	body	个人证件类型，可选值如下： CRED_PSN_CH_IDCARD - 中国大陆居民身份证（默认值） CRED_PSN_CH_HONGKONG - 香港来往大陆通行证（回乡证） CRED_PSN_CH_MACAO - 澳门来往大陆通行证（回乡证） CRED_PSN_CH_TWCARD - 台湾来往大陆通行证（台胞证） CRED_PSN_PASSPORT - 护照【注】CRED_PSN_CH_IDCARD 类型同时兼容港澳台居住证（81、82、83开头18位证件号）、外国人永久居住证（9开头18位证件号）
signFields				array	是	body	签署区信息（设置签署方盖章/签名/文字输入的区域）【注】指定了签署方signers的情况下，签署区必传（单个签署方若对应多个签署区，可传多个数组，整个流程中，签署区不能超过300个）
	fileId			string	是	body	签署区所在待签署文件ID 【注】这里的fileId需先添加在docs数组中，否则会报错“参数错误: 文件id不在签署流程中”
	customBizNum			string	否	body	开发者自定义业务编号【注】该参数会在【签署方-签署结果通知】中原样返回，用于标识开发者自身业务
	normalSignFieldConfig			object	是	body	签章区配置项
	freeMode		boolean	否	body	是否自由签章，默认值 false （点击了解指定位置签章与自由签章） true - 是，false - 否补充说明：自由签章指不限制印章、签署位置、签章样式（单页、骑缝）、和签章个数。自由签章模式下，无需传normalSignFieldConfig对象下的其他参数。
	autoSign		boolean	否	body	是否后台自动落章，默认值 false true - 后台自动落章（无感知），false - 签署页手动签章补充说明：当签署方为个人时，不支持自动签章。当签署方为机构（且非应用Id所属企业），静默签署自动落章需先经过印章授权，点击查看印章授权规则。当签署方为应用Id所属主体企业自身静默签署时，支持后台自动落章。
	assignedSealId		string	否	body	指定印章ID（印章ID是e签宝SaaS官网的印章编号，点击查看获取方式）【注】平台方企业自动落章场景，如不指定印章ID，则取平台默认印章
	signFieldSize		float	否	body	签章区尺寸（正方形的边长，单位为px）【注】不指定默认以印章原始大小展示
	signFieldStyle		int32	否	body	签章区样式 1 - 单页签章，2 - 骑缝签章（点击了解骑缝盖章）
	signFieldPosition		object	否	body	签章区位置信息（点击了解指定位置签章与自由签章）
	acrossPageMode	string	否	body	骑缝章模式选择（点击了解骑缝盖章） ALL - 全部页盖骑缝章，AssignedPages - 指定页码盖骑缝章补充说明：当signFieldStyle为1即单页签章时，该参数无需设置当signFieldStyle为2即骑缝签章时，可以指定该参数，默认值ALL
	positionPage	string	否	body	签章区所在页码补充说明：（1）当signFieldStyle为1即单页签章时，只能传单个页码（2）当signFieldStyle为2即骑缝签章时，且acrossPageMode为AssignedPages即指定页码范围时，连续页码可使用'-'指定页码范围，多个页码范围用逗号分隔，例如：1-3,6-10
	positionX	float	否	body	签章区所在X坐标（当signFieldStyle为2即骑缝签章时，该参数不生效，可不传值）【注】可选择如下方式可以确定坐标：（1）开放平台拖章定位工具：【请点击】（2）根据关键字辅助定位接口【请点击】
	positionY	float	否	body	签章区所在Y坐标

响应参数

展开全部参数参数名称		参数类型	必选	参数说明
code		int32	是	业务码，0表示成功，非0表示异常。
message		string	否	业务信息请根据 code 来判断错误情况，不应该依赖 message匹配，因为 message 可能会调整。
data（点击“+”展开详情）		object	否	业务数据
	signFlowId	string	否	签署流程ID（建议开发者保存此流程ID）

请求示例

此场景案例为个人用户和平台自身（应用Id所属主体企业）双方签署案例

更多参数案例请参考【常见场景对接说明】中“发起签署”和“签署可选功能”模块

{
    "docs": [
        {
            "fileId": "55607bb*****702b5f92ed565",
            "fileName": "xx企业劳动合同.pdf"
        }
    ],
    "signFlowConfig": {
        "signFlowTitle": "企业员工劳动合同签署",
        "signFlowExpireTime": 169111118000,
        "autoFinish": true,
        "notifyUrl": "http://xxx/asyn/notify",
        "redirectConfig": {
            "redirectUrl": "http://www.xx.cn/"
        }
    },
    "signers": [
        {
            "signConfig": {
                "signOrder": 1
            },
            "noticeConfig": {
                "noticeTypes": "1"
            },
            "signerType": 0,
            "psnSignerInfo": {
                "psnAccount": "15****50",
                "psnInfo": {
                    "psnName": "张三"
                }
            },
            "signFields": [
                {
                    "customBizNum": "自定义编码001",
                    "fileId": "55607bb5*******ed565",
                    "normalSignFieldConfig": {
                        "signFieldStyle": 1,
                        "signFieldPosition": {
                            "positionPage": "1",
                            "positionX": 200,
                            "positionY": 200
                        }
                    }
                }
            ]
        },
        {
            "signConfig": {
                "signOrder": 2
            },
            "signerType": 1,
            "signFields": [
                {
                    "customBizNum": "自定义编码002",
                    "fileId": "55607b********2ed565",
                    "normalSignFieldConfig": {
                        "autoSign": true,
                        "signFieldStyle": 1,
                        "signFieldPosition": {
                            "positionPage": "1",
                            "positionX": 458,
                            "positionY": 200
                        }
                    }
                }
            ]
        }
    ]
}

响应示例

{
    "code":0,
    "message":"成功",
    "data":{
        "signFlowId":"165467****000"
    }
}

错误码

点击查看错误码

附录

发起签署的参数较多，不同的场景容易弄混，所以结合四种签署场景，整理了关键参数signers（签署方信息）中的传参规则。

signers中参数设置规则如下（signers本身是数组，多场景可以传多个）：

参数字段\签署场景	appId对应的自身机构自动落章	机构用户自动落章	机构用户手动签署	个人用户手动签署
signerType	传值：1	传值：1	传值：1	传值：0
orgSignerInfo	不传	不传	（1）传入机构用户的账号orgId或者orgName （2）传入代机构签署的经办人信息transactorInfo （1）和（2）均须	不传
psnSignerInfo	不传	不传	不传	个人签署账号psnAccount或者psnId
autoSign	true	true	false	false
assignedSealId	（1）不传此字段取默认印章（2）传入appId对应的自身机构账号的印章ID （1）或者（2）	传入机构用户授权给appId对应的自身机构的印章ID （跨企业印章授权与自动签署流程）	不传	不传