Быстрое создание конверта

POST /esignglobal/v1/envelope/createAndStart

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

Быстрое создание конверта, включающее функции создания конверта, добавления документов на подпись и добавления подписантов.

Поддержка автоматического запуска: После успешного вызова интерфейса конверт успешно создается и активируется, после чего автоматически начинает процесс流转.
Поддержка автоматического завершения: После того как все стороны подпишут документы, конверт автоматически завершается.

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

Имя параметра					Тип	Обязательный	Описание
subject					string	true	Тема конверта Пример: "Offer Letter"
remark					string	false	Примечание к конверту, ограничение длины — 1000 символов
signerSettings					object	false	Действия, разрешенные подписантам
	allowTransfer				boolean	false	Разрешено ли подписанту передать этот конверт другому лицу для подписания, по умолчанию false true — разрешает подписанту в конверте право передачи конверта другому лицу; false — запрещает подписанту в конверте право передачи конверта другому лицу;
	allowModifyName				boolean	false	Разрешено ли стороне подписания изменять имя, действует только для шаблонных подписей, по умолчанию false true — разрешает подписанту изменять имя false — запрещает подписанту изменять имя
expireAfterSeconds					long	false	Время истечения срока действия конверта, через сколько секунд конверт истекает Диапазон истечения: от 86 400 секунд (1 день) до 7 776 000 секунд (90 дней)
redirectUrl					string	false	Должно быть действительным адресом https
callBackUrl					string	false	Адрес обратного вызова (длина 500), должен соответствовать адресу протокола https.
sendLaterAfterSeconds					long	false	Поддержка отложенной отправки пользователем, в секундах Поддерживаемый диапазон времени: от 3600 секунд (1 час) до 259 200 секунд (30 дней)
autoFinish					boolean	false	Управление автоматическим завершением конверта, по умолчанию true true- Конверт автоматически завершается false- Конверт завершается вручную
CCInfos					array	false	Коллекция информации о получателях копии
	userEmail				string	false	Адрес электронной почты получателя копии
	userName				string	false	Имя получателя копии, используется для отображения имени получателя копии на странице подписания и в конверте. [Внимание]: не должно содержать следующие 9 специальных символов: / \ : * " < > \| ? а также все эмодзи
	customizeSettings				object	false	Пользовательская настройка
		notificationSettings			object	false	Настройка уведомлений
			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 корейский
signFiles					array	true	Сбор информации о документах для подписания, порядок отображения соответствует порядку добавления документов.
	fileKey				string	true	fileKey документа для подписания, поддерживается только формат PDF
	documentFields				array	false	Список элементов управления размером документа. Используется для добавления элементов управления размером документа на указанный документ без привязки к конкретному подписанту.
		fieldType			string	false	Тип элемента управления. Передайте eMeterai для обозначения элемента управления налогом на печать Индонезии.
		pageNo			string	false	Номер страницы, на которой находится элемент управления. Для элемента управления налогом на печать Индонезии поддерживается только указание одной страницы; необходимо передать один номер страницы, форматы непрерывных или разрывных диапазонов страниц, такие как 1-3 или 1,3, не поддерживаются.
		posX			float	false	Смещение по оси X, начало координат находится в левом нижнем углу страницы. Диапазон координат совпадает с диапазоном координат других элементов управления.
		posY			float	false	Смещение по оси Y, начало координат находится в левом нижнем углу страницы. Диапазон координат совпадает с диапазоном координат других элементов управления.
attachments					array	false	Коллекция вложений конверта, порядок отображения соответствует порядку добавления файлов.
	fileKey				string	false	fileKey файла
signerInfos					array	true	Коллекция информации о подписантах
	businessId				string	false	Пользовательский бизнес-номер разработчика, ограничение длины — 500 символов
	roleTypes				array	false	Способ действия подписанта, значение по умолчанию — `["sign", "fill"]` fill — заполнение sign — подписание
	deliveryMethods				string	false	Способ уведомления, значение по умолчанию — auto auto- при передаче userEmail отправляется уведомление по электронной почте, при передаче phoneNumber — уведомление по SMS none- уведомления не отправляются email- отправляется уведомление по электронной почте sms- отправляется уведомление по SMS WhatsApp- отправляется уведомление через WhatsApp
	userEmail				string	false	Адрес электронной почты подписанта
	userName				string	true	Имя подписанта, используется на странице подписания и для внешнего отображения имени подписанта в конверте. [Примечание] Не должно содержать следующие 9 специальных символов: / \ : * " < > \| ? а также все эмодзи
	minimumReadingDuration				int	false	Устанавливает время обратного отсчета для обязательного чтения на странице настроек. Значение по умолчанию — 0 (единица измерения: секунды, максимальное значение 999) 0 или отсутствие параметра означает отключение функции, без необходимости обратного отсчета времени чтения
	readToEndRequired				boolean	false	Определяет, обязательно ли прочитать материал до конца. По умолчанию false; true означает включение, false или отсутствие параметра означает отключение.
	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 испанский (Мексика) pt-PT португальский th-TH тайский id-ID индонезийский vi-VN вьетнамский ms-MY малайский fil-PH филиппинский de-DE немецкий fr-FR французский ru-RU русский it-IT итальянский ko-KR корейский
	signOrder				int	true	Порядок подписания документа, минимум 1. Для неупорядоченного подписания можно указать одинаковые значения порядка.
	anySigner				boolean	false	Поддерживает ли любой пользователь подписание, по умолчанию false true- Для одного signOrder достаточно подписания одним из участников false- Для одного signOrder требуется подпись всех участников
	authModes				string	false	Способ проверки, по умолчанию noAuth noAuth- Без проверки accessCode- Проверка с помощью пароля для подписи sms- Проверка SMS OTP idVerification- Проверка по удостоверению личности emailAuth- Проверка email 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	Проверка email OTP; обязательно, когда authModes=emailAuth,
			authEmail		string	false	Адрес электронной почты для верификации личности подписанта
		digitalId			array	false	Электронная верификация личности; обязательно, когда authModes=digitalId
			authApp		string	false	Приложение, используемое для электронной верификации личности singpass- Аутентификация личности через Singpass iamsmart-Использование i AM Smart для аутентификации
			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	Проверка OTP через WhatsApp, обязательно при authModes=whatsappAuth
			countryCode		string	false	Международный код страны/региона, символ «+» передавать не нужно
			number		string	false	Форматная проверка не выполняется, ограничение только по максимальной длине — 13 символов
	digitalSignature				boolean	false	Включена ли цифровая подпись, значение по умолчанию false true — включить, false — не включать
	freeFormSign				boolean	false	Может ли подписант использовать свободное заверение печатью, значение по умолчанию false Дополнительные пояснения: При установке freeFormSign в true остальные параметры в sealInfos передавать не требуется. Если они переданы одновременно, приоритет имеет freeFormSign, а параметры из sealInfos не будут действовать. [Внимание]Свободное размещение печати означает отсутствие ограничений на количество и позицию печатей/подписей, которые может перетаскивать подписывающий.
	sealInfos				array	false	Информация о задаче подписания
		fileKey			string	true	fileKey подписываемого документа
		signConfigs			array	false	Информация о расположении элемента управления. Для выполнения электронной подписи необходимо указать расположение элемента управления.
			fieldType		string	false	Тип элемента управления, по умолчанию signature signature- элемент управления для подписи stamp- элемент управления для печати approval- элемент управления для согласования
			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–250 px; При fieldType = stamp допустимый диапазон составляет 30–280 px; Для сквозной печати печать не требует указания данного параметра.
			width		int	false	Ширина элемента подписи, применяется при fieldType = signature/stamp, единица измерения — пиксели (px), поддерживается только передача положительных целых чисел, значение по умолчанию — auto (автоматический размер системы); При fieldType = signature допустимый диапазон составляет 20–250 px; При fieldType = stamp допустимый диапазон составляет 30–280 px; Для сквозной печати печать не требует указания данного параметра.
			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 Передавайте диапазон страниц для размещения печати на стыке страниц при pagingSealMode=assignedPages. Печать на стыке страниц может использоваться только для документов, состоящих более чем из одной страницы.
			posX		float	false	Координата по оси X [Внимание] Если fieldType равен signature, то координаты указывают позицию области подписиЛевый нижний угол； Если fieldType равен stamp, то координаты указывают позицию области для печатиЦентральная точкаПозиция Начиная с 3 февраля 2026 года, если fieldType равен signature или stamp, координаты указывают на центральную точку области печати. Для сквозной печати можно передавать 0, null передавать нельзя; элемент управления фиксируется по правому краю документа.
			posY		float	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	Действует только для text, шрифт, по умолчанию SimSun 1-SimSun 2-New SimSun 4-HeiTi 5-KaiTi 6-Arial 7-Helvetica 9-Times New Roman 10-FangSong 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	Действует только для tickBox, значение по умолчанию 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 MMM dd,yyyy dd MMM yyyy

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

{
    "subject": "员工入职合约",
    "remark": "这是描述",
    "expireAfterSeconds": 86400,
    "redirectUrl": "https://app-sml.esignglobal.com/home/main/esign/contract/list/inbox",
    "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
    "signerInfos": [
      {
        "userEmail": "sender_user@tsign.cn",
        "userName": "sender_user_name",
        "phoneNumber": {
        	"countryCode": "86",
        	"number": "158****9242"
        }
        "signOrder": 1,
        "authModes": "sms",
        "authConfig": {
            "sms": {
                "countryCode": "86",
                "number": "158****9242"
            }
        },
        "sealInfos": [
        {
            "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
            "signConfigs": [
              {
                "fieldType": "stamp",
                "pageNo": "1,3-5",
                "posX": 100.22222,
                "posY": 100.11111
              }
              "fillConfigs": [
              {
                "fieldId": "df0dd777bc774a2ba3fec4d108de242d",
                "fieldKey": "必填单行文本自动缩小字号最小字号Arial",
                "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": "888b899853544c49bd819d9f6d1e52cf",
                  "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 конверта
CCInfos		array	Коллекция информации о лицах, указанных в копии
	userEmail	string	Адрес электронной почты лица, указанного в копии
	userName	string	Имя лица, указанного в копии
signFiles		array	Коллекция информации о документах для подписания
	fileKey	string	Ключ файла для подписания
attachments		array	Коллекция вложений конверта
	fileKey	string	Ключ файла
signerInfos		array	Информация о подписании
	recipientId	string	ID подписанта
	businessId	string	Пользовательский номер бизнес-задачи разработчика, ограничение длины — 500 символов
	userEmail	string	Адрес электронной почты подписанта
	userName	string	Имя подписанта
	signUrl	string	URL ссылки на подписание
	signOrder	int	Порядок подписания подписанта, минимальное значение — 1
	accessCode	string	Пароль доступа к странице подписания

Пример ответа

{
  "code": "0",
    "data": {
    "signerInfos": [
      {
        "accessCode": "123456",
        "userEmail": "sender_user@tsign.cn",
        "signUrl": "http://app-test.esignglobal-inc.com/home/main/sign/start/base/dosign?envelopeId=4cd738a60225445f9d5f3afec468a639&signature=eyJhbGciOiJIUzI1NiIsInppcCI6IkRFRiJ9.eNqqVkrOzytJrShRsqpWSs0rS83JL0gNSSzO9kxRslJKtjC1MDKxTDVIMzA0SU4xSTIwNjAxSDRNTTVKMTIxTFOqrQUAAAD__w.YMBA5X9O8Ylk7x2rma-s1WxGwo2cjqy-O9CCQopzw88&tenantToken=AA0DDgQ0Y2Q3MzhhNjAyMjU0NDVmOWQ1ZjNhZmVjNDY4YTYzuQ4GNGNkNzM4YTYwMjI1NDQ1ZjlkNWYzYWZlYzQ2OGE2M7kOCjRjZDczOGE2MDIyNTQ0NWY5ZDVmM2FmZWM0NjhhNjO5AIBjNDIwMzg1ZDMyYzU0MGE4YTk1ZTE3ZTNkZmZjMDNm4g%3D%3D",
        "userName": "sender_user_name",
        "signOrder": "1"
      }
    ],
      "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
      "envelopeId": "4cd738a60225445f9d5f3afec468a639"
  },
  "message": "success"
}