البدء السريع

ينقلك هذا الدليل من قالب منشور إلى ملف PDF موقَّع ومختوم. ويستخدم مفتاح اختبار، فلا يُحتسب أي شيء في الفوترة ويحمل كل مستند العلامة المائية TEST.

1. إنشاء مفتاح API

   تُنشأ مفاتيح API في لوحة التحكم، ضمن الإعدادات › مفاتيح API. اختر Test لهذا الدليل: يبدأ المفتاح بـ bf_test_. يُعرض المفتاح كاملًا مرة واحدة فقط؛ فاحفظه في متغير بيئة.

   export BONA_FIDE_API_KEY=bf_test_…

   يُرسَل المفتاح مع كل طلب بصيغة Authorization: Bearer … (أو x-api-key: …). راجع المصادقة.

2. العثور على القالب

   تُصمَّم القوالب في لوحة التحكم (ارفع ملف PDF أو مستند Word وضع الحقول، أو اكتبه في وضع المستند) ثم تُنشر. اعرض قائمتها للحصول على المعرّف:

   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 قيم roles وfields الخاصة بالإصدار وJSON Schema الخاص بـ variables. وتحتوي صفحة القالب في لوحة التحكم أيضًا على لوحة Use in API فيها طلب جاهز لهذا الإصدار بعينه.

3. إنشاء مظروف

   يعرض POST /v1/envelopes القالب بمتغيراتك، ويثبّت الإصدار، ويبدأ التوجيه. حدّد مستلمًا واحدًا لكل دور (أدوار CC اختيارية). أرسل Idempotency-Key حتى لا تؤدي إعادة المحاولة إلى إرسال مزدوج.

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

   الاستجابة هي 201 Created مع المظروف:

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

   جرّبه دون إرسال

   أضف ?dry_run=true للتحقق من المتغيرات والمستلمين وعرض المستند دون تخزين أي شيء أو إرساله أو احتسابه في الفوترة. تتضمن الاستجابة (200) قيمة documentHash للمستند المعروض وعدد صفحاته.

   يحدّد delivery طريقة الوصول إلى المستلمين: email (الافتراضي) يرسل إلى كل مستلم رابط توقيع بالبريد الإلكتروني عندما يحين دوره؛ أما embedded وnone فلا يرسلان أي بريد، وتفتح أنت جلسات التوقيع بنفسك (الخطوة التالية).

4. دع المستلم يوقّع

   أصدِر جلسة توقيع للمستلم من الخادم الخلفي لديك. الجلسات قصيرة العمر (ttlSeconds، من 60 إلى 3600، والافتراضي 600) وأحادية الاستخدام.

   مضمَّن

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

   مرّر قيمة token المُعادة (bfs_…) إلى صفحتك واعرض مكوّن الويب:

   <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 وVue، والأحداث، ونموذج الأمان: التوقيع المضمَّن.

   مستضاف

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

   أعِد توجيه الموقِّع إلى قيمة url المُعادة (https://sign.bonafidesign.com/s/bfs_…). الصفحة المستضافة مصمَّمة للهاتف المحمول أولًا ولا تتطلب حسابًا.

   مع طريقة التحقق الافتراضية email_otp يؤكد الموقِّع رمزًا من ستة أرقام يُرسَل إلى بريده الإلكتروني قبل الإرسال. في وضع الاختبار، لا يُسلَّم البريد الإلكتروني إلا لأعضاء مؤسستك، لذا استخدم عنوانك الخاص أثناء الاختبار.

5. تلقَّ إشعارًا عند الإتمام

   سجّل نقطة نهاية webhook في الإعدادات › Webhooks (أو باستخدام POST /v1/webhook-endpoints) واحتفظ بالسر whsec_…. عندما يوقّع آخر مستلم يصلك envelope.completed، مع كل متغير وكل قيمة مُدخلة في data.values. ثم يتبعه ملف PDF المختوم مع 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);
   });

   نزّل ملف PDF المختوم (المستند مع شهادة الإتمام، مع طابع زمني):

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

   القائمة الكاملة للأحداث، وإعادة المحاولة، والتحقق اليدوي: Webhooks.

الانتقال إلى الوضع المباشر

استبدل مفتاح الاختبار بمفتاح bf_live_. لا تحمل المظاريف المباشرة علامة مائية، ويُرسَل البريد الإلكتروني إلى أي مستلم، وتُحتسب المظاريف المكتملة ضمن خطتك (الخطط والحدود). كل ما يُنشئه مفتاح يأخذ وضعه، ولا تعرض قوائمه إلا ذلك الوضع، ولا تُرسل مظاريف الاختبار إشعارات إلا إلى نقاط نهاية webhook في وضع الاختبار، لذا سجّل نقطة نهاية مباشرة أيضًا.