Tạo phong bì nhanh

Tên tham số

Kiểu dữ liệu

Bắt buộc

Giải thích

subject

string

true

Chủ đề phong bì

Ví dụ: "Offer Letter"

remark

string

false

Ghi chú phong bì, giới hạn độ dài 1000 ký tự

signerSettings

object

false

Các thao tác cho phép người ký thực hiện

allowTransfer

boolean

false

Có cho phép người ký chuyển phong bì này cho người khác ký hay không, mặc định là false

true - Cho phép người ký trong phong bì có quyền chuyển phong bì cho người khác;

false - Không cho phép người ký trong phong bì có quyền chuyển phong bì cho người khác;

allowModifyName

boolean

false

Có cho phép bên ký sửa đổi tên hay không, chỉ áp dụng cho chữ ký trên mẫu, mặc định là false

true - Cho phép người ký sửa đổi tên

false - Không cho phép người ký sửa đổi tên

expireAfterSeconds

long

false

Thời gian hết hạn của phong bì, sau bao nhiêu giây thì phong bì hết hạn

Phạm vi hết hạn: 86.400 giây (1 ngày) ~ 7.776.000 giây (90 ngày)

redirectUrl

string

false

Phải là địa chỉ https hợp lệ

callBackUrl

string

false

Địa chỉ gọi lại (độ dài tối đa 500), phải tuân thủ giao thức địa chỉ https.

sendLaterAfterSeconds

long

false

Hỗ trợ người dùng trì hoãn gửi, tính bằng giây

Phạm vi thời gian hỗ trợ: 3.600 giây (1 giờ) ~ 259.200 giây (30 ngày)

autoFinish

boolean

false

Kiểm soát việc phong bì có tự động kết thúc hay không, mặc định là true

true- Phong bì tự động kết thúc

false- Phong bì kết thúc thủ công

CCInfos

array

false

Danh sách thông tin người được sao chép

userEmail

string

false

Địa chỉ email của người được sao chép

userName

string

false

Họ tên người được sao chép, dùng để hiển thị họ tên người được sao chép trên trang ký và phong bì.

[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

ccOrder

int

false

Vị trí thứ tự của người được sao chép trong quy trình ký, chia sẻ thứ tự với signOrder của người ký. Khi không truyền, sẽ kế thừa logic thông báo sao chép cũ.

customizeSettings

object

false

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

notificationSettings

object

false

Cấu hình tùy chỉnh loại thông báo

notificationLanguage

string

false

Ngôn ngữ thông báo, mặc định lấy từ 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

signFiles

array

true

Tập hợp thông tin tài liệu ký, hiển thị theo thứ tự thêm tài liệu.

fileKey 

string

true

fileKey của tài liệu ký, chỉ hỗ trợ định dạng PDF

fieldType

string

false

Loại điều khiển. Truyền eMeterai để biểu thị điều khiển thuế tem Indonesia.

pageNo

string

false

Số trang mà điều khiển nằm trên đó. Điều khiển thuế tem Indonesia chỉ hỗ trợ chỉ định một trang đơn lẻ, cần truyền số trang đơn, không hỗ trợ định dạng nhiều trang liên tiếp hoặc không liên tiếp như 1-3, 1,3, v.v.

attachments

array

false

Tập hợp phụ lục phong bì, thứ tự hiển thị theo thứ tự thêm tệp.

fileKey 

string

false

fileKey của tệp

signerInfos

array

true

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

businessId

string

false

Mã nghiệp vụ tùy chỉnh của nhà phát triển, giới hạn độ dài 500

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

Phương thức thông báo, mặc định là auto

auto-khi truyền userEmail sẽ gửi thông báo qua email, khi truyền phoneNumber sẽ gửi thông báo qua tin nhắn SMS

none-không gửi thông báo tin nhắn

email-gửi thông báo qua email

sms-gửi thông báo qua tin nhắn SMS

WhatsApp-gửi thông báo qua WhatsApp

userEmail

string

false

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

userName

string

true

Tên người ký, dùng để hiển thị tên người ký trên trang ký và phong bì.

[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)

phoneNumber

object

false

Số điện thoại, mặc định là rỗng

Là tham số bắt buộc khi cần thông báo qua tin nhắn SMS, cả countryCode và number đều phải được truyền

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, chỉ giới hạn độ 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 cho loại thông báo

customizeMessage

string

false

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

notificationLanguage

string

false

Ngôn ngữ thông báo, mặc định lấy theo 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

signOrder

int

true

Thứ tự ký của người ký, giá trị nhỏ nhất là 1. 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 (OR) cùng signOrder phải nhất quán.

suspensionKey

string

false

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

suspendReason

string

false

Lý do chặn, khi truyền vào không được để trống, tối đa 50 ký tự. Chỉ được truyền khi signTaskSuspend=true; khi không truyền, 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ỳ ai cũng ký được 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 phải ký

authModes

string

false

Phương thức xác minh, mặc định là noAuth

noAuth- Không xác minh

accessCode- Xác minh bằng mật khẩu ký

sms- Xác minh OTP qua SMS

idVerification- Xác minh giấy tờ tùy thân

emailAuth- Xác minh OTP qua email

digitalId- Xác minh danh tính điện tử

whatsappAuth- Xác minh OTP qua WhatsApp

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ố, giới hạn độ dài 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/khu vực, không cần truyền "+"

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ự

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

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

emailAuth

object

false

Xác thực Email OTP, 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 tính điện tử, bắt buộc khi authModes=digitalId

authApp

string

false

Ứng dụng được sử dụng để xác minh danh tính điện tử

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

iamsmart- Sử dụng i AM Smart để 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=singpassthì quy tắc nhập là: chữ cái viết hoa + 7 hoặc 8 chữ số + chữ cái viết hoa

Khi authApp=iamsmartthì 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;

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

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)

whatsappAuth

object

false

Xác minh OTP qua WhatsApp, bắt buộc khi authModes=whatsappAuth

countryCode

string

false

Mã quốc tế của quốc gia/khu vực, không cần nhập dấu '+'

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ố hay 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ẽ 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ị liệt kê 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 quyền tự do đóng dấu hay không, giá trị mặc định false

Giải thích bổ sung:

Khi chọn freeFormSign=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 ý]Chữ ký tự do 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

documentVisibility

object

false

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

documentViewType

string

false

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

viewableFileKeys

array

false

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

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í của điều khiển, bắt buộc phải chỉ định thông tin vị trí của điều khiển để thực hiện ký điện tử.

fieldType

string

false

Loại điều khiển, mặc định là signature

signature-Điều khiển ký tên

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

approval-Điều khiển phê duyệt

required

boolean

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 khiển ký, mặc định là normalSeal.

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

pagingSeal-Con dấu giáp lai

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

pagingSealMode

string

false

Phạm vi số trang áp dụng con dấu giáp lai, mặc định là all.

all-Tất cả các trang

assignedPages-Trang được 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ý kết

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

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

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

Khi sizeRule trống, height, 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ý kết, áp dụng cho fieldType là signature/stamp, đơn vị tính bằng px, chỉ chấp nhận số nguyên dương, mặc định là auto (tức là kích thước tự động do 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ý kết, áp dụng cho fieldType là signature/stamp, đơn vị tính bằng px, chỉ chấp nhận số nguyên dương, mặc định là auto (tức là kích thước tự động do hệ thống);

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

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

Con dấu xuyên trang 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: Ký theo mẫu

handDrawn: Ký vẽ tay

upload: Tải lên hình ảnh ký từ máy tính

aiHandDrawn: Ký viết tay bằng AI

Có thể chọn nhiều giá trị, phân cách bằng dấu ",", 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 đóng dấu giáp lai khi pagingSealMode=assignedPages. Dấu giáp lai chỉ có thể áp dụng cho các tài liệu có nhiều hơn 1 trang.

posX

float

false

Tọa độ trục x

[Lưu ý] Nếu fieldType là signature, thì vị trí tọa độ chỉ khu vực chữ kýGóc dưới bên trái；

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

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

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

posY

float

false

Tọa độ trục y

[Lưu ý] Nếu fieldType là signature, thì vị trí tọa độ chỉ khu vực chữ kýGóc dưới bên trái；

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

Kể từ ngày 3 tháng 2 năm 2026, đối với fieldType là signature hoặc stamp, vị trí tọa độ của chúng chỉ điểm trung tâm của khu vực đó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 điền hay không, mặc định là bắt buộc

true - Bắt buộc điền

false - Không bắt buộc điền

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ỏ kích thước phông chữ

2-Hạn chế đầu vào

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 160px

font

int

false

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

1-Songti

2-Xin Songti

4-Heiti

5-Kaiti

6-Arial

7-Helvetica

9-Times New Roman

10-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 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 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 false

true-In nghiêng

false-Không in nghiêng

underline

boolean

false

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

true-Thêm gạch chân

false-Không thêm 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 tickBox, mặc định là 1

1-Kiểm

2-branch

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í đ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

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

MMM dd,yyyy

dd MMM yyyy

Tên tham số

Kiểu dữ liệu

Mô tả

envelopeId

string

ID phong bì

CCInfos

array

Danh sách thông tin người sao chép

userEmail

string

Địa chỉ email của người sao chép

userName

string

Họ tên người sao chép

signFiles

array

Danh sách thông tin tài liệu ký

fileKey

string

fileKey của tài liệu ký

attachments

array

Danh sách tệp đính kèm phong bì

fileKey

string

fileKey của tệp

signerInfos

array

Thông tin ký

recipientId

string

ID người ký

businessId

string

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

userEmail

string

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

userName

string

Tên của người ký

signOrder

int

Thứ tự ký của người ký, giá trị nhỏ nhất là 1

accessCode

string

Mật khẩu truy cập trang ký