Thêm người ký

Tên tham số

Kiểu dữ liệu

Bắt buộc

Mô tả

envelopeId

string

true

ID phong bì

signerInfos

array

true

Tập hợp thông tin người ký

businessId

string

false

Mã nghiệp vụ do nhà phát triển tự định nghĩa, độ dài tối đa 500 ký tự

roleTypes

array

false

Phương thức thao tác của người ký, giá trị mặc định là ["sign", "fill"]

fill-điền

sign-ký

string

false

userEmail

string

false

Địa chỉ email của người ký

documentVisibility

object

false

Cấu hình khả năng hiển thị của tệp, mặc định là tất cả đều có thể xem được.

documentViewType

string

false

Chiến lược hiển thị, mặc định là all; all biểu thị có thể xem tất cả các tệp ký trong phong bì, limited biểu thị chỉ có thể xem các tệp do chính mình ký và các tệp bổ sung được phép xem.

viewableFileKeys

array

false

Danh sách fileKey mà bên ký được phép xem thêm; chỉ cho phép truyền và có hiệu lực khi documentViewType=limited.

phoneNumber

object

false

Bắt buộc khi cần thông báo qua tin nhắn SMS, countryCode và number đều cần truyền vào, mặc định là rỗng

countryCode

string

false

Mã quốc tế của quốc gia/khu vực, không cần truyền dấu “+”

number

string

false

Không kiểm tra định dạng, độ dài tối đa là 13 ký tự

customizeSettings

object

false

Cấu hình tùy chỉnh

notificationSettings

object

false

Cấu hình tùy chỉnh dành cho thông báo

customizeMessage

string

false

Thông báo tin nhắn chuyên dụng, giới hạn ký tự là 200

notificationLanguage

string

false

Ngôn ngữ thông báo, mặc định lấy cấu hình “Ngôn ngữ thông báo mặc định”

en-US Tiếng Anh

zh-CN Tiếng Trung giản thể

zh-Hant Tiếng Trung phồn thể

ja-JP Tiếng Nhật

es-MX tiếng Tây Ban Nha

pt-PT tiếng Bồ Đào Nha
th-TH tiếng Thái
id-ID tiếng Indonesia
vi-VN tiếng Việt
ms-MY tiếng Mã Lai
fil-PH tiếng Philippines
de-DE tiếng Đức
fr-FR tiếng Pháp
ru-RU tiếng Nga
it-IT tiếng Ý
ko-KR tiếng Hàn

userName

string

true

Tên người ký, dùng để hiển thị tên của người ký trên trang và quy trình ký.

[Lưu ý] Không được chứa 9 ký tự đặc biệt sau: / \ : * " < > | ? và tất cả các biểu tượng cảm xúc (emoji)

signOrder

int

true

Thứ tự ký của người ký, giá trị tối thiểu là 1. Đối với ký không theo thứ tự, có thể chỉ định cùng một giá trị thứ tự.

signTaskSuspend

boolean

false

Có thiết lập nút chặn quy trình trước vị trí ký này hay không, mặc định là false. true - thiết lập nút chặn; false - không thiết lập nút chặn. Cấu hình chặn trong nhóm ký hoặc cùng signOrder phải nhất quán.

suspensionKey

string

false

Mã nhận diện nút chặn, tối đa 500 ký tự, duy nhất trong cùng một phong bì. Bắt buộc nhập khi signTaskSuspend=true; không được truyền khi signTaskSuspend=false hoặc không truyền.

suspendReason

string

false

Lý do chặn, không được để trống khi truyền, tối đa 50 ký tự. Chỉ được truyền khi signTaskSuspend=true; nếu không truyền thì mặc định biểu thị cần chờ xử lý từ hệ thống bên ngoài. Không được truyền khi signTaskSuspend=false hoặc không truyền.

anySigner

boolean

false

Có hỗ trợ bất kỳ người nào ký hay không, mặc định là false

true - chỉ cần một người trong cùng signOrder ký

false - tất cả mọi người trong cùng signOrder đều cần ký

authModes

string

false

Phương thức xác thực danh tính, mặc định là noAuth

Kiểu liệt kê:

authConfig

object

false

Cài đặt phương thức xác thực

accessCode

object

false

Cài đặt mật khẩu ký, bắt buộc khi authModes=accessCode

accessCode

string

false

Nội dung mật khẩu, không phân biệt chữ hoa chữ thường, có thể chứa chữ cái và số, độ dài tối đa 45 ký tự

promptInfo

string

false

Thông báo nhắc nhở mật khẩu truy cập, không được chứa mật khẩu truy cập, giới hạn độ dài 30 ký tự, bắt buộc khi authModes=accessCode

sms

object

false

Xác thực SMS OTP, bắt buộc khi authModes=sms

countryCode

string

false

Mã quốc tế của quốc gia/vùng lãnh thổ, không cần thêm dấu “+”

number

string

false

Không kiểm tra định dạng, độ dài tối đa 13 ký tự

idVerification

object

false

Cài đặt xác thực giấy tờ tùy thân, bắt buộc khi authModes=idVerification

name

string

false

Tên đầy đủ trên giấy tờ tùy thân của người ký, độ dài tối đa 100 ký tự

emailAuth

object

false

Xác thực OTP qua email, bắt buộc khi authModes=emailAuth

authEmail

string

false

Địa chỉ email xác minh danh tính người ký

digitalId

array

false

Xác minh danh nghĩa điện tử, bắt buộc khi authModes=digitalId

authApp

string

false

Ứng dụng được sử dụng để xác minh danh nghĩa điện tử

singpass- Sử dụng Singpass để xác thực danh tính

iamsmart- Sử dụng SmartID để xác thực danh tính

idNumber

string

false

Số giấy tờ tùy thân của người ký cần xác minh

Khi authApp=singpass

quy tắc nhập là: chữ cái viết hoa + 7 hoặc 8 chữ số + chữ cái viết hoaiamsmartKhi authApp=

quy tắc nhập là:

1. Một chữ cái viết hoa (A-Z), hoặc hai chữ cái viết hoa (AA-ZZ), làm phần mở đầu của chuỗi;

whatsappAuth

object

false

2. Tiếp theo là 6 chữ số;

countryCode

string

false

3. Cuối cùng là một mã kiểm tra, có thể là số (0-9) hoặc chữ cái (A-Z). Ví dụ: A888888(A)

number

string

false

Không kiểm tra định dạng, chỉ giới hạn độ dài tối đa là 13 ký tự

digitalSignature

boolean

false

Có bật chữ ký số không, mặc định false

true-Bật

false-Không bật

tsp

string

false

Chọn TSP mà người ký sử dụng, mặc định false.

Khi không thiết lập, người ký sẽ tự chọn TSP cần sử dụng. Các giá trị bao gồm:

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

Người ký có được tự do đóng dấu không, giá trị mặc định false

Giải thích bổ sung:

Khi chọn freeFormSign là true, các tham số khác dưới sealInfos không cần truyền vào. Nếu đồng thời truyền cả hai, freeFormSign có độ ưu tiên cao hơn sealInfos, các tham số dưới sealInfos sẽ không có hiệu lực.

[Lưu ý] Tự do đóng dấu nghĩa là không giới hạn số lượng và vị trí con dấu/chữ ký mà người ký có thể kéo thả vào.

sealInfos

array

false

Thông tin nhiệm vụ ký

fileKey

string

true

fileKey của tệp ký

signConfigs

array

false

Thông tin vị trí điều khiển, bắt buộc phải chỉ định thông tin vị trí của điều khiển thì mới thực hiện được chữ ký điện tử.

fieldType

string

false

Loại điều khiển, có thể nhập tham số:

signature-Điều khiển chữ ký

stamp-Điều khiển con dấu

Mặc định là signature

Có bắt buộc hay không, mặc định là bắt buộc

true-Bắt buộc

false-Không bắt buộc

signFieldStyle

string

false

Phương thức đặt con dấu cho điều ký kết, mặc định là normalSeal.

normalSeal-Con dấu thông thường

pagingSeal-Con dấu xuyên trang

Chỉ có điều khiển ký và điều khiển con dấu mới hỗ trợ thiết lập con dấu xuyên trang.

pagingSealMode

string

false

Phạm vi số trang đặt con dấu xuyên trang, mặc định là all.

all-Tất cả các trang

assignedPages-Số trang chỉ định

even-Trang chẵn

odd-Trang lẻ

Chỉ hỗ trợ chỉ định khi signFieldStyle=pagingSeal.

sizeRule

string

false

Phương thức hiển thị kích thước khu vực ký

originalSize- Đặt dấu theo kích thước thực tế của chữ ký/đồ án

targetSize- Tùy chỉnh chiều rộng và chiều cao của khu vực chữ ký/đồ án

Khi sizeRule, height, width đều trống, đặt dấu theo kích thước thực tế của chữ ký/đồ án;

Khi sizeRule trống, height và width không trống, đặt dấu theo kích thước đã chỉ định;

Khi sizeRule không trống, đặt dấu theo phương thức hiển thị đã chỉ định;

Dấu giáp lai không cần chỉ định tham số này, chỉ đặt dấu theo kích thước thực tế.

height

int

false

Chiều cao của điều khiển ký, áp dụng cho fieldType là signature/stamp, đơn vị là px, chỉ hỗ trợ truyền số nguyên dương, mặc định là auto (tức kích thước tự động của hệ thống);

Khi fieldType=signature, phạm vi có thể thiết lập là 20-250px;

Khi fieldType=stamp, phạm vi có thể thiết lập là 30-280px;

Dấu giáp lai không cần chỉ định tham số này.

width

int

false

Chiều rộng của điều khiển ký, áp dụng cho fieldType là signature/stamp, đơn vị là px, chỉ hỗ trợ truyền số nguyên dương, mặc định là auto (tức kích thước tự động của hệ thống);

Khi fieldType=signature, phạm vi có thể thiết lập là 20-250px;

Khi fieldType=stamp, phạm vi có thể thiết lập là 30-280px;

Con dấu giáp lai không cần chỉ định tham số này.

signatureOptions

string

false

Tùy chọn điều khiển ký. Chỉ áp dụng khi fieldType là signature.

Có thể nhập các tham số:

template

handDrawn

upload

aiHandDrawn

Có thể chọn nhiều, phân cách bằng ",", mặc định chọn tất cả

movable

boolean

false

Cho phép di chuyển vị trí khi ký, mặc định là false

false- Không cho phép người ký điều chỉnh vị trí điều khiển ký của mình

true- Cho phép người ký điều chỉnh vị trí điều khiển ký của mình

allowedOptions

array

false

Tùy chọn cho phép người ký phê duyệt, áp dụng khi fieldType là approval. Mặc định là ["approve", "decline"]

approve- Đồng ý

decline- Từ chối

pageNo

string

false

Số trang ký; các trang liên tiếp được nối bằng "-", các trang riêng lẻ được nối bằng ",", ví dụ: 1-3, 6-10

Truyền phạm vi trang nơi con dấu giáp lai sẽ được đóng khi pagingSealMode=assignedPages. Con dấu giáp lai chỉ có thể dùng cho tệp có hơn 1 trang.

posX

string

false

Tọa độ trục X

Giải thích bổ sung:

Nếu fieldType là signature, thì vị trí tọa độ đề cập đến khu vực ký tênGóc dưới bên trái；

Nếu fieldType là stamp, thì vị trí tọa độ chỉ vùng đóng dấuĐiểm trung tâmVị trí

Kể từ ngày 3 tháng 2 năm 2026, nếu fieldType là signature hoặc stamp, thì vị trí tọa độ của nó chỉ điểm trung tâm của vùng đóng dấu.

Dấu giáp lai có thể truyền giá trị 0, không được truyền null; điều khiển được cố định ở mép phải của tệp.

posY

string

false

Tọa độ trục Y

Giải thích bổ sung:

Nếu fieldType là signature, thì vị trí tọa độ chỉ vùng ký tênGóc dưới bên trái；

Nếu fieldType là stamp, thì vị trí tọa độ chỉ vùng đóng dấuĐiểm trung tâmVị trí

Kể từ ngày 3 tháng 2 năm 2026, nếu fieldType là signature hoặc stamp, thì vị trí tọa độ của nó chỉ điểm trung tâm của vùng đóng dấu.

fillConfigs

array

false

Nhập thông tin điều khiển

fieldName

string

false

Tên điều khiển, giới hạn ký tự là 128

required

boolean

false

Có bắt buộc hay không, mặc định là bắt buộc

true - Bắt buộc

false - Không bắt buộc

fieldType

string

false

Loại điều khiển:

1 - Văn bản một dòng

15 - Hộp kiểm

textField

object

false

Thuộc tính của điều khiển văn bản

overflowType

int

false

Chỉ áp dụng cho text, mặc định là 1

1 - Tự động thu nhỏ cỡ chữ

2 - Giới hạn nhập liệu

minFontSize

float

false

Chỉ áp dụng cho text, chỉ áp dụng khi overflowType=1, mặc định là 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

Chiều rộng của điều khiển, mặc định là 160px

font

int

false

Chỉ áp dụng cho text, phông chữ, mặc định là Songti.

1 - Songti

2-Phông chữ Song mới

4-Phông chữ Hei

5-Phông chữ Kai

6-Arial

7-Helvetica

9-Times New Roman

10-Phông chữ Fangsong

11-Georgia

12-Monospace

fontSize

float

false

Chỉ áp dụng cho text, kích thước phông chữ, mặc định là 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

Chỉ áp dụng cho text, màu sắc thập lục phân, mặc định là đen #000

bold

boolean

false

Chỉ áp dụng cho text, có in đậm hay không, mặc định là false

true-In đậm

false-Không in đậm

italic

boolean

false

Chỉ áp dụng cho text, có in nghiêng hay không, mặc định là false

true-In nghiêng

false-Không in nghiêng

underline

boolean

false

Chỉ áp dụng cho text, có gạch chân hay không, mặc định là false

true-Gạch chân

false-Không gạch chân

lineThrough

boolean

false

Chỉ áp dụng cho text, có thêm gạch ngang hay không, mặc định là false

true - thêm gạch ngang

false - không thêm gạch ngang

horizontalAlignment

string

false

Chỉ áp dụng cho text, căn giữa theo chiều ngang, mặc định là left

LEFT - căn trái

CENTER - căn giữa

RIGHT - căn phải

tickBoxField

object

false

Thuộc tính hộp kiểm

tickOptions

array

false

Chỉ áp dụng cho Check, mặc định là 1

1 - dấu tích

2 - dấu chéo

posX

float

false

Tọa độ X của vị trí điều khiển

posY

float

false

Tọa độ Y của vị trí điều khiển

pageNo

string

false

Số trang chứa điều khiển

signDateConfigs

array

false

Thông tin vị trí ngày ký

movable

boolean

false

Cho phép di chuyển vị trí khi ký, mặc định là false

false- Không cho phép người ký điều chỉnh vị trí của các thành phần ký của mình

true- Cho phép người ký điều chỉnh vị trí của các thành phần ký của mình

pageNo

string

false

Số trang ký; các trang liên tiếp được nối bằng "-", các trang riêng lẻ được nối bằng ",", ví dụ: 1-3, 6-10

Nếu không liên tiếp thì truyền "," để phân tách

posX

float

false

Độ lệch trục x, gốc tọa độ là góc dưới bên trái của trang

posY

float

false

Độ lệch trục y, gốc tọa độ là góc dưới bên trái của trang

signDateFormat

string

false

Định dạng ngày ký, định dạng mặc định là yyyy-MM-dd

Hỗ trợ chỉ định định dạng:

yyyy năm MM tháng dd ngày

yyyy-MM-dd

yyyy/MM/dd

dd.MM.yyyy

MM dd yyyy

dd MM yyyy