Mulakan Sampul Surat dengan Cepat

POST /esignglobal/v1/envelope/createAndStart

Deskripsi Antara Muka

Lancarkan 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-Penandatangan dalam sampul surat dibenarkan untuk memindahkan kuasa sampul surat kepada orang lain; false-Penandatangan dalam sampul surat tidak dibenarkan untuk memindahkan kuasa sampul surat kepada orang lain;
	allowModifyName				boolean	false	Sama ada pihak penandatangan dibenarkan untuk mengubah suai nama, hanya berkuat kuasa untuk tandatangan templat, lalai adalah false true-Penandatangan dibenarkan untuk mengubah suai nama false-Penandatangan tidak dibenarkan untuk mengubah suai nama
expireAfterSeconds					long	false	Masa tamat tempoh 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 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
signFiles					array	true	Koleksi maklumat fail tandatangan, susunan paparan adalah susunan penambahan fail.
	fileKey				string	true	FailKey fail tandatangan, hanya menyokong format PDF
attachments					array	false	Koleksi lampiran sampul surat, susunan paparan adalah susunan penambahan fail.
	fileKey				string	false	FailKey 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	true	Alamat e-mel penandatangan
	userName				string	true	Nama penandatangan, digunakan untuk memaparkan nama penandatangan pada halaman tandatangan dan sampul surat. 【注】Tidak boleh mengandungi 9 aksara khas berikut: / \ : * " < > \| ？dan semua emoji
	phoneNumber				object	false	Nombor telefon, lalai ialah kosong Apabila pemberitahuan SMS diperlukan, ini ialah parameter yang wajib diisi, countryCode dan number perlu dihantar
		countryCode			string	false	Kod antarabangsa negara/rantau, tidak perlu menghantar “+”
		number			string	false	Tiada pengesahan format, hanya had panjang maksimum 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 Bahasa Jepun ES-MX Bahasa Sepanyol
	signOrder				int	true	Urutan tandatangan penandatangan, minimum ialah 1. Tandatangan tidak teratur boleh menentukan nilai urutan yang sama.
	anySigner				boolean	false	Sama ada menyokong mana-mana satu orang untuk menandatangani, lalai ialah false true-Hanya seorang sahaja yang perlu menandatangani dalam signOrder yang sama 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 OTP SMS idVerification- Pengesahan Dokumen Identiti emailAuth- Pengesahan OTP E-mel digitalId- Pengesahan Identiti Elektronik
	authConfig				object	false	Tetapan Kaedah Pengesahan
		accessCode			object	false	Tetapan kata laluan tandatangan, diperlukan apabila authModes=accessCodediisi
			accessCode		string	false	Kandungan kata laluan, tidak mengira huruf besar atau kecil, boleh mengandungi huruf dan nombor, had panjang 45
			promptInfo		string	false	Maklumat gesaan kata laluan akses, tidak boleh mengandungi kata laluan akses, had panjang 30, diperlukan apabila authModes=1.
		sms			object	false	Pengesahan OTP SMS, diperlukan apabila authModes=smsdiisi
			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 identiti, diperlukan apabila authModes=idVerificationdiisi
			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-Gunakan Singpass untuk pengesahan identiti
			idNumber		string	false	Nombor dokumen pengenalan penandatangan yang akan disahkan
	digitalSignature				boolean	false	Sama ada untuk menghidupkan tandatangan digital, lalai adalah false true-hidupkan, false-jangan hidupkan
	freeFormSign				boolean	false	Sama ada penandatangan boleh menandatangani dengan bebas, 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 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	Tandatangan Maklumat Tugasan
		fileKey			string	true	Tandatangan fail fileKey
		signConfigs			array	false	Maklumat lokasi kawalan, maklumat lokasi kawalan mesti ditentukan untuk melakukan tandatangan elektronik.
			fieldType		string	false	Jenis kawalan, lalai ialah signature signature-Kawalan tandatangan stamp-Kawalan setem approval-Kawalan kelulusan
			sizeRule		string	false	Cara paparan saiz kawasan tandatangan originalSize-Letakkan setem mengikut saiz sebenar tandatangan/setem targetSize-Sesuaikan lebar dan tinggi kawasan tandatangan/setem Apabila sizeRule, height, width semuanya kosong, letakkan setem mengikut saiz sebenar tandatangan/setem; Apabila sizeRule kosong, height, width tidak kosong, letakkan setem mengikut saiz yang ditentukan; Apabila sizeRule tidak kosong, letakkan setem mengikut cara paparan yang ditentukan.
			height		int	false	Ketinggian kawalan tandatangan, sesuai untuk fieldType ialah signature/stamp, unit ialah 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 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 sesuai untuk fieldType signature Boleh memasukkan parameter: template: Tandatangan templat handDrawn: Tandatangan lukisan tangan upload: Muat naik gambar tandatangan tempatan Boleh memilih berbilang, dipisahkan dengan ",", lalai ialah pilih semua
			movable		boolean	false	Benarkan kedudukan 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 yang membenarkan penandatangan meluluskan, sesuai untuk fieldType approval. Lalai ialah ["approve", "decline"] approve-Setuju decline-Tolak
			pageNo		string	false	Halaman tandatangan; halaman berturut-turut disambungkan dengan "-", halaman individu disambungkan dengan "," Contoh: 1-3,6-10
			posX		float	false	Koordinat paksi-x 【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 Bermula dari 3 Februari 2026, fieldType ialah signature atau stamp, kedudukan koordinatnya 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 Bermula dari 3 Februari 2026, fieldType ialah tandatangan atau cap, dan kedudukan koordinat 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 berkuat kuasa untuk teks, lalai 1 1-Automatik kecilkan saiz fon 2-Hadkan input
				minFontSize	float	false	Hanya berkuat kuasa untuk teks, hanya berkuat kuasa untuk 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 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 tebal atau tidak, lalai palsu true-Tebal false-Tidak tebal
				italic	boolean	false	Hanya berkesan pada teks, sama ada condong atau tidak, lalai palsu true-Condong false-Tidak condong
				underline	boolean	false	Hanya berkesan pada teks, sama ada fon ditambah garis bawah, lalai adalah false true-Tambah garis bawah false-Jangan tambah garis bawah
				lineThrough	boolean	false	Hanya berkesan pada teks, sama ada menambah garis potong, lalai adalah false true-Tambah garis potong false-Jangan tambah garis potong
				horizontalAlignment	string	false	Hanya berkesan pada teks, format penjajaran mendatar, lalai adalah left LEFT-Jajar kiri CENTER-Jajar tengah RIGHT-Jajar kanan
			tickBoxField		object	false	Atribut kotak semak
				tickOptions	array	false	Hanya berkesan pada tickBox, lalai adalah 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 adalah false 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; nombor halaman berturutan disambungkan dengan "-", nombor halaman tunggal disambungkan dengan ","，Contoh: 1-3, 6-10; Jika tidak berturutan, masukkan "," untuk memisahkan.
			posX		float	false	Ofset paksi-x, sudut kiri bawah halaman adalah titik asal koordinat
			posY		float	false	Ofset paksi-y, sudut kiri bawah halaman adalah 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

{
    "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
CCInfos		array	Koleksi Maklumat Salinan Kepada
	userEmail	string	Alamat E-mel Salinan Kepada
	userName	string	Nama Salinan Kepada
signFiles		array	Koleksi Maklumat Fail yang Ditandatangani
	fileKey	string	fileKey Fail yang Ditandatangani
attachments		array	Koleksi Lampiran Sampul
	fileKey	string	fileKey Fail
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"
}