جلسات التوقيع وروابطه

يوقّع المستلمون على صفحة التوقيع الخاصة بـ Bona Fide: إما الصفحة المستضافة على https://sign.bonafidesign.com/s/…، أو الصفحة نفسها مضمَّنة في منتجك باستخدام <bf-signing>. لا يحتاج المستلمون إلى حساب. وما يتيح لهم الدخول هو جلسة توقيع.

جلسات التوقيع

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

curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

الحقل	ملاحظات
recipient	مستلم في المظروف لا يزال بإمكانه التوقيع (ليس CC، ولم ينتهِ)
mode	embedded (الافتراضي) أو hosted. عناوين url المستضافة بالشكل …/s/<token>، لإعادة التوجيه إليها أو لإرسالها بنفسك
allowedOrigins	حتى 10 أصول (origins) يجوز لها تأطير الصفحة المضمَّنة
returnUrl	المكان الذي ترسل إليه الصفحة المستضافة الموقِّع عند انتهائه
ttlSeconds	من 60 إلى 3600، والافتراضي 600

الجلسات أحادية الاستخدام: بمجرد أن يرسل المستلم، تُستنفد الجلسة، وتجيب الجلسة المستخدمة أو المنتهية الصلاحية بـ 410 Gone. أصدِر جلسة جديدة في كل مرة تُعرض فيها صفحتك. ولا يمكن إنشاء الجلسات إلا عندما يكون المظروف sent، وإلغاء المظروف يُنهيها جميعًا.

ما يمر به الموقِّع

تتبع صفحة التوقيع (وأي واجهة مخصصة تبنيها على الـ API نفسها) هذه الخطوات:

1. التبادل: يعيد POST /v1/signing/exchange { "token": "bfs_…" } رمز وصول قصير العمر (bfa_…) يُحفظ في الذاكرة. لا تُستخدم ملفات تعريف الارتباط، لذا لا يهم حظر ملفات تعريف الارتباط من الطرف الثالث داخل iframe.
2. التحميل: يعيد GET /v1/signing/session عرض الموقِّع (عنوان المظروف، والمرسل، ودور المستلم وحقوله، والقيم المعبأة مسبقًا، وإفصاح المستهلك) ويسجّل recipient.viewed في المرة الأولى. وGET /v1/signing/document هو ملف PDF المراد عرضه.
3. التحقق (مع email_otp فقط): يرسل POST /v1/signing/otp رمزًا من ستة أرقام بالبريد الإلكتروني (صالحًا لمدة 10 دقائق) ويتحقق منه POST /v1/signing/otp/verify. الرمز الخاطئ يعيد verified: false مع عدد المحاولات المتبقية. وتكون قيمة verification.verified في العرض true مسبقًا عندما لا تتطلب طريقة المستلم أي رمز.
4. الإرسال: POST /v1/signing/submit مع values الحقول (توقيعات مرسومة أو مكتوبة أو مرفوعة)، والموافقة على الإفصاح، وviewedDocumentHash: تجزئة SHA-256 لملف PDF الذي عُرض بالضبط. وإذا تغيّر المستند منذ ذلك الحين، يُرفض الإرسال (409).
5. أو الرفض: يُنهي POST /v1/signing/decline { "reason": "…" } المظروف (envelope.declined).

لا يحين دور المستلم إلا عندما تنتهي كل مجموعات التوجيه السابقة؛ وقبل ذلك يتضمن العرض canSign: false، ويجيب الإرسال بـ 409 not-your-turn.

التحقق من الموقِّع

لكل مستلم طريقة verification: طريقة الدور (المحددة في لوحة الأدوار في مصمم القوالب) ما لم يتجاوزها المظروف لكل مستلم (شاشة الإرسال، أو recipients[].verification).

الطريقة	ما يفعله الموقِّع	متى تستخدمها
none (الافتراضي)	يفتح رابط التوقيع الفريد ويوقّع	يُرسل الرابط إليه بالبريد الإلكتروني: لا يملكه إلا من يستطيع الوصول إلى ذلك البريد
email_otp	يفتح الرابط، ثم يُدخل رمزًا من ستة أرقام يُرسل إلى العنوان نفسه	تريد إثباتًا ثانيًا جديدًا لحظة التوقيع (العقود عالية القيمة، وصناديق البريد المشتركة)
integrator_asserted	يوقّع داخل منتجك، الذي يشهد بهويته (externalUserId)	التوقيع المضمَّن خلف نظام تسجيل الدخول الخاص بك

none هي الطريقة الافتراضية لأن الرابط الذي ترسله Bona Fide بالبريد الإلكتروني فريد للمستلم بحد ذاته ولا يمكن تخمينه: فتحه يُثبت السيطرة على عنوان البريد الإلكتروني، وهو أساس الإسناد الذي تعتمد عليه قوانين التوقيع الإلكتروني (ESIGN / UETA في الولايات المتحدة، والتوقيعات الإلكترونية البسيطة بموجب eIDAS). وتعتمدها المنتجات المماثلة افتراضيًا أيضًا. والقوالب المنشورة مع email_otp تحتفظ بها، ويظل email_otp المحدد صراحةً يعمل في كل مكان.

هناك مساران لا يعتمدان على الرابط وحده أبدًا:

• روابط التوقيع الدائمة (/l/…): يكتب الزائر عنوانه بنفسه، لذا يؤكد دائمًا رمزًا مرسلًا بالبريد الإلكتروني قبل إنشاء المظروف، أيًّا كان ما يحدده القالب.
• الجلسات التي تُصدرها أنت (POST /v1/envelopes/{id}/sessions) لا تحمل أي إثبات لعنوان البريد الإلكتروني على الإطلاق: فتلك مهمة نظام تسجيل الدخول لديك، لذا استخدم معها integrator_asserted (مع externalUserId) أو email_otp.

تسجّل شهادة الإتمام، لكل موقِّع، ما استُخدم فعليًا:

يُسجَّل بصفته	متى
رابط البريد الإلكتروني (رابط فريد أُرسل إلى العنوان)	none، والتوقيع من الرابط المرسل بالبريد الإلكتروني
رابط البريد الإلكتروني + رمز لمرة واحدة (أُرسل إلى العنوان)	email_otp، والتوقيع من الرابط المرسل بالبريد الإلكتروني
رابط التوقيع + رمز لمرة واحدة (أُرسل إلى العنوان)	زائر رابط دائم
رمز لمرة واحدة (أُرسل إلى العنوان)	email_otp في جلسة أصدرتها أنت
جلسة توقيع أصدرها المرسل	none في جلسة أصدرتها أنت
إقرار جهة التكامل	integrator_asserted

يعرض ملخص التحقق العام التسميات نفسها دون العنوان.

اللغات

تتوفر صفحة التوقيع، ورسائلها (الطلب، والتذكيرات، والرموز، والإتمام، والإلغاء)، وصفحة الرابط الدائم، وصفحة حالة المشاهد بـ 50 لغة. ويراها الموقِّع وفق ترتيب الأفضلية التالي:

1. اللغة التي اختارها من قائمة اللغات في الصفحة (وتُحفظ على ذلك الجهاز)؛
2. <bf-signing locale="…"> (التوقيع المضمَّن) أو ?locale= على رابط مستضاف؛
3. قيمة locale الخاصة بالمستلم، المحددة عند إنشاء المظروف (recipients[].locale، أو locale على المظروف لكل من لا يملك قيمة خاصة به)؛
4. لغة متصفحه.

تحتاج الرسائل إلى لغة قبل أن يفتح أي شخص صفحة، لذا تستخدم locale الخاصة بالمستلم وتكون بالإنجليزية في غيابها. وترسل الروابط الدائمة رسالة الرمز باللغة التي تعرضها صفحة الزائر.

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

تُقبل الوسوم القريبة وتُخزَّن باللغة التي تقابلها (de-AT → de، es-MX → es-419، zh-TW → zh-Hant)؛ وأي قيمة أخرى تُعد خطأ تحقق. تذكر إفصاحات الموافقة المترجمة أن النص الإنجليزي هو الذي يسري، ويمكن للموقِّع التبديل إليه؛ وتُسجَّل اللغة التي قُرئ بها الإفصاح مع التوقيع (consentLocale في حدث التدقيق recipient.signed).

الرمز	اللغة	الاسم الأصلي
ar	العربية	العربية	من اليمين إلى اليسار
hy	الأرمنية	Հայերեն
bn	البنغالية	বাংলা
bg	البلغارية	Български
zh-Hans	الصينية (المبسطة)	简体中文
zh-Hant	الصينية (التقليدية)	繁體中文
hr	الكرواتية	Hrvatski
cs	التشيكية	Čeština
da	الدنماركية	Dansk
nl	الهولندية	Nederlands
en-GB	الإنجليزية (المملكة المتحدة)	English (UK)
en-US	الإنجليزية (الولايات المتحدة)	English (US)
et	الإستونية	Eesti
fil	الفلبينية	Filipino
fi	الفنلندية	Suomi
fr	الفرنسية	Français
fr-CA	الفرنسية (كندا)	Français (Canada)
de	الألمانية	Deutsch
el	اليونانية	Ελληνικά
he	العبرية	עברית	من اليمين إلى اليسار
hi	الهندية	हिन्दी
hu	المجرية	Magyar
id	الإندونيسية	Bahasa Indonesia
it	الإيطالية	Italiano
ja	اليابانية	日本語
ko	الكورية	한국어
lv	اللاتفية	Latviešu
lt	الليتوانية	Lietuvių
ms	الملايوية	Bahasa Melayu
mr	الماراثية	मराठी
nb	النرويجية	Norsk bokmål
fa	الفارسية	فارسی	من اليمين إلى اليسار
pl	البولندية	Polski
pt-BR	البرتغالية (البرازيل)	Português (Brasil)
pt-PT	البرتغالية (البرتغال)	Português (Portugal)
ro	الرومانية	Română
ru	الروسية	Русский
sr-Latn	الصربية (اللاتينية)	Srpski
sk	السلوفاكية	Slovenčina
sl	السلوفينية	Slovenščina
es-419	الإسبانية (أمريكا اللاتينية)	Español (Latinoamérica)
es-ES	الإسبانية (إسبانيا)	Español (España)
sw	السواحيلية	Kiswahili
sv	السويدية	Svenska
te	التيلوغوية	తెలుగు
th	التايلاندية	ไทย
tr	التركية	Türkçe
uk	الأوكرانية	Українська
ur	الأردية	اردو	من اليمين إلى اليسار
vi	الفيتنامية	Tiếng Việt

روابط التوقيع الدائمة

رابط التوقيع عنوان URL دائم للعقود التي يوقّعها كثير من الناس بالطريقة نفسها: إخلاء مسؤولية، أو اتفاقية مقاول، أو شروط برنامج تجريبي. يحصل كل زائر يُكمله على مظروفه الخاص.

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

• visitorRole هو دور الموقِّع الذي يتخذه الزائر. تدعم الروابط زائرًا واحدًا وموقِّعًا مقابلًا واحدًا على الأكثر: mode: "auto" يوقّع توقيعًا مقابلًا تلقائيًا بختم منصة Bona Fide، وmode: "person" يوجّه المظروف إلى email المحدد. وأي دور آخر غير CC سيبقى بلا مستلم، لذا تُرفض مثل هذه القوالب.
• يُدخل الزائر اسمه وبريده الإلكتروني ومتغيرات القالب، ثم يؤكد رمزًا مرسلًا بالبريد الإلكتروني قبل إنشاء أي شيء (POST /v1/links/{id}/start، ثم POST /v1/links/{id}/verify).
• يضع limits حدودًا للاستخدام لكل بريد إلكتروني يوميًا (الافتراضي 3)، ولكل IP في الساعة (الافتراضي 20)، ولليوم إجمالًا، وحسب نطاق البريد الإلكتروني. ومع dedupe (مفعّل افتراضيًا)، يحصل عنوان البريد الإلكتروني الذي وقّع من قبل على 409 already-signed.
• يوقف PATCH /v1/signing-links/{id} الرابط مؤقتًا (active: false)، أو يستأنفه، أو ينقله إلى إصدار أحدث؛ وحذف الرابط يُبقي على المظاريف التي أنشأها. ويُطلق كل استخدام الحدث signing_link.used.

ملاحظة

توجد صفحة الزائر على url الخاص بالرابط (https://sign.bonafidesign.com/l/lnk_…). وGET /v1/links/{id} هو الوصف العام الذي تعرضه: اسم القالب، وحقول الزائر، والمتغيرات التي يملؤها.