Developer & API

Ikhtisar & autentikasi

Semua endpoint berada di bawah /api/v1 pada domain ttdHUB Anda dan memakai JSON (kecuali unggah berkas: multipart/form-data).

Autentikasi organisasi: header X-API-Key: ttd_… (buat di halaman Integrasi). Kunci mewarisi peran penggunanya; peran Peninjau hanya dapat membaca. Operasi tulis lewat API key membutuhkan fitur paket api_webhooks (paket Bisnis); membaca, mengunduh, audit, dan ekspor selalu boleh.

Autentikasi mitra: header X-Partner-Key: ttdp_… di bawah /partner-api. Untuk bertindak atas organisasi pelanggan, sertakan juga X-Organization-Id. Semua endpoint Dokumen, Penerima, Field, Permintaan tanda tangan, Audit, dan Embed tersedia di bawah /partner-api/… dengan jalur yang sama (mis. POST /partner-api/documents) dan dijalankan sebagai akun layanan organisasi tersebut. Mitra tidak pernah memegang kunci atau sesi pemilik organisasi.

Galat: {error, code?}. Batas paket: 402 {code:'plan_required', feature, required_plan, required_plan_name}; kuota: 402 {code:'quota_exceeded', key, limit, used, period}. Urutan pemeriksaan: 401 → 403 → 404 → 400 → 402.

Batas laju: 600 permintaan/menit per IP untuk /api/v1, dan 600/menit per kunci mitra.

Uang selalu dalam rupiah bulat (integer).

Basis URL: https://paraf.ai.id/api/v1 · Versi 1.0.0

Mulai cepat

Buat API key di Integrasi, lalu unggah, siapkan, dan kirim dokumen:

# 1. Unggah PDF
curl -X POST "https://paraf.ai.id/api/v1/documents" -H "X-API-Key: $TTD_KEY" -F "[email protected]" -F "title=Kontrak kerja"

# 2. Tambah field tanda tangan untuk penerima (koordinat 0–1 dari halaman)
curl -X POST "https://paraf.ai.id/api/v1/document-roles" -H "X-API-Key: $TTD_KEY" -H "Content-Type: application/json" \
  -d '{"document_id":"<DOC_ID>","name":"Budi","email":"[email protected]","signer_type":"signer"}'
curl -X POST "https://paraf.ai.id/api/v1/form-fields" -H "X-API-Key: $TTD_KEY" -H "Content-Type: application/json" \
  -d '{"document_id":"<DOC_ID>","document_role_id":"<ROLE_ID>","page_number":1,"ff_type":"signature","x":0.1,"y":0.8,"w":0.3,"h":0.08}'

# 3. Kirim
curl -X POST "https://paraf.ai.id/api/v1/sign-requests/create-with-document-roles" -H "X-API-Key: $TTD_KEY" -H "Content-Type: application/json" \
  -d '{"document_id":"<DOC_ID>","document_roles":[{"id":"<ROLE_ID>","name":"Budi","email":"[email protected]"}]}'

Verifikasi webhook

Setiap webhook membawa X-ttdHUB-Event, X-ttdHUB-Timestamp, dan X-ttdHUB-Signature (HMAC-SHA256 hex atas timestamp.isi-mentah).

// Node.js: verifikasi webhook ttdHUB
const crypto = require('crypto');
function verify(rawBody, headers, secret) {
  const ts = headers['x-ttdhub-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // tolak pengulangan
  const expected = crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const got = String(headers['x-ttdhub-signature'] || '');
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Penandatanganan tersemat (mitra)

Server Anda memanggil POST /api/v1/partner-api/embed/sign-url; tampilkan URL-nya dalam iframe. Halaman ttdHUB mengirim postMessage hanya ke origin Anda yang disetujui, dengan isi {type, sign_request_id}.

<!-- Halaman mitra (origin harus disetujui, mis. https://app.mitra.co.id) -->
<iframe src="<url dari POST /embed/sign-url>" title="Tanda tangan dokumen" allow="clipboard-write"></iframe>
<script>
window.addEventListener('message', (e) => {
  if (e.origin !== 'https://paraf.ai.id') return;           // hanya pesan dari ttdHUB
  if (e.data && e.data.type === 'ttdhub:signed') { /* selesai: e.data.sign_request_id */ }
  if (e.data && e.data.type === 'ttdhub:declined') { /* ditolak */ }
});
</script>

Dokumen

Unggah PDF, lihat, unduh, dan batalkan dokumen. Dokumen baru berstatus draft.

GET`/documents`

Daftar dokumen

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /documents
Nama	Tipe	Keterangan
`q`	string · query	Cari judul — maks. 200 karakter
`status`	string · query	salah satu: "draft", "sent", "completed", "voided", "declined", "expired"
`folder_id`	string (uuid) · query
`scope`	string · query	`mine` = hanya dokumen milik pemanggil — salah satu: "mine", "team"
`limit`	integer · query	min 1 · maks 200 · bawaan 100
`offset`	integer · query	min 0 · bawaan 0

Respons

200OK
401Kredensial tidak ada atau tidak valid

POST`/documents`

Unggah dokumen PDF

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

PDF maksimal 25 MB. Dokumen baru berstatus draft.

Isi permintaan (multipart/form-data)

Isi permintaan /documents
Nama	Tipe	Keterangan
`file` wajib	string (binary)	Berkas PDF (application/pdf)
`title`	string	Judul; bawaan: nama berkas tanpa .pdf — maks. 200 karakter

Respons

201Dokumen dibuat
400Input tidak valid
401Kredensial tidak ada atau tidak valid
402Fitur di luar paket atau kuota habis
403Peran tidak mengizinkan, sesi browser diperlukan, atau mitra ditangguhkan
413Berkas terlalu besar

POST`/documents/import`

Ambil PDF dari URL publik

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

URL diambil server (dilindungi SSRF: hanya alamat publik, tanpa pengalihan), maksimal 25 MB.

Isi permintaan (application/json)

Isi permintaan /documents/import
Nama	Tipe	Keterangan
`url` wajib	string (uri)	maks. 2048 karakter
`title`	string	maks. 200 karakter

Respons

201Dokumen dibuat
400Input tidak valid

GET`/documents/{id}`

Detail dokumen beserta halaman, penerima, dan field

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /documents/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Respons

200OK
404Tidak ditemukan (juga untuk data milik organisasi lain)

PATCH`/documents/{id}`

Ubah folder atau judul (judul hanya untuk draf)

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /documents/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Isi permintaan (application/json)

Isi permintaan /documents/{id}
Nama	Tipe	Keterangan
`folder_id`	string \| null (uuid)
`title`	string	maks. 200 karakter

Respons

200OK
404Tidak ditemukan (juga untuk data milik organisasi lain)

GET`/documents/{id}/file.pdf`

Unduh PDF

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Salinan yang belum selesai diberi watermark DRAF. signed=1 mengunduh salinan final bersegel (PAdES) setelah selesai.

Parameter

Parameter /documents/{id}/file.pdf
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path
`signed`	string · query	salah satu: "1"
`raw`	string · query	Tanpa watermark; hanya untuk pengguna yang dapat mengubah dokumen — salah satu: "1"

Respons

200PDF
404Tidak ditemukan (juga untuk data milik organisasi lain)

POST`/documents/{id}/void`

Batalkan dokumen yang sedang berjalan

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Selalu tersedia lewat API key, apa pun paketnya. Memicu webhook voided.

Parameter

Parameter /documents/{id}/void
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Isi permintaan (application/json)

Isi permintaan /documents/{id}/void
Nama	Tipe	Keterangan
`reason`	string	maks. 500 karakter

Respons

200OK
400Input tidak valid
404Tidak ditemukan (juga untuk data milik organisasi lain)

Penerima

Peran penerima dokumen (Penanda tangan, Penyetuju, Peninjau/tembusan). Field ditautkan ke peran.

POST`/document-roles`

Tambah penerima ke dokumen

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Isi permintaan (application/json)

Isi permintaan /document-roles
Nama	Tipe	Keterangan
`document_id` wajib	string (uuid)
`name`	string	maks. 254 karakter
`email`	string (email)	maks. 254 karakter
`signer_type`	string	signer = Penanda tangan, approver = Penyetuju, viewer/cc = Peninjau (tembusan) — salah satu: "signer", "approver", "viewer", "cc"
`queue_position`	integer
`routing_stage`	integer	min 1 · maks 50
`is_enabled`	boolean
`require_verification`	boolean	Wajib OTP
`otp_channel`	string	salah satu: "email", "sms"
`phone`	string	Untuk OTP SMS (E.164, mis. +6281234567890)
`require_id`	boolean	Wajib verifikasi identitas
`access_code`	string \| null	Kode akses; tidak pernah dikembalikan — maks. 100 karakter
`receives_final_copy`	boolean
`badge_color`	string

Respons

201Dibuat
400Input tidak valid
404Tidak ditemukan (juga untuk data milik organisasi lain)

PUT`/document-roles/{id}`

Ubah penerima

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /document-roles/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Isi permintaan (application/json)

Isi permintaan /document-roles/{id}
Nama	Tipe	Keterangan
`name`	string	maks. 254 karakter
`email`	string (email)	maks. 254 karakter
`signer_type`	string	signer = Penanda tangan, approver = Penyetuju, viewer/cc = Peninjau (tembusan) — salah satu: "signer", "approver", "viewer", "cc"
`queue_position`	integer
`routing_stage`	integer	min 1 · maks 50
`is_enabled`	boolean
`require_verification`	boolean	Wajib OTP
`otp_channel`	string	salah satu: "email", "sms"
`phone`	string	Untuk OTP SMS (E.164, mis. +6281234567890)
`require_id`	boolean	Wajib verifikasi identitas
`access_code`	string \| null	Kode akses; tidak pernah dikembalikan — maks. 100 karakter
`receives_final_copy`	boolean
`badge_color`	string

Respons

200OK
404Tidak ditemukan (juga untuk data milik organisasi lain)

DELETE`/document-roles/{id}`

Hapus penerima

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /document-roles/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Respons

204Dihapus

Field

Field formulir pada halaman PDF. Koordinat x, y, w, h adalah pecahan 0–1 dari lebar/tinggi halaman, titik asal kiri atas.

POST`/form-fields`

Tambah satu field

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Isi permintaan (application/json)

Isi permintaan /form-fields
Nama	Tipe	Keterangan
`document_id` wajib	string (uuid)
`document_role_id`	string \| null (uuid)
`page_number`	integer	min 1 · bawaan 1
`ff_type` wajib	string	salah satu: "signature", "initials", "date", "text", "checkbox", "dropdown", "radio", "stamp", "attachment", "number", "formula"
`x` wajib	number	min 0 · maks 1
`y` wajib	number	min 0 · maks 1
`w` wajib	number	min 0 · maks 1
`h` wajib	number	min 0 · maks 1
`is_required`	boolean	bawaan true
`font_size`	integer	bawaan 12
`validation`	string	salah satu: "none", "email", "number", "date"
`auto_fill`	string	salah satu: "none", "name", "email", "date"
`locked`	boolean	Nilai diisi pengirim dan dikunci
`value`	string \| null	maks. 2000 karakter
`choices`	array<string> \| null	Pilihan dropdown/radio; untuk lampiran: `[teks permintaan]`
`name`	string	Wajib untuk angka/rumus — pola ^[a-z][a-z0-9_]{0,31}$
`formula`	string	Untuk ff_type=formula, mis. `harga * jumlah`
`min`	number
`max`	number
`condition`	object \| null	Tampilkan field hanya bila kondisi terpenuhi
`condition.field_id` wajib	string	Id field pengendali (atau `ref` dalam batch)
`condition.op` wajib	string	salah satu: "checked", "unchecked", "equals", "not_equals", "not_empty"
`condition.value`	string \| number

Respons

201Dibuat
400Input tidak valid
402Fitur di luar paket atau kuota habis

POST`/form-fields/update-many`

Simpan banyak field sekaligus (buat & ubah)

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Entri dengan id mengubah field yang ada; tanpa id membuat field baru. ref (≤ 64 karakter) dapat dirujuk oleh condition.field_id field lain dalam batch yang sama. Maksimal 1000 field.

Isi permintaan (application/json)

Isi permintaan /form-fields/update-many
Nama	Tipe	Keterangan
`document_id` wajib	string (uuid)
`fields` wajib	array<object>	maks. 1000 item
`fields[].document_role_id`	string \| null (uuid)
`fields[].page_number`	integer	min 1 · bawaan 1
`fields[].ff_type` wajib	string	salah satu: "signature", "initials", "date", "text", "checkbox", "dropdown", "radio", "stamp", "attachment", "number", "formula"
`fields[].x` wajib	number	min 0 · maks 1
`fields[].y` wajib	number	min 0 · maks 1
`fields[].w` wajib	number	min 0 · maks 1
`fields[].h` wajib	number	min 0 · maks 1
`fields[].is_required`	boolean	bawaan true
`fields[].font_size`	integer	bawaan 12
`fields[].validation`	string	salah satu: "none", "email", "number", "date"
`fields[].auto_fill`	string	salah satu: "none", "name", "email", "date"
`fields[].locked`	boolean	Nilai diisi pengirim dan dikunci
`fields[].value`	string \| null	maks. 2000 karakter
`fields[].choices`	array<string> \| null	Pilihan dropdown/radio; untuk lampiran: `[teks permintaan]`
`fields[].name`	string	Wajib untuk angka/rumus — pola ^[a-z][a-z0-9_]{0,31}$
`fields[].formula`	string	Untuk ff_type=formula, mis. `harga * jumlah`
`fields[].min`	number
`fields[].max`	number
`fields[].condition`	object \| null	Tampilkan field hanya bila kondisi terpenuhi
`fields[].id`	string (uuid)
`fields[].ref`	string	maks. 64 karakter

Respons

200OK
400Input tidak valid
402Fitur di luar paket atau kuota habis

DELETE`/form-fields/{id}`

Hapus field

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /form-fields/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Respons

204Dihapus

Permintaan tanda tangan

Kirim dokumen ke penerima. Setiap pengiriman memakai 1 kuota dokumen bulanan organisasi.

POST`/sign-requests/create-with-document-roles`

Kirim dokumen untuk ditandatangani

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Membuat/memperbarui peran penerima lalu mengirim undangan ke tahap pertama. routing_stage > 1, Penyetuju, atau allow_delegation membutuhkan fitur routing_stages; field kondisional/angka/rumus logic_fields; stempel/lampiran stamp_attachments; OTP SMS sms_otp. Memakai 1 kuota dokumen (402 quota_exceeded bila habis). Memicu webhook sent.

Isi permintaan (application/json)

Isi permintaan /sign-requests/create-with-document-roles
Nama	Tipe	Keterangan
`document_id` wajib	string (uuid)
`title`	string
`email_subject`	string
`email_body`	string
`has_queue`	boolean	Urutan lama: tahap 1..n mengikuti queue_position
`allow_delegation`	boolean
`reminders_enabled`	boolean
`reminder_every_hours`	integer	min 0
`sender_receives_final_copy`	boolean	bawaan true
`expires_in_days`	number	maks 3650
`document_roles` wajib	array<object>	maks. 50 item
`document_roles[].name`	string	maks. 254 karakter
`document_roles[].email`	string (email)	maks. 254 karakter
`document_roles[].signer_type`	string	signer = Penanda tangan, approver = Penyetuju, viewer/cc = Peninjau (tembusan) — salah satu: "signer", "approver", "viewer", "cc"
`document_roles[].queue_position`	integer
`document_roles[].routing_stage`	integer	min 1 · maks 50
`document_roles[].is_enabled`	boolean
`document_roles[].require_verification`	boolean	Wajib OTP
`document_roles[].otp_channel`	string	salah satu: "email", "sms"
`document_roles[].phone`	string	Untuk OTP SMS (E.164, mis. +6281234567890)
`document_roles[].require_id`	boolean	Wajib verifikasi identitas
`document_roles[].access_code`	string \| null	Kode akses; tidak pernah dikembalikan — maks. 100 karakter
`document_roles[].receives_final_copy`	boolean
`document_roles[].badge_color`	string
`document_roles[].id`	string (uuid)	Peran yang sudah ada (field tetap tertaut)

Respons

201Terkirim
400Input tidak valid
402Fitur di luar paket atau kuota habis
404Tidak ditemukan (juga untuk data milik organisasi lain)

POST`/sign-requests/{id}/void`

Batalkan permintaan tanda tangan

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /sign-requests/{id}/void
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Isi permintaan (application/json)

Isi permintaan /sign-requests/{id}/void
Nama	Tipe	Keterangan
`reason`	string

Respons

200OK
404Tidak ditemukan (juga untuk data milik organisasi lain)
409Status tidak mengizinkan aksi ini

POST`/sign-requests/signers/{signerId}/reassign`

Ganti penanda tangan yang belum menandatangani

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Tautan lama berhenti berlaku; penerima baru menerima undangan.

Parameter

Parameter /sign-requests/signers/{signerId}/reassign
Nama	Tipe	Keterangan
`signerId` wajib	string (uuid) · path

Isi permintaan (application/json)

Isi permintaan /sign-requests/signers/{signerId}/reassign
Nama	Tipe	Keterangan
`email` wajib	string (email)	maks. 254 karakter
`name`	string	maks. 200 karakter

Respons

200OK
409Status tidak mengizinkan aksi ini

Audit

Jejak audit lengkap dokumen. Token penanda tangan, hash kode, dan berkas identitas tidak pernah dikembalikan.

GET`/audit/{documentId}`

Jejak audit dokumen

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /audit/{documentId}
Nama	Tipe	Keterangan
`documentId` wajib	string (uuid) · path

Respons

200OK
404Tidak ditemukan (juga untuk data milik organisasi lain)

Integrasi

API key dan webhook organisasi. Webhook dikelola Pemilik/Admin; membuat API key hanya lewat sesi browser.

GET`/integrations/api-keys`

Daftar API key (Anggota: miliknya; Admin: seluruh organisasi)

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Respons

200OK

DELETE`/integrations/api-keys/{id}`

Cabut API key

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /integrations/api-keys/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Respons

204Dicabut

GET`/integrations/webhooks`

Daftar webhook (Pemilik/Admin)

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Respons

200OK

POST`/integrations/webhooks`

Tambah webhook (Pemilik/Admin)

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

URL harus alamat publik (diperiksa ulang saat pengiriman). Maksimal 25 webhook. secret HMAC hanya ditampilkan sekali.

Isi permintaan (application/json)

Isi permintaan /integrations/webhooks
Nama	Tipe	Keterangan
`url` wajib	string (uri)	maks. 2048 karakter
`events`	array<string>	Kosong = semua event

Respons

201Dibuat
402Fitur di luar paket atau kuota habis

DELETE`/integrations/webhooks/{id}`

Hapus webhook

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Parameter

Parameter /integrations/webhooks/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Respons

204Dihapus

GET`/integrations/webhooks/{id}/deliveries`

50 pengiriman terakhir sebuah webhook

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

status: sent, failed, atau skipped_plan (organisasi tidak lagi memiliki fitur API & webhook; webhook tidak dihapus).

Parameter

Parameter /integrations/webhooks/{id}/deliveries
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Respons

200OK

Embed

Penandatanganan tersemat (iframe) untuk organisasi pelanggan mitra. URL berlaku 10 menit, sekali pakai, dan hanya dapat dibingkai oleh origin mitra yang disetujui.

POST`/embed/sign-url`

Buat URL penandatanganan tersemat

Header X-API-Key (juga tersedia di /partner-api dengan X-Partner-Key + X-Organization-Id untuk organisasi pelanggan mitra)

Hanya untuk organisasi pelanggan mitra (atau lewat /partner-api/embed/sign-url dengan X-Organization-Id). origin harus persis salah satu origin embed mitra yang disetujui (https://host[:port]); bawaan: origin dari return_url, atau satu-satunya origin yang disetujui. return_url harus memakai origin yang sama. URL berlaku 10 menit dan hanya dapat ditukar sekali; buat URL baru untuk setiap pemuatan iframe.

Isi permintaan (application/json)

Isi permintaan /embed/sign-url
Nama	Tipe	Keterangan
`sign_request_id` wajib	string (uuid)
`signer_email` wajib	string (email)
`origin`	string
`return_url`	string (uri)

Respons

201URL dibuat
400Input tidak valid
403Peran tidak mengizinkan, sesi browser diperlukan, atau mitra ditangguhkan
404Tidak ditemukan (juga untuk data milik organisasi lain)
409Status tidak mengizinkan aksi ini

POST`/embed/exchange`

Tukar token embed (dipakai halaman tanda tangan)

Publik, tanpa kunci.

Dipanggil oleh sign.html?embed=…, bukan oleh server mitra. Sekali pakai; pemanggilan berikutnya, token kedaluwarsa, mitra ditangguhkan, atau origin yang dicabut menghasilkan 410 embed_unavailable.

Isi permintaan (application/json)

Isi permintaan /embed/exchange
Nama	Tipe	Keterangan
`token` wajib	string

Respons

200OK
410Tidak lagi tersedia

Mitra

API OEM untuk mitra: buat organisasi pelanggan, pantau pemakaian, dan jalankan API dokumen atas nama organisasi pelanggan (header X-Organization-Id).

GET`/partner-api/me`

Profil mitra

Header X-Partner-Key

Respons

200OK
401Kredensial tidak ada atau tidak valid

GET`/partner-api/organizations`

Daftar organisasi pelanggan

Header X-Partner-Key

Parameter

Parameter /partner-api/organizations
Nama	Tipe	Keterangan
`q`	string · query	Cari nama atau external_id — maks. 120 karakter
`page`	integer · query	min 1 · bawaan 1
`page_size`	integer · query	min 1 · maks 100 · bawaan 25
`period`	string · query	Bulan `YYYY-MM` (Asia/Jakarta); bawaan bulan berjalan — pola ^\d{4}-(0[1-9]\|1[0-2])$

Respons

200OK

POST`/partner-api/organizations`

Buat organisasi pelanggan

Header X-Partner-Key

Membuat organisasi dengan paket mitra (tanpa uji coba), akun layanan untuk API, dan undangan Pemilik yang dikirim langsung ke email pemilik (tautan undangan tidak pernah dikembalikan ke mitra). Maksimal 100 organisasi per 24 jam per mitra.

Isi permintaan (application/json)

Isi permintaan /partner-api/organizations
Nama	Tipe	Keterangan
`name` wajib	string	maks. 120 karakter
`owner_email` wajib	string (email)	maks. 254 karakter
`external_id`	string	Referensi Anda sendiri; unik per mitra — pola ^[A-Za-z0-9._:-]{1,100}$

Respons

201Dibuat
400Input tidak valid
401Kredensial tidak ada atau tidak valid
403Peran tidak mengizinkan, sesi browser diperlukan, atau mitra ditangguhkan
409Status tidak mengizinkan aksi ini
429Batas 100 organisasi per 24 jam (`org_daily_limit`)

GET`/partner-api/organizations/{id}`

Detail organisasi pelanggan

Header X-Partner-Key

Parameter

Parameter /partner-api/organizations/{id}
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path
`period`	string · query	Bulan `YYYY-MM` (Asia/Jakarta); bawaan bulan berjalan — pola ^\d{4}-(0[1-9]\|1[0-2])$

Respons

200OK
404Tidak ditemukan (juga untuk data milik organisasi lain)

POST`/partner-api/organizations/{id}/owner-invite`

Kirim ulang undangan Pemilik

Header X-Partner-Key

Hanya selama organisasi belum memiliki Pemilik (409 owner_exists). Undangan lama dicabut.

Parameter

Parameter /partner-api/organizations/{id}/owner-invite
Nama	Tipe	Keterangan
`id` wajib	string (uuid) · path

Isi permintaan (application/json)

Isi permintaan /partner-api/organizations/{id}/owner-invite
Nama	Tipe	Keterangan
`owner_email`	string (email)

Respons

200OK
404Tidak ditemukan (juga untuk data milik organisasi lain)
409Status tidak mengizinkan aksi ini

GET`/partner-api/usage`

Pemakaian dokumen per organisasi pelanggan

Header X-Partner-Key

Dokumen terkirim dalam periode (Asia/Jakarta), dasar tagihan partner_usage bulanan = dokumen × doc_price. Sertakan X-Organization-Id untuk satu organisasi.

Parameter

Parameter /partner-api/usage
Nama	Tipe	Keterangan
`period`	string · query	Bulan `YYYY-MM` (Asia/Jakarta); bawaan bulan berjalan — pola ^\d{4}-(0[1-9]\|1[0-2])$
`X-Organization-Id`	string (uuid) · header

Respons

200OK

POST`/partner-api/sign-requests/create-with-document-roles`

Contoh: kirim dokumen atas nama organisasi pelanggan

Header X-Partner-Key

Sama dengan POST /sign-requests/create-with-document-roles, dengan header X-Partner-Key + X-Organization-Id. Pola yang sama berlaku untuk /partner-api/documents, /partner-api/document-roles, /partner-api/form-fields, /partner-api/sign-requests, /partner-api/audit, dan /partner-api/embed.

Parameter

Parameter /partner-api/sign-requests/create-with-document-roles
Nama	Tipe	Keterangan
`X-Organization-Id` wajib	string (uuid) · header	Id organisasi pelanggan milik mitra

Isi permintaan (application/json)

Isi permintaan /partner-api/sign-requests/create-with-document-roles
Nama	Tipe	Keterangan
`document_id` wajib	string (uuid)
`title`	string
`email_subject`	string
`email_body`	string
`has_queue`	boolean	Urutan lama: tahap 1..n mengikuti queue_position
`allow_delegation`	boolean
`reminders_enabled`	boolean
`reminder_every_hours`	integer	min 0
`sender_receives_final_copy`	boolean	bawaan true
`expires_in_days`	number	maks 3650
`document_roles` wajib	array<object>	maks. 50 item
`document_roles[].name`	string	maks. 254 karakter
`document_roles[].email`	string (email)	maks. 254 karakter
`document_roles[].signer_type`	string	signer = Penanda tangan, approver = Penyetuju, viewer/cc = Peninjau (tembusan) — salah satu: "signer", "approver", "viewer", "cc"
`document_roles[].queue_position`	integer
`document_roles[].routing_stage`	integer	min 1 · maks 50
`document_roles[].is_enabled`	boolean
`document_roles[].require_verification`	boolean	Wajib OTP
`document_roles[].otp_channel`	string	salah satu: "email", "sms"
`document_roles[].phone`	string	Untuk OTP SMS (E.164, mis. +6281234567890)
`document_roles[].require_id`	boolean	Wajib verifikasi identitas
`document_roles[].access_code`	string \| null	Kode akses; tidak pernah dikembalikan — maks. 100 karakter
`document_roles[].receives_final_copy`	boolean
`document_roles[].badge_color`	string
`document_roles[].id`	string (uuid)	Peran yang sudah ada (field tetap tertaut)

Respons

201Terkirim (lihat sendDocument)
403Peran tidak mengizinkan, sesi browser diperlukan, atau mitra ditangguhkan
404Tidak ditemukan (juga untuk data milik organisasi lain)

Event webhook

Isi permintaan: {"event", "at", "data"}. Balas 2xx dalam 10 detik; pengiriman tidak diulang.

EVENT`sent`

Dokumen dikirim

Data event sent
Nama	Tipe	Keterangan
`data.document_id`	string (uuid)
`data.sign_request_id`	string (uuid)
`data.title`	string
`data.signers`	array<string>

EVENT`completed`

Semua pihak selesai; salinan final bersegel tersedia

Data event completed
Nama	Tipe	Keterangan
`data.document_id`	string (uuid)
`data.signed_hash`	string	SHA-256 PDF final

EVENT`declined`

Penerima menolak

Data event declined
Nama	Tipe	Keterangan
`data.document_id`	string (uuid)
`data.by`	string (email)
`data.reason`	string \| null

EVENT`voided`

Pengirim membatalkan dokumen

Data event voided
Nama	Tipe	Keterangan
`data.document_id`	string (uuid)
`data.reason`	string \| null

ttdHUB API

Ikhtisar & autentikasi

Mulai cepat

Verifikasi webhook

Penandatanganan tersemat (mitra)

Dokumen

GET/documents

Parameter

Respons

POST/documents

Isi permintaan (multipart/form-data)

Respons

POST/documents/import

Isi permintaan (application/json)

Respons

GET/documents/{id}

Parameter

Respons

PATCH/documents/{id}

Parameter

Isi permintaan (application/json)

Respons

GET/documents/{id}/file.pdf

Parameter

Respons

POST/documents/{id}/void

Parameter

Isi permintaan (application/json)

Respons

Penerima

POST/document-roles

Isi permintaan (application/json)

Respons

PUT/document-roles/{id}

Parameter

Isi permintaan (application/json)

Respons

DELETE/document-roles/{id}

Parameter

Respons

Field

POST/form-fields

Isi permintaan (application/json)

Respons

POST/form-fields/update-many

Isi permintaan (application/json)

Respons

DELETE/form-fields/{id}

Parameter

Respons

Permintaan tanda tangan

POST/sign-requests/create-with-document-roles

Isi permintaan (application/json)

Respons

POST/sign-requests/{id}/void

Parameter

Isi permintaan (application/json)

Respons

POST/sign-requests/signers/{signerId}/reassign

Parameter

Isi permintaan (application/json)

Respons

Audit

GET/audit/{documentId}

Parameter

Respons

Integrasi

GET/integrations/api-keys

Respons

DELETE/integrations/api-keys/{id}

Parameter

Respons

GET/integrations/webhooks

Respons

POST/integrations/webhooks

Isi permintaan (application/json)

Respons

DELETE/integrations/webhooks/{id}

Parameter

Respons

GET`/documents`

POST`/documents`

POST`/documents/import`

GET`/documents/{id}`

PATCH`/documents/{id}`

GET`/documents/{id}/file.pdf`

POST`/documents/{id}/void`

POST`/document-roles`

PUT`/document-roles/{id}`

DELETE`/document-roles/{id}`

POST`/form-fields`

POST`/form-fields/update-many`

DELETE`/form-fields/{id}`

POST`/sign-requests/create-with-document-roles`

POST`/sign-requests/{id}/void`

POST`/sign-requests/signers/{signerId}/reassign`

GET`/audit/{documentId}`

GET`/integrations/api-keys`

DELETE`/integrations/api-keys/{id}`

GET`/integrations/webhooks`

POST`/integrations/webhooks`

DELETE`/integrations/webhooks/{id}`

GET`/integrations/webhooks/{id}/deliveries`

POST`/embed/sign-url`

POST`/embed/exchange`

GET`/partner-api/me`

GET`/partner-api/organizations`

POST`/partner-api/organizations`

GET`/partner-api/organizations/{id}`

POST`/partner-api/organizations/{id}/owner-invite`

GET`/partner-api/usage`

POST`/partner-api/sign-requests/create-with-document-roles`

EVENT`sent`

EVENT`completed`

EVENT`declined`

EVENT`voided`