المصادقة

تصادق الـ API على الخوادم باستخدام مفاتيح API الخاصة بالمؤسسة. ينتمي المفتاح إلى مؤسسة (لا إلى شخص)، ويحمل مجموعة من الصلاحيات، ويعمل في وضع واحد فقط: الاختبار أو المباشر.

إرسال المفتاح

استخدم أيًّا من الترويستين:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

تبدو المفاتيح بالشكل bf_live_… أو bf_test_…. غياب المفتاح يعيد 401 (unauthorized)؛ والمفتاح المشوّه أو الملغى أو المنتهي الصلاحية يعيد 401 كذلك. احتفظ بالمفاتيح على خادمك: لا ترسلها أبدًا إلى متصفح أو تطبيق جوّال. وللتوقيع داخل المتصفح، أصدِر جلسة توقيع بدلًا من ذلك.

مفاتيح الاختبار والمفاتيح المباشرة

	الاختبار (`bf_test_…`)	المباشر (`bf_live_…`)
المستندات	تُعرض مع العلامة المائية `TEST`	نظيفة
البريد الإلكتروني	يُسلَّم لأعضاء مؤسستك فقط	يُسلَّم لكل مستلم
الفوترة	مجاني وغير محدود، ولا يُحتسب أبدًا	تُحتسب المظاريف المكتملة ضمن خطتك
البيانات	المظاريف والروابط ونقاط نهاية webhook التي يُنشئها المفتاح تكون في وضع الاختبار	في الوضع المباشر

يأتي الوضع من المفتاح، لا من الطلب أبدًا: لا ينطبق ?test_mode=true على POST /v1/envelopes إلا على جلسات لوحة التحكم. لا تعيد القوائم (GET /v1/envelopes، GET /v1/signing-links) إلا عناصر وضع المفتاح، ولا تذهب أحداث المظروف إلا إلى نقاط نهاية webhook من الوضع نفسه. ويذكر كل مظروف وكل حمولة webhook الوضع الذي ينتمي إليه (testMode).

إنشاء المفاتيح وإلغاؤها

تُدار المفاتيح في لوحة التحكم، ضمن الإعدادات › مفاتيح API، بواسطة الأعضاء الذين يملكون الصلاحية apikey:manage (المالكون والمسؤولون). يُعرض السر مرة واحدة، عند إنشاء المفتاح. ويمكنك أن تمنح المفتاح اسمًا ووضعًا ومدة صلاحية (من 1 إلى 365 يومًا، أو بلا انتهاء) ونطاقات.

النطاقات

نطاقات المفتاح هي صلاحيات المؤسسة التي يجوز له استخدامها. افتراضيًا يحصل المفتاح الجديد على صلاحيات منشئه مطروحًا منها الصلاحيات الإدارية (org:manage، member:manage، sso:manage، apikey:manage، billing:manage)، ولا يمكن لأحد أن يمنح مفتاحًا صلاحية لا يملكها هو. والاستدعاء الذي يقع خارج نطاقات المفتاح يعيد 403 مع ذكر الصلاحية الناقصة:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

الصلاحية	تسمح للمفتاح بـ
`template:read`	عرض القوالب والإصدارات وملفات PDF الخاصة بها وقراءتها
`template:write`	إنشاء القوالب، ورفع الملفات، وحفظ المسودات، وحذف القوالب غير المستخدمة
`template:publish`	نشر مسودة كإصدار جديد
`envelope:read`	عرض المظاريف والمستندات ومسارات التدقيق وقراءتها؛ وعرض روابط التوقيع
`envelope:send`	إنشاء المظاريف وجلسات التوقيع وروابط التوقيع؛ وإعادة إرسال الروابط
`envelope:void`	إلغاء المظاريف الجارية
`org:manage`	إدارة نقاط نهاية webhook وإعادة تسليم الأحداث؛ وقراءة إعدادات المؤسسة
`billing:manage`	قراءة الاستخدام (`GET /v1/usage`) ومبالغ الفواتير

تتطلب إدارة نقاط نهاية webhook الصلاحية org:manage، التي لا تحصل عليها المفاتيح افتراضيًا: سجّل نقاط النهاية في لوحة التحكم، أو أنشئ مفتاحًا بهذا النطاق صراحةً.

ما الذي تقبله كل نقطة نهاية

تذكر كل عملية في مرجع الـ API مخططات الأمان الخاصة بها. باختصار:

مفتاح API أو جلسة لوحة التحكم: القوالب، والمظاريف، وجلسات التوقيع، وروابط التوقيع، ونقاط نهاية webhook، وإعدادات المؤسسة، ونظرة عامة على الفوترة والاستخدام.
جلسة لوحة التحكم فقط: مفاتيح API، ورموز SCIM، وإعدادات اتصال SSO، ورفع شعار المؤسسة، ودفع الفوترة وبوابتها، وكشف سر webhook.
رمز الموقِّع: /v1/signing/*، وتستخدمه الصفحة المستضافة و<bf-signing> مع رمز جلسة (bfs_…) أو رمز الوصول الذي يُستبدل به (bfa_…).
عامة: /v1/links/{id} (الروابط الدائمة)، و/v1/sso/discover، وAPI التحقق (/v1/public/*، /.well-known/bona-fide/keys.json).

تسجيل الدخول إلى لوحة التحكم

يسجّل الأشخاص (لا الخوادم) الدخول إلى لوحة التحكم على https://app.bonafidesign.com/sign-in. الطريقة الافتراضية هي البريد الإلكتروني وكلمة المرور؛ والبدائل هي رمز من ستة أرقام يُرسَل بالبريد الإلكتروني (أرسل لي رمزًا بدلًا من ذلك)، أو رابط سحري، أو مفتاح مرور، أو Google أو Microsoft، أو SSO الخاص بشركتك.

إنشاء حساب بكلمة مرور يرسل رسالة بريد إلكتروني واحدة: رمزًا يؤكد أن العنوان يخصك. وحتى ذلك الحين لا تتيح لك كلمة المرور تسجيل الدخول. والتسجيل بعنوان له حساب بالفعل لا يغيّر شيئًا ويُجاب تمامًا كتسجيل جديد؛ ويتلقى صاحب العنوان رسالة بريد إلكتروني تشرح له كيف يسجّل الدخول بدلًا من ذلك.
كلمات المرور من 12 إلى 128 حرفًا، وتُخزَّن كتجزئات scrypt مملّحة. وتُرفض كلمة المرور الجديدة التي تظهر في تسريب بيانات معروف: لا يُرسل سوى أول خمسة أحرف من تجزئة SHA-1 الخاصة بها إلى Have I Been Pwned (إخفاء الهوية k-anonymity)، ولا تُرسل كلمة المرور أبدًا. وإذا لم تستجب تلك الخدمة خلال ثانيتين، تُقبل كلمة المرور دون فحص.
نسيت كلمة المرور؟ تحتوي رسالة إعادة التعيين على رابط لصفحة تختار فيها كلمة مرور جديدة. يعمل الرابط مرة واحدة وتنتهي صلاحيته بعد ساعة، واستخدامه يسجّل خروجك من كل الأجهزة.
ليست لديك كلمة مرور بعد؟ الحسابات التي أُنشئت برمز أو رابط أو مفتاح مرور أو Google / Microsoft تواصل تسجيل الدخول بتلك الطريقة، ويمكنها إضافة كلمة مرور في الإعدادات › الحساب. يتطلب تعيين أول كلمة مرور تسجيل دخول خلال آخر 15 دقيقة (ترسل لك الصفحة رمزًا بالبريد الإلكتروني لتأكيد هويتك)؛ ويتطلب تغييرها كلمة المرور الحالية. وكلاهما يسجّل خروج جلساتك الأخرى.
لا تكشف الأخطاء عن الحسابات أبدًا: كلمة المرور الخاطئة، والعنوان غير المعروف، والحساب الذي لا كلمة مرور له تحصل كلها على الإجابة نفسها، وطلب إعادة التعيين يقول دائمًا إن الرسالة في طريقها.
حدود المعدل: طلبات تسجيل الدخول بكلمة المرور والتسجيل وإعادة التعيين محدودة لكل عنوان IP ولكل عنوان بريد إلكتروني؛ وبعد تجاوز الحد تكون الإجابة 429 حتى تنقضي النافذة الزمنية.
SSO الخاص بالشركة: عندما تفرض مؤسستك SSO، يسجّل الأعضاء الذين ينتمون إلى نطاقات بريدها الإلكتروني الدخول عبر مزوّد الهوية فقط. تُرفض لهم كلمات المرور والرموز والروابط السحرية؛ ويحتفظ المالكون برمز البريد الإلكتروني كوسيلة دخول للطوارئ.

معرّفات الطلبات

تحمل كل استجابة الترويسة x-request-id، ويحمل كل جسم خطأ requestId. يمكنك إرسال x-request-id خاص بك (من 8 إلى 128 حرفًا من A-Z a-z 0-9 . _ -) لربط السجلات؛ وإلا تولّد الـ API واحدًا. اذكره عند التواصل مع الدعم.