Hızlı başlangıç

Bu adım adım kılavuz, yayımlanmış bir şablondan imzalı ve mühürlü bir PDF’e kadar ilerler. Bir test anahtarı kullandığı için hiçbir şey ücretlendirilmez ve her belgeye TEST filigranı eklenir.

1. API anahtarı oluşturun

   API anahtarları panelde, Ayarlar › API anahtarları bölümünde oluşturulur. Bu kılavuz için Test seçeneğini seçin: anahtar bf_test_ ile başlar. Anahtarın tamamı yalnızca bir kez gösterilir; onu bir ortam değişkeninde saklayın.

   export BONA_FIDE_API_KEY=bf_test_…

   Her istek anahtarı Authorization: Bearer … (veya x-api-key: …) olarak gönderir. Bkz. Kimlik doğrulama.

2. Şablonunuzu bulun

   Şablonlar panelde tasarlanır (bir PDF veya Word belgesi yükleyip alanları yerleştirin ya da Belge modunda yazın) ve ardından yayımlanır. Kimliği almak için şablonları listeleyin:

   curl

   curl https://api.bonafidesign.com/v1/templates \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY"

   TypeScript

   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, … }]

   Python

   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, sürümün roles, fields değerlerini ve variables için JSON Schema’yı döndürür. Paneldeki şablon sayfasında ayrıca o sürüme özel, hazır bir istek içeren API’de kullan paneli bulunur.

3. Zarf oluşturun

   POST /v1/envelopes, şablonu değişkenlerinizle oluşturur, sürümü sabitler ve yönlendirmeyi başlatır. Her rol için bir alıcı verin (CC rolleri isteğe bağlıdır). Yeniden denemenin iki kez gönderim yapamaması için bir Idempotency-Key gönderin.

   curl

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

   TypeScript

   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_…', … }] }

   Python

   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()

   Yanıt, zarf ile birlikte 201 Created olur:

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

   Göndermeden deneyin

   Değişkenleri ve alıcıları doğrulamak ve hiçbir şeyi saklamadan, göndermeden veya ücretlendirmeden belgeyi oluşturmak için ?dry_run=true ekleyin. Yanıt (200), oluşturulan belgenin documentHash değerini ve sayfa sayısını içerir.

   delivery, alıcılara nasıl ulaşılacağını belirler: email (varsayılan) sırası gelen her alıcıya e-postayla bir imzalama bağlantısı gönderir; embedded ve none e-posta göndermez ve imzalama oturumlarını kendiniz açarsınız (sonraki adım).

4. Alıcının imzalamasını sağlayın

   Arka ucunuzdan alıcı için bir imzalama oturumu oluşturun. Oturumlar kısa ömürlüdür (ttlSeconds, 60 ile 3600 arası, varsayılan 600) ve tek kullanımlıktır.

   Yerleşik

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

   Döndürülen token değerini (bfs_…) sayfanıza iletin ve web bileşenini oluşturun:

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

   React ve Vue sarmalayıcıları, olaylar ve güvenlik modeli: Yerleşik imzalama.

   Barındırılan

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

   İmzacıyı döndürülen url adresine (https://sign.bonafidesign.com/s/bfs_…) yönlendirin. Barındırılan sayfa mobil öncelikli tasarlanmıştır ve hesap gerektirmez.

   Varsayılan email_otp doğrulamasında imzacı, göndermeden önce e-postasına gelen altı haneli bir kodu onaylar. Test modunda e-postalar yalnızca kuruluşunuzun üyelerine teslim edilir; bu nedenle test sırasında kendi adresinizi kullanın.

5. Tamamlanınca bildirim alın

   Ayarlar › Webhook’lar bölümünde (veya POST /v1/webhook-endpoints ile) bir webhook uç noktası kaydedin ve whsec_… sırrını saklayın. Son alıcı imzaladığında, her değişkeni ve girilen her değeri data.values içinde barındıran envelope.completed olayını alırsınız. Mühürlü PDF ardından envelope.sealed ile gelir.

   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);
   });

   Mühürlü PDF’i (tamamlama sertifikasını içeren, zaman damgalı belge) indirin:

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

   Olayların tam listesi, yeniden denemeler ve elle doğrulama: Webhook’lar.

Canlıya geçiş

Test anahtarını bir bf_live_ anahtarıyla değiştirin. Canlı zarflara filigran eklenmez, e-postalar her alıcıya gider ve tamamlanan zarflar planınızdan düşülür (Planlar ve limitler). Bir anahtarın oluşturduğu her şey o anahtarın modunu alır, listeleri yalnızca o modu gösterir ve test zarfları yalnızca test modu webhook uç noktalarına bildirim gönderir; bu yüzden bir canlı uç nokta da kaydedin.