Khởi tạo phong bì nhanh chóng

POST /esignglobal/v1/envelope/createAndStart

Mô tả giao diện

Khởi tạo phong bì nhanh chóng, bao gồm các chức năng như tạo phong bì, thêm tài liệu chờ ký, thêm người ký, v.v.

Hỗ trợ tự động mở：Sau khi gọi giao diện thành công, phong bì sẽ được tạo và mở thành công, lúc này phong bì sẽ tự động bắt đầu luân chuyển.
Hỗ trợ tự động kết thúc：Sau khi tất cả các bên ký hoàn tất việc ký, phong bì sẽ tự động kết thúc.

Tham số yêu cầu

Tên tham số					Loại	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 được phép cho người ký
	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ỉ có hiệu lực đối với chữ ký 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ì, phong bì sẽ hết hạn sau bao nhiêu giây 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 500), phải tuân thủ địa chỉ giao thức https.
sendLaterAfterSeconds					long	false	Hỗ trợ người dùng gửi chậm, tính bằng giây Phạm vi thời gian hỗ trợ: 3600 giây (1 giờ) ~ 259200 giây (30 ngày)
CCInfos					array	false	Tập hợp thông tin người nhận bản sao
	userEmail				string	false	Địa chỉ email của người nhận bản sao
	userName				string	false	Tên người nhận bản sao, được sử dụng để hiển thị tên người nhận bản sao 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
	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 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ý, thứ tự hiển thị là 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
attachments					array	false	Tập hợp tệp đính kèm phong bì, thứ tự hiển thị là thứ tự thêm tài liệu.
	fileKey				string	false	FileKey của tài liệu
signerInfos					array	true	Tập hợp thông tin người ký
	businessId				string	false	Số nghiệp vụ tùy chỉnh của nhà phát triển, giới hạn độ dài 500
	deliveryMethods				string	false	Phương thức thông báo, mặc định là auto auto- Gửi thông báo qua email khi truyền userEmail, gửi thông báo qua SMS khi truyền phoneNumber none- Không gửi thông báo email- Gửi thông báo qua email sms- Gửi thông báo qua 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ý, được sử dụng để hiển thị tên người ký trên trang ký và phong bì. 【注】Không được chứa 9 ký tự đặc biệt sau: / \ : * " < > \| ？và tất cả các biểu tượng emoji
	phoneNumber				object	false	Số điện thoại, mặc định là trống Khi cần thông báo qua SMS, đây là tham số bắt buộc, cần truyền cả countryCode và number
		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 có 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 thông báo
			customizeMessage		string	false	Thông báo tin nhắn riêng, giới hạn 200 ký tự
			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 Malay 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ý, nhỏ nhất 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 một signOrder ký false-Tất cả mọi người trong cùng một 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-Sử dụng mật khẩu ký để xác minh sms-Xác minh OTP SMS idVerification-Xác minh bằng 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 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=accessCodethì bắt buộc phải điền
			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ữ và số, giới hạn độ dài 45
			promptInfo		string	false	Thông tin gợi ý 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, khi authModes=accessCodethì bắt buộc phải điền.
		sms			object	false	Xác minh SMS OTP, khi authModes=smsthì bắt buộc phải điền
			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 13 ký tự
		idVerification			object	false	Cài đặt xác minh giấy tờ tùy thân, khi authModes=idVerificationthì bắt buộc phải điền
			name		string	false	Họ và 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 minh Email OTP, khi authModes=emailAuththì bắt buộc phải điền
			authEmail		string	false	Địa chỉ email xác minh danh tính của 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- Xác thực bằng Singpass iamsmart- Xác thực bằng i AM Smart
			idNumber		string	false	Số CMND/CCCD của người ký chờ xác minh Khi authApp=singpassthì quy tắc truyền vào là: Chữ in hoa + 7 hoặc 8 chữ số + Chữ in hoa Khi authApp=iamsmartthì quy tắc truyền vào 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 đầ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 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 vào 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 chữ số
	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 ký tên hay không, giá trị mặc định là false Giải thích bổ sung: Khi chọn freeFormSign là true, không cần truyền các tham số khác trong sealInfos. Nếu đồng thời truyền, freeFormSign sẽ có mức độ ưu tiên cao hơn sealInfos, các tham số trong sealInfos sẽ không có hiệu lực 【Lưu ý】Ký tự do 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 vào
	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, phải chỉ định thông tin vị trí điều khiển thì mới có thể thực hiện chữ 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
			sizeRule		string	false	Cách hiển thị kích thước khu vực ký originalSize- Đóng 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 của khu vực chữ ký/con dấu Khi sizeRule, height, width đều trống, đóng dấu theo kích thước thực tế của chữ ký/con dấu; Khi sizeRule trống, height, width không trống, đóng dấu theo kích thước chỉ định; Khi sizeRule không trống, đóng dấu theo phương thức hiển thị được chỉ định.
			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 là kích thước tự động của hệ thống); Khi fieldType=signature, phạm vi có thể cài đặt là 20-250px; Khi fieldType=stamp, phạm vi có thể cài đặt là 30-280px;
			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 là kích thước tự động của hệ thống); Khi fieldType=signature, phạm vi có thể cài đặt là 20-250px; Khi fieldType=stamp, phạm vi có thể cài đặt là 30-280px;
			signatureOptions		string	false	Tùy chọn điều khiển chữ ký. Chỉ áp dụng cho fieldType là signature Có thể nhập tham số: template：Chữ ký mẫu handDrawn：Chữ ký vẽ tay upload：Tải ảnh chữ ký lên từ máy tính Có thể chọn nhiều, phân tá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í các điều khiển ký của họ true - Cho phép người ký điều chỉnh vị trí các điều khiển ký của họ
			allowedOptions		array	false	Các tùy chọn cho phép người ký phê duyệt, áp dụng cho 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
			posX		float	false	Tọa độ trục x 【Chú ý】Nếu fieldType là signature, vị trí tọa độ chỉ khu vực chữ kýGóc dưới bên trái； Nếu fieldType là stamp, 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, fieldType là signature hoặc stamp, vị trí tọa độ của nó chỉ vị trí tâm của khu vực đóng dấ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, fieldType là signature hoặc stamp, vị trí tọa độ của nó đề cập đến vị trí điểm trung tâm của khu vực đóng dấu.
		fillConfigs			array	false	Điền thông tin điều khiển
			fieldName		string	false	Tên điều khiển, giới hạn 128 ký 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
			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 giảm kích thước phông 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 với 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 đ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à 宋体 1-宋体 2-新宋体 4-黑体 5-楷体 6-Arial 7-Helvetica 9-Times New Roman 10-仿宋 11-Georgia 12-Monospace
				fontSize	float	false	Chỉ có hiệu lực với 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ỉ có hiệu lực với text, màu hệ thập lục phân, mặc định là màu đen #000
				bold	boolean	false	Chỉ có hiệu lực với text, phông chữ có được in đậm hay không, mặc định là false true-In đậm false-Không in đậm
				italic	boolean	false	Chỉ có hiệu lực với 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ỉ có hiệu lực với text, có thêm gạch chân cho phông chữ 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ỉ có hiệu lực với text, có thêm đường gạch ngang hay không, mặc định là false true-Thêm đường gạch ngang false-Không thêm đường gạch ngang
				horizontalAlignment	string	false	Chỉ có hiệu lực với text, định dạng 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ỉ có hiệu lực đối với 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 là false false-Không cho phép người ký điều chỉnh vị trí điều khiển ký của họ true-Cho phép người ký điều chỉnh vị trí điều khiển ký của họ
			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 tục, hãy truyền vào "," để phân tách.
			posX		float	false	Độ lệch trục x, góc dưới bên trái của trang là gốc tọa độ
			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 được chỉ định: yyyy năm MM tháng dd ngày yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

Ví dụ yêu cầu

{
    "subject": "员工入职合约",
    "remark": "这是描述",
    "expireAfterSeconds": 86400,
    "redirectUrl": "https://app-sml.esignglobal.com/home/main/esign/contract/list/inbox",
    "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
    "signerInfos": [
      {
        "userEmail": "sender_user@tsign.cn",
        "userName": "sender_user_name",
        "phoneNumber": {
        	"countryCode": "86",
        	"number": "158****9242"
        }
        "signOrder": 1,
        "authModes": "sms",
        "authConfig": {
            "sms": {
                "countryCode": "86",
                "number": "158****9242"
            }
        },
        "sealInfos": [
        {
            "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
            "signConfigs": [
              {
                "fieldType": "stamp",
                "pageNo": "1,3-5",
                "posX": 100.22222,
                "posY": 100.11111
              }
              "fillConfigs": [
              {
                "fieldId": "df0dd777bc774a2ba3fec4d108de242d",
                "fieldKey": "必填单行文本自动缩小字号最小字号Arial",
                "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": "888b899853544c49bd819d9f6d1e52cf",
                  "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"
              }
            ]
        }
      ]
    }
  ]
}

Tham số phản hồi

Tên tham số		Loại	Mô tả
envelopeId		string	ID phong bì
CCInfos		array	Tập hợp thông tin người nhận bản sao
	userEmail	string	Địa chỉ email của người nhận bản sao
	userName	string	Tên người nhận bản sao
signFiles		array	Tập hợp thông tin tệp ký
	fileKey	string	fileKey của tệp ký
attachments		array	Tập hợp các tệp đính kèm phong bì
	fileKey	string	Tệp fileKey
signerInfos		array	Thông tin ký
	businessId	string	Số nghiệp vụ tùy chỉnh của nhà phát triển, giới hạn độ dài 500
	userEmail	string	Địa chỉ email của người ký
	userName	string	Tên người ký
	signUrl	string	Địa chỉ liên kết ký
	signOrder	int	Thứ tự ký của người ký, tối thiểu là 1
	accessCode	string	Mật khẩu truy cập trang ký

Ví dụ phản hồi

{
  "code": "0",
    "data": {
    "signerInfos": [
      {
        "accessCode": "123456",
        "userEmail": "sender_user@tsign.cn",
        "signUrl": "http://app-test.esignglobal-inc.com/home/main/sign/start/base/dosign?envelopeId=4cd738a60225445f9d5f3afec468a639&signature=eyJhbGciOiJIUzI1NiIsInppcCI6IkRFRiJ9.eNqqVkrOzytJrShRsqpWSs0rS83JL0gNSSzO9kxRslJKtjC1MDKxTDVIMzA0SU4xSTIwNjAxSDRNTTVKMTIxTFOqrQUAAAD__w.YMBA5X9O8Ylk7x2rma-s1WxGwo2cjqy-O9CCQopzw88&tenantToken=AA0DDgQ0Y2Q3MzhhNjAyMjU0NDVmOWQ1ZjNhZmVjNDY4YTYzuQ4GNGNkNzM4YTYwMjI1NDQ1ZjlkNWYzYWZlYzQ2OGE2M7kOCjRjZDczOGE2MDIyNTQ0NWY5ZDVmM2FmZWM0NjhhNjO5AIBjNDIwMzg1ZDMyYzU0MGE4YTk1ZTE3ZTNkZmZjMDNm4g%3D%3D",
        "userName": "sender_user_name",
        "signOrder": "1"
      }
    ],
      "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
      "envelopeId": "4cd738a60225445f9d5f3afec468a639"
  },
  "message": "success"
}