دليل التكامل لاختبار توقيع المستند عن بُعد باستخدام eSigner CSC API

سيقودك هذا الدليل خلال توقيع تجزئة مستند وملف PDF مع SSL.com التوقيع الإلكتروني خدمة التوقيع السحابي وواجهة برمجة تطبيقات Cloud Signature Consortium (CSC). سيتم عرض جميع أمثلة طلبات API مع ساعي البريد، ونوصي بتثبيت برنامج تطبيق ساعي البريد لسطح المكتب على جهاز الكمبيوتر الخاص بك إذا كنت ترغب في العمل من خلال الأمثلة. يتم أيضًا تضمين أمثلة أوامر cURL لطلبات واجهة برمجة التطبيقات.

قم بإنشاء طلب اختبار

1. أولاً ، ستحتاج إلى إنشاء أمر توقيع مستند في Sandbox. ابدأ بتسجيل الدخول إلى حساب Sandbox الخاص بك والذهاب إلى لوحة المعلومات علامة التبويب.
   
2. انقر أدوات المطورين.
   
3. أختار توقيع وثيقة eSigner، ثم انقر فوق إنشاء أمر اختبار .
   
4. سيظهر مربع الحوار. انقر على OK .
   
5. حدد موقع طلب الاختبار الخاص بك ، ثم انقر فوق تفاصيل الرابط.
   
6. انقر تحرير المسجل لبدء إدخال معلومات مقدم الطلب والمستلم لطلب الاختبار الخاص بك. لاحظ أنه نظرًا لعدم استخدام هذه المعلومات لإصدار شهادة توقيع وثيقة صالحة ، يمكنك إدخال معلومات وهمية إذا رغبت في ذلك.
   
7. أضف معلومات مقدم الطلب لشهادة الاختبار ، ثم انقر فوق التالي >> .
   
8. أدخل معلومات المستلم ، ثم انقر فوق التالي >> .
   
9. انقر على تخطى لتخطي تحميل مستندات التحقق من صحة شهادة الاختبار.
   
10. يجب أن يكون طلب الاختبار الخاص بك الآن بحالة في انتظار التحقق من صحة. اتصل بفريق دعم SSL.com على Support@SSL.com للتحقق من صحة شهادة الاختبار الخاصة بك.
    

قم بالتسجيل في eSigner وقم بإعداد المصادقة الثنائية

1. بمجرد التحقق من صحة طلب الاختبار الخاص بك بواسطة فريق دعم SSL.com ، يمكنك تسجيله في eSigner. انتقل إلى الطلبات علامة التبويب في حساب وضع الحماية لـ SSL.com الخاص بك وحدد موقع طلب الاختبار الخاص بك.
   
2. انقر فوق الأمر تفاصيل الرابط.
   
3. قم بإنشاء وتأكيد رقم التعريف الشخصي المكون من 4 أرقام ، ثم انقر فوق إنشاء PIN .
   
   إذا كنت بحاجة إلى إعادة تعيين رمز PIN الخاص بـ eSigner ، فيرجى القراءة هذا كيف.
   
4. سيظهر رمز الاستجابة السريعة.
   
   في المرة التالية التي تعيد فيها تحميل الصفحة ، لن يكون رمز الاستجابة السريعة مرئيًا. إذا كنت بحاجة لعرض أو إعادة تعيين رمز الاستجابة السريعة الخاص بـ eSigner ، فيرجى القراءة هذا كيف.
   
5. امسح الرمز ضوئيًا في تطبيق مصادقة ثنائية على جهازك المحمول ، مثل Google Authenticator أو Authy. سيوفر لك التطبيق كلمات مرور لمرة واحدة (OTPs) لاستخدامها عند التوقيع. كل OTP صالح لمدة 2 ثانية.
   

تثبيت ساعي البريد واستيراد مجموعة CSC API

1. تحميل وفك ضغط مجموعة CSC API Postman (انظر https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation للحصول على أحدث نقاط نهاية API أو تنزيلات المجموعة).
   
2. تحميل وتثبيت عميل Postman REST.
   
3. قم بتشغيل Postman ، ثم أنشئ حساب Postman جديدًا أو سجل الدخول إلى حساب موجود.
   
4. انقر على استيراد .
   
5. انقر على تحميل الملفات زر ، انتقل إلى ملف مجموعة API غير المضغوط (CSC-API.postman_collection.json) وافتحه.
   
6. انقر على استيراد .
   
7. انقر على المجموعات علامة التبويب في Postman وقم بتوسيع مجموعة CSC API لعرض طلبات POST الخمسة التي ستعمل معها:
   • معلومات CSC
   • قائمة أوراق اعتماد CSC
   • معلومات اعتماد CSC
   • تفويض أوراق الاعتماد
   • علامة التجزئة

   

استرجاع رمز الوصول

1. الخطوة التالية هي استرداد رمز وصول من SSL.com. قبل أن تطلب رمز الوصول الخاص بك ، ستحتاج إلى ملف معرف العميل (المعروف أيضا باسم معرف التطبيق. يرجى الرجوع إلى هذا كيف للحصول على إرشادات حول إنشاء بيانات الاعتماد هذه).
2. إختار ال ترخيص علامة التبويب، حدد بروتوكول OAuth 2.0 من النوع القائمة ، وانقر فوق احصل على رمز وصول جديد .
   
3. أدخل المعلومات التالية في النموذج:
   • اسم الرمز المميز: SandBox CSC (أو أي اسم آخر تفضله يسهل تذكره)
   • نوع المنحة: قانون التفويض
   • عاود الاتصال بالعنوان: [اتركه فارغا]
   • التصريح باستخدام المتصفح: التحقق
   • عنوان URL للمصادقة: https://oauth-sandbox.ssl.com/oauth2/authorize
   • عنوان URL لرمز الوصول: https://oauth-sandbox.ssl.com/oauth2/token
   • معرف العميل: [معرّف العميل الخاص بك]
   • سر العميل: [سر العميل]
   • مجال العمل الخدمة
   • حالة: [اتركه فارغا]
   • مصادقة العميل: إرسال كرأس المصادقة الأساسية

   عند الانتهاء ، انقر فوق طلب رمز .
   

4. سيظهر نموذج تسجيل الدخول في متصفح الويب الخاص بك. أدخل اسم المستخدم وكلمة المرور لـ SSL.com ، ثم انقر فوق دخول الأعضاء .
   
5. يجب أن يظهر رمز الوصول الجديد في Postman. حدد نص رمز الوصول وانسخه إلى الحافظة ، ثم أغلق ملف إدارة رموز الوصول صندوق المحادثة. الصق رمز الوصول الخاص بك في محرر نصوص حيث يمكنك الوصول إليه بسهولة. ستنتهي صلاحية كل رمز وصول بعد ساعة واحدة.
   
   يمكنك أيضًا حفظ الرمز المميز الخاص بك لإعادة استخدامه في ساعي البريد الطلبات ، لكننا وجدنا أنه من الأكثر موثوقية نسخ الرمز المميز ولصقه مباشرةً في كل طلب.
   

التوقيع على الهاش

الآن بعد أن أصبح لديك رمز وصول ، يمكنك البدء في تقديم طلبات API وإنشاء التوقيعات. سيوجهك هذا القسم خلال الطلبات الخمسة المتاحة في جمع ساعي البريد CSC، مما يؤدي إلى إنشاء توقيع رقمي من تجزئة المستند.

الحصول على معلومات CSC (اختياري)

1. يمكنك استخدام معلومات CSC طلب الحصول على معلومات حول خدمة التوقيع السحابي الخاصة بـ SSL.com. لاحظ أنه ، بخلاف الآخرين في المجموعة ، لا يتطلب هذا الطلب رمز الوصول الخاص بك. لإرسال الطلب ، حدد معلومات CSC من واجهة برمجة تطبيقات CSC المجموعة ، ثم انقر فوق أرسل .
   
2. ستظهر معلومات حول خدمة التوقيع السحابي في كائن JSON في Postman's استجابة الميدان.
   

الأمر cURL

curl --location --request POST "https://cs-try.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}"

قائمة أوراق اعتماد CSC

1. • قائمة أوراق اعتماد CSC سيقوم الطلب باسترداد بيانات الاعتماد التي ستستخدمها في طلبات API اللاحقة. تحديد قائمة أوراق اعتماد CSC وانقر فوق ترخيص علامة التبويب.
   
2. اختار رمز لحاملها من النوع القائمة ، الصق رمز الوصول الخاص بك في ملف رمز حقل ، ثم انقر فوق أرسل .
   
3. سيظهر كائن JSON بقائمة بمعرفات بيانات الاعتماد المرتبطة بالمستخدم في ملف استجابة حقل. من المحتمل أن تحتوي قائمتك على قيمة واحدة. انسخ معرف بيانات الاعتماد والصقه في محرر نصوص لاستخدامه في الطلبات اللاحقة.
   

الأمر cURL

استبدل MY-ACCESS-TOKEN مع رمز الوصول الفعلي الخاص بك:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "التفويض: الحامل MY-ACCESS-TOKEN "\ --data-raw" {}

في حالة استخدام شهادة eseal (شهادة توقيع المستند مع معلومات المؤسسة فقط ؛ المضمنة في حساب esigner.com المجاني الخاص بك) ، قم بتضمين "clientData": "DS_ESEAL" (ملاحظة: لا تتطلب eseals مصادقة OTP). الخيارات الأخرى لـ "clientData" هي "EVCS" لتوقيع رمز EV و "DS" (افتراضي) لتوقيع المستند IV أو IV + OV:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "التفويض: الحامل MY-ACCESS-TOKEN "\ --data-raw" {\ "clientData \": \ "DS_ESEAL \"} "

معلومات اعتماد CSC (اختياري)

1. • معلومات اعتماد CSC سيعيد الطلب الشهادات والمعلومات الأخرى المرتبطة بمعرف بيانات الاعتماد ، وهو غير مطلوب للتوقيع. لاستخدام هذا الطلب ، حدد معلومات اعتماد CSC من المجموعة وانقر فوق ترخيص علامة التبويب.
   
2. اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
   
3. إختار ال الجسم ، ثم الصق معرف بيانات الاعتماد كقيمة لـ credentialID.
   
4. انقر على أرسل .
   
5. سيظهر كائن JSON مع سلسلة شهادات التوقيع والمعلومات الأخرى في ملف استجابة الميدان.
   

الأمر cURL

استبدل MY-ACCESS-TOKEN و MY-CREDENTIAL-ID بمعلوماتك الفعلية:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application / json" \ --header "التفويض: الحامل MY-ACCESS-TOKEN "\ --data-raw" {\ "معرّف الاعتماد \": \ "MY-CREDENTIAL-ID \"، \ "الشهادات \": \ "chain \"، \ "certInfo \": true، \ "authInfo \": true} "

تفويض أوراق الاعتماد

1. • تفويض أوراق الاعتماد طلب استرداد الإذن لتوقيع التجزئة. ابدأ بالاختيار تفويض أوراق الاعتماد من المجموعة والنقر فوق ترخيص علامة التبويب.
   
2. اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
   
3. إختار ال الجسم التبويب. الصق معرف بيانات الاعتماد الخاص بك كملف credentialID قيمة وتجزئة للمستند الذي ترغب في توقيعه على أنه hash القيمة. استرجع وأدخل OTP من تطبيق المصادقة الخاص بك وأدخله كقيمة لـ OTP، ثم انقر فوق أرسل .
   
4. سيظهر كائن JSON مع بيانات تنشيط التوقيع (SAD) في ملف استجابة حقل. انسخ هذه القيمة والصقها في محرر نصوص لاستخدامها في طلب توقيع التجزئة.
   

الأمر cURL

استبدل MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASHو MY-OTP بمعلوماتك الفعلية:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application / json" \ --header "التفويض: الحامل MY-ACCESS-TOKEN "\ --data-raw" {\ "معرّف الاعتماد \": \ "MY-CREDENTIAL-ID \"، \ "numSignatures \": 1، \ "hash \": [\ "MY-HASH \ "]، \" OTP \ ": \" MY-OTP \ "}"

علامة التجزئة

1. نحن الآن جاهزون لتوقيع تجزئة المستند. تحديد علامة التجزئة من المجموعة ، ثم حدد ملف ترخيص علامة التبويب.
   
2. اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
   
3. إختار ال الجسم التبويب. الصق معرف بيانات الاعتماد الخاص بك كملف credentialID القيمة ، بيانات تنشيط التوقيع الخاصة بك مثل SAD القيمة ، وتجزئة للمستند الذي ترغب في توقيعه باسم hash القيمة ، ثم انقر فوق أرسل .
   
4. سيظهر كائن JSON بتوقيعك في ملف استجابة الميدان.
   

الأمر cURL

استبدل MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADو MY-HASH بمعلوماتك الفعلية:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application / json" \ --header "التفويض: الحامل MY-ACCESS-TOKEN "\ --data-raw" {\ "معرّف الاعتماد \": \ "معرف بطاقة الاعتماد \" ، \ "حزين \": \ "MY-SAD \" ، \ "التجزئة \": [\ "MY-HASH \"]، \ "signAlgo \": \ "1.2.840.113549.1.1.11 \"} "

وقّع على ملف PDF

بالإضافة إلى توقيع تجزئات المستندات ، يمكنك أيضًا تحميل ملف PDF وتوقيعه. ابدأ بتنزيل واستيراد ملف وثيقة توقيع API مجموعة ساعي البريد (انظر https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation للحصول على أحدث نقاط نهاية api وتنزيلات المجموعة) ، باتباع نفس الشيء خطوات التثبيت الذي اتبعته أعلاه لمجموعة CSC API.

• تحميل مستند PDF
• توقيع وثيقة PDF

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

تحميل مستند PDF

1. إختار ال تحميل مستند PDF اطلب وانقر فوق ترخيص علامة التبويب.
   
2. اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
   
3. إختار ال رؤوس علامة التبويب والصق معرف بيانات الاعتماد الخاص بك في ملف القيم العمود.
   
4. إختار ال الجسم ثم انقر فوق × قرب hello.pdf لإزالة اسم ملف العنصر النائب هذا.
   
5. انقر على حدد ملف ، ثم انتقل إلى الملف الذي تريد تحميله.
   
6. انقر على أرسل .
   
7. حدد وانسخ ملف id قيمة في الاستجابة لاستخدامها في الطلب التالي.
   

الأمر cURL

استبدل MY-CREDENTIAL-ID, MY-ACCESS-TOKENو /PATH/TO/FILE.pdf بمعلوماتك الفعلية:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/upload" \ --header "Credential-ID: MY-CREDENTIAL-ID" \ --header "التفويض: الحامل MY-ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "

ملاحظة: للتواقيع المرئية ، يرجى الرجوع إلى رؤوس طلبات HTTP التالية (/ v1 / pdf / upload):

توقيع وثيقة PDF

1. الآن يمكنك التوقيع على ملف PDF. حدد ملف تحميل مستند PDF اطلب وانقر فوق ترخيص علامة التبويب.
     
2. اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
   
3. حدد علامة التبويب الجسم ، والصق في ملف id القيمة من الخطوة السابقة.
   
4. أدخل OTP من تطبيق المصادقة الخاص بك وانقر فوق أرسل .
   
5. ستظهر بيانات PDF أدناه في ملف استجابة حقل. أختر حفظ في ملف من حفظ الاستجابة القائمة ، ثم قم بتسمية الملف.
   
6. افتح الملف في Acrobat للتأكد من توقيع الملف. (لاحظ أنه في لقطة الشاشة أدناه ، تم الوثوق يدويًا بجذر تطوير RSA الخاص بـ SSL.com في Acrobat.)
   

الأمر cURL

استبدل MY-CREDENTIAL-ID, MY-FILE-IDو MY-OTP بمعلوماتك الفعلية:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Content-Transfer-Encoding: application / json" \ --header "Content-Type : application / json "\ --header" التفويض: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "id \": \ "MY-FILE-ID \"، \ "otp \": \ "MY-OTP \"} "

 بدء الإنتاج

لبدء البث المباشر ، تحتاج إلى إزالة "-حاول" من النطاق الفرعي. على سبيل المثال ، لبدء البث المباشر باستخدام ds-try.ssl.com ، قم بإزالة "-try" حتى يصبح النطاق الفرعي ds.ssl.com.