添加簽署人

參數名稱

型別

必填

說明

envelopeId

string

true

信封 ID

signerInfos

array

true

簽署人資訊集合

businessId

string

false

開發者自訂業務編號，長度500

roleTypes

array

false

簽署人操作方式，預設值為 ["sign", "fill"]

fill-填寫

sign-簽署

string

false

userEmail

string

false

簽署人郵箱地址

documentVisibility

object

false

檔案可見性配置，預設全部可見。

documentViewType

string

false

可見策略，預設 all；all 表示可查看信封內所有簽署檔案，limited 表示僅可查看自身簽署檔案和補充可見檔案。

viewableFileKeys

array

false

指定簽署方額外允許查看的 fileKey 列表；僅在 documentViewType=limited 時允許傳入並生效。

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 韓語

userName

string

true

簽署人姓名，用於簽署頁面與流程對外展示簽署人姓名。

【注意】不可含有以下9個特殊字元：/ \ : * " < > | ？以及所有emoji表情

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

枚舉類型：

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-使用智方便進行身分認證

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下的參數不會生效。

【注意】自由签章即不限制簽名人可拖入的圖章/簽名數量和位置。

sealInfos

array

false

簽署任務資訊

fileKey

string

true

簽署文件fileKey

signConfigs

array

false

控件位置資訊，必須指定控件的位置資訊才可以進行電子簽名。

fieldType

string

false

控件類型，可入參：

signature-簽名控件

stamp-圖章控件

預設為signature

是否必填，預設必填

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

可多選，用","分隔，默認全選

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

string

false

X軸座標

補充說明：

若fieldType為signature，則座標位置指簽名區左下角；

若fieldType為stamp，則座標位置指蓋章區中心點位置

自2026年2月3日起，fieldType 為 signature 或 stamp，其座標位置指蓋章區中心點位置。

騎縫章可傳0，不可傳null，控件固定在文件右側邊緣。

posY

string

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

僅對 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

簽署日期格式，預設格式為 yyyy-MM-dd

支援指定格式：

yyyy 年 MM 月 dd 日

yyyy-MM-dd

yyyy/MM/dd

dd.MM.yyyy

MM dd yyyy

dd MM yyyy