Добавить подписанта

POST/esignglobal/v1/envelope/recipients/addSigners

Описание интерфейса

Добавление подписанта в конверт, подписант является задачей подписи. Включает добавление элементов управления, методов аутентификации и другой информации для подписанта.

Внимание:

Поддерживается добавление новых подписантов после открытия конверта. Порядок подписи нового добавленного подписанта не может быть меньше или равен значению порядка подписи любого подписывающего подписанта.
Не допускается повторное добавление одного и того же подписанта (электронная почта используется в качестве уникального идентификатора пользователя). Если вам необходимо обновить информацию о задаче подписи, повторно добавьте соответствующего подписанта.
В одном конверте может быть не более 10 подписантов.

Параметры запроса

Название параметра					Тип	Обязательно	Описание
envelopeId					string	true	ID конверта
signerInfos					array	true	Набор информации о подписанте
	businessId				string	false	Пользовательский бизнес-номер разработчика, длина 500
	userEmail				string	true	Адрес электронной почты подписавшего
	phoneNumber				object	false	Обязательно для заполнения при необходимости отправки SMS-уведомлений, необходимо указать параметры 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 Испанский
	userName				string	true	Имя подписавшего, используемое для отображения имени подписавшего на странице подписи и в процессе. 【Внимание】Не должно содержать следующие 9 специальных символов: / \ : * " < > \| ？и все эмодзи
	signOrder				int	true	Порядок подписи подписавшего, минимум 1. Для неупорядоченной подписи можно указать одинаковое значение порядка.
	anySigner				boolean	false	Поддерживается ли подпись любым лицом, по умолчанию false true - для одного signOrder требуется подпись только одного человека false - для одного signOrder требуется подпись всех людей
	authModes				string	false	Способ аутентификации, по умолчанию noAuth Тип перечисления: noAuth- Без проверки accessCode- Использовать проверку пароля подписи sms- SMS OTP проверка idVerification- Проверка удостоверения личности emailAuth- Подтверждение OTP по электронной почте digitalId- Электронная идентификация
	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	Приложение, используемое для электронной аутентификации singpass - использовать Singpass для аутентификации
			idNumber		string	false	Номер удостоверения личности подписанта, ожидающего проверки
	digitalSignature				boolean	false	Включить ли цифровую подпись, по умолчанию false true-Включить false-Не включать
	freeFormSign				boolean	false	Подписывающее лицо свободно ставит подпись, значение по умолчанию false Дополнительные примечания: Если выбрано значение true для freeFormSign, другие параметры в sealInfos не нужно передавать. Если они передаются одновременно, freeFormSign имеет более высокий приоритет, чем sealInfos, и параметры в sealInfos не вступают в силу. 【Внимание】Свободная подпись означает отсутствие ограничений на количество и положение печатей/подписей, которые может добавить подписывающее лицо.
	sealInfos				array	false	Информация о задаче подписи
		fileKey			string	true	FileKey файла подписи
		signConfigs			array	false	Информация о местоположении элемента управления. Для выполнения электронной подписи необходимо указать информацию о местоположении элемента управления.
			fieldType		string	false	Тип элемента управления, может быть входным параметром: signature- Элемент управления подписью stamp- Элемент управления печатью approval- Элемент управления утверждением По умолчанию signature
			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 Можно выбрать несколько вариантов, разделенных ",", по умолчанию выбраны все
			movable		boolean	false	Разрешить перемещение местоположения при подписании, по умолчанию false false-Не разрешать подписывающему лицу изменять положение своих элементов управления подписью true-Разрешить подписывающему лицу изменять положение своих элементов управления подписью
			allowedOptions		array	false	Опции, позволяющие подписывающему лицу утверждать, применимо к fieldType approval. По умолчанию["approve", "decline"] approve-Согласен decline-Отклонить
			pageNo		string	false	Номера страниц для подписи; последовательные номера страниц соединяются знаком "-", отдельные номера страниц соединяются знаком ",", например: 1-3, 6-10
			posX		string	false	Координата по оси X Дополнительные примечания: Если fieldType имеет значение signature, то координаты указывают на область подписиНижний левый угол； Если fieldType имеет значение stamp, то координаты указывают на область штампаЦентральная точкаПоложение С 3 февраля 2026 года, если fieldType имеет значение signature или stamp, его координаты указывают на положение центральной точки области штампа.
			posY		string	false	Координата по оси Y Дополнительное пояснение: Если fieldType имеет значение signature, то координаты указывают на область подписиНижний левый угол； Если fieldType имеет значение stamp, то координаты указывают на область штампаЦентральная точкаПоложение Начиная с 3 февраля 2026 года, для 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	Действует только для текста, шрифт по умолчанию SimSun. 1-SimSun 2-NSimSun 4-Heiti 5-KaiTi 6-Arial 7-Helvetica 9-Times New Roman 10-FangSong 11-Georgia 12-Monospace
				fontSize	float	false	Действует только для текста, размер шрифта, по умолчанию 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	Действует только для текста, шестнадцатеричный цвет, по умолчанию черный #000
				bold	boolean	false	Действует только для текста, полужирный шрифт, по умолчанию false true-полужирный false-не полужирный
				italic	boolean	false	Действует только для текста, курсив, по умолчанию false true-курсив false-не курсив
				underline	boolean	false	Действует только для текста, добавлять ли подчеркивание к шрифту, по умолчанию 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	Формат даты подписания, формат по умолчанию — гггг-ММ-дд Поддерживаемые форматы: гггг год ММ месяц дд день гггг-ММ-дд гггг/ММ/дд дд.ММ.гггг ММ дд гггг дд ММ гггг

Пример запроса

{
    "envelopeId": "{{envelope-id}}",
    "signerInfos": [
        {
    	   "userEmail": "sender_user@esignglobal.com",
    	   "userName": "sender_user_name",
    	   "signOrder": 1,
    	   "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	Коллекция информации о подписантах
	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"
}