Tên tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
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 hạn 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: từ 86.400 giây (1 ngày) đến 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ợ: từ 3.600 giây (1 giờ) đến 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 | Tên của người được sao chép, dùng để hiển thị tên người được sao chép trên trang ký và phong bì. [Lưu ý]: Không được chứa các ký tự đặc biệt sau: / \ : * " < > | ? và tất cả biểu tượng cảm xúc emoji |
| | 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 |
| | documentFields | array | false | Danh sách điều khiển kích thước tài liệu. Dùng để thêm các điều khiển kích thước tài liệu không gắn với người ký trên tài liệu chỉ định. |
| | 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 chứa điều khiể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. |
| | | posX | float | false | Độ lệch trục x, góc dưới bên trái của trang là gốc tọa độ. Phạm vi tọa độ giống với phạm vi tọa độ của các điều khiển khác. |
| | | posY | float | false | Độ lệch trục y, góc dưới bên trái của trang là gốc tọa độ. Phạm vi tọa độ giống với phạm vi tọa độ của các điều khiển khác. |
attachments | array | false | Tập hợp phụ kiện 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ý |
| | deliveryMethods | string | false | Phương thức thông báo, mặc định là auto auto-khi truyền userEmail thì gửi thông báo qua email, khi truyền phoneNumber thì 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 của người ký, dùng để hiển thị tên người ký trên trang ký và đối với 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 |
| | minimumReadingDuration | int | false | Thiết lập thời gian đếm ngược bắt buộc đọc trên trang cài đặt, giá trị mặc định là 0 (đơn vị: giây, tối đa 999) Giá trị 0 hoặc không truyền nghĩa là không kích hoạt, không cần đếm ngược thời gian đọc |
| | readToEndRequired | boolean | false | Biểu thị việc có bắt buộc phải đọc đến cuối hay không. Giá trị mặc định là false; true biểu thị kích hoạt, false hoặc không truyền nghĩa là không kích hoạt. |
| phoneNumber | object | false | Số điện thoại, mặc định để trố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ị tối thiểu là 1. Ký không theo thứ tự có thể chỉ định cùng một giá trị thứ tự. |
| anySigner | boolean | false | Có hỗ trợ bất kỳ người nào ký 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 minh |
| | accessCode | object | false | Cài đặt mật khẩu ký, khi authModes=accessCodebắt buộc điền |
| | | accessCode | string | false | Nội dung mật khẩu, không phân biệt chữ hoa/thường, có thể chứa chữ cái và số, giới hạn độ dài 45 |
| | | | promptInfo | string | false | Thông báo 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 OTP SMS, 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 minh 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ý, tối đa 100 ký tự |
| | | emailAuth | object | false | Xác thực OTP email, bắt buộc khi authModes=emailAuth |
| | | | authEmail | string | false | Địa chỉ email xác thực danh tính của người ký |
| | digitalId | array | false | Xác thực 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 thực 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ý đang chờ xác minh Khi authApp=singpass Khi authApp=iamsmart 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 đầ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à chữ số (0-9) hoặc chữ cái (A-Z). Ví dụ: A888888(A) |
| | whatsappAuth | object | false | Xác thực 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 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ự |
| digitalSignature | boolean | false | Có bật chữ ký số hay không, mặc định là false true - Bật, false - Không bật |
| freeFormSign | boolean | false | Người ký có được tự do đóng dấu hay không, giá trị mặc định là false Giải thích bổ sung: Khi freeFormSign được đặt là true, các tham số khác dưới sealInfos không cần truyền vào. Nếu truyền đồng thời, 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 ý]Ký tự do nghĩa là không giới hạn số lượng con dấu/chữ ký mà người ký có thể kéo thả và vị trí của chúng. |
| sealInfos | array | false | Thông tin nhiệm vụ ký |
| | fileKey | string | true | fileKey của tài liệu 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ự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 chữ ký stamp-Điều khiển con dấu approval-Điều khiển phê duyệt |
| | | | 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 |
| | | | signFieldStyle | string | false | Phương thức đặt con dấu của điều khiển ký, mặc định là normalSeal. normalSeal- Dấu thông thường pagingSeal- Dấu chồng mép 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 dấu chồng mép. |
| | | | pagingSealMode | string | false | Phạm vi số trang áp dụng dấu chồng mép, mặc định là all. all- Tất cả các trang assignedPages- Chỉ định số trang 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 vùng ký kết originalSize- Đặt dấu theo kích thước thực tế của chữ ký/con dấu targetSize- Tùy chỉnh chiều rộng và chiều cao khu vực chữ ký/con dấu Khi sizeRule, height, width đều trống, đặt dấu theo kích thước thực tế của chữ ký/con dấu; Khi sizeRule trống như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; Con dấu xuyên trang không cần chỉ định tham số này, chỉ cần đóng 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 khi fieldType là signature/stamp, đơn vị tính bằng px, chỉ hỗ trợ truyền số nguyên dương, mặc định là auto (tức hệ thống tự động xác định kích thước); 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. |
| | | width | int | false | Chiều rộng của điều khiển ký kết, áp dụng khi fieldType là signature/stamp, đơn vị tính bằng px, chỉ hỗ trợ truyền số nguyên dương, mặc định là auto (tức hệ thống tự động xác định kích thước); 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 cho điều khiển chữ ký. Chỉ áp dụng khi fieldType là signature Các giá trị có thể nhập: template: Chữ ký mẫu handDrawn: Chữ ký vẽ tay upload: Tải lên hình ảnh chữ ký từ máy cục bộ Có thể chọn nhiều giá trị, phân cách bằng dấu ",", mặc định là 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í 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ác thành phầ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 dấu "-", các trang riêng lẻ được nối bằng dấu "," Ví dụ: 1-3,6-10 Truyền phạm vi trang nơi con dấu giáp lai được đóng khi pagingSealMode=assignedPages. Con dấu giáp lai chỉ có thể sử dụng cho 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 độ đề cập đến khu vực chữ kýGóc dưới bên trái; Nếu fieldType là stamp, thì vị trí tọa độ đề cập đến 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 độ chỉ điểm trung tâm của khu vực đó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 ở cạnh bên phải của tệp. |
| | | posY | float | false | Tọa độ trục y [Lưu ý] Nếu fieldType là signature, thì vị trí tọa độ chỉ khu vực ký tênGó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 độ 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 số 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 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 điều khiển văn bản |
| | | | overflowType | int | false | Chỉ có hiệu lực với text, mặc định là 1 1-Tự động thu nhỏ cỡ chữ 2-Hạn chế nhập liệu |
| | | | minFontSize | float | false | Chỉ có hiệu lực với text, chỉ có hiệu lực 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ỉ có hiệu lực với text, phông chữ, mặc định là Song thể (SimSun) 1-Song thể (SimSun) 2-Tân Song thể (SimSun New) 4-Hắc thể (SimHei) 5-Khải thể (KaiTi) 6-Arial 7-Helvetica 9-Times New Roman 10-Phỏng Tống (FangSong) 11-Georgia 12-Monospace |
| | | | fontSize | float | false | Chỉ có hiệu lực với text, cỡ 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 đen #000 |
| | | | bold | boolean | false | Chỉ áp dụng cho text, có in đậm font 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ó nghiêng font hay không, mặc định false true - Nghiêng false - Không nghiêng |
| | | | underline | boolean | false | Chỉ áp dụng cho text, có gạch chân font hay không, mặc định false true - Gạch chân false - Không gạch chân |
| | | | lineThrough | boolean | false | Chỉ áp dụng cho text, có gạch ngang (strike-through) hay không, mặc định false true - Gạch ngang false - Không gạch ngang |
| | | | horizontalAlignment | string | false | Chỉ áp dụng cho text, căn giữa theo chiều ngang, mặc định 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-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 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 phân cách bằng ",", ví dụ: 1-3, 6-10; Nếu không liên tục thì truyền vào "," để 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ợ định dạng chỉ định: yyyy năm MM tháng dd ngày yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MMM dd,yyyy dd MMM yyyy |