Mulakan Sampul Surat dengan Cepat

POST /esignglobal/v1/envelope/createAndStart

Deskripsi Antara Muka

Memulakan sampul surat dengan cepat, termasuk mencipta sampul surat, menambah fail yang akan ditandatangani, menambah penandatangan, dsb.

Menyokong permulaan automatik：Selepas panggilan antara muka berjaya, sampul surat berjaya dicipta dan dimulakan, dan sampul surat akan mula beredar secara automatik pada masa ini.
Menyokong penamatan automatik：Sampul surat akan ditamatkan secara automatik selepas semua pihak yang menandatangani selesai menandatangani.

Parameter Permintaan

Nama Parameter					Jenis	Diperlukan	Keterangan
subject					string	true	Tajuk Sampul Surat Contoh: “Offer Letter”
remark					string	false	Nota Sampul Surat，Had panjang 1000 aksara
signerSettings					object	false	Operasi yang dibenarkan untuk penandatangan
	allowTransfer				boolean	false	Sama ada penandatangan dibenarkan untuk memindahkan sampul surat ini kepada orang lain untuk ditandatangani, lalai adalah false true-Membenarkan penandatangan dalam sampul surat mempunyai kuasa untuk memindahkan sampul surat kepada orang lain; false-Tidak membenarkan penandatangan dalam sampul surat mempunyai kuasa untuk memindahkan sampul surat kepada orang lain;
	allowModifyName				boolean	false	Sama ada pihak yang menandatangani dibenarkan untuk mengubah suai nama, hanya berkuat kuasa untuk tandatangan templat, lalai adalah false true-Membenarkan penandatangan mengubah suai nama false-Tidak membenarkan penandatangan mengubah suai nama
expireAfterSeconds					long	false	Masa tamat sampul surat, selepas berapa saat sampul surat akan tamat tempoh Julat tamat tempoh: 86,400 saat (1 hari) ~ 7,776,000 saat (90 hari)
redirectUrl					string	false	Mesti alamat https yang sah
callBackUrl					string	false	Alamat panggilan balik (panjang 500), mesti mematuhi alamat protokol https.
sendLaterAfterSeconds					long	false	Menyokong pengguna untuk menangguhkan penghantaran, dalam unit saat Julat masa yang disokong: 3600 saat (1 jam) ~ 259200 saat (30 hari)
CCInfos					array	false	Koleksi maklumat penerima salinan
	userEmail				string	false	Alamat e-mel penerima salinan
	userName				string	false	Nama CC, digunakan untuk memaparkan nama CC pada halaman tandatangan dan sampul surat. 【Perhatian】: Tidak boleh mengandungi 9 aksara khas berikut: / \ : * " < > \| ？dan semua emoji
	customizeSettings				object	false	Konfigurasi tersuai
		notificationSettings			object	false	Konfigurasi tersuai jenis pemberitahuan
			notificationLanguage		string	false	Bahasa pemberitahuan, lalai kepada konfigurasi "Bahasa Pemberitahuan Lalai" en-US Bahasa Inggeris zh-CN Bahasa Cina Ringkas zh-Hant Bahasa Cina Tradisional ja-JP Bahasa Jepun es-MX Bahasa Sepanyol pt-PT Bahasa Portugis th-TH Bahasa Thai id-ID Bahasa Indonesia vi-VN Bahasa Vietnam ms-MY Bahasa Melayu fil-PH Bahasa Filipina de-DE Bahasa Jerman fr-FR Bahasa Perancis ru-RU Bahasa Rusia it-IT Bahasa Itali ko-KR Bahasa Korea
signFiles					array	true	Koleksi maklumat dokumen yang ditandatangani, susunan paparan adalah susunan penambahan fail.
	fileKey				string	true	FileKey fail yang ditandatangani, hanya menyokong format PDF
attachments					array	false	Koleksi lampiran sampul surat, susunan paparan adalah susunan penambahan fail.
	fileKey				string	false	FileKey fail
signerInfos					array	true	Koleksi maklumat penandatangan
	businessId				string	false	Nombor perniagaan tersuai pembangun, had panjang 500
	deliveryMethods				string	false	Kaedah pemberitahuan, lalai ialah auto auto-Hantar pemberitahuan e-mel apabila userEmail dihantar, hantar pemberitahuan SMS apabila phoneNumber dihantar none-Jangan hantar pemberitahuan mesej email-Hantar pemberitahuan e-mel sms-Hantar pemberitahuan SMS WhatsApp-Hantar pemberitahuan WhatsApp
	userEmail				string	false	Alamat e-mel penandatangan
	userName				string	true	Nama penandatangan, digunakan untuk memaparkan nama penandatangan pada halaman tandatangan dan sampul surat. 【Nota】Tidak boleh mengandungi 9 aksara khas berikut: / \ : * " < > \| ？dan semua emoji
	phoneNumber				object	false	Nombor telefon, lalai kepada kosong Apabila pemberitahuan SMS diperlukan, parameter ini wajib diisi, countryCode dan number perlu dihantar
		countryCode			string	false	Kod antarabangsa negara/rantau, tidak perlu memasukkan “+”
		number			string	false	Tiada pengesahan format, hanya had panjang maksimum 13 digit
	customizeSettings				object	false	Konfigurasi tersuai
		notificationSettings			object	false	Konfigurasi tersuai kelas pemberitahuan
			customizeMessage		string	false	Pemberitahuan mesej eksklusif, had aksara 200
			notificationLanguage		string	false	Bahasa pemberitahuan, lalai kepada konfigurasi “Bahasa Pemberitahuan Lalai” en-US Bahasa Inggeris zh-CN Cina Ringkas zh-Hant Cina Tradisional ja-JP Jepun es-MX Sepanyol pt-PT Portugis th-TH Thai id-ID Indonesia vi-VN Vietnam ms-MY Bahasa Melayu fil-PH Filipina de-DE Jerman fr-FR Perancis ru-RU Rusia it-IT Itali ko-KR Korea
	signOrder				int	true	Urutan tandatangan penandatangan, yang terkecil ialah 1. Tandatangan tidak teratur boleh menetapkan nilai urutan yang sama.
	anySigner				boolean	false	Sama ada menyokong mana-mana satu orang untuk menandatangani, lalai ialah false true-Hanya seorang sahaja daripada signOrder yang sama diperlukan untuk menandatangani false-Semua orang dalam signOrder yang sama perlu menandatangani
	authModes				string	false	Kaedah pengesahan, lalai ialah noAuth 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 whatsappAuth-Pengesahan WhatsApp OTP
	authConfig				object	false	Tetapan kaedah pengesahan
		accessCode			object	false	Tetapan kata laluan tandatangan, apabila authModes=accessCodediperlukan
			accessCode		string	false	Kandungan kata laluan, tidak membezakan huruf besar atau kecil, boleh mengandungi huruf dan nombor, had panjang 45
			promptInfo		string	false	Maklumat petunjuk 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 memasukkan “+”
			number		string	false	Tidak melakukan pengesahan format, hanya mengehadkan panjang maksimum 13 digit
		idVerification			object	false	Tetapan pengesahan dokumen pengenalan, apabila authModes=idVerificationmesti diisi
			name		string	false	Nama penuh pada dokumen pengenalan penandatangan, panjang maksimum 100 aksara
		emailAuth			object	false	Pengesahan OTP e-mel, apabila authModes=emailAuthmesti diisi
			authEmail		string	false	Alamat e-mel pengesahan identiti penandatangan
		digitalId			array	false	Pengesahan identiti elektronik, mesti diisi apabila authModes=digitalId
			authApp		string	false	APP yang digunakan untuk pengesahan identiti elektronik singpass- Pengesahan identiti menggunakan Singpass iamsmart- Pengesahan identiti menggunakan i AM Smart
			idNumber		string	false	Nombor pengenalan diri penandatangan yang menunggu untuk disahkan Apabila authApp=singpassmasukkan peraturan seperti berikut: huruf besar + 7 atau 8 digit + huruf besar Apabila authApp=iamsmartmasukkan peraturan seperti berikut: 1. Satu huruf besar (A-Z), atau dua huruf besar (AA-ZZ), sebagai permulaan jujukan; 2. Diikuti dengan 6 digit; 3. Akhir sekali ialah kod semakan, yang boleh menjadi nombor (0-9) atau huruf (A-Z). Contoh: A888888(A)
		whatsappAuth			object	false	Pengesahan OTP WhatsApp, wajib diisi apabila authModes=whatsappAuth
			countryCode		string	false	Kod antarabangsa negara/rantau, tidak perlu memasukkan “+”
			number		string	false	Tidak melakukan pengesahan format, hanya mengehadkan panjang maksimum kepada 13 digit
	digitalSignature				boolean	false	Sama ada untuk menghidupkan tandatangan digital, lalai ialah false true-hidupkan, false-jangan hidupkan
	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 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 sebelum tandatangan elektronik boleh dilakukan.
			fieldType		string	false	Jenis kawalan, lalai ialah signature signature-Kawalan tandatangan stamp-Kawalan cap approval-Kawalan kelulusan
			sizeRule		string	false	Kaedah paparan saiz kawasan tandatangan originalSize-Cap berdasarkan saiz sebenar tandatangan/cap targetSize-Lebar dan tinggi kawasan tandatangan/cap tersuai Apabila sizeRule, height, width semuanya kosong, cap diletakkan mengikut saiz sebenar tandatangan/cop; Apabila sizeRule kosong, height, width tidak kosong, cap diletakkan mengikut saiz yang ditetapkan; Apabila sizeRule tidak kosong, cap diletakkan mengikut kaedah paparan yang ditetapkan.
			height		int	false	Ketinggian kawalan tandatangan, sesuai untuk fieldType ialah signature/stamp, unit dalam px, hanya menyokong integer positif, lalai ialah 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 ialah signature/stamp, unit dalam px, hanya menyokong integer positif, lalai ialah 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 sesuai untuk fieldType ialah signature Boleh masukkan parameter: template: Tandatangan templat handDrawn: Tandatangan lukisan tangan upload: Muat naik gambar tandatangan tempatan Boleh pilih berbilang, dipisahkan dengan ",", lalai ialah pilih semua
			movable		boolean	false	Benarkan alih lokasi semasa menandatangani, lalai adalah false false-Tidak benarkan penandatangan melaraskan lokasi kawalan tandatangan mereka sendiri true-Benarkan penandatangan melaraskan lokasi kawalan tandatangan mereka sendiri
			allowedOptions		array	false	Pilihan yang dibenarkan untuk kelulusan oleh penandatangan, sesuai untuk fieldType adalah approval. Lalai adalah ["approve", "decline"] approve-Setuju decline-Tolak
			pageNo		string	false	Nombor halaman tandatangan; nombor halaman berturutan disambungkan dengan "-", nombor halaman tunggal disambungkan dengan "," Contoh: 1-3,6-10
			posX		float	false	Koordinat paksi-x 【Perhatian】Jika fieldType adalah signature, maka kedudukan koordinat merujuk kepada kawasan tandatanganSudut kiri bawah； Jika fieldType adalah stamp, maka kedudukan koordinat merujuk kepada kawasan pengecapanTitik tengahLokasi Mulai 3 Februari 2026, fieldType adalah signature atau stamp, kedudukan koordinat merujuk kepada kedudukan titik tengah kawasan pengecapan.
			posY		float	false	Koordinat paksi-y 【Perhatian】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 Mulai 3 Februari 2026, fieldType ialah signature atau stamp, kedudukan koordinatnya merujuk kepada kedudukan titik tengah kawasan pengecapan.
		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 false-Tidak wajib diisi
			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 Songti 1-Songti 2-Xin Songti 4-Hitam 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 berkuat kuasa pada teks, sama ada condong, lalai false true-Condong false-Tidak Condong
				underline	boolean	false	Hanya berkuat kuasa pada teks, sama ada fon ditambah garis bawah, lalai false true-Tambah Garis Bawah false-Tidak Tambah Garis Bawah
				lineThrough	boolean	false	Hanya berkuat kuasa pada teks, sama ada menambah garis potong, lalai false true-Tambah Garis Potong false-Tidak Tambah Garis Potong
				horizontalAlignment	string	false	Hanya berkuat kuasa pada teks, format penjajaran mendatar, lalai left LEFT-Jajaran Kiri CENTER-Jajaran Tengah RIGHT-Jajaran Kanan
			tickBoxField		object	false	Atribut Kotak Semak
				tickOptions	array	false	Hanya berkesan untuk tickBox, lalai 1 1-Tanda 2-Pangkah
			posX		float	false	Koordinat-X mendatar kedudukan kawalan
			posY		float	false	Koordinat-Y menegak kedudukan kawalan
			pageNo		string	false	Nombor halaman kawalan berada
		signDateConfigs			array	false	Maklumat kedudukan tarikh tandatangan
			movable		boolean	false	Benarkan kedudukan dialihkan semasa menandatangani, lalai palsu false-Tidak membenarkan penandatangan melaraskan kedudukan kawalan tandatangan mereka sendiri true-Membenarkan penandatangan melaraskan kedudukan kawalan tandatangan mereka sendiri
			pageNo		string	false	Nombor halaman tandatangan; halaman berturut-turut disambungkan dengan "-", halaman tunggal disambungkan dengan ","，Contoh: 1-3, 6-10; Jika tidak berturutan, masukkan "," untuk pemisahan.
			posX		float	false	Ofset paksi-x, sudut kiri bawah halaman adalah asal koordinat
			posY		float	false	Ofset paksi-y, sudut kiri bawah halaman adalah 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

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

Parameter respons

Nama parameter		Jenis	Keterangan
envelopeId		string	ID sampul surat
CCInfos		array	Koleksi maklumat penerima salinan
	userEmail	string	Alamat e-mel penerima salinan
	userName	string	Nama penerima salinan
signFiles		array	Koleksi maklumat fail tandatangan
	fileKey	string	FailKey fail tandatangan
attachments		array	Koleksi Lampiran Sampul Surat
	fileKey	string	Fail fileKey
signerInfos		array	Maklumat Tandatangan
	businessId	string	Nombor perniagaan tersuai pembangun, had panjang 500
	userEmail	string	Alamat e-mel penandatangan
	userName	string	Nama penandatangan
	signUrl	string	Alamat pautan tandatangan
	signOrder	int	Urutan tandatangan penandatangan, minimum ialah 1
	accessCode	string	Kata laluan akses halaman tandatangan

Contoh respons

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