快速發起信封

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表情
	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。無序簽可指定相同順序值。
	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-不開啟
	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-審批控件
			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：本地上傳簽名圖片可多選，用","分隔，默認全選
			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",
    "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	簽署資訊
	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"
}