เพิ่มผู้ลงนาม

POST/esignglobal/v1/envelope/recipients/addSigners

คำอธิบายอินเทอร์เฟซ

เพิ่มผู้ลงนามในซองจดหมาย ผู้ลงนามคือภารกิจการลงนาม รวมถึงการเพิ่มการควบคุม วิธีการตรวจสอบสิทธิ์ และข้อมูลอื่นๆ สำหรับผู้ลงนาม

ข้อควรระวัง:

รองรับการเพิ่มผู้ลงนามใหม่หลังจากเปิดซองจดหมาย ลำดับการลงนามของผู้ลงนามที่เพิ่มใหม่ต้องไม่น้อยกว่าหรือเท่ากับค่าลำดับการลงนามของผู้ลงนามที่กำลังลงนาม
ไม่อนุญาตให้เพิ่มผู้ลงนามคนเดียวกันซ้ำ (โดยใช้อีเมลเป็นตัวระบุผู้ใช้ที่ไม่ซ้ำกัน) หากคุณต้องการอัปเดตข้อมูลภารกิจการลงนาม โปรดเพิ่มผู้ลงนามที่เกี่ยวข้องอีกครั้ง
ซองจดหมายหนึ่งซองสามารถมีผู้ลงนามได้สูงสุด 10 คนเท่านั้น

พารามิเตอร์คำขอ

ชื่อพารามิเตอร์					ประเภท	จำเป็น	คำอธิบาย
envelopeId					string	true	ID ซองจดหมาย
signerInfos					array	true	ชุดข้อมูลข้อมูลผู้ลงนาม
	businessId				string	false	หมายเลขธุรกิจที่ผู้พัฒนาปรับแต่งเอง ความยาว 500
	userEmail				string	true	ที่อยู่อีเมลของผู้ลงนาม
	phoneNumber				object	false	จำเป็นต้องกรอกเมื่อต้องการแจ้งเตือนทาง SMS ต้องใส่ทั้ง countryCode และ number ค่าเริ่มต้นคือค่าว่าง
		countryCode			string	false	รหัสสากลของประเทศ/ภูมิภาค ไม่จำเป็นต้องใส่ “+”
		number			string	false	ไม่ตรวจสอบรูปแบบ ความยาวสูงสุด 13 หลัก
	customizeSettings				object	false	การกำหนดค่าที่กำหนดเอง
		notificationSettings			object	false	การกำหนดค่าแบบกำหนดเองสำหรับการแจ้งเตือน
			customizeMessage		string	false	การแจ้งเตือนข้อความพิเศษ จำกัด 200 ตัวอักษร
			notificationLanguage		string	false	ภาษาของการแจ้งเตือน ค่าเริ่มต้นคือภาษาอังกฤษ en-US ภาษาอังกฤษ zh-CN ภาษาจีนตัวย่อ zh-Hant ภาษาจีนตัวเต็ม ja-JP ภาษาญี่ปุ่น ES-MX ภาษาสเปน
	userName				string	true	ชื่อผู้ลงนาม ใช้สำหรับแสดงชื่อผู้ลงนามในหน้าลงนามและขั้นตอน 【ข้อควรระวัง】ห้ามมีอักขระพิเศษ 9 ตัวต่อไปนี้: / \ : * " < > \| ？และอีโมจิทั้งหมด
	signOrder				int	true	ลำดับการลงนามของผู้ลงนาม ค่าต่ำสุดคือ 1 การลงนามแบบไม่เรียงลำดับสามารถระบุค่าลำดับเดียวกันได้
	anySigner				boolean	false	รองรับการลงนามโดยบุคคลใดบุคคลหนึ่งหรือไม่ ค่าเริ่มต้นคือ false true-signOrder เดียวกันต้องการเพียงหนึ่งคนลงนาม false-signOrder เดียวกันทุกคนต้องลงนาม
	authModes				string	false	วิธีการตรวจสอบสิทธิ์ ค่าเริ่มต้นคือ noAuth ประเภทการแจงนับ: noAuth- ไม่มีการตรวจสอบ accessCode- ใช้การตรวจสอบรหัสผ่านการลงนาม sms- การตรวจสอบ SMS OTP idVerification- การตรวจสอบเอกสารประจำตัว emailAuth- การตรวจสอบ OTP ทางอีเมล digitalId- การตรวจสอบ ID อิเล็กทรอนิกส์
	authConfig				object	false	ตั้งค่าวิธีการตรวจสอบ
		accessCode			object	false	ตั้งค่ารหัสผ่านการลงนาม เมื่อ authModes=accessCodeจำเป็นต้องกรอก
			accessCode		string	false	เนื้อหารหัสผ่าน ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ สามารถมีตัวอักษรและตัวเลข ความยาว 45
			promptInfo		string	false	ข้อความแจ้งเตือนรหัสผ่านการเข้าถึง ห้ามมีรหัสผ่านการเข้าถึง ความยาวจำกัด 30 เมื่อ authModes=accessCodeจำเป็นต้องกรอก
		sms			object	false	การตรวจสอบ SMS OTP เมื่อ authModes=smsจำเป็นต้องกรอก
			countryCode		string	false	รหัสสากลของประเทศ/ภูมิภาค ไม่ต้องใส่ "+"
			number		string	false	ไม่ตรวจสอบรูปแบบ ความยาวสูงสุด 13 หลัก
		idVerification			object	false	การตั้งค่าการตรวจสอบเอกสารประจำตัว เมื่อ authModes=idVerificationจำเป็นต้องกรอก
			name		string	false	ชื่อเต็มบนเอกสารประจำตัวของผู้ลงนาม ความยาวสูงสุด 100 ตัวอักษร
		emailAuth			object	false	การตรวจสอบ OTP ทางอีเมล เมื่อ authModes=emailAuthจำเป็นต้องกรอก
			authEmail		string	false	ที่อยู่อีเมลสำหรับตรวจสอบยืนยันตัวตนของผู้ลงนาม
		digitalId			array	false	การตรวจสอบสิทธิ์ทางอิเล็กทรอนิกส์ จำเป็นต้องระบุเมื่อ authModes=digitalId
			authApp		string	false	แอปที่ใช้สำหรับการตรวจสอบสิทธิ์ทางอิเล็กทรอนิกส์ singpass - ใช้ Singpass เพื่อตรวจสอบสิทธิ์
			idNumber		string	false	หมายเลขประจำตัวประชาชนของผู้ลงนามที่รอการตรวจสอบสิทธิ์
	digitalSignature				boolean	false	เปิดใช้งานลายเซ็นดิจิทัลหรือไม่ ค่าเริ่มต้นคือ false true- เปิดใช้งาน false- ไม่เปิดใช้งาน
	freeFormSign				boolean	false	ผู้ลงนามมีอิสระในการประทับตราหรือไม่ ค่าเริ่มต้นคือ false คำอธิบายเพิ่มเติม: เมื่อเลือก freeFormSign เป็น true พารามิเตอร์อื่นๆ ภายใต้ sealInfos ไม่จำเป็นต้องส่ง หากส่งพร้อมกัน freeFormSign จะมีความสำคัญเหนือกว่า sealInfos และพารามิเตอร์ภายใต้ sealInfos จะไม่มีผล 【ข้อควรระวัง】การประทับตราอิสระคือการไม่จำกัดจำนวนและตำแหน่งของตราประทับ/ลายเซ็นที่ผู้ลงนามสามารถลากเข้ามาได้
	sealInfos				array	false	ข้อมูลงานลงนาม
		fileKey			string	true	ไฟล์คีย์เอกสารลงนาม
		signConfigs			array	false	ข้อมูลตำแหน่งของตัวควบคุม ต้องระบุข้อมูลตำแหน่งของตัวควบคุมเพื่อทำการลงนามอิเล็กทรอนิกส์
			fieldType		string	false	ประเภทของคอนโทรล, สามารถใส่พารามิเตอร์ได้: signature- คอนโทรลลายเซ็น stamp- คอนโทรลตราประทับ approval- คอนโทรลการอนุมัติ ค่าเริ่มต้นคือ signature
			sizeRule		string	false	วิธีการแสดงขนาดพื้นที่ลงนาม originalSize- ลงตราตามขนาดจริงของลายเซ็น/ตราประทับ targetSize- กำหนดความกว้างและความสูงของพื้นที่ลายเซ็น/ตราประทับเอง เมื่อ sizeRule, height, width เป็นค่าว่างทั้งหมด จะลงตราตามขนาดจริงของลายเซ็น/ตราประทับ เมื่อ sizeRule ว่างเปล่า แต่ height และ width ไม่ว่างเปล่า จะทำการประทับตราตามขนาดที่กำหนด เมื่อ sizeRule ไม่ว่างเปล่า จะทำการประทับตราตามวิธีการแสดงผลที่ระบุ
			height		int	false	ความสูงของส่วนควบคุมการลงนาม เหมาะสำหรับ fieldType เป็น signature/stamp หน่วยเป็น px รองรับเฉพาะจำนวนเต็มบวกเท่านั้น ค่าเริ่มต้นคือ auto (ขนาดอัตโนมัติของระบบ) เมื่อ fieldType=signature สามารถตั้งค่าช่วงได้ตั้งแต่ 20-250px เมื่อ fieldType=stamp สามารถตั้งค่าช่วงได้ตั้งแต่ 30-280px
			width		int	false	ความกว้างของส่วนควบคุมการลงนาม เหมาะสำหรับ fieldType เป็น signature/stamp หน่วยเป็น px รองรับเฉพาะจำนวนเต็มบวกเท่านั้น ค่าเริ่มต้นคือ auto (ขนาดอัตโนมัติของระบบ) เมื่อ fieldType=signature สามารถตั้งค่าช่วงได้ตั้งแต่ 20-250px เมื่อ fieldType=stamp สามารถตั้งค่าช่วงได้ตั้งแต่ 30-280px
			signatureOptions		string	false	ตัวเลือกการควบคุมลายเซ็น ใช้ได้เฉพาะกับ fieldType ที่เป็น signature เท่านั้น สามารถใส่พารามิเตอร์: template handDrawn upload สามารถเลือกได้หลายรายการ โดยคั่นด้วย "," ค่าเริ่มต้นคือเลือกทั้งหมด
			movable		boolean	false	อนุญาตให้ย้ายตำแหน่งขณะลงนาม ค่าเริ่มต้นคือ false false-ไม่อนุญาตให้ผู้ลงนามปรับตำแหน่งการควบคุมการลงนามของตนเอง true-อนุญาตให้ผู้ลงนามปรับตำแหน่งการควบคุมการลงนามของตนเอง
			allowedOptions		array	false	ตัวเลือกสำหรับผู้อนุมัติที่สามารถอนุมัติได้ ใช้ได้กับ fieldType ที่เป็น approval ค่าเริ่มต้นคือ ["approve", "decline"] approve- อนุมัติ decline- ปฏิเสธ
			pageNo		string	false	หมายเลขหน้าสำหรับลงนาม; ใช้ "-" เพื่อเชื่อมต่อหมายเลขหน้าที่ต่อเนื่องกัน และใช้ "," เพื่อเชื่อมต่อหมายเลขหน้าเดี่ยว เช่น 1-3, 6-10
			posX		string	false	พิกัดแกน X คำอธิบายเพิ่มเติม: หาก fieldType เป็น signature ตำแหน่งพิกัดจะหมายถึงบริเวณลายเซ็นมุมล่างซ้าย； หาก fieldType เป็น stamp ตำแหน่งพิกัดจะหมายถึงบริเวณตราประทับจุดศูนย์กลางตำแหน่ง ตั้งแต่วันที่ 3 กุมภาพันธ์ 2026 เป็นต้นไป หาก fieldType เป็น signature หรือ stamp ตำแหน่งพิกัดจะหมายถึงตำแหน่งจุดศูนย์กลางของบริเวณตราประทับ
			posY		string	false	พิกัดแกน Y คำอธิบายเพิ่มเติม: หาก fieldType เป็น signature ตำแหน่งพิกัดจะหมายถึงบริเวณลายเซ็นมุมล่างซ้าย； หาก fieldType เป็น stamp ตำแหน่งพิกัดจะหมายถึงบริเวณตราประทับจุดศูนย์กลางตำแหน่ง ตั้งแต่วันที่ 3 กุมภาพันธ์ 2026 เป็นต้นไป fieldType เป็น signature หรือ stamp ตำแหน่งพิกัดหมายถึงตำแหน่งจุดศูนย์กลางของพื้นที่ประทับตรา
		fillConfigs			array	false	กรอกข้อมูลการควบคุม
			fieldName		string	false	ชื่อการควบคุม จำกัดจำนวนอักขระ 128 ตัว
			required		boolean	false	จำเป็นต้องกรอกหรือไม่ ค่าเริ่มต้นคือต้องกรอก true-จำเป็นต้องกรอก false-ไม่บังคับ
			fieldType		string	false	ประเภทของส่วนควบคุม: 1-ข้อความบรรทัดเดียว 15-ช่องทำเครื่องหมาย
			textField		object	false	คุณสมบัติของส่วนควบคุมข้อความ
				overflowType	int	false	มีผลกับ text เท่านั้น ค่าเริ่มต้นคือ 1 1-ลดขนาดตัวอักษรโดยอัตโนมัติ 2-จำกัดการป้อนข้อมูล
				minFontSize	float	false	มีผลกับ text เท่านั้น มีผลกับ overflowType=1 เท่านั้น ค่าเริ่มต้นคือ 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	ความกว้างของคอนโทรล ค่าเริ่มต้นคือ 160px
				font	int	false	ใช้ได้เฉพาะกับข้อความเท่านั้น แบบอักษร ค่าเริ่มต้นคือ 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	มีผลเฉพาะกับข้อความ ขนาดตัวอักษร ค่าเริ่มต้นคือ 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	มีผลเฉพาะกับข้อความ สีฐานสิบหก ค่าเริ่มต้นคือสีดำ #000
				bold	boolean	false	มีผลเฉพาะกับข้อความ ตัวอักษรเป็นตัวหนาหรือไม่ ค่าเริ่มต้นคือ false true-ตัวหนา false-ไม่เป็นตัวหนา
				italic	boolean	false	มีผลเฉพาะกับข้อความเท่านั้น ตัวเอียงหรือไม่ ค่าเริ่มต้นคือ false true-ตัวเอียง false-ไม่เอียง
				underline	boolean	false	มีผลเฉพาะกับข้อความเท่านั้น เพิ่มขีดเส้นใต้ให้กับแบบอักษรหรือไม่ ค่าเริ่มต้นคือ false true-เพิ่มขีดเส้นใต้ false-ไม่เพิ่มขีดเส้นใต้
				lineThrough	boolean	false	มีผลเฉพาะกับ text เท่านั้น เพิ่มหรือลบเส้นขีดฆ่าหรือไม่ ค่าเริ่มต้นคือ false true-เพิ่มเส้นขีดฆ่า false-ไม่เพิ่มเส้นขีดฆ่า
				horizontalAlignment	string	false	มีผลเฉพาะกับ text เท่านั้น รูปแบบจัดกึ่งกลางแนวนอน ค่าเริ่มต้นคือ left LEFT-ชิดซ้าย CENTER-กึ่งกลาง RIGHT-ชิดขวา
			tickBoxField		object	false	คุณสมบัติช่องทำเครื่องหมาย
				tickOptions	array	false	มีผลเฉพาะกับ Check เท่านั้น ค่าเริ่มต้นคือ 1 1-เครื่องหมายถูก 2-กากบาท
			posX		float	false	พิกัด X ของตำแหน่งวิดเจ็ต
			posY		float	false	ตำแหน่งแกน Y ของคอนโทรล
			pageNo		string	false	หมายเลขหน้าของคอนโทรล
		signDateConfigs			array	false	ข้อมูลตำแหน่งวันที่ลงนาม
			movable		boolean	false	อนุญาตให้ย้ายตำแหน่งเมื่อลงนาม ค่าเริ่มต้นคือ false false- ไม่อนุญาตให้ผู้ลงนามปรับตำแหน่งคอนโทรลการลงนามของตนเอง true- อนุญาตให้ผู้ลงนามปรับตำแหน่งของตัวควบคุมการลงนามของตนเอง
			pageNo		string	false	หมายเลขหน้าสำหรับลงนาม; หมายเลขหน้าที่ต่อเนื่องเชื่อมต่อด้วย "-", หมายเลขหน้าเดี่ยวเชื่อมต่อด้วย "," เช่น: 1-3, 6-10 หากไม่ต่อเนื่องให้ป้อน "," เพื่อแบ่ง
			posX		float	false	ค่าชดเชยแกน x โดยที่มุมล่างซ้ายของหน้าเป็นจุดกำเนิดของพิกัด
			posY		float	false	ค่าชดเชยแกน y โดยที่มุมล่างซ้ายของหน้าเป็นจุดกำเนิดของพิกัด
			signDateFormat		string	false	รูปแบบวันที่ลงนาม รูปแบบเริ่มต้นคือ yyyy-MM-dd รองรับรูปแบบที่กำหนด: yyyy年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

ตัวอย่างคำขอ

{
    "envelopeId": "{{envelope-id}}",
    "signerInfos": [
        {
    	   "userEmail": "sender_user@esignglobal.com",
    	   "userName": "sender_user_name",
    	   "signOrder": 1,
    	   "authModes": "sms",
           "authConfig": {
                "sms": {
                    "countryCode": "86",
                    "number": "158****9242"
                }
            },
            "sealInfos": [
                {
                    "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
                    "signConfigs": [
                        {
                           "fieldType": "stamp",
                            "pageNo": "1",
                            "posX": 100.22,
                            "posY": 100
                        }
                    ],
                    "fillConfigs": [
                        {
                            "fieldId": "df0dd777bcc4d108de242d",
                            "fieldKey": "demo",
                            "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": "96e6c7d414f04e98938ea84013b",
                            "fieldKey": "红色加深斜体下划线删除线",
                            "pageNo": "1",
                            "posX": 94.516624,
                            "posY": 284.54953,
                            "fieldType": "1",
                            "required": false,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 10.5,
                                "font": "1",
                                "fontSize": 12.0,
                                "textColor": "#E25041",
                                "bold": true,
                                "italic": true,
                                "lineThrough": true,
                                "horizontalAlignment": "LEFT"
                            }
                        },
                        {
                            "fieldId": "888b899853544c49bd819d9f6d1",
                            "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"
                    ]
                }
            ]
        }
    ]
}

พารามิเตอร์การตอบสนอง

ชื่อพารามิเตอร์			ประเภท	คำอธิบาย
envelopeId			string	ID ซองจดหมาย
signFiles			array	ชุดเอกสารลงนาม
	fileKey		string	fileKey เอกสารลงนาม
attachments			array	ชุดไฟล์แนบซองจดหมาย
	fileKey		string	fileKey ไฟล์
signerInfos			array	ชุดข้อมูลผู้ลงนาม
	businessId		string	หมายเลขธุรกิจที่กำหนดเองของผู้พัฒนา ความยาว 500
	userEmail		string	ที่อยู่อีเมลของผู้ลงนาม
	userName		string	ชื่อผู้ลงนาม
	signOrder		int	ลำดับโหนดของผู้ลงนาม, ขั้นต่ำคือ 1
		accessCode	string	รหัสผ่านการเข้าถึงหน้าลงนาม

ตัวอย่างการตอบสนอง

{
    "code": "0",
    "data": {
        "signerInfos": [
            {
                "organizationName": "Esign Global CO.",
                "userLastName": "",
                "accessCode": "",
                "userEmail": "sender_user@tsign.cn",
                "userFirstName": "",
                "signOrder": "1"
            }
        ],
        "signFiles": [
            {
                "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
            }
        ],
        "attachments": [

        ],
        "envelopeId": "9fbe6c8190824227bde29136b0145c81"
    },
    "message": "success"
}