ahlan hamad

دليل الإعداد · التوقيع عبر DocuSign · وصول مبكر

إعداد التوقيع عبر DocuSign بتطبيقكم الخاص: خطوة بخطوة

هذا الدليل لشخصين يعملان معًا: مسؤول DocuSign لديكم، الذي ينشئ مفتاح التكامل في DocuSign، ومدير للشركة في أهلاً حمد، الذي يربطه ويختار DocuSign مزوّدًا للتوقيع. يتصل أهلاً حمد بـ DocuSign عبر مفتاح التكامل الخاص بشركتكم (منح JWT)، فتُرسَل المغلفات من حسابكم وتُحتسب على باقة DocuSign الخاصة بكم. اتبعوا الخطوات بالترتيب، وكل اسم زر أو حقل من أهلاً حمد مذكور هنا هو نفسه الظاهر على الشاشة.

آخر تحديث: 12 أكتوبر 2026

1. قبل أن تبدأ

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

البندالمطلوب
حساب DocuSignحساب DocuSign eSignature لشركتكم. تُحتسب المغلفات على باقة DocuSign الخاصة بكم؛ فأهلاً حمد لا يدفع عنها ولا يعيد بيعها ولا يتقاضى منكم أي رسوم عليها.
ابدؤوا بالاختبارابدؤوا بحساب مطوّرين (demo) مجاني لدى DocuSign. يعمل مفتاح التكامل الجديد في بيئة demo فقط إلى أن يجتاز مراجعة Go-Live الخاصة بـ DocuSign (القسم 6). والمغلفات المُرسلة في بيئة demo للاختبار وليست ملزمة قانونيًا.
أين وصلناالربط مبني، وجُرّب من البداية إلى النهاية بحساب مطوّرين (demo) لدى DocuSign. لم يُستخدم بعد مع حساب DocuSign إنتاجي لدى عميل، لذا راجعوا أول المغلفات بعناية وأبلغونا إن لاحظتم أي خلل.
مسؤول في DocuSignشخص يستطيع فتح Apps and Keys وConnect في لوحة DocuSign eSignature Admin. ومستخدم DocuSign الذي تلصقون معرّفه هو الذي تُرسل المغلفات باسمه.
في أهلاً حمدمدير للشركة يستطيع إدارة الإعدادات، لربط DocuSign واختيار مزوّد التوقيع.

2. في DocuSign: أنشئوا مفتاح التكامل

سجّلوا الدخول إلى حساب المطوّرين في DocuSign وافتحوا لوحة eSignature Admin (Settings). ويشرح DocuSign كل إعداد في صفحة إعداد التطبيق.

  1. افتحوا Apps and Keys واختاروا Add App and Integration Key، وسمّوا التطبيق، مثلًا AhlanHamad.
  2. في قسم User Application أبقوا الإجابة Yes على سؤال Is your application able to securely store a client secret? (أي Authorization Code Grant، وهو الإعداد الافتراضي للتطبيقات الجديدة). يحتاج رابط الموافقة في DocuSign (القسم 3) إلى هذا الإعداد، ولا حاجة لإنشاء مفتاح سري، فأهلاً حمد لا يستخدمه.
  3. في قسم Service Integration اختاروا Generate RSA. انسخوا المفتاح الخاص (private key) فورًا، بما في ذلك سطرا -----BEGIN RSA PRIVATE KEY----- و-----END RSA PRIVATE KEY-----، واحفظوه في مكان آمن: لا يعرضه DocuSign إلا في هذه الشاشة. ولا تحتاجون إلى المفتاح العام.
  4. في Additional settings ← Redirect URIs اختاروا Add URI وأضيفوا عنوانًا واحدًا، مثل موقع شركتكم. يشترط DocuSign وجود عنوان إعادة توجيه لرابط الموافقة؛ وبعد القبول يفتح DocuSign هذا العنوان ويمكنكم إغلاق الصفحة. ولا يستخدمه أهلاً حمد.
  5. احفظوا. ثم دوّنوا من صفحة Apps and Keys أربع قيم: Integration Key لتطبيقكم الجديد، وUser ID الخاص بكم، وAPI Account ID، وbase URI لحسابكم (في بيئة المطوّرين https://demo.docusign.net).

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

4. في أهلاً حمد: اربطوا تطبيق DocuSign الخاص بكم

افتحوا التكاملات ثم دوكوساين. في بطاقة اتصال دوكوساين يكون القسم الأول اربط عبر تطبيق DocuSign الخاص بك.

  1. مفتاح التكامل: قيمة Integration Key لتطبيقكم.
  2. معرّف المستخدم: قيمة User ID لمستخدم DocuSign الذي منح الموافقة.
  3. معرّف الحساب: قيمة API Account ID.
  4. المفتاح الخاص RSA (PEM): الصقوا المفتاح الخاص كاملًا من القسم 2، بما في ذلك سطرا BEGIN وEND. يُقبل الشكلان «BEGIN RSA PRIVATE KEY» و«BEGIN PRIVATE KEY».
  5. عنوان REST الأساسي: لبيئة المطوّرين اتركوا https://demo.docusign.net/restapi. وللحساب الإنتاجي استخدموا base URI لحسابكم الإنتاجي متبوعًا بـ /restapi.
  6. خادم المصادقة: لبيئة المطوّرين اتركوا account-d.docusign.com. وللحساب الإنتاجي أدخلوا account.docusign.com (وإن تُرك فارغًا يستخدم أهلاً حمد account.docusign.com).
  7. اضغطوا الاتصال بدوكوساين.

يتحقق أهلاً حمد من المفتاح، ويطلب من DocuSign رمز وصول، ويتأكد أن معرّف الحساب يخص مستخدم DocuSign هذا، ثم يستخدم base URI الذي يذكره DocuSign لذلك الحساب. وعند النجاح تقول البطاقة متصل بدوكوساين و«مربوط عبر تطبيقك الخاص»، مع معرّف الحساب وعنوان REST الأساسي. وإن رفض DocuSign، تخبركم الرسالة بما يجب إصلاحه (القسم 7).

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

5. اجعلوا DocuSign مزوّد التوقيع

يتحقق أهلاً حمد من كل تحديث حالة يصل من DocuSign بمفتاح HMAC الخاص بكم في DocuSign Connect (DocuSign: HMAC)، لذا أنشئوا مفتاحًا أولًا.

  1. في لوحة DocuSign eSignature Admin افتحوا Connect ثم Connect Keys، واختاروا Add Secret Key، وانسخوا المفتاح عندما يعرضه DocuSign.
  2. في أهلاً حمد، في صفحة DocuSign، اذهبوا إلى بطاقة مزوّد التوقيع. وتحت أرسل طلبات التوقيع عبر اختاروا DocuSign.
  3. الصقوا المفتاح في حقل مفتاح HMAC الخاص بـ DocuSign Connect. يحفظه أهلاً حمد مشفّرًا ولا يعرضه مرة أخرى.
  4. اضغطوا حفظ. تقول البطاقة بعدها: «تُرسل طلبات التوقيع الجديدة من حساب DocuSign الخاص بكم. إذا تعذّر إرسال أحدها عبر DocuSign يُرسل بالتوقيع الإلكتروني من أهلاً حمد ويُبلَّغ المرسِل.»
  5. اضغطوا إرسال مغلف تجريبي. يُرسل من حساب DocuSign الخاص بكم إلى مستخدم DocuSign المتصل به، ويُحتسب على باقة DocuSign لديكم كأي مغلف. افتحوا رسالة DocuSign ووقّعوه لتروا مغلفًا مكتملًا.

وتعرض البطاقة أيضًا العنوان بعد «يرسل DocuSign تحديثات حالة كل مغلف إلى:» (وينتهي بـ /webhooks/docusign). لا تحتاجون إلى إنشاء إعداد Connect له: فكل مغلف يرسله أهلاً حمد يحمل إشعار الحالة الخاص به إلى هذا العنوان، موقّعًا بمفاتيح Connect لديكم. ويعيد أهلاً حمد قراءة كل مغلف من DocuSign قبل أن يغيّر أي شيء، وعند اكتمال التوقيعات يحفظ ملف PDF الموقّع وشهادة الإتمام من DocuSign.

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

6. الانتقال من بيئة demo إلى الإنتاج

يبدأ مفتاح التكامل الجديد في بيئة المطوّرين (demo) لدى DocuSign، والمغلفات المُرسلة فيها ليست ملزمة قانونيًا. ولإرسال مغلفات حقيقية من حساب DocuSign الإنتاجي، يجب أن يجتاز مفتاحكم مراجعة Go-Live الخاصة بـ DocuSign. هذه المراجعة بينكم وبين DocuSign وعلى مفتاح التكامل الخاص بكم: لا يستطيع أهلاً حمد إجراءها نيابة عنكم، لكننا نسعد بمساعدتكم في التحضير لها.

  1. استخدموا المفتاح في بيئة demo أولًا: اربطوه، وأرسلوا المغلف التجريبي وبعض طلبات التوقيع الحقيقية. فمراجعة DocuSign تنظر في نشاط المفتاح الأخير عبر الواجهة البرمجية في بيئة demo.
  2. في حساب المطوّرين، ابدؤوا مراجعة Go-Live للمفتاح (من Apps and Keys، أو من Developer Console الأحدث لدى DocuSign إن كان مفتاحكم هناك). يطلب DocuSign تصنيفًا للتكامل؛ ويذكر «Third-party integration key» لمنتج شريك يحتاج إلى مفتاحكم الخاص. وإن لم تكونوا متأكدين من التصنيف المناسب فاسألوا DocuSign.
  3. يشترط DocuSign حسابًا إنتاجيًا مدفوعًا ومسؤولًا لذلك الحساب. وعند اجتياز المراجعة رقّوا المفتاح إلى حسابكم الإنتاجي. ينسخ DocuSign المفتاح بقيمة Integration Key نفسها، لكن دون أسراره وعناوين إعادة التوجيه.
  4. في Apps and Keys بحسابكم الإنتاجي: أضيفوا عنوان إعادة توجيه، واختاروا Generate RSA لمفتاح خاص جديد، ودوّنوا User ID وAPI Account ID وbase URI الإنتاجية.
  5. امنحوا الموافقة مرة أخرى، هذه المرة على account.docusign.com (القسم 3).
  6. في أهلاً حمد اضغطوا قطع الاتصال بدوكوساين ثم اربطوا من جديد بالقيم الإنتاجية: خادم المصادقة account.docusign.com، وbase URI الإنتاجي متبوعًا بـ /restapi.
  7. أضيفوا مفتاح Connect في حسابكم الإنتاجي (Connect ← Connect Keys)، والصقوه في مفتاح HMAC الخاص بـ DocuSign Connect ثم حفظ: مفاتيح حساب المطوّرين لا تعمل في الإنتاج.

يشرح DocuSign المراجعة في صفحة Go-Live، وإعدادات الإنتاج في After Go-Live.

7. إذا حدث خطأ

ما يقوله أهلاً حمدما العمل
«يحتاج DocuSign إلى الموافقة أولاً. افتح رابط الموافقة الخاص بمفتاح التكامل وأنت مسجّل الدخول بمستخدم DocuSign صاحب معرّف المستخدم هذا، واضغط "قبول"، ثم اتصل مرة أخرى.»امنحوا الموافقة (القسم 3) بمستخدم DocuSign نفسه، وفي البيئة نفسها التي يشير إليها خادم المصادقة (account-d لبيئة demo وaccount للإنتاج)، ثم اضغطوا الاتصال بدوكوساين مرة أخرى. (زر القبول في DocuSign اسمه Accept.)
«لا يمكن استخدام مفتاح RSA الخاص هذا. الصق المفتاح الخاص كاملاً كما أنشأه DocuSign لتطبيقك، بما في ذلك سطرا BEGIN وEND. لا يصلح المفتاح العام ولا المفتاح المحمي بكلمة مرور.»الصقوا المفتاح الخاص مرة أخرى بسطري BEGIN وEND. وإن لم يعد لديكم، اختاروا Generate RSA لزوج مفاتيح جديد في تطبيقكم ضمن Apps and Keys والصقوا المفتاح الخاص الجديد.
«معرّف الحساب هذا ليس من حسابات مستخدم DocuSign هذا. انسخ "API Account ID" من صفحة Apps and Keys في DocuSign.»انسخوا API Account ID (لا رقم الحساب) من Apps and Keys في البيئة نفسها التي فيها المستخدم.
«رفض DocuSign الاتصال. تحقّق من مفتاح التكامل ومعرّف المستخدم وخادم المصادقة، ثم حاول مرة أخرى.»تأكدوا أن مفتاح التكامل ومعرّف المستخدم من بيئة DocuSign نفسها التي يشير إليها خادم المصادقة: مفتاح بيئة demo لا يعمل إلا مع account-d.docusign.com حتى يجتاز Go-Live ويُرقّى.
Paste your DocuSign Connect HMAC key before choosing DocuSign — without it Ahlan Hamad cannot verify that a document was signed.أضيفوا مفتاحًا في Connect ← Connect Keys (القسم 5)، والصقوه في مفتاح HMAC الخاص بـ DocuSign Connect، ثم حفظ. (تظهر هذه الرسالة بالإنجليزية.)
«اربط DocuSign أعلاه قبل اختياره.»اربطوا تطبيق DocuSign الخاص بكم أولًا (القسم 4).

8. قطع الاتصال

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

ولإيقاف عمل المفتاح لدى DocuSign أيضًا، احذفوا زوج مفاتيح RSA من تطبيقكم في Apps and Keys.

عن ربط أهلاً حمد مع DocuSign· كل التكاملات