Tambah Penandatangan

POST/esignglobal/v1/envelope/recipients/addSigners

Deskripsi Antara Muka

Menambah penandatangan ke dalam sampul surat, di mana penandatangan adalah tugas menandatangani. Ini termasuk menambah kawalan, kaedah pengesahan identiti, dan maklumat lain untuk penandatangan.

Perhatian:

Menyokong penambahan penandatangan baharu selepas sampul surat dibuka. Urutan menandatangani penandatangan baharu yang ditambah tidak boleh kurang daripada atau sama dengan nilai urutan menandatangani mana-mana penandatangan yang sedang menandatangani.
Penandatangan yang sama (dengan e-mel sebagai pengecam unik pengguna) tidak dibenarkan ditambah berulang kali. Jika anda perlu mengemas kini maklumat tugas menandatangani, sila tambah semula penandatangan yang sepadan.
Paling banyak hanya 10 penandatangan dibenarkan dalam satu sampul surat.

Parameter Permintaan

Nama Parameter					Jenis	Diperlukan	Keterangan
envelopeId					string	true	ID Sampul Surat
signerInfos					array	true	Koleksi Maklumat Penandatangan
	businessId				string	false	Nombor perniagaan tersuai pembangun, panjang 500
	userEmail				string	true	Alamat e-mel penandatangan
	phoneNumber				object	false	Wajib diisi apabila pemberitahuan SMS diperlukan, countryCode dan number perlu dimasukkan sebagai parameter, lalai adalah kosong
		countryCode			string	false	Kod antarabangsa negara/rantau, tidak perlu memasukkan “+”
		number			string	false	Tidak melakukan pengesahan format, panjang maksimum ialah 13 digit
	customizeSettings				object	false	Konfigurasi tersuai
		notificationSettings			object	false	Konfigurasi Tersuai Jenis Pemberitahuan
			customizeMessage		string	false	Pemberitahuan mesej eksklusif, had aksara 200
			notificationLanguage		string	false	Bahasa pemberitahuan, lalai ialah Bahasa Inggeris en-US Bahasa Inggeris zh-CN Bahasa Cina Ringkas zh-Hant Bahasa Cina Tradisional ja-JP Bahasa Jepun ES-MX Bahasa Sepanyol
	userName				string	true	Nama penandatangan, digunakan untuk memaparkan nama penandatangan pada halaman dan proses tandatangan kepada pihak luar. 【Perhatian】Tidak boleh mengandungi 9 aksara khas berikut: / \ : * " < > \| ？dan semua emoji
	signOrder				int	true	Urutan tandatangan penandatangan, minimum ialah 1. Tandatangan tidak berurutan boleh menetapkan nilai urutan yang sama.
	anySigner				boolean	false	Sama ada menyokong mana-mana seorang untuk menandatangani, lalai ialah false true-Hanya seorang sahaja diperlukan untuk menandatangani dalam signOrder yang sama false-Semua orang dalam signOrder yang sama perlu menandatangani
	authModes				string	false	Kaedah pengesahan identiti, lalai ialah noAuth Jenis enum: noAuth-Tidak mengesahkan accessCode-Gunakan pengesahan kata laluan tandatangan sms-Pengesahan SMS OTP idVerification-Pengesahan dokumen pengenalan emailAuth- Pengesahan OTP E-mel digitalId- Pengesahan Identiti Elektronik
	authConfig				object	false	Tetapan Kaedah Pengesahan
		accessCode			object	false	Tetapan Kata Laluan Tandatangan, apabila authModes=accessCodediperlukan
			accessCode		string	false	Kandungan kata laluan, tidak mengira huruf besar atau kecil, boleh mengandungi huruf dan nombor, panjang 4-5
			promptInfo		string	false	Mesej gesaan kata laluan akses, tidak boleh mengandungi kata laluan akses, had panjang 30, apabila authModes=accessCodemesti diisi.
		sms			object	false	Pengesahan SMS OTP, apabila authModes=smsmesti diisi
			countryCode		string	false	Kod antarabangsa negara/rantau, tidak perlu membawa “+”
			number		string	false	Tidak melakukan pengesahan format, panjang maksimum ialah 13 digit
		idVerification			object	false	Tetapan pengesahan dokumen pengenalan diri, diperlukan apabila authModes=idVerification
			name		string	false	Nama penuh pada dokumen pengenalan diri penandatangan, panjang maksimum 100 aksara
		emailAuth			object	false	Pengesahan OTP e-mel, diperlukan apabila authModes=emailAuth
			authEmail		string	false	Alamat e-mel pengesahan identiti penandatangan
		digitalId			array	false	Pengesahan identiti elektronik, diperlukan apabila authModes=digitalId
			authApp		string	false	APP yang digunakan untuk pengesahan identiti elektronik singpass - Gunakan Singpass untuk pengesahan identiti
			idNumber		string	false	Nombor kad pengenalan yang menunggu untuk disahkan oleh penandatangan
	digitalSignature				boolean	false	Sama ada untuk menghidupkan tandatangan digital, lalai adalah false true-Dihidupkan false-Tidak diaktifkan
	freeFormSign				boolean	false	Sama ada penandatangan bebas menandatangani, nilai lalai ialah false Keterangan tambahan: Apabila freeFormSign dipilih sebagai true, parameter lain di bawah sealInfos tidak perlu dihantar. Jika dihantar pada masa yang sama, keutamaan freeFormSign adalah lebih tinggi daripada sealInfos, dan parameter di bawah sealInfos tidak akan berkuat kuasa. 【Perhatian】Tandatangan bebas bermaksud tiada had pada bilangan dan kedudukan cap/tandatangan yang boleh diseret masuk oleh penandatangan.
	sealInfos				array	false	Maklumat tugas tandatangan
		fileKey			string	true	Kunci fail dokumen tandatangan
		signConfigs			array	false	Maklumat lokasi kawalan, maklumat lokasi kawalan mesti ditentukan untuk melakukan tandatangan elektronik.
			fieldType		string	false	Jenis kawalan, parameter yang boleh dimasukkan: signature-Kawalan tandatangan stamp-Kawalan cap approval-Kawalan kelulusan Lalai ialah signature
			sizeRule		string	false	Kaedah paparan saiz kawasan tandatangan originalSize-Letakkan cap mengikut saiz sebenar tandatangan/cap targetSize-Sesuaikan lebar dan tinggi kawasan tandatangan/cap Apabila sizeRule, height, width semuanya kosong, letakkan cap mengikut saiz sebenar tandatangan/cap; Apabila sizeRule kosong, dan height, width tidak kosong, letakkan cop mengikut saiz yang ditetapkan; Apabila sizeRule tidak kosong, letakkan cop mengikut cara paparan yang ditetapkan.
			height		int	false	Ketinggian kawalan tandatangan, sesuai untuk fieldType signature/stamp, unit dalam px, hanya menyokong integer positif, lalai adalah auto (iaitu saiz automatik sistem); Apabila fieldType=signature, julat yang boleh ditetapkan ialah 20-250px; Apabila fieldType=stamp, julat yang boleh ditetapkan ialah 30-280px
			width		int	false	Lebar kawalan tandatangan, sesuai untuk fieldType signature/stamp, unit dalam px, hanya menyokong integer positif, lalai adalah auto (iaitu saiz automatik sistem); Apabila fieldType=signature, julat yang boleh ditetapkan ialah 20-250px; Apabila fieldType=stamp, julat yang boleh ditetapkan ialah 30-280px
			signatureOptions		string	false	Pilihan kawalan tandatangan. Hanya terpakai untuk fieldType signature. Boleh dimasukkan sebagai parameter: template handDrawn upload Boleh pilih berbilang, dipisahkan dengan ",", lalai ialah pilih semua
			movable		boolean	false	Benarkan lokasi dialihkan semasa menandatangani, lalai ialah false false-Tidak membenarkan penandatangan melaraskan kedudukan kawalan tandatangan mereka sendiri true-Membenarkan penandatangan melaraskan kedudukan kawalan tandatangan mereka sendiri
			allowedOptions		array	false	Pilihan untuk membenarkan penandatangan meluluskan, sesuai untuk fieldType sebagai approval. Lalai ialah ["approve", "decline"] approve-Setuju decline-Tolak
			pageNo		string	false	Nombor halaman tandatangan; nombor halaman berturut-turut disambungkan dengan "-", nombor halaman individu disambungkan dengan ",", contohnya: 1-3, 6-10
			posX		string	false	Koordinat paksi-X Keterangan tambahan: Jika fieldType ialah signature, maka kedudukan koordinat merujuk kepada kawasan tandatanganSudut kiri bawah； Jika fieldType ialah stamp, maka kedudukan koordinat merujuk kepada kawasan pengecapanTitik tengahKedudukan Bermula dari 3 Februari 2026, fieldType ialah signature atau stamp, kedudukan koordinatnya merujuk kepada kedudukan titik tengah kawasan pengecapan.
			posY		string	false	Koordinat paksi Y Keterangan tambahan: Jika fieldType ialah signature, maka kedudukan koordinat merujuk kepada kawasan tandatanganSudut kiri bawah； Jika fieldType ialah stamp, maka kedudukan koordinat merujuk kepada kawasan pengecapanTitik tengahLokasi Bermula dari 3 Februari 2026, fieldType ialah tandatangan atau setem, kedudukan koordinatnya merujuk kepada kedudukan titik tengah kawasan setem.
		fillConfigs			array	false	Isi maklumat kawalan
			fieldName		string	false	Nama kawalan, had bilangan aksara 128
			required		boolean	false	Adakah wajib diisi, lalai wajib diisi true-Wajib diisi palsu-Tidak Wajib
			fieldType		string	false	Jenis Kawalan: 1-Teks Satu Baris 15-Kotak Semak
			textField		object	false	Sifat Kawalan Teks
				overflowType	int	false	Hanya berkesan pada teks, lalai 1 1-Automatik kecilkan saiz fon 2-Hadkan input
				minFontSize	float	false	Hanya berkesan pada teks, hanya berkesan pada overflowType=1, lalai 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	Lebar kawalan, lalai 160px
				font	int	false	Hanya berkesan pada teks, fon, lalai adalah 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	Hanya berkesan pada teks, saiz fon, lalai 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	Hanya berkesan pada teks, warna heksadesimal, lalai hitam #000
				bold	boolean	false	Hanya berkesan pada teks, sama ada fon ditebalkan, lalai false true-tebal false-tidak tebal
				italic	boolean	false	Hanya berkesan pada teks, sama ada condong atau tidak, lalai adalah false true-condong false-tidak condong
				underline	boolean	false	Hanya berkesan pada teks, sama ada fon ditambah garis bawah atau tidak, lalai adalah false true-tambah garis bawah false-tidak tambah garis bawah
				lineThrough	boolean	false	Hanya berkesan pada teks, sama ada untuk menambah garis potong, lalai adalah false true - Tambah garis potong false - Tidak menambah garis potong
				horizontalAlignment	string	false	Hanya berkesan pada teks, format penjajaran mendatar, lalai adalah left LEFT - Sebelah kiri CENTER - Tengah RIGHT - Sebelah kanan
			tickBoxField		object	false	Atribut Kotak Semak
				tickOptions	array	false	Sah untuk Check sahaja, lalai 1 1-Tanda 2-Pangkah
			posX		float	false	Koordinat-X mendatar kedudukan kawalan
			posY		float	false	Koordinat-Y lokasi kawalan
			pageNo		string	false	Nombor halaman kawalan berada
		signDateConfigs			array	false	Maklumat lokasi tarikh tandatangan
			movable		boolean	false	Benarkan lokasi dipindahkan semasa menandatangani, lalai adalah false false-Tidak membenarkan penandatangan melaraskan lokasi kawalan tandatangan mereka sendiri true-Membenarkan penandatangan untuk melaraskan kedudukan kawalan tandatangan mereka sendiri
			pageNo		string	false	Nombor halaman tandatangan; nombor halaman berturutan disambungkan dengan "-", nombor halaman tunggal disambungkan dengan ",", contohnya: 1-3, 6-10 Jika tidak berturutan, masukkan "," untuk pemisahan
			posX		float	false	Ofset paksi-x, sudut kiri bawah halaman sebagai titik asal koordinat
			posY		float	false	Ofset paksi-y, sudut kiri bawah halaman sebagai titik asal koordinat
			signDateFormat		string	false	Format tarikh tandatangan, format lalai ialah yyyy-MM-dd Menyokong format yang ditentukan: yyyy年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

Contoh Permintaan

{
    "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"
                    ]
                }
            ]
        }
    ]
}

Parameter Respons

Nama Parameter			Jenis	Keterangan
envelopeId			string	ID Sampul Surat
signFiles			array	Koleksi Dokumen yang Ditandatangani
	fileKey		string	fileKey Dokumen yang Ditandatangani
attachments			array	Koleksi Lampiran Sampul Surat
	fileKey		string	fileKey Dokumen
signerInfos			array	Koleksi Maklumat Penandatangan
	businessId		string	Nombor perniagaan tersuai pembangun, panjang 500
	userEmail		string	Alamat e-mel penandatangan
	userName		string	Nama Penandatangan
	signOrder		int	Urutan nod penandatangan, minimum ialah 1
		accessCode	string	Kata laluan akses halaman tandatangan

Contoh Respons

{
    "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"
}