Amplop & penerima

Amplop adalah satu kontrak yang sedang dalam proses ditandatangani: sebuah versi template yang dirender dengan variabel Anda, penerima yang bertindak atasnya, dan bukti dari semua yang terjadi. Buat amplop dengan POST /v1/envelopes.

Membuat amplop

Kolom	Tipe	Catatan
template	tpl_…	Wajib
version	angka atau "latest"	Default latest; diselesaikan dan disematkan saat pembuatan. Harus sudah dipublikasikan
variables	objek	Divalidasi terhadap JSON Schema versi tersebut
recipients	array	Satu per peran (role, name, email; opsional externalUserId, verification, fields untuk prefill berdasarkan id kolom, order untuk mengubah urutan penandatanganan)
subject, message	string	Dipakai dalam email penandatanganan dan ditampilkan di halaman penandatanganan
delivery	email · embedded · none	Default email
expiresAt	RFC 3339	Harus di masa depan; amplop kedaluwarsa pada saat itu, dan tautan penandatanganan serta tautan pemantau berhenti berfungsi
cc	array	Penerima CC tambahan (name, email) di luar peran CC template; hingga 50
viewers	array	Orang yang mengikuti amplop tanpa menandatangani (name, email, opsional notifyOnSignature); jumlah per amplop dibatasi sesuai paket
viewerDocumentAccess	boolean	Izinkan pemantau membuka dokumen di halaman statusnya. Default false (hanya status); paket Team ke atas
reminders	objek	{ "enabled": false } menonaktifkan pengingat; { "enabled": true, "intervalHours": 24 } mengubah intervalnya (1 hingga 720)
externalId	string	Id milik Anda sendiri, hingga 200 karakter
dedupeOn	"external_id"	Mengembalikan amplop yang sudah ada dengan externalId ini alih-alih membuat yang baru
metadata	objek berisi string	Hingga 500 karakter per nilai; dikembalikan pada amplop dan di webhook

Setiap penerima memerlukan peran dari versi tersebut; setiap peran non-CC memerlukan tepat satu penerima. Error dilaporkan sekaligus, dengan pointer seperti /recipients/1/role atau /recipients/0/fields/start_date.

Respons: 201 dengan amplop dan header Location; 200 dengan amplop yang sudah ada dan x-deduplicated: true saat dedupeOn cocok; 200 dengan ringkasan dry run untuk ?dry_run=true; 402 saat workspace Free telah menghabiskan amplop yang termasuk dalam paketnya; 403 plan-upgrade-required saat jumlah pemantau melebihi jatah paket atau viewerDocumentAccess tidak tersedia di paket (Paket & batas). Dry run juga memeriksa batas paket.

Setiap kolom yang ditambahkan setelah rilis pertama bersifat opsional: permintaan tanpa kolom tersebut berperilaku persis seperti sebelumnya.

Opsi saat pengiriman

Template menentukan siapa menandatangani dalam urutan apa. Untuk satu amplop, Anda dapat mengubahnya tanpa menyentuh template:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

• Urutan: recipients[].order adalah langkah tempat penerima menandatangani; penerima dengan nomor yang sama menandatangani pada waktu yang sama. Tanpa nilai ini, order peran dari template yang berlaku. Urutan berupa bilangan bulat positif; peran CC tidak dapat diurutkan; setiap peran tetap memerlukan penerimanya (agar kolom template tetap memiliki penanda tangan); minimal satu penerima harus menandatangani. Event envelope.created mencatat routingOverridden: true.
• CC: penerima CC tambahan mendapat email dokumen yang telah selesai dan tidak pernah menandatangani. Mereka muncul di recipients dengan kind: "cc" dan peran _cc.
• Pengingat: penerima yang sedang mendapat giliran diingatkan setiap intervalHours (default: nilai REMINDER_INTERVAL_HOURS deployment, 72), paling banyak tiga kali; enabled: false tidak mengirim pengingat sama sekali. Pengingat berlaku untuk pengiriman email.
• Autentikasi penanda tangan berlaku per penerima: verification menggantikan metode peran. none (hanya tautan penandatanganan unik, default untuk peran yang tidak menetapkannya) dan email_otp (tautan ditambah kode yang dikirim lewat email) tersedia saat ini; passkey dan id_check ditolak karena belum tersedia. Lihat verifikasi penanda tangan.
• Bahasa: locale pada penerima, CC, atau pemantau (atau pada amplop, untuk semua orang yang tidak memiliki nilainya sendiri) menetapkan bahasa halaman penandatanganan dan email mereka, salah satu dari 50 bahasa penandatanganan. Tanpa nilai ini, halaman penandatanganan mengikuti browser dan email dikirim dalam bahasa Inggris.

Layar kirim di dasbor menawarkan opsi yang sama: majukan atau mundurkan langkah, centang Tanda tangani bersamaan, tambahkan CC dan pemantau, pilih autentikasi setiap penanda tangan (Hanya tautan email atau Tautan email + kode) dan bahasanya, serta tetapkan tanggal kedaluwarsa dan jadwal pengingat.

Pengiriman

• email: setiap penerima dikirimi email berisi tautan ke halaman penandatanganan yang di-hosting saat tiba gilirannya. Penerima yang belum menandatangani mendapat pengingat setiap beberapa hari (hingga tiga kali), dan semua orang dikirimi email saat amplop selesai.
• embedded: tidak ada email ke penanda tangan. Buat sesi penandatanganan saat penanda tangan berada di produk Anda. Pemantau tetap dikirimi tautan status melalui email.
• none: tidak ada email sama sekali (termasuk pemantau); gunakan saat Anda mengirimkan tautan sendiri (sesi yang di-hosting).

POST /v1/envelopes/{id}/recipients/{recipient}/resend mengirim email berisi tautan baru kepada penerima yang sedang mendapat giliran (paling banyak sekali per menit).

Siklus hidup

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

status	Arti
rendering	Sedang disiapkan
sent	Sedang berjalan: penerima menandatangani sesuai urutan perutean
completed	Semua penerima selesai. Penyegelan dimulai
declined	Seorang penerima menolak; amplop berakhir
voided	Anda membatalkannya ({ "reason": "…" }); sesi penandatanganan yang terbuka berhenti berfungsi
expired	expiresAt terlewati sebelum selesai

seal melacak PDF yang disegel: not_started, pending (selesai, sedang disegel), sealed, atau failed. Penyegelan tidak pernah menghambat penyelesaian: amplop selesai terlebih dahulu lalu langsung disegel setelahnya.

Penerima dan perutean

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

status penerima adalah pending (belum gilirannya), sent, viewed, completed, atau declined, dan kind adalah jenis peran: signer, approver, form_filler, atau cc. Perutean berdasarkan order (milik peran, atau penggantian saat pengiriman): semua penerima dari urutan terendah yang belum selesai bertindak secara paralel, dan grup berikutnya dimulai setelah mereka selesai. Penerima CC tidak pernah menghambat perutean.

Pemantau

Pemantau mengikuti amplop tanpa menandatangani: seorang manajer, paralegal, atau pemilik akun di pihak pelanggan. Pemantau bukan penerima. Mereka tidak memiliki peran maupun giliran, tidak pernah menghambat atau menyelesaikan apa pun, dan tidak pernah muncul di daftar penanda tangan pada sertifikat.

• Saat amplop dikirim (atau saat Anda menambahkan mereka kemudian dengan POST /v1/envelopes/{id}/viewers), setiap pemantau mendapat email bermerek berisi tautan ke halaman status hanya-baca: judul amplop, pengirim, setiap langkah beserta nama, peran, status, dan stempel waktu penerimanya, diperbarui secara langsung saat orang menandatangani. Alamat email penerima tidak ditampilkan.
• Pemantau dikirimi email lagi saat amplop selesai, ditolak, atau dibatalkan, dan setelah setiap tanda tangan jika notifyOnSignature bernilai true (default nonaktif).
• Dokumen hanya ada di halaman tersebut jika Anda menetapkan viewerDocumentAccess: true (paket Team ke atas): dokumen asli selama proses berjalan, PDF yang disegel setelah disegel. Jika tidak, pemantau hanya melihat status.
• DELETE /v1/envelopes/{id}/viewers/{viewer} mencabut akses pemantau: setiap tautan yang pernah dikirim kepadanya langsung berhenti berfungsi.
• Tautan adalah URL kapabilitas pribadi. Hanya SHA-256 dari setiap token tautan yang disimpan. Tautan berfungsi hingga amplop kedaluwarsa (paling lama 90 hari), selama 30 hari setelah amplop selesai, dan tidak pernah setelah akses pemantau dicabut.
• Penambahan, pembukaan (tampilan pertama halaman dan dokumen), dan pencabutan dicatat dalam jejak audit sebagai viewer.added, viewer.viewed, viewer.document_viewed, dan viewer.revoked, sehingga juga tercantum di sertifikat.

Respons untuk satu amplop (create, get, void) mencantumkan mereka:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

Jumlah pemantau per amplop bergantung pada paket (Free 1, Bayar sesuai pemakaian 2, Team 5, Business 20, Platform tanpa batas); penerima CC tidak dihitung. Pemantau yang aksesnya dicabut membebaskan tempatnya.

Dokumen

GET /v1/envelopes/{id}/document?version=… mengunduh PDF, dengan SHA-256-nya di x-document-sha256:

version	File
original (default)	Dokumen hasil render seperti saat dikirim untuk ditandatangani
sealed	PDF akhir: nilai diratakan, sertifikat penyelesaian ditambahkan, stempel waktu dokumen. Setelah envelope.sealed
certificate	Sertifikat penyelesaian saja

documentHash amplop adalah SHA-256 dokumen asli, dan sealedDocumentHash adalah SHA-256 file yang disegel; nilai-nilai inilah yang dicari oleh verifikasi.

Jejak audit

Setiap tindakan adalah event dalam rantai hash per amplop: hash = SHA-256(prevHash ‖ canonical JSON of the event), dengan prevHash pertama berupa 64 angka nol. GET /v1/envelopes/{id}/events mengembalikan event dan memeriksa rantainya:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

Selain jenis event webhook, jejak ini memiliki entri khusus audit seperti session.created, recipient.verified, recipient.reminded, dan event pemantau (jenis aktor viewer saat pemantau membuka halamannya).

Untuk status langsung di UI, GET /v1/envelopes/{id}/events/stream adalah aliran server-sent events: nama event setiap frame adalah type event dan id-nya adalah seq; sambungkan ulang dengan Last-Event-ID untuk melanjutkan.

Menampilkan daftar

GET /v1/envelopes memfilter berdasarkan status, seal, template, dan q (teks bebas pada nama dan email penerima, externalId, dan id amplop). Seperti semua daftar, hasilnya dipaginasi dengan kursor:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

Kirim kembali nextCursor sebagai cursor; limit bernilai 1 hingga 100 (default 20).

Tips

Simpan id amplop (atau gunakan externalId) di sisi Anda, dan tanggapi webhook alih-alih melakukan polling.