Центр разработчиков
Home

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

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 час) ~ 259200 секунд (30 дней)

CCInfos

array

false

Коллекция информации о получателях копий

 

userEmail

string

false

Адрес электронной почты получателя копии

 

userName

string

false

Имя получателя копии, используется для отображения имени получателя копии на странице подписи и в конверте.

【Внимание】: Не должно содержать следующие 9 специальных символов: / \ : * " < > | ？и все emoji-эмодзи

 

customizeSettings

object

false

Пользовательская конфигурация

 

 

notificationSettings

object

false

Пользовательская конфигурация уведомлений

 

 

 

notificationLanguage

string

false

Язык уведомлений, по умолчанию английский

en-US Английский

zh-CN Упрощенный китайский

zh-Hant Традиционный китайский

ja-JP Японский

ES-MX Испанский

signFiles

array

true

Набор информации о подписываемых файлах, порядок отображения соответствует порядку добавления файлов.

 

fileKey 

string

true

fileKey подписываемого файла, поддерживается только формат PDF

attachments

array

false

Набор вложений конверта, порядок отображения соответствует порядку добавления файлов.

 

fileKey 

string

false

fileKey файла

signerInfos

array

true

Набор информации о подписантах

 

businessId

string

false

Определяемый разработчиком бизнес-номер, ограничение длины 500

 deliveryMethods

string

false

Способ уведомления, по умолчанию auto

auto- Отправляет уведомление по электронной почте при передаче userEmail, отправляет SMS-уведомление при передаче phoneNumber

none- Не отправлять уведомления

email- Отправить уведомление по электронной почте

sms- Отправить SMS-уведомление

WhatsApp- Отправить уведомление WhatsApp

 

userEmail

string

true

Адрес электронной почты подписанта

 

userName

string

true

Имя подписанта, используется для отображения имени подписанта на странице подписи и в конверте.

【Примечание】Не может содержать следующие 9 специальных символов: / \ : * " < > | ？и все эмодзи

 

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 Японский

ES-MX Испанский

 

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- Электронная идентификация

 

authConfig

object

false

Настройки способа верификации

 

 

accessCode

object

 

false

Настройка пароля для подписи, когда authModes=accessCodeобязательно для заполнения

 

 

 

accessCode

string

false

Содержимое пароля, без учета регистра, может содержать буквы и цифры, ограничение длины 45

   

promptInfo

string

false

Подсказка для пароля доступа, не может содержать пароль доступа, ограничение длины 30, обязательно для заполнения, когда authModes=1. 

 

 

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

Дополнительные примечания:

Если выбрано freeFormSign как true, нет необходимости передавать другие параметры в sealInfos. Если они передаются одновременно, freeFormSign имеет приоритет над sealInfos, и параметры в sealInfos не вступят в силу

【Внимание】Свободная печать означает отсутствие ограничений на количество и положение штампов/подписей, которые может добавить подписавший

 

sealInfos

array

false

Подписание информации о задаче

 

 

fileKey

string

true

Подписание файла fileKey

 

 

signConfigs

array

false

Информация о местоположении элемента управления. Для выполнения электронной подписи необходимо указать информацию о местоположении элемента управления.

 

 

 

fieldType

string

false

Тип элемента управления, по умолчанию signature

signature-Элемент управления подписью

stamp-Элемент управления печатью

approval-Элемент управления утверждением

   

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

float

false

Координата по оси x

【Внимание】Если fieldType имеет значение signature, то координаты указывают на область подписиВ нижнем левом углу；

Если fieldType имеет значение stamp, то координаты указывают на область печатиЦентральная точкаПоложение

С 3 февраля 2026 года, если fieldType имеет значение signature или stamp, координаты указывают на положение центральной точки области печати.

 

 

 

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-NSimSun

4-SimHei

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

Применимо только к тексту, добавлять ли подчеркивание к шрифту, по умолчанию false

true - добавить подчеркивание

false - не добавлять подчеркивание

 

 

 

 

lineThrough

boolean

false

Применимо только к тексту, добавлять ли зачеркивание, по умолчанию false

true - добавить зачеркивание

false - не добавлять зачеркивание

 

 

 

 

horizontalAlignment

string

false

Применимо только к тексту, формат горизонтального выравнивания, по умолчанию 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

MM dd yyyy

dd MM 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

fileKey подписанного файла

attachments

array

Коллекция вложений конверта

 

fileKey

string

fileKey файла

signerInfos

array

Информация о подписи

 

businessId

string

Определенный разработчиком номер бизнес-операции, ограничение длины 500

 

userEmail

string

Адрес электронной почты подписавшего

 

userName

string

Имя подписавшего

 signUrlstringURL-адрес ссылки для подписи

 

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"
}

 

 

Описание интерфейса
Параметры запроса
Пример запроса
Параметры ответа
Пример ответа
    Ссылка: