添加签署人

POST/esignglobal/v1/envelope/recipients/addSigners

接口描述

向信封中添加签署人，签署人即为签署任务。包括为签署人添加控件、身份验证方式等信息。

注意：

分步发起的信封，需要手动结束。
信封流程未结束前，可以随时添加签署人。
添加新签署人时，只能加在当前流程的最后，不能插到正在签或已经签完的人前面。
同一签署顺序下，同一签署人（优先以邮箱判定，无邮箱则以手机号判定）不可重复添加。如需修改信息，请删除后重新添加。
一个信封中最多仅能有10个签署人。

请求参数

参数名称					类型	必填	说明
envelopeId					string	true	信封 ID
signerInfos					array	true	签署人信息集合
	businessId				string	false	开发者自定义业务编号，长度500
	roleTypes				array	false	签署人操作方式，默认值为 `["sign", "fill"]` fill-填写 sign-签署
	deliveryMethods				string	false	通知方式，默认为auto auto-传入userEmail时发送邮件通知，传入phoneNumber时发送短信通知 none-不发送消息通知 email-发送邮件通知 sms-发送短信通知 WhatsApp-发送WhatsApp通知
	userEmail				string	false	签署人邮箱地址
	minimumReadingDuration				int	false	设置页面强制阅读倒计时时间，默认值为 0（单位：秒，最大值999） 0 或不传表示不开启，无需阅读倒计时
	readToEndRequired				boolean	false	表示是否必须阅读到底。默认 false； true 表示开启，false 或不传表示不开启。
	documentVisibility				object	false	文件可见性配置，默认全部可见。
		documentViewType			string	false	可见策略，默认 all；all 表示可查看信封内所有签署文件，limited 表示仅可查看自身签署文件和补充可见文件。
		viewableFileKeys			array	false	指定签署方额外允许查看的 fileKey 列表；仅在 documentViewType=limited 时允许传入并生效。
	phoneNumber				object	false	当需要进行短信通知时为必填，countryCode与number都需要入参，默认为空
		countryCode			string	false	国家地区的国际码，无需传入“+”
		number			string	false	不做格式校验，长度最大为13位
	customizeSettings				object	false	自定义配置
		notificationSettings			object	false	通知类自定义配置
			customizeMessage		string	false	专属消息通知，字符限制200
			notificationLanguage		string	false	通知语言，默认取“默认通知语言”配置 en-US 英语 zh-CN 简体中文 zh-Hant 繁体中文 ja-JP 日语 es-MX 西班牙语 pt-PT 葡萄牙语 th-TH 泰语 id-ID 印尼语 vi-VN 越南语 ms-MY 马来语 fil-PH 菲律宾语 de-DE 德语 fr-FR 法语 ru-RU 俄语 it-IT 意大利语 ko-KR 韩语
	userName				string	true	签署人姓名，用于签署页面与流程对外展示签署人姓名。【注意】不可含有以下9个特殊字符：/ \ : * " < > \| ？以及所有emoji表情
	signOrder				int	true	签署人签署顺序，最小为1。无序签可指定相同顺序值。
	signTaskSuspend				boolean	false	是否在该签署位置前设置流程阻塞节点，默认 false。true-设置阻塞节点；false-不设置阻塞节点。同一 signOrder 的或签组内阻塞配置必须一致。
	suspensionKey				string	false	阻塞节点标识，最长 500 个字符，同一信封内唯一。当 signTaskSuspend=true 时必填；signTaskSuspend=false 或未传时不得传入。
	suspendReason				string	false	阻塞原因，传入时不能为空，最长 50 个字符。仅 signTaskSuspend=true 时可传；不传时默认表示需要等待外部系统处理。signTaskSuspend=false 或未传时不得传入。
	anySigner				boolean	false	是否支持任一人签署，默认 false true-同一signOrder仅需其中一人签署 false-同一signOrder所有人均需签署
	authModes				string	false	身份验证方式，默认为noAuth 枚举类型： noAuth-不验证 accessCode-使用签署口令验证 sms-SMS OTP 验证 idVerification-身份证件验证 emailAuth-邮箱OTP验证 digitalId-电子身份验证 whatsappAuth-WhatsApp OTP验证
	authConfig				object	false	验证方式设置
		accessCode			object	false	签署口令设置，当authModes=accessCode时必填
			accessCode		string	false	口令内容，不区分大小写，可以包含字母数字，长度45
			promptInfo		string	false	访问口令提示信息，不可以包含访问口令，长度限制30，当authModes=accessCode时必填。
		sms			object	false	SMS OTP验证，当authModes=sms时必填
			countryCode		string	false	国家地区的国际码，无需带“+”
			number		string	false	不做格式校验，长度最大为13位
		idVerification			object	false	身份证件验证设置，当authModes=idVerification时必填
			name		string	false	签署人身份证件上的姓名全称，最大长度100个字符
		emailAuth			object	false	邮箱OTP校验，当authModes=emailAuth时必填
			authEmail		string	false	签署人身份验证邮箱地址
		digitalId			array	false	电子身份验证，当authModes=digitalId时必填
			authApp		string	false	电子身份验证使用的APP singpass-使用Singpass进行身份认证 iamsmart-使用智方便进行身份认证
			idNumber		string	false	签署人待验证的身份证件号码当authApp=singpass时，传入规则为：大写字母+7或8位数字+大写字母当authApp=iamsmart时，传入规则为： 1.一个大写字母（A-Z），或者两个大写字母（AA-ZZ），作为序列的开头； 2. 接着是6位数字； 3. 最后是一个检查码，可以是数字（0-9）或者字母（A-Z）。示例：A888888(A)
		whatsappAuth			object	false	WhatsApp OTP验证，当authModes=whatsappAuth时必填
			countryCode		string	false	国家地区的国际码，无需传入“+”
			number		string	false	不做格式校验，仅限制长度最大为13位
	digitalSignature				boolean	false	是否开启数字签名，默认false true-开启 false-不开启
	tsp				string	false	选择签署人使用的 TSP，默认false。不设置时，由签署人自行选择需要使用的TSP。枚举包括： vinotek、eSignPersonal、localCertificates、iAmSmart、vnptSmartCa、adacomOneShot、audkenni belgianIdCard、certEuropeUsbToken、certSignWebSign、chaveMovel、croatianIdCard、czechIdCard、dTrustSignMe、diia estonianIdCard、estonianMobileId、evrotrust、finnishIdCard、frejaEid、frejaEidSign、gseGestionDeSeguridadElectronica、halcom harica、idAustriaATrustSignatur、infoCert、ltId、latvianIdCard、latvianEParakstsMobile、lithuanianIdCard、lithuanianMobileId mscTrustGate、mitId、norwegianBankId、oneId、pscWorldWallet、spid、serproId、simplySign smartId、swedenBankId、swissId、swisscom、transSped、trustAsia、zealidApp、certMe certSignUsbToken、eCertChile、eMudhra、itsme、mojeId、emdha
	freeFormSign				boolean	false	签署人是否自由签章，默认值 false 补充说明：当选择freeFormSign为true时，针对sealInfos下的其他参数无需传入。如同时传入，freeFormSign优先级高于sealInfos，sealInfos下的参数不会生效。【注意】自由签章即不限制签名人可拖入的图章/签名数量和位置。
	sealInfos				array	false	签署任务信息
		fileKey			string	true	签署文件fileKey
		signConfigs			array	false	控件位置信息，必须指定控件的位置信息才可以进行电子签名。
			fieldType		string	false	控件类型，可入参： signature-签名控件 stamp-图章控件 approval-审批控件默认为signature
			required		boolean	false	是否必填，默认必填 true-必填 false-非必填
			signFieldStyle		string	false	签署控件落章方式，默认为normalSeal。 normalSeal-普通签章 pagingSeal-骑缝章仅签名控件、图章控件支持设置骑缝章。
			pagingSealMode		string	false	骑缝章落章页数范围，默认为all。 all-全部页码 assignedPages-指定页码 even-偶数页 odd-奇数页仅 signFieldStyle=pagingSeal 时支持指定。
			sizeRule		string	false	签署区尺寸展示方式 originalSize-根据签名/图章实际尺寸落章 targetSize-自定义签名/图章区宽高当sizeRule, height, width均为空时，按签名/图章实际尺寸落章；当sizeRule为空，height, width不为空时，按指定尺寸落章；当sizeRule不为空时，按指定的展示方式落章；骑缝章不需要指定此参数，仅根据实际尺寸落章。
			height		int	false	签署控件高度，适用于fieldType为signature/stamp，单位为px，仅支持正整数传入，默认auto（即系统自动尺寸）；当fieldType=signature时，可设置范围为20-250px；当fieldType=stamp时，可设置范围为30-280px；骑缝章不需要指定此参数。
			width		int	false	签署控件宽度，适用于fieldType为signature/stamp，单位为px，仅支持正整数传入，默认auto（即系统自动尺寸）；当fieldType=signature时，可设置范围为20-250px；当fieldType=stamp时，可设置范围为30-280px；骑缝章不需要指定此参数。
			signatureOptions		string	false	签名控件选项。仅适用于fieldType为signature。可入参： template handDrawn upload aiHandDrawn 可多选，用","分隔，默认全选
			movable		boolean	false	签署时允许移动位置，默认false false-不允许签署人调整自己的签署控件位置 true-允许签署人调整自己的签署控件位置
			allowedOptions		array	false	允许签署人审批的选项，适用于fieldType为approval。默认为["approve", "decline"] approve-同意 decline-拒绝
			pageNo		string	false	签署页码；连续页码用"-"连接，单独页码用","连接，例如：1-3, 6-10 pagingSealMode=assignedPages 时传入骑缝章落章的页码范围。骑缝章只能用于大于1页的文件。
			posX		string	false	X轴坐标补充说明：若fieldType为signature，则坐标位置指签名区左下角；若fieldType为stamp，则坐标位置指盖章区中心点位置自2026年2月3日起，fieldType 为 signature 或 stamp，其坐标位置指盖章区中心点位置。骑缝章可传0，不可传null，控件固定在文件右侧边缘。
			posY		string	false	Y轴坐标补充说明：若fieldType为signature，则坐标位置指签名区左下角；若fieldType为stamp，则坐标位置指盖章区中心点位置自2026年2月3日起，fieldType 为 signature 或 stamp，其坐标位置指盖章区中心点位置。
		fillConfigs			array	false	填写控件信息
			fieldName		string	false	控件名称，字符数限制128
			required		boolean	false	是否必填，默认必填 true-必填 false-非必填
			fieldType		string	false	控件类型： 1-单行文本 15-勾选框
			textField		object	false	文本控件属性
				overflowType	int	false	只对text生效，默认1 1-自动缩小字号 2-限制输入
				minFontSize	float	false	只对text生效，只对overflowType=1生效，默认8。 5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72
				width	int	false	控件宽度，默认160px
				font	int	false	只对text生效，字体，默认宋体。 1-宋体 2-新宋体 4-黑体 5-楷体 6-Arial 7-Helvetica 9-Times New Roman 10-仿宋 11-Georgia 12-Monospace
				fontSize	float	false	只对text生效，字体大小，默认12 5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72
				textColor	string	false	只对text生效，十六进制颜色，默认黑色#000
				bold	boolean	false	只对text生效，字体是否加粗，默认false true-加粗 false-不加粗
				italic	boolean	false	只对text生效，是否斜体，默认false true-斜体 false-非斜体
				underline	boolean	false	只对text生效，字体是否添加下划线，默认false true-添加下划线 false-不添加下划线
				lineThrough	boolean	false	只对text生效，是否添加删除线，默认false true-添加删除线 false-不添加删除线
				horizontalAlignment	string	false	只对text生效，水平居中格式，默认left LEFT-靠左 CENTER-居中 RIGHT-靠右
			tickBoxField		object	false	勾选框属性
				tickOptions	array	false	只对Check生效，默认1 1-勾 2-叉
			posX		float	false	控件位置X横坐标
			posY		float	false	控件位置Y纵坐标
			pageNo		string	false	控件所在页码
		signDateConfigs			array	false	签署日期位置信息
			movable		boolean	false	签署时允许移动位置，默认false false-不允许签署人调整自己的签署控件位置 true-允许签署人调整自己的签署控件位置
			pageNo		string	false	签署页码；连续页码用"-"连接，单独页码用","连接，例如：1-3, 6-10 非连续则传入","进行分割
			posX		float	false	x轴偏移量，页面左下角为坐标原点
			posY		float	false	y轴偏移量，页面左下角为坐标原点
			signDateFormat		string	false	签署日期格式，默认格式为yyyy-MM-dd 支持指定格式： yyyy年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

请求示例

{
    "envelopeId": "{{envelope-id}}",
    "signerInfos": [
        {
    	   "userEmail": "sender_user@esignglobal.com",
    	   "userName": "sender_user_name",
    	   "signOrder": 1,
    	   "signTaskSuspend": true,
    	   "suspensionKey": "approval-node-001",
    	   "suspendReason": "等待外部审批",
    	   "authModes": "sms",
           "authConfig": {
                "sms": {
                    "countryCode": "86",
                    "number": "158****9242"
                }
            },
            "sealInfos": [
                {
                    "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
                    "signConfigs": [
                        {
                           "fieldType": "stamp",
                            "pageNo": "1",
                            "posX": 100.22,
                            "posY": 100
                        }
                    ],
                    "fillConfigs": [
                        {
                            "fieldId": "df0dd777bcc4d108de242d",
                            "fieldKey": "demo",
                            "pageNo": "1",
                            "posX": "88.70021",
                            "posY": 745.409,
                            "fieldType": "1",
                            "required": true,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 8,
                                "font": "6",
                                "fontSize": "12",
                                "textColor": "#54ACD2",
                                "bold": false,
                                "italic": true,
                                "lineThrough": false,
                                "horizontalAlignment": "RIGHT"
                            }
                        },
                        {
                            "fieldId": "96e6c7d414f04e98938ea84013b",
                            "fieldKey": "红色加深斜体下划线删除线",
                            "pageNo": "1",
                            "posX": 94.516624,
                            "posY": 284.54953,
                            "fieldType": "1",
                            "required": false,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 10.5,
                                "font": "1",
                                "fontSize": 12.0,
                                "textColor": "#E25041",
                                "bold": true,
                                "italic": true,
                                "lineThrough": true,
                                "horizontalAlignment": "LEFT"
                            }
                        },
                        {
                            "fieldId": "888b899853544c49bd819d9f6d1",
                            "fieldKey": "必填勾选控件选中样式不显示边框",
                            "pageNo": "3",
                            "posX": 451.77127,
                            "posY": 429.07626,
                            "fieldType": "15",
                            "required": true,
                            "tickBoxField": {
                                "tickOptions": [1,2],
                                "showBorder": false
                            }
                        }
                    ],
                    "signDateConfigs":[
                          "pageNo":"1",
                          "posX": 100.22,
                          "posY": 100,
                          "signDateFormat": "dd MMM yyyy"
                    ]
                }
            ]
        }
    ]
}

响应参数

参数名称			类型	说明
envelopeId			string	信封 ID
signFiles			array	签署文件集合
	fileKey		string	签署文件fileKey
attachments			array	信封附件集合
	fileKey		string	文件fileKey
signerInfos			array	签署人信息集合
	recipientId		string	参与人ID
	businessId		string	开发者自定义业务编号，长度500
	userEmail		string	签署人邮箱地址
	userName		string	签署人姓名
	signOrder		int	签署人节点顺序，最小为1
		accessCode	string	签署页访问口令

响应示例

{
    "code": "0",
    "data": {
        "signerInfos": [
            {
                "organizationName": "Esign Global CO.",
                "userLastName": "",
                "accessCode": "",
                "userEmail": "sender_user@tsign.cn",
                "userFirstName": "",
                "signOrder": "1"
            }
        ],
        "signFiles": [
            {
                "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
            }
        ],
        "attachments": [
        ],
        "envelopeId": "9fbe6c8190824227bde29136b0145c81"
    },
    "message": "success"
}