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 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 chữ
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à tiếng Anh 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
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ệp
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	true	Đị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 cảm xúc 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 “+”
		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 loại 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à tiếng Anh en-US Tiếng Anh zh-CN Tiếng Trung giản thể zh-Hant Tiếng Trung phồn thể ja Tiếng Nhật ES-MX Tiếng Tây Ban Nha
	signOrder				int	true	Thứ tự ký của người ký, tối thiểu là 1. Có thể chỉ định giá trị thứ tự giống nhau cho ký không theo 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 ký trong cùng một signOrder 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 thực OTP SMS idVerification- Xác thực giấy tờ tùy thân emailAuth- Xác thực OTP Email digitalId- Xác thực danh tính điện tử
	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ý, khi authModes=accessCodethì bắt buộc
			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 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, bắt buộc khi authModes=1.
		sms			object	false	Xác thực SMS OTP, khi authModes=smsthì bắt buộc
			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 thực giấy tờ tùy thân, khi authModes=idVerificationthì bắt buộc
			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 OTP qua email, 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ử, khi authModes=digitalId thì bắt buộc phải điền
			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
			idNumber		string	false	Số giấy tờ tùy thân của người ký cần xác minh
	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 thêm: 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 ý]Tự do đóng dấu có nghĩa là không giới hạn số lượng và vị trí hình dấu/chữ ký mà người ký có thể kéo vào
	sealInfos				array	false	Ký thông tin nhiệm vụ
		fileKey			string	true	Ký file tài liệu fileKey
		signConfigs			array	false	Thông tin vị trí điều khiển, phải chỉ định thông tin vị trí của đ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	Phương thức 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 cao và chiều rộng 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 đượ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ể đặt là 20-250px; Khi fieldType=stamp, phạm vi có thể được đặ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 đặt là 20-250px; Khi fieldType=stamp, phạm vi có thể được đặ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 lên ảnh chữ ký cục bộ 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í điều khiển ký của riêng họ true - Cho phép người ký điều chỉnh vị trí điều khiển ký của riêng 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	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 【Lưu ý】Nếu fieldType là signature, 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, 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, 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.
			posY		float	false	Tọa độ trục y 【Lưu ý】Nếu fieldType là signature, 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, 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, fieldType là signature hoặc stamp, vị trí tọa độ của nó đề cập đến vị trí 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 đối 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
				minFontSize	float	false	Chỉ có hiệu lực đối với text, chỉ có hiệu lực đối 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 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à SimSun 1-SimSun 2-NSimSun 4-Heiti 5-Kaiti 6-Arial 7-Helvetica 9-Times New Roman 10-Fangsong 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ỉ áp dụng cho text, có thêm gạch dưới cho font chữ hay không, mặc định là false true - Thêm gạch dưới false - Không thêm gạch dưới
				lineThrough	boolean	false	Chỉ áp dụng cho text, có thêm gạch ngang (strikethrough) 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, đị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ỉ áp dụng cho tickBox, mặc định là 1 1 - Đánh dấu 2 - Chữ thập
			posX		float	false	Tọa độ X vị trí của đ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 dưới bên trái của trang là gốc tọa độ
			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 CC
	userEmail	string	Địa chỉ email người nhận CC
	userName	string	Tên người nhận CC
signFiles		array	Tập hợp thông tin tài liệu ký
	fileKey	string	fileKey của tài liệu ký
attachments		array	Tập hợp tệp đính kèm phong bì
	fileKey	string	fileKey của tệp
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ý, nhỏ nhất 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"
}