Home

添加簽署人

POST/esignglobal/v1/envelope/recipients/addSigners

接口描述

向信封中添加簽署人，簽署人即為簽署任務。包括為簽署人添加控件、身份驗證方式等信息。

注意：

  • 支持在信封開啟後添加新的簽署人，新添加的簽署人的簽署順序，不可以小於或等於有任何一個正在簽署的簽署人的簽署順序值。
  • 同一簽署人（以郵箱作為用戶唯一標識）不允許重複添加，如需更新簽署任務信息，請重新添加對應的簽署人。
  • 一個信封中最多僅能有10個簽署人。

请求参数

參數名稱

類型

必填

說明

envelopeId

string

true

信封ID

signerInfos

array

true

簽署人信息集合

 

businessId

string

false

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

 

userEmail

string

true

簽署人郵箱地址

 

phoneNumber

object

false

當需要進行短信通知時為必填，countryCode與number都需要入參，默認為空

 

 

countryCode

string

false

國家地區的國際碼，無需帶「+」

 

 

number

string

false

不做格式校驗，長度最大為13位

 

userName

string

true

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

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

 

signOrder

int

true

簽署人簽署順序，最小為1

 

anySigner

boolean

false

是否支持任一人簽署，默認 false

true-同一signOrder僅需其中一人簽署

false-同一signOrder所有人均需簽署

 

authModes

string

false

身份驗證方式，默認為0

枚舉類型：

0-不驗證

1-使用簽署口令驗證

2-使用智方便身份信息驗證

3-SMS OTP 驗證

4-身份證件驗證

 

authConfig

object

false

驗證方式設置

 

 

accessCode

object

false

簽署口令設置，當authModes=1時必填

 

 

 

accessCode

string

false

口令內容，不區分大小寫，可以包含字母數字，長度45

 

 

iAMSmart

object

false

智方便身份驗證設置，當authModes=2時必填

 

 

 

name

string

false

簽署人香港身份證件上的姓名全稱，最大長度100個字符

 

 

 

idCardType

string

false

身份證件類型：

HKG_PSN_IDCARD-香港居民身份證

 

 

 

idCardNum

string

false

身份證件號碼，目前不限制格式
香港居民身份證號碼示例：A888888(A)

 

 

sms

object

false

SMS OTP 驗證，當authModes=3時必填

 

 

 

countryCode

string

false

國家地區的國際碼，無需帶「+」

 

 

 

number

string

false

不做格式校驗，長度最大為13位

 

 

idVerification

object

false

身份證件驗證設置，當authModes=4時必填

 

 

 

name

string

false

簽署人身份證件上的姓名全稱，最大長度100個字符

 

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-簽名控件

stamp-圖章控件

默認為signature

 

 

 

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

可入參：

模板

手繪

上傳

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

 

 

 

movable

boolean

false

簽署時允許移動位置，默認false

false-不允許簽署人調整自己的簽署控件位置

true-允許簽署人調整自己的簽署控件位置

 

 

 

pageNo

 

string

false

簽署頁碼；連續頁碼用"-"連接，單獨頁碼用","連接，例如：1-3, 6-10

 

 

 

posX

 

string

false

X軸坐標

補充說明：

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

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

 

 

 

posY

 

string

false

Y軸坐標

補充說明：

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

若fieldType為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

float

false

控件寬度，默認160px

 

 

 

 

font

int

false

只對text生效，字體，默認宋體

1-宋體

2-新宋體

4-黑體

5-楷體

6-Arial

7-Helvetica

9-次新羅馬

10-仿宋

11-格魯吉亞

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

請求示例

{
    "envelopeId": "{{envelope-id}}",
    "signerInfos": [
        {
    	   "userEmail": "sender_user@esignglobal.com",
    	   "userName": "sender_user_name",
    	   "signOrder": 1,
    	   "authModes": "3",
            "authConfig": {
                "sms": {
                    "countryCode": "86",
                    "number": "158****9242"
                }
            },
            "sealInfos": [
                {
                    "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
                    "signConfigs": [
                        {
                           "fieldType": "stamp",
                            "pageNo": "1",
                            "posX": 100.22,
                            "posY": 100
                        }
                    ],
                    "fillConfigs": [
                        {
                            "fieldId": "df0dd777bcc4d108de242d",
                            "fieldKey": "demo",
                            "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": "96e6c7d414f04e98938ea84013b",
                            "fieldKey": "红色加深斜体下划线删除线",
                            "pageNo": "1",
                            "posX": 94.516624,
                            "posY": 284.54953,
                            "fieldType": "1",
                            "required": false,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 10.5,
                                "font": "1",
                                "fontSize": 12.0,
                                "textColor": "#E25041",
                                "bold": true,
                                "italic": true,
                                "lineThrough": true,
                                "horizontalAlignment": "LEFT"
                            }
                        },
                        {
                            "fieldId": "888b899853544c49bd819d9f6d1",
                            "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

signFiles

array

簽署文件集合

 

fileKey 

string

簽署文件fileKey

attachments

array

信封附件集合

 

fileKey 

string

文件fileKey

signerInfos

array

簽署人信息集合

 

businessId

string

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

 

userEmail

string

簽署人郵箱地址

 

userName

string

簽署人姓名

 

signOrder

int

簽署人節點順序，最小為1

 

 

accessCode

string

簽署頁訪問口令

響應示例

{
    "code": "0",
    "data": {
        "signerInfos": [
            {
                "organizationName": "Esign Global CO.",
                "userLastName": "",
                "accessCode": "",
                "userEmail": "sender_user@tsign.cn",
                "userFirstName": "",
                "signOrder": "1"
            }
        ],
        "signFiles": [
            {
                "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
            }
        ],
        "attachments": [

        ],
        "envelopeId": "9fbe6c8190824227bde29136b0145c81"
    },
    "message": "success"
}

接口描述
请求参数
請求示例
響應參數
響應示例