Mulai cepat

Panduan ini membawa template yang sudah dipublikasikan hingga menjadi PDF yang ditandatangani dan disegel. Panduan ini memakai kunci uji, sehingga tidak ada yang ditagih dan setiap dokumen diberi tanda air TEST.

Buat kunci API
Section titled “Buat kunci API”

Kunci API dibuat di dasbor, di Pengaturan › Kunci API. Pilih Test untuk panduan ini: kuncinya diawali bf_test_. Kunci lengkap hanya ditampilkan sekali; simpan sebagai variabel lingkungan.
Terminal window
```
export BONA_FIDE_API_KEY=bf_test_…
```
Setiap permintaan mengirimkannya sebagai Authorization: Bearer … (atau x-api-key: …). Lihat Autentikasi.
Temukan template Anda
Section titled “Temukan template Anda”

Template dirancang di dasbor (unggah dokumen PDF atau Word lalu tempatkan kolom, atau tulis dalam mode Dokumen), lalu dipublikasikan. Tampilkan daftarnya untuk mendapatkan id:
Terminal window
curl https://api.bonafidesign.com/v1/templates \ -H "Authorization: Bearer $BONA_FIDE_API_KEY"
const res = await fetch('https://api.bonafidesign.com/v1/templates', { headers: { Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}` }, }); const { data } = await res.json(); // [{ id: 'tpl_…', name: 'Mutual NDA', latestVersion: 3, … }]
import os, requests API = "https://api.bonafidesign.com" headers = {"Authorization": f"Bearer {os.environ['BONA_FIDE_API_KEY']}"} templates = requests.get(f"{API}/v1/templates", headers=headers).json()["data"]
GET /v1/templates/{id}/versions/latest mengembalikan roles, fields versi tersebut, dan JSON Schema dari variables-nya. Halaman template di dasbor juga memiliki panel Gunakan di API berisi permintaan siap pakai untuk versi tersebut.

Buat amplop

POST /v1/envelopes merender template dengan variabel Anda, menyematkan versinya, dan mulai merutekan. Berikan satu penerima per peran (peran CC bersifat opsional). Kirim Idempotency-Key agar percobaan ulang tidak mengirim dua kali.

curl https://api.bonafidesign.com/v1/envelopes \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-8841" \
  -d '{
    "template": "tpl_…",
    "version": "latest",
    "variables": {
      "client": { "name": "Acme Robotics, Inc." },
      "effective_date": "2026-10-13"
    },
    "recipients": [
      { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev" }
    ],
    "delivery": "embedded",
    "externalId": "user_8841",
    "dedupeOn": "external_id"
  }'

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'onboarding-8841',
  },
  body: JSON.stringify({
    template: 'tpl_…',
    version: 'latest',
    variables: { client: { name: 'Acme Robotics, Inc.' }, effective_date: '2026-10-13' },
    recipients: [{ role: 'client', name: 'Jane Doe', email: 'jane@acme.dev' }],
    delivery: 'embedded',
    externalId: 'user_8841',
    dedupeOn: 'external_id',
  }),
});
if (res.status === 422) {
  // RFC 9457 problem: one entry per error, each with a JSON Pointer such as /variables/client/name
  console.error((await res.json()).errors);
}
const envelope = await res.json(); // { id: 'env_…', status: 'sent', recipients: [{ id: 'rcp_…', … }] }

res = requests.post(
    f"{API}/v1/envelopes",
    headers={**headers, "Idempotency-Key": "onboarding-8841"},
    json={
        "template": "tpl_…",
        "version": "latest",
        "variables": {"client": {"name": "Acme Robotics, Inc."}, "effective_date": "2026-10-13"},
        "recipients": [{"role": "client", "name": "Jane Doe", "email": "jane@acme.dev"}],
        "delivery": "embedded",
        "externalId": "user_8841",
        "dedupeOn": "external_id",
    },
)
if res.status_code == 422:
    print(res.json()["errors"])  # [{"pointer": "/variables/client/name", "message": "…"}]
envelope = res.json()

Responsnya adalah 201 Created dengan amplop:

{
  "id": "env_8Gm2kQ4rT1",
  "organization": "org_…",
  "template": "tpl_…",
  "templateVersion": 3,
  "status": "sent",
  "seal": "not_started",
  "testMode": true,
  "recipients": [
    {
      "id": "rcp_5Jw0pLs9Xe",
      "role": "client",
      "name": "Jane Doe",
      "email": "jane@acme.dev",
      "order": 1,
      "status": "sent",
      "verification": "email_otp",
      "completedAt": null
    }
  ],
  "documentHash": "9f2c…",
  "sealedDocumentHash": null,
  "externalId": "user_8841",
  "metadata": {},
  "createdAt": "2026-10-13T13:58:04.512Z",
  "completedAt": null
}

delivery menentukan cara menjangkau penerima: email (default) mengirim email berisi tautan penandatanganan kepada setiap penerima saat tiba gilirannya; embedded dan none tidak mengirim email, dan Anda sendiri yang membuka sesi penandatanganan (langkah berikutnya).

Biarkan penerima menandatangani
Section titled “Biarkan penerima menandatangani”

Buat sesi penandatanganan untuk penerima dari backend Anda. Sesi berumur pendek (ttlSeconds, 60 hingga 3600, default 600) dan sekali pakai.
- Tersemat
- Di-hosting
Terminal window
curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \ -H "Authorization: Bearer $BONA_FIDE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"] }'
Teruskan token yang dikembalikan (bfs_…) ke halaman Anda dan render web component-nya:
<script type="module" src="https://js.bonafidesign.com/v1"></script> <bf-signing session="bfs_…"></bf-signing> <script> document.querySelector('bf-signing') .addEventListener('completed', (e) => console.log('signed', e.detail.envelope)); </script>
Wrapper React dan Vue, event, dan model keamanan: Penandatanganan tersemat.
Terminal window
curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \ -H "Authorization: Bearer $BONA_FIDE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "hosted", "returnUrl": "https://app.example.com/done" }'
Arahkan penanda tangan ke url yang dikembalikan (https://sign.bonafidesign.com/s/bfs_…). Halaman yang di-hosting dirancang mobile-first dan tidak memerlukan akun.
Dengan verifikasi default email_otp, penanda tangan mengonfirmasi kode enam digit yang dikirim ke emailnya sebelum mengirimkan. Dalam mode uji, email hanya dikirim ke anggota organisasi Anda, jadi gunakan alamat Anda sendiri saat menguji.

Dapatkan notifikasi saat selesai

Daftarkan endpoint webhook di Pengaturan › Webhook (atau dengan POST /v1/webhook-endpoints) dan simpan secret whsec_…. Saat penerima terakhir menandatangani, Anda menerima envelope.completed, dengan setiap variabel dan nilai yang diisi di data.values. PDF yang disegel menyusul dengan envelope.sealed.

import express from 'express';
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.BONA_FIDE_WEBHOOK_SECRET!);
const app = express();

app.post('/hooks/bona-fide', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = wh.verify(req.body, req.headers as Record<string, string>) as { type: string; data: any };
  if (event.type === 'envelope.completed') await saveValues(event.data.envelope.id, event.data.values);
  if (event.type === 'envelope.sealed') await fetchSealedPdf(event.data.envelope.id);
  res.sendStatus(204);
});

Unduh PDF yang disegel (dokumen beserta sertifikat penyelesaiannya, dengan stempel waktu):

curl -o signed.pdf "https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/document?version=sealed" \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY"

Daftar event lengkap, percobaan ulang, dan verifikasi manual: Webhook.

Beralih ke live

Ganti kunci uji dengan kunci bf_live_. Amplop live tidak diberi tanda air, email dikirim ke penerima mana pun, dan amplop yang selesai dihitung dalam kuota paket Anda (Paket & batas). Semua yang dibuat oleh sebuah kunci mengikuti mode kunci tersebut, daftarnya hanya menampilkan mode itu, dan amplop uji hanya memberi notifikasi ke endpoint webhook mode uji, jadi daftarkan juga endpoint live.

Mulai cepat

Buat kunci API

Temukan template Anda

Buat amplop

Biarkan penerima menandatangani

Dapatkan notifikasi saat selesai

Beralih ke live