快速發起信封

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天）
autoFinish					boolean	false	控制信封是否自動結束，預設為true true-信封自動結束 false-信封手動結束
CCInfos					array	false	抄送人資訊集合
	userEmail				string	false	抄送人郵箱地址
	userName				string	false	抄送人名稱，用於簽署頁面與信封對外展示抄送人名稱。【注意】：不可含有以下9個特殊字符：/ \ : * " < > \| ？以及所有emoji表情
	ccOrder				int	false	抄送人在簽署流程中的順序位置，與簽署人的 signOrder 共用順序。不傳時沿用原有抄送通知邏輯。
	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時發送簡訊通知 none-不發送訊息通知 email-發送郵件通知 sms-發送簡訊通知 WhatsApp-發送WhatsApp通知
	userEmail				string	false	簽署人郵箱地址
	userName				string	true	簽署人姓名，用於簽署頁面與信封對外展示簽署人姓名。【注】不可含有以下9個特殊字符：/ \ : * " < > \| ？以及所有emoji表情
	minimumReadingDuration				int	false	設置頁面強制閱讀倒計時時間，預設值為 0（單位：秒，最大值999） 0 或不傳表示不開啟，無需閱讀倒計時
	readToEndRequired				boolean	false	表示是否必須閱讀到底。預設 false； true 表示開啟，false 或不傳表示不開啟。
	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 韓語
	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-使用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	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下的參數不會生效【注意】自由蓋章即不限制簽名人可拖入的圖章/簽名數量和位置
	documentVisibility				object	false	文件可見性配置，預設全部可見。
		documentViewType			string	false	可見策略，預設 all；all 表示可查看信封內所有簽署文件，limited 表示僅可查看自身簽署文件和補充可見文件。
		viewableFileKeys			array	false	指定簽署方額外允許查看的 fileKey 列表；僅在 documentViewType=limited 時允許傳入並生效。
	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-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：AI 手寫簽名可多選，用","分隔，默認全選
			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		float	false	x軸座標【注意】若fieldType為signature，則座標位置指簽名區左下角；若fieldType為stamp，則座標位置指蓋章區中心點位置自2026年2月3日起，fieldType 為 signature 或 stamp，其座標位置指蓋章區中心點位置。騎縫章可傳0，不可傳null，控件固定在文件右側邊緣。
			posY		float	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	僅對 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",
    "CCInfos": [
      {
        "userEmail": "cc_user@esignglobal.com",
        "userName": "cc_user_name",
        "ccOrder": 1
      }
    ],
    "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,
        "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,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	簽署資訊
	recipientId	string	簽署人 ID
	businessId	string	開發者自訂業務編號，長度限制500
	userEmail	string	簽署人電子郵件地址
	userName	string	簽署人姓名
	signUrl	string	簽署連結地址
	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"
}