Tambahkan Penandatangan

POST/esignglobal/v1/envelope/recipients/addSigners

Deskripsi Antarmuka

Tambahkan penandatangan ke dalam amplop, penandatangan adalah tugas penandatanganan. Termasuk menambahkan kontrol, metode autentikasi, dan informasi lainnya untuk penandatangan.

Catatan:

Mendukung penambahan penandatangan baru setelah amplop dibuka. Urutan penandatanganan penandatangan baru yang ditambahkan tidak boleh kurang dari atau sama dengan nilai urutan penandatanganan penandatangan mana pun yang sedang menandatangani.
Penandatangan yang sama (dengan email sebagai pengenal unik pengguna) tidak boleh ditambahkan berulang kali. Jika Anda perlu memperbarui informasi tugas penandatanganan, harap tambahkan kembali penandatangan yang sesuai.
Hanya boleh ada maksimal 10 penandatangan dalam satu amplop.

Parameter Permintaan

Nama Parameter					Jenis	Wajib Diisi	Keterangan
envelopeId					string	true	ID Amplop
signerInfos					array	true	Kumpulan Informasi Penandatangan
	businessId				string	false	Nomor bisnis yang ditentukan khusus oleh pengembang, panjang 500
	userEmail				string	true	Alamat email penandatangan
	phoneNumber				object	false	Wajib diisi ketika pemberitahuan SMS diperlukan, countryCode dan number harus dimasukkan sebagai parameter, defaultnya kosong
		countryCode			string	false	Kode internasional negara/wilayah, tidak perlu memasukkan tanda “+”
		number			string	false	Tidak ada validasi format, panjang maksimum 13 digit
	customizeSettings				object	false	Konfigurasi khusus
		notificationSettings			object	false	Konfigurasi Kustom untuk Pemberitahuan
			customizeMessage		string	false	Pemberitahuan pesan eksklusif, batas karakter 200
			notificationLanguage		string	false	Bahasa pemberitahuan, defaultnya adalah bahasa Inggris en-US Bahasa Inggris zh-CN Bahasa Mandarin Sederhana zh-Hant Bahasa Mandarin Tradisional ja-JP Bahasa Jepang ES-MX Bahasa Spanyol
	userName				string	true	Nama penanda tangan, digunakan untuk menampilkan nama penanda tangan di halaman dan proses penandatanganan. 【Perhatian】Tidak boleh mengandung 9 karakter khusus berikut: / \ : * " < > \| ？dan semua emoji
	signOrder				int	true	Urutan penandatanganan penanda tangan, minimal 1. Untuk tanda tangan tidak berurutan, dapat menentukan nilai urutan yang sama.
	anySigner				boolean	false	Apakah mendukung penandatanganan oleh salah satu orang, defaultnya adalah false true - Hanya satu orang yang perlu menandatangani dalam signOrder yang sama false - Semua orang dalam signOrder yang sama harus menandatangani
	authModes				string	false	Metode verifikasi identitas, defaultnya adalah noAuth Tipe enumerasi: noAuth-Tidak ada verifikasi accessCode-Verifikasi menggunakan kata sandi penandatanganan sms-Verifikasi SMS OTP idVerification-Verifikasi dokumen identitas emailAuth- Verifikasi OTP Email digitalId- Verifikasi Identitas Elektronik
	authConfig				object	false	Pengaturan Metode Verifikasi
		accessCode			object	false	Pengaturan Kata Sandi Penandatanganan, wajib diisi ketika authModes=accessCodediaktifkan
			accessCode		string	false	Isi kata sandi, tidak membedakan huruf besar atau kecil, dapat berisi huruf dan angka, panjang 45
			promptInfo		string	false	Pesan petunjuk kata sandi akses, tidak boleh berisi kata sandi akses, batasan panjang 30, ketika authModes=accessCodewajib diisi.
		sms			object	false	Verifikasi SMS OTP, ketika authModes=smswajib diisi
			countryCode		string	false	Kode internasional negara/wilayah, tidak perlu menyertakan tanda “+”
			number		string	false	Tidak ada validasi format, panjang maksimum 13 digit
		idVerification			object	false	Pengaturan verifikasi identitas, wajib diisi ketika authModes=idVerification
			name		string	false	Nama lengkap penandatangan sesuai dengan identitas, panjang maksimum 100 karakter
		emailAuth			object	false	Verifikasi OTP email, wajib diisi ketika authModes=emailAuth
			authEmail		string	false	Alamat email verifikasi identitas penandatangan
		digitalId			array	false	Otentikasi identitas elektronik, wajib diisi ketika authModes=digitalId
			authApp		string	false	APP yang digunakan untuk otentikasi identitas elektronik singpass - Gunakan Singpass untuk otentikasi
			idNumber		string	false	Nomor identitas yang akan diverifikasi oleh penandatangan
	digitalSignature				boolean	false	Apakah akan mengaktifkan tanda tangan digital, defaultnya adalah false true- Diaktifkan false- Tidak diaktifkan
	freeFormSign				boolean	false	Apakah penandatangan bebas menandatangani, nilai default adalah false Catatan tambahan: Ketika freeFormSign dipilih sebagai true, parameter lain di bawah sealInfos tidak perlu diteruskan. Jika diteruskan secara bersamaan, prioritas freeFormSign lebih tinggi daripada sealInfos, dan parameter di bawah sealInfos tidak akan berlaku. [Perhatian] Tanda tangan bebas berarti tidak ada batasan jumlah dan posisi stempel/tanda tangan yang dapat diseret oleh penandatangan.
	sealInfos				array	false	Informasi tugas penandatanganan
		fileKey			string	true	FileKey dokumen yang ditandatangani
		signConfigs			array	false	Informasi posisi kontrol, informasi posisi kontrol harus ditentukan agar tanda tangan elektronik dapat dilakukan.
			fieldType		string	false	Tipe kontrol, dapat berupa parameter: signature- Kontrol tanda tangan stamp- Kontrol stempel approval- Kontrol persetujuan Defaultnya adalah signature
			sizeRule		string	false	Metode tampilan ukuran area penandatanganan originalSize- Jatuhkan stempel sesuai dengan ukuran sebenarnya tanda tangan/stempel targetSize- Kustomisasi tinggi dan lebar area tanda tangan/stempel Ketika sizeRule, height, dan width semuanya kosong, jatuhkan stempel sesuai dengan ukuran sebenarnya tanda tangan/stempel; Ketika sizeRule kosong, height, width tidak kosong, cap akan ditempatkan sesuai ukuran yang ditentukan; Ketika sizeRule tidak kosong, cap akan ditempatkan sesuai dengan metode tampilan yang ditentukan.
			height		int	false	Tinggi kontrol tanda tangan, berlaku untuk fieldType signature/stamp, satuan dalam px, hanya mendukung input bilangan bulat positif, default adalah auto (yaitu ukuran otomatis sistem); Ketika fieldType=signature, rentang yang dapat diatur adalah 20-250px; Ketika fieldType=stamp, rentang yang dapat diatur adalah 30-280px
			width		int	false	Lebar kontrol tanda tangan, berlaku untuk fieldType signature/stamp, satuan dalam px, hanya mendukung input bilangan bulat positif, default adalah auto (yaitu ukuran otomatis sistem); Ketika fieldType=signature, rentang yang dapat diatur adalah 20-250px; Ketika fieldType=stamp, rentang yang dapat diatur adalah 30-280px
			signatureOptions		string	false	Opsi kontrol tanda tangan. Hanya berlaku untuk fieldType signature. Parameter yang dapat dimasukkan: template handDrawn upload Dapat memilih banyak, dipisahkan dengan tanda ",", defaultnya adalah memilih semua
			movable		boolean	false	Izinkan memindahkan lokasi saat menandatangani, defaultnya adalah false false-Tidak mengizinkan penandatangan untuk menyesuaikan posisi kontrol tanda tangan mereka sendiri true-Mengizinkan penandatangan untuk menyesuaikan posisi kontrol tanda tangan mereka sendiri
			allowedOptions		array	false	Opsi yang memungkinkan penanda tangan untuk menyetujui, berlaku untuk fieldType approval. Standarnya adalah ["approve", "decline"] approve- Setuju decline- Tolak
			pageNo		string	false	Halaman tanda tangan; halaman berurutan dihubungkan dengan "-", halaman terpisah dihubungkan dengan ",", contoh: 1-3, 6-10
			posX		string	false	Koordinat sumbu X Catatan tambahan: Jika fieldType adalah signature, maka posisi koordinat mengacu pada area tanda tanganSudut kiri bawah； Jika fieldType adalah stamp, maka posisi koordinat mengacu pada area stempelTitik tengahPosisi Mulai 3 Februari 2026, fieldType adalah signature atau stamp, posisi koordinatnya mengacu pada posisi titik tengah area stempel.
			posY		string	false	Koordinat sumbu Y Catatan tambahan: Jika fieldType adalah signature, maka posisi koordinat mengacu pada area tanda tanganSudut kiri bawah； Jika fieldType adalah stamp, maka posisi koordinat mengacu pada area stempelTitik tengahPosisi Mulai 3 Februari 2026, fieldType adalah signature atau stamp, posisi koordinatnya mengacu pada posisi titik tengah area stempel.
		fillConfigs			array	false	Isi informasi kontrol
			fieldName		string	false	Nama kontrol, batasan jumlah karakter 128
			required		boolean	false	Apakah wajib diisi, defaultnya wajib diisi true-Wajib diisi false-Tidak Wajib
			fieldType		string	false	Tipe Kontrol: 1-Teks Satu Baris 15-Kotak Centang
			textField		object	false	Properti Kontrol Teks
				overflowType	int	false	Hanya berlaku untuk teks, default 1 1-Otomatis memperkecil ukuran font 2-Batasi input
				minFontSize	float	false	Hanya berlaku untuk teks, hanya berlaku untuk overflowType=1, default 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 kontrol, default 160px
				font	int	false	Hanya berlaku untuk teks, font, defaultnya 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 berlaku untuk teks, ukuran font, default 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 berlaku untuk teks, warna heksadesimal, default hitam #000
				bold	boolean	false	Hanya berlaku untuk teks, apakah font tebal, default false true-Tebal false-Tidak tebal
				italic	boolean	false	Hanya berlaku untuk teks, apakah miring, defaultnya adalah false true-Miring false-Tidak miring
				underline	boolean	false	Hanya berlaku untuk teks, apakah font ditambahkan garis bawah, defaultnya adalah false true-Tambahkan garis bawah false-Jangan tambahkan garis bawah
				lineThrough	boolean	false	Hanya berlaku untuk teks, apakah akan menambahkan garis coret, defaultnya adalah false true-Tambahkan garis coret false-Jangan tambahkan garis coret
				horizontalAlignment	string	false	Hanya berlaku untuk teks, format rata tengah horizontal, defaultnya adalah left LEFT-Rata kiri CENTER-Rata tengah RIGHT-Rata kanan
			tickBoxField		object	false	Properti Kotak Centang
				tickOptions	array	false	Hanya berlaku untuk Check, default 1 1-Centang 2-Silang
			posX		float	false	Koordinat X horizontal posisi kontrol
			posY		float	false	Koordinat Y posisi kontrol
			pageNo		string	false	Nomor halaman tempat kontrol berada
		signDateConfigs			array	false	Informasi posisi tanggal penandatanganan
			movable		boolean	false	Izinkan memindahkan posisi saat menandatangani, defaultnya false false-Tidak mengizinkan penandatangan untuk menyesuaikan posisi kontrol penandatanganan mereka sendiri true-Izinkan penandatangan untuk menyesuaikan posisi kontrol penandatanganan mereka sendiri
			pageNo		string	false	Nomor halaman tanda tangan; nomor halaman berurutan dihubungkan dengan "-", nomor halaman terpisah dihubungkan dengan ",", contoh: 1-3, 6-10 Jika tidak berurutan, masukkan "," untuk memisahkan
			posX		float	false	Offset sumbu x, sudut kiri bawah halaman adalah titik asal koordinat
			posY		float	false	Offset sumbu y, sudut kiri bawah halaman adalah titik asal koordinat
			signDateFormat		string	false	Format tanggal penandatanganan, format default adalah yyyy-MM-dd Mendukung 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			Tipe	Keterangan
envelopeId			string	ID Amplop
signFiles			array	Kumpulan Dokumen yang Ditandatangani
	fileKey		string	fileKey Dokumen yang Ditandatangani
attachments			array	Kumpulan Lampiran Amplop
	fileKey		string	fileKey Dokumen
signerInfos			array	Kumpulan Informasi Penanda Tangan
	businessId		string	Nomor bisnis kustom pengembang, panjang 500
	userEmail		string	Alamat email penanda tangan
	userName		string	Nama Penandatangan
	signOrder		int	Urutan node penandatangan, minimal 1
		accessCode	string	Kata sandi akses halaman penandatanganan

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