Kirim Amplop Cepat

POST /esignglobal/v1/envelope/createAndStart

Deskripsi Antarmuka

Inisiasi cepat pembuatan amplop, mencakup fungsi seperti membuat amplop, menambahkan dokumen yang menunggu penandatanganan, dan menambahkan penandatangan.

Mendukung pengaktifan otomatis: Setelah pemanggilan antarmuka berhasil, amplop akan dibuat dan diaktifkan secara sukses, sehingga amplop mulai mengalir secara otomatis.
Mendukung pengakhiran otomatis: Setelah semua pihak penandatangan menyelesaikan penandatanganan, amplop akan berakhir secara otomatis.

Parameter Permintaan

Nama Parameter					Tipe	Wajib Diisi	Keterangan
subject					string	true	Subjek Amplop Contoh: "Surat Penawaran"
remark					string	false	Catatan amplop, batas panjang 1000 karakter
signerSettings					object	false	Operasi yang diperbolehkan bagi penandatangan
	allowTransfer				boolean	false	Apakah penandatangan diperbolehkan menyerahkan amplop ini kepada orang lain untuk ditandatangani, default false true - mengizinkan penandatangan dalam amplop memiliki hak untuk menyerahkan amplop kepada pihak lain; false - tidak mengizinkan penandatangan dalam amplop memiliki hak untuk menyerahkan amplop kepada pihak lain;
	allowModifyName				boolean	false	Apakah penandatangan diperbolehkan mengubah nama, hanya berlaku untuk tanda tangan template, default false true - mengizinkan penandatangan mengubah nama false - tidak mengizinkan penandatangan mengubah nama
expireAfterSeconds					long	false	Waktu kedaluwarsa amplop, setelah berapa detik amplop menjadi kedaluwarsa Rentang kedaluwarsa: 86.400 detik (1 hari) ~ 7.776.000 detik (90 hari)
redirectUrl					string	false	Harus berupa alamat https yang valid
callBackUrl					string	false	Alamat callback (panjang 500), harus sesuai dengan alamat protokol https.
sendLaterAfterSeconds					long	false	Mendukung pengiriman tertunda oleh pengguna, dalam satuan detik Rentang waktu yang didukung: 3.600 detik (1 jam) ~ 259.200 detik (30 hari)
autoFinish					boolean	false	Mengontrol apakah amplop berakhir secara otomatis, default true true- Amplop berakhir secara otomatis false- Amplop berakhir secara manual
CCInfos					array	false	Kumpulan informasi penerima salinan
	userEmail				string	false	Alamat email penerima salinan
	userName				string	false	Nama penerima salinan, digunakan untuk menampilkan nama penerima salinan di halaman penandatanganan dan amplop. [Perhatian]: Tidak boleh mengandung 9 karakter khusus berikut: / \ : * " < > \| ? serta semua emoji
	customizeSettings				object	false	Konfigurasi kustom
		notificationSettings			object	false	Konfigurasi kustom untuk notifikasi
			notificationLanguage		string	false	Bahasa notifikasi, secara default menggunakan konfigurasi "Bahasa Notifikasi Default" en-US Bahasa Inggris zh-CN Bahasa Mandarin Sederhana zh-Hant Bahasa Mandarin Tradisional ja-JP Bahasa Jepang es-MX Bahasa Spanyol pt-PT Bahasa Portugis th-TH Bahasa Thailand id-ID Bahasa Indonesia vi-VN Bahasa Vietnam ms-MY Bahasa Melayu fil-PH Bahasa Filipina de-DE Bahasa Jerman fr-FR Bahasa Prancis ru-RU Bahasa Rusia it-IT Bahasa Italia ko-KR Bahasa Korea
signFiles					array	true	Kumpulan informasi dokumen penandatanganan, ditampilkan sesuai urutan penambahan dokumen.
	fileKey				string	true	fileKey dokumen penandatanganan, hanya mendukung format PDF
	documentFields				array	false	Daftar kontrol dimensi dokumen. Digunakan untuk menambahkan kontrol dimensi dokumen pada file tertentu yang tidak terikat dengan penandatangan.
		fieldType			string	false	Tipe kontrol. Gunakan eMeterai untuk menunjukkan kontrol bea meterai Indonesia.
		pageNo			string	false	Nomor halaman tempat kontrol berada. Kontrol bea meterai Indonesia hanya mendukung satu halaman tertentu; harus memasukkan nomor halaman tunggal, tidak mendukung format multi-halaman berurutan atau tidak berurutan seperti 1-3, 1,3, dll.
		posX			float	false	Offset sumbu x, titik asal koordinat adalah sudut kiri bawah halaman. Rentang koordinat konsisten dengan rentang koordinat kontrol lainnya.
		posY			float	false	Offset sumbu y, titik asal koordinat adalah sudut kiri bawah halaman. Rentang koordinat konsisten dengan rentang koordinat kontrol lainnya.
attachments					array	false	Kumpulan lampiran amplop, urutan tampilan sesuai dengan urutan penambahan file.
	fileKey				string	false	fileKey file
signerInfos					array	true	Kumpulan informasi penandatangan
	businessId				string	false	Nomor bisnis kustom pengembang, batas panjang 500
	roleTypes				array	false	Metode operasi penandatangan, nilai default adalah `["sign", "fill"]` fill-isian sign-tanda tangan
	deliveryMethods				string	false	Metode notifikasi, default auto auto- Kirim notifikasi email saat userEmail dimasukkan, kirim notifikasi SMS saat phoneNumber dimasukkan none- Tidak mengirim notifikasi pesan email- Kirim notifikasi email sms- Kirim notifikasi SMS WhatsApp- Kirim notifikasi WhatsApp
	userEmail				string	false	Alamat email penandatangan
	userName				string	true	Nama penandatangan, digunakan untuk menampilkan nama penandatangan pada halaman tanda tangan dan amplop. [Catatan] Tidak boleh mengandung 9 karakter khusus berikut: / \ : * " < > \| ? serta semua emoji
	minimumReadingDuration				int	false	Atur waktu hitung mundur bacaan wajib di halaman pengaturan, nilai default adalah 0 (satuan: detik, maksimum 999) 0 atau tidak mengirim berarti tidak mengaktifkan, tidak perlu hitung mundur bacaan
	readToEndRequired				boolean	false	Menunjukkan apakah harus dibaca sampai akhir. Default false; true berarti mengaktifkan, false atau tidak mengirim berarti tidak mengaktifkan.
	phoneNumber				object	false	Nomor telepon, default kosong Parameter wajib saat diperlukan notifikasi SMS, countryCode dan number harus dikirim
		countryCode			string	false	Kode internasional negara/wilayah, tidak perlu memasukkan tanda '+'
		number			string	false	Tidak ada validasi format, hanya membatasi panjang maksimal 13 digit
	customizeSettings				object	false	Konfigurasi kustom
		notificationSettings			object	false	Konfigurasi kustom untuk notifikasi
			customizeMessage		string	false	Notifikasi pesan khusus, batas karakter 200
			notificationLanguage		string	false	Bahasa notifikasi, default menggunakan konfigurasi 'bahasa notifikasi default' en-US Bahasa Inggris zh-CN Bahasa Mandarin Sederhana zh-Hant Bahasa Tionghoa Tradisional ja-JP Bahasa Jepang es-MX Bahasa Spanyol pt-PT Bahasa Portugis th-TH Bahasa Thailand id-ID Bahasa Indonesia vi-VN Bahasa Vietnam ms-MY Bahasa Melayu fil-PH Bahasa Filipina de-DE Bahasa Jerman fr-FR Bahasa Prancis ru-RU Bahasa Rusia it-IT Bahasa Italia ko-KR Bahasa Korea
	signOrder				int	true	Urutan penandatanganan penandatangan, nilai minimum adalah 1. Penandatanganan tanpa urutan dapat menentukan nilai urutan yang sama.
	anySigner				boolean	false	Apakah mendukung penandatanganan oleh siapa saja, default false true- Hanya perlu satu orang menandatangani dalam satu signOrder yang sama false- Semua orang harus menandatangani dalam satu signOrder yang sama
	authModes				string	false	Metode verifikasi, default noAuth noAuth- Tidak memverifikasi accessCode- Verifikasi menggunakan kata sandi penandatanganan sms- Verifikasi OTP SMS idVerification- Verifikasi identitas resmi emailAuth- Verifikasi OTP email digitalId- Verifikasi identitas elektronik whatsappAuth- Verifikasi OTP WhatsApp
	authConfig				object	false	Pengaturan metode verifikasi
		accessCode			object	false	Pengaturan kata sandi penandatanganan, wajib diisi ketika authModes=accessCode
			accessCode		string	false	Konten kata sandi, tidak membedakan huruf besar/kecil, dapat mengandung huruf dan angka, batas panjang 45
			promptInfo		string	false	Pesan petunjuk kata sandi akses, tidak boleh mengandung kata sandi akses, batas panjang 30 karakter, diperlukan saat authModes=accessCode
		sms			object	false	Verifikasi OTP SMS, diperlukan saat authModes=sms
			countryCode		string	false	Kode internasional negara/wilayah, tidak perlu menyertakan "+"
			number		string	false	Tidak ada validasi format, hanya membatasi panjang maksimal 13 digit
		idVerification			object	false	Pengaturan verifikasi identitas dokumen, diperlukan saat authModes=idVerification
			name		string	false	Nama lengkap penandatangan sesuai yang tercantum dalam dokumen identitas, panjang maksimal 100 karakter
		emailAuth			object	false	Verifikasi OTP email, diperlukan saat authModes=emailAuth
			authEmail		string	false	Alamat email verifikasi identitas penandatangan
		digitalId			array	false	Verifikasi identitas elektronik, diperlukan saat authModes=digitalId
			authApp		string	false	Aplikasi yang digunakan untuk verifikasi identitas elektronik singpass-Gunakan Singpass untuk autentikasi identitas iamsmart-Gunakan i AM Smart untuk autentikasi identitas
			idNumber		string	false	Nomor dokumen identitas penandatangan yang menunggu verifikasi Ketika authApp=singpass Ketika authApp=iamsmart 1. Satu huruf kapital (A-Z), atau dua huruf kapital (AA-ZZ), sebagai awal urutan; 2. Diikuti oleh 6 digit angka; 3. Terakhir adalah kode pemeriksaan, bisa berupa angka (0-9) atau huruf (A-Z). Contoh: A888888(A)
		whatsappAuth			object	false	Verifikasi OTP WhatsApp, wajib diisi ketika authModes=whatsappAuth
			countryCode		string	false	Kode internasional negara/wilayah, tidak perlu memasukkan tanda “+”
			number		string	false	Tidak melakukan validasi format, hanya membatasi panjang maksimal 13 karakter
	digitalSignature				boolean	false	Apakah tanda tangan digital diaktifkan, default false true-Aktif, false-Tidak aktif
	freeFormSign				boolean	false	Apakah penandatangan dapat menggunakan stempel bebas, nilai default false Catatan tambahan: Ketika freeFormSign ditetapkan sebagai true, parameter lain di bawah sealInfos tidak perlu dimasukkan. Jika keduanya dimasukkan secara bersamaan, prioritas freeFormSign lebih tinggi daripada sealInfos, sehingga parameter di bawah sealInfos tidak akan berlaku. [Perhatian]Penandatanganan bebas berarti tidak ada batasan pada jumlah dan posisi stempel/tanda tangan yang dapat ditarik 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 penandatanganan elektronik dapat dilakukan.
			fieldType		string	false	Tipe kontrol, defaultnya adalah signature signature-Kontrol tanda tangan stamp-Kontrol stempel approval-Kontrol persetujuan
			required		boolean	false	Apakah wajib diisi, defaultnya wajib diisi true-Wajib diisi false-Tidak wajib diisi
			signFieldStyle		string	false	Metode penerapan stempel pada kontrol penandatanganan, defaultnya adalah normalSeal. normalSeal-Stempel biasa pagingSeal-Stempel sambungan halaman Hanya kontrol tanda tangan dan kontrol stempel yang mendukung pengaturan stempel sambungan halaman.
			pagingSealMode		string	false	Rentang jumlah halaman untuk penerapan stempel sambungan halaman, default adalah all. all-Semua nomor halaman assignedPages-Nomor halaman tertentu even-Halaman genap odd-Halaman ganjil Hanya dapat ditentukan saat signFieldStyle=pagingSeal.
			sizeRule		string	false	Tampilan ukuran area penandatanganan originalSize-Penerapan stempel sesuai ukuran aktual tanda tangan/stempel targetSize-Kustomisasi lebar dan tinggi area tanda tangan/stempel Ketika sizeRule, height, dan width semuanya kosong, stempel diterapkan sesuai ukuran aktual tanda tangan/stempel; Ketika sizeRule kosong, tetapi height dan width tidak kosong, stempel diterapkan sesuai ukuran yang ditentukan; Ketika sizeRule tidak kosong, stempel diterapkan sesuai tampilan yang ditentukan; Cap tumpang tindih tidak memerlukan parameter ini, hanya cap berdasarkan ukuran aktual.
			height		int	false	Tinggi kontrol penandatanganan, berlaku untuk fieldType signature/stamp, dalam satuan px, hanya mendukung bilangan bulat positif, default 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; Cap tumpang tindih tidak memerlukan parameter ini.
			width		int	false	Lebar kontrol penandatanganan, berlaku untuk fieldType signature/stamp, dalam satuan px, hanya mendukung bilangan bulat positif, default 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; Cap tumpang tindih tidak memerlukan parameter ini.
			signatureOptions		string	false	Opsi kontrol tanda tangan. Hanya berlaku untuk fieldType signature Parameter yang dapat dimasukkan: template: Tanda tangan templat handDrawn: Tanda tangan gambar tangan upload: Unggah gambar tanda tangan lokal Dapat dipilih beberapa, dipisahkan dengan ",", default semua terpilih
			movable		boolean	false	Memungkinkan pemindahan posisi saat ditandatangani, default false false - Penandatangan tidak diizinkan menyesuaikan posisi kontrol penandatangan mereka sendiri true - Penandatangan diizinkan menyesuaikan posisi kontrol penandatangan mereka sendiri
			allowedOptions		array	false	Opsi yang memungkinkan penandatangan untuk menyetujui, berlaku ketika fieldType adalah approval. Defaultnya adalah ["approve", "decline"] approve- Setuju decline- Tolak
			pageNo		string	false	Nomor halaman penandatanganan; halaman berurutan dihubungkan dengan "-", halaman terpisah dihubungkan dengan "," Contoh: 1-3,6-10 Masukkan rentang nomor halaman tempat stempel jahitan akan ditempatkan saat pagingSealMode=assignedPages. Stempel jahitan hanya dapat digunakan pada dokumen dengan lebih dari 1 halaman.
			posX		float	false	Koordinat sumbu-x [Perhatian] Jika fieldType adalah signature, maka posisi koordinat merujuk pada area tanda tanganKiri bawah； Jika fieldType adalah stamp, maka posisi koordinat merujuk pada area capTitik tengahPosisi Sejak 3 Februari 2026, jika fieldType adalah signature atau stamp, posisi koordinatnya merujuk pada titik pusat area cap. Cap sambungan dapat dikirim dengan nilai 0, tidak boleh null; kontrol terpasang tetap di tepi kanan dokumen.
			posY		float	false	Koordinat sumbu y [Perhatian] Jika fieldType adalah signature, maka posisi koordinatnya merujuk pada area tanda tanganKiri bawah； Jika fieldType adalah stamp, maka posisi koordinatnya merujuk pada area capTitik pusatPosisi Sejak 3 Februari 2026, jika fieldType adalah signature atau stamp, posisi koordinatnya merujuk pada titik pusat area cap.
		fillConfigs			array	false	Isi informasi kontrol
			fieldName		string	false	Nama kontrol, batas jumlah karakter 128
			required		boolean	false	Apakah wajib diisi, default wajib diisi true-wajib diisi false-tidak wajib diisi
			fieldType		string	false	Tipe kontrol: 1-Teks satu baris 15-Kotak centang
			textField		object	false	Atribut kontrol teks
				overflowType	int	false	Hanya berlaku untuk text, default 1 1-Perkecil ukuran font secara otomatis 2-Batasi input
				minFontSize	float	false	Hanya berlaku untuk text, hanya berlaku saat 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 text, font, default Songti 1-Songti 2-Xin Songti 4-Heiti 5-Kaiti 6-Arial 7-Helvetica 9-Times New Roman 10-Fangsung 11-Georgia 12-Monospace
				fontSize	float	false	Hanya berlaku untuk text, 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 text, warna heksadesimal, default hitam #000
				bold	boolean	false	Hanya berlaku untuk text, apakah font tebal, default false true-tebal false-tidak tebal
				italic	boolean	false	Hanya berlaku untuk text, apakah miring, default false true-miring false-tidak miring
				underline	boolean	false	Hanya berlaku untuk text, apakah font bergaris bawah, default false true-menambahkan garis bawah false-tidak menambahkan garis bawah
				lineThrough	boolean	false	Hanya berlaku untuk text, apakah ada coretan, default false true-menambahkan coretan false-tidak menambahkan coretan
				horizontalAlignment	string	false	Hanya berlaku untuk text, format rata tengah horizontal, default left LEFT-rata kiri CENTER-Tengah RIGHT-Kanan
			tickBoxField		object	false	Atribut kotak centang
				tickOptions	array	false	Hanya berlaku untuk tickBox, default 1 1-Centang 2-Silang
			posX		float	false	Koordinat X 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	Memungkinkan perpindahan posisi saat menandatangani, default false false-Penandatangan tidak diizinkan menyesuaikan posisi kontrol penandatanganan mereka sendiri true-Penandatangan diizinkan menyesuaikan posisi kontrol penandatanganan mereka sendiri
			pageNo		string	false	Nomor halaman penandatanganan; halaman berurutan dihubungkan dengan "-", halaman terpisah dihubungkan dengan ",", contoh: 1-3, 6-10; Jika tidak berurutan, gunakan "," sebagai pemisah.
			posX		float	false	Offset sumbu-x, titik asal koordinat berada di sudut kiri bawah halaman
			posY		float	false	Offset sumbu-y, titik asal koordinat berada di sudut kiri bawah halaman
			signDateFormat		string	false	Format tanggal penandatanganan, format default adalah yyyy-MM-dd Mendukung format yang ditentukan: yyyy tahun MM bulan dd hari yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MMM dd,yyyy dd MMM 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		Tipe	Keterangan
envelopeId		string	ID amplop
CCInfos		array	Kumpulan informasi penerima karbon
	userEmail	string	Alamat email penerima karbon
	userName	string	Nama penerima karbon
signFiles		array	Kumpulan informasi dokumen penandatanganan
	fileKey	string	fileKey dokumen yang ditandatangani
attachments		array	kumpulan lampiran amplop
	fileKey	string	fileKey dokumen
signerInfos		array	informasi penandatanganan
	recipientId	string	ID penandatangan
	businessId	string	nomor bisnis kustom pengembang, batas panjang 500
	userEmail	string	alamat email penandatangan
	userName	string	nama penandatangan
	signUrl	string	alamat tautan penandatanganan
	signOrder	int	urutan penandatanganan penandatangan, minimum 1
	accessCode	string	kata sandi akses halaman penandatanganan

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