واجهة برمجة للتوقيع الإلكتروني بالعربية: ما الذي يجب التحقق منه

واجهة من اليمين إلى اليسار، نصوص عربية ولاتينية مختلطة، ملفات PDF عربية، رسائل وتواريخ وأدلة: قائمة تحقق لاختيار واجهة برمجة للتوقيع الإلكتروني بالعربية.

نُشر في 3 أكتوبر 2026 · 8 دقيقة قراءة

واجهة البرمجة التي تدعم العربية فعلاً لا تكتفي بترجمة العبارات. إذا كان برنامجك يخدم مستخدمين في الخليج أو المغرب، فتحقّق من أن رحلة الموقّع تسير كلها من اليمين إلى اليسار، وأن الأسماء والمبالغ الممزوجة بنصوص لاتينية تظهر بشكل سليم، وأن ملفات PDF العربية تبقى كما هي، وأن كل موقّع يتلقى رابطه بلغته.

يعرض هذا الدليل النقاط التي ينبغي اختبارها قبل اختيار أي حل، ثم يشرح كيف يتعامل Khatm مع كل نقطة: رحلة توقيع أصيلة بالعربية والفرنسية والإنجليزية، وواجهة برمجة REST v1 يمكن تجربتها في sandbox، وانتقال إلى الإنتاج نعدّه معك.

قائمة التحقق باختصار

أفضل طريقة للتحقق هي إرسال مستند حقيقي من منتجك إلى موقّع تجريبي، كعقد عمل محرَّر بالعربية في نظام الموارد البشرية لديك أو عرض سعر ثنائي اللغة يولّده نظام إدارة العملاء، ثم مراجعة كل شاشة والملف النهائي الموقّع.

واجهة توقيع من اليمين إلى اليسار فعلاً

الصفحة العربية تُقرأ بكاملها من اليمين إلى اليسار، لذلك لا تكفي ترجمة النصوص، بل يجب عكس بنية الواجهة نفسها. الموقّع في الرياض أو الدار البيضاء يلاحظ فوراً صفحة كلماتها عربية ومنطقها البصري غربي.

• تُعلن الصفحة اتجاه الكتابة من اليمين إلى اليسار (dir="rtl") واللغة العربية، للمتصفح ولقارئات الشاشة.
• تُعكس أسهم «التالي» و«السابق» وأشرطة التقدم والقوائم.
• تظهر حقول الإدخال ومربعات الاختيار ورسائل الخطأ في الجهة الصحيحة.
• يغطي خط الواجهة الحروف العربية بحجم مقروء على الهاتف، حيث تتم معظم عمليات التوقيع.
• تبقى العناصر التي لا ينبغي عكسها كما هي، مثل ملف PDF نفسه أو الشعار.

النصوص المختلطة بين العربية واللاتينية

في أي رحلة توقيع حقيقية يجاور النصُّ العربي نصاً لاتينياً: عنوان بريد إلكتروني، رقم عقد، اسم شركة بالإنجليزية، أو مبلغ تتبعه SAR أو MAD. تتولى خوارزمية Unicode ثنائية الاتجاه معالجة هذا المزج، لكن بشرط أن تعزل الواجهة كل جزء على حدة بشكل صحيح.

• يبقى الاسم العربي متبوعاً بالبريد اللاتيني في ترتيبه الصحيح، دون قوس أو نقطة تقفز إلى الطرف الآخر من السطر.
• تظهر المراجع مثل HR-2026-0042 كما أُدخلت تماماً.
• تحافظ المبالغ على موضع العملة والفواصل المتوقعة.
• تُحفظ أسماء الموقّعين التي يرسلها منتجك بالعربية كما هي في الواجهة والرسائل والأدلة.

للاختبار، جهّز بيانات صعبة عن قصد: اسماً عربياً، واسماً فرنسياً، وبريداً إلكترونياً، ومرجعاً يحتوي على شرطات، ومبلغاً. إذا ظهرت هذه القيم الخمس سليمة في كل شاشة، فقد غطيت معظم الحالات الواقعية.

ملفات PDF العربية: الخطوط ومواضع الحقول

برنامجك هو الذي يُنتج ملف PDF، لذلك تقع على مولّد المستندات لديك مسؤولية تضمين خطوط عربية كاملة ومعالجة أشكال الحروف بحسب موضعها والحروف المركبة مثل «لا». الملف المولَّد جيداً يظهر بالشكل نفسه في كل قارئ، أما الملف الذي يعتمد على خط غير موجود على جهاز الموقّع فقد تظهر فيه حروف منفصلة أو مربعات فارغة.

أما خدمة التوقيع فعليها أن توقّع هذا الملف دون إعادة كتابته. مع توقيع PAdES، يُبطل أي تعديل على المحتوى بعد التوقيع صحةَ التوقيع. وهذه ضمانة مفيدة، بشرط ألا تمسّ الخدمة تنسيق مستندك. ما الذي يحدث داخل ملف PDF موقّع؟

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

الرسائل والروابط ولغة كل موقّع

كثيراً ما يجمع الطلب الواحد موقّعين بلغات مختلفة: موظف يوقّع بالعربية، ومسؤول موارد بشرية يفضّل الفرنسية، وشريك أجنبي بالإنجليزية. لذا ينبغي ضبط اللغة لكل موقّع على حدة، لا للطلب بأكمله.

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

التواريخ والأرقام والتنسيقات

تختلف الأعراف من بلد إلى آخر. في المغرب تُعتمد الأرقام الغربية (0 إلى 9)، بينما ما زالت الأرقام العربية المشرقية (٠ إلى ٩) شائعة في بعض السياقات بالخليج. ويُستخدم التقويم الهجري في وثائق إدارية بالمملكة العربية السعودية. لذلك تحقّق قبل اختيار أي خدمة من:

• تنسيق التاريخ الذي يراه الموقّع ويُدوَّن في ملف PDF وفي الأدلة؛
• المنطقة الزمنية المعتمدة في توقيت الأحداث؛
• نوع الأرقام المستخدم في الواجهة العربية؛
• طريقة عرض التواريخ الهجرية في مستنداتك إن كان نشاطك يحتاجها، لأنها جزء من محتوى ملف PDF الذي تولّده.

أدلة يقرؤها فريقك بسهولة

عند الطعن في عقد ما، يفتح الملفَّ فريقك القانوني أو فريق الدعم، وغالباً ما يكون ناطقاً بالعربية. تأكّد من أن تقرير الأدلة يُقرأ بلغته، وأن الأسماء العربية تظهر فيه بشكل صحيح، وأن البيانات المنظَّمة قابلة للمعالجة بأدواتك.

كيف يعمل ذلك مع Khatm

يدمج Khatm توقيع PDF في برنامجك، تحت علامتك، بالعربية والفرنسية والإنجليزية. صُمّمت رحلة الموقّع أصلاً بهذه اللغات الثلاث، مع واجهة من اليمين إلى اليسار للعربية. والمحرّك نفسه متاح عبر المنصة دون أي تطوير، وعبر واجهة البرمجة REST v1.

عبر واجهة البرمجة، تنشئ الطلب بإرسال ملف PDF وكائن JSON. يجعل الحقل client_reference عملية الإنشاء آمنة عند التكرار، ولكل موقّع مرجع واسم وبريد إلكتروني وترتيب، ولغة اختيارية (fr أو en أو ar) تحدّد لغة صفحة توقيعه ورسائله معاً. ويطبّق الكائن الاختياري email علامتك على الدعوات والتذكيرات: sender_name وmessage وlogo_url.

REQUEST_JSON='{
  "client_reference": "hr-contract-2026-0042",
  "signers": [
    {
      "reference": "employee",
      "name": "سارة العتيبي",
      "email": "sara@example.com",
      "order": 1,
      "locale": "ar"
    }
  ],
  "email": {
    "sender_name": "Acme HR",
    "message": "يرجى توقيع عقد العمل قبل يوم الخميس.",
    "logo_url": "https://example.com/logo.png"
  }
}'

curl --fail-with-body -sS \
  -H "Authorization: Bearer $KHATM_API_KEY" \
  -F "document=@contrat-ar.pdf;type=application/pdf" \
  -F "request=$REQUEST_JSON" \
  "$KHATM_BASE_URL/v1/signature-requests"

1. حدّد الحقول في الطلب أو من قالب، أو اطلب اقتراحات عبر detect-fields ثم اعتمدها.
2. فعّل الطلب. مع send_emails يرسل Khatm إلى كل موقّع دعوة بلغته وتحت علامتك، ويحدّد link_expiry_days مدة صلاحية الرابط (من 1 إلى 30 يوماً، و7 أيام افتراضياً). ويمكنك أيضاً أخذ رابط التوقيع وإرساله في رسائلك الخاصة.
3. استقبل إشعارات webhook الموقّعة بـ HMAC-SHA256: signature_request.completed أو signature_request.declined أو signature_request.cancelled.
4. نزّل ملف PDF الموقّع وتقرير الأدلة بصيغة PDF والأدلة بصيغة JSON.

يقبل الطلب الواحد حتى 10 موقّعين و100 حقل، لملف PDF لا يتجاوز 8 MiB. تُشفَّر الملفات أثناء التخزين، ويُعرَّف كل مستند ببصمة SHA-256. توثيق واجهة البرمجة صفحة المطوّرين

من sandbox إلى الإنتاج

بيئة sandbox ذاتية الخدمة: أنشئ حساباً، وولّد مفتاح khatm_test_… وسرّ webhook من نوع whsec_…، ثم أرسل قوالبك العربية الحقيقية إلى موقّعين تجريبيين. تُوقَّع الملفات بشهادة اختبار ذاتية التوقيع، ويُحذف المحتوى بعد 10 أيام من رفع ملف PDF.

أما الإنتاج فنعدّه معك ضمن المرافقة: تكييف الرحلة وعلامتك، والتكامل مع مطوّريك، وربط هوية الموقّعين عبر مزوّد الهوية لديك، وشهادة البنية التحتية للمفاتيح العامة (PKI) أو وحدة HSM أو مزوّد خدمة الثقة الذي تتعامل معه، والطوابع الزمنية RFC 3161 عندما يوفّرها هذا المزوّد. لا يُصدر Khatm شهادات وليس مزوّد خدمة ثقة معتمداً. ولا تشمل الخدمة افتراضياً خدمات الهوية الوطنية مثل نفاذ أو UAE Pass. تعرّف على المرافقة

للبدء، جرّب العرض التجريبي دون حساب، ثم احصل على مفتاح sandbox واقرأ التوثيق. وعندما تطمئن إلى الرحلة العربية، نرافقك حتى الإنتاج. جرّب العرض التجريبي احصل على مفتاح sandbox

معلومات عامة وليست استشارة قانونية. تحقق من متطلبات معاملتك مع المستشار المناسب أو الجهة المستقبلة.