سيوضح لك هذا الدليل كيفية تسجيل طلب شهادة توقيع المستند مع SSL.com التوقيع الإلكتروني الخدمة واستخدام Cloud Signature Consortium (CSC) API للتوقيع رقميًا على تجزئة مستند وملف PDF. يمكنك استخدام هذا الدليل مع أي منهما حليقة or ساعي البريد. نوصي مستخدمي Postman بتثبيت ملف تطبيق سطح المكتب للعمل من خلال الأمثلة. الأمثلة الواردة في هذا الدليل قابلة للتطبيق على بيئات إنتاج واختبار eSigner و eSealing الخاصة بـ SSL.com. يتم شرح الاختلافات في الأوامر بين أوضاع الإنتاج والاختبار في الأقسام التالية.
لاتباع هذه التعليمات سوف تحتاج:
- أمر شهادة توقيع وثيقة مصدقة. يرجى القراءة هذا كيف للحصول على إرشادات كاملة حول الطلب والتحقق من الصحة.
- A معرف العميل (المعروف أيضا باسم معرف التطبيق. يرجى الرجوع إلى هذا كيف للحصول على إرشادات حول إنشاء بيانات الاعتماد هذه).
اطلب شهادة توقيع وثيقة SSL.com الخاصة بك
كيف تطلب شهادة في بيئة الإنتاج
يرجى الرجوع إلى مقالة الدليل هذه للحصول على إرشادات حول كيفية طلب شهادة توقيع مستند الإنتاج: عملية طلب شهادات توقيع التعليمات البرمجية والمستندات
كيفية طلب شهادة اختبار على Sandbox الخاص بـ SSL.com
يوفر موقع SSL.com بيئة Sandbox مخصصة، تعكس بوابة SSL.com المباشرة الخاصة بنا وSWS API، لتوفير مساحة تجريبية خالية من المخاطر. يسمح هذا الإعداد "المختبري" للمستخدمين باستكشاف واختبار خدمات SSL.com دون القلق من التسبب في انقطاع الخدمة أو تكبد تكاليف فعلية.
المقالة، استخدام SSL.com Sandbox للاختبار والتكامل, سيساعدك على التنقل في عملية إنشاء حساب Sandbox، وبدء أمر اختبار، ودمج Sandbox مع SWS API.
بمجرد إنشاء شهادة الاختبار الخاصة بك، يرجى الاتصال بفريق دعم SSL.com للتحقق من صحتها. يمكنك القيام بذلك عن طريق النقر فوق زر الدردشة عبر الإنترنت الموجود في الركن الأيمن السفلي من الصفحة SSL.com الموقع أو إرسال بريد إلكتروني إلى support@ssl.com.
قم بالتسجيل في eSigner وقم بإعداد المصادقة الثنائية
قبل أن تتمكن من البدء في استخدام CSC API، ستحتاج إلى التسجيل في خدمة التوقيع السحابي eSigner الخاصة بـ SSL.com. يمكن تسجيل الطلبات التي تم التحقق منها في eSigner باتباع الإرشادات التالية:
- . انتقل إلى الطلبات علامة التبويب في حساب SSL.com الخاص بك وتحديد موقع طلبك.
- انقر فوق الأمر تفاصيل الرابط.
- قم بإنشاء وتأكيد رقم التعريف الشخصي المكون من 4 أرقام ، ثم انقر فوق إنشاء PIN .
إذا كنت بحاجة إلى إعادة تعيين رمز PIN الخاص بـ eSigner ، فيرجى القراءة هذا كيف.
- سيظهر رمز الاستجابة السريعة.
في المرة التالية التي تعيد فيها تحميل الصفحة ، لن يكون رمز الاستجابة السريعة مرئيًا. إذا كنت بحاجة لعرض أو إعادة تعيين رمز الاستجابة السريعة الخاص بـ eSigner ، فيرجى القراءة هذا كيف.
- امسح الرمز ضوئيًا في تطبيق مصادقة ثنائية على جهازك المحمول ، مثل أداة مصادقة Google or Authy. سيوفر لك التطبيق كلمات مرور لمرة واحدة (OTPs) لاستخدامها عند التوقيع. كل OTP صالح لمدة 30 ثانية.
اختياري: قم بتحويل شهادة توقيع مستند OV إلى شهادة ختم
ملحوظة: هذا القسم مخصص فقط للمستخدمين الذين يريدون القيام بالختم. لأتمتة توقيع المستندات وعدم المطالبة بكلمات مرور لمرة واحدة (OTP)، يقوم المستخدمون بتحويل شهادة توقيع مستند التحقق من صحة المؤسسة (OV) الخاصة بهم إلى شهادة ختم على حسابات SSL.com الخاصة بهم. لاحظ أنه لا يمكن تحويل شهادة توقيع مستند التحقق الفردي (IV) للختم. تعليمات تحويل الختم مفصلة أدناه:
- انقر الطلبات في القائمة العلوية لحساب SSL.com الخاص بك.
- حدد موقع شهادتك وانقر فوق تنزيل / التفاصيل الرابط.
- انقر على إزالة 2FA .
تثبيت Postman and Import API Collections
التعليمات الواردة في هذا القسم مخصصة لمستخدمي Postman فقط. إذا كنت تستخدم cURL مع CSC API ، فيمكنك الانتقال إلى القسم التالي.
- تحميل وفك ضغط مجموعة CSC API Postman و وثيقة توقيع API مجموعة ساعي البريد (انظر https://www.postman.com/sslcom لمجموعات SSL.com API عبر الإنترنت).
- تحميل وتثبيت عميل Postman REST.
- قم بتشغيل Postman ، ثم أنشئ حساب Postman جديدًا أو سجل الدخول إلى حساب موجود.
- انقر على استيراد .
- انقر على تحميل الملفات زر ، انتقل إلى ملفات مجموعة API التي تم فك ضغطها (
csc-api-prod.postman_collection.jsonوdocument-signing-api-prod.postman_collection.json) وافتحها.
- انقر على استيراد .
- طلبات API التي ستعمل معها متاحة الآن في المجموعات علامة التبويب على الجانب الأيسر من نافذة ساعي البريد.
استرجاع رمز الوصول
الخطوة التالية هي استرداد رمز وصول من SSL.com. ستحتاج الخاص بك معرف العميل متوفر ، بالإضافة إلى اسم المستخدم وكلمة المرور لحساب SSL.com الخاص بك. رموز الوصول صالحة لمدة ساعة واحدة بعد إصدارها.
استخدم علامات التبويب القابلة للنقر أدناه لاختيار إرشادات لـ Postman أو cURL:
- حدد طلب API من مجموعة CSC API.
- إختار ال ترخيص وحدد علامة التبويب بروتوكول OAuth 2.0 من النوع القائمة.
- أدخل المعلومات التالية في النموذج:
- بادئة الرأس:
Bearer - اسم الرمز المميز:
SSLCOM CSC(أو أي اسم آخر تفضله يسهل تذكره) - نوع المنحة:
Authorization Code - عاود الاتصال بالعنوان:
https://upload.esigner.com - التصريح باستخدام المتصفح: لحالها
- عنوان URL للمصادقة:
https://login.ssl.com/oauth2/authorizeلبيئة الإنتاج ؛https://oauth-sandbox.ssl.com/oauth2/authorizeلبيئة Sandbox. - عنوان URL لرمز الوصول:
https://login.ssl.com/oauth2/tokenلبيئة الإنتاج ؛https://oauth-sandbox.ssl.com/oauth2/tokenلبيئة Sandbox. - معرف العميل: [معرّف العميل الخاص بك]
- سر العميل: [سر العميل]
- مجال العمل
service - حالة: [اتركه فارغا]
- مصادقة العميل:
Send as Basic Auth header
عند الانتهاء ، انقر فوق احصل على رمز وصول جديد .
- بادئة الرأس:
- سيظهر نموذج تسجيل الدخول. أدخل اسم المستخدم وكلمة المرور لـ SSL.com ، ثم انقر فوق دخول الأعضاء .
- يجب أن يظهر رمز الوصول الجديد في Postman. حدد نص رمز الوصول وانسخه إلى الحافظة ، ثم أغلق ملف إدارة رموز الوصول صندوق المحادثة. الصق رمز الوصول الخاص بك في محرر نصوص حيث يمكنك الوصول إليه بسهولة. ستنتهي صلاحية كل رمز وصول بعد ساعة واحدة.
يمكنك أيضًا حفظ الرمز المميز الخاص بك لإعادة استخدامه في طلبات Postman ، لكننا وجدنا أنه من الأكثر موثوقية نسخ الرمز المميز ولصقه مباشرةً في كل طلب.
- استخدم الأمر التالي لطلب رمز وصول. استبدل القيم الموضحة في ALL-CAPS بقيمك الفعلية:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application / json" \ --data-raw '{"client_id": "YOUR -CLIENT-ID "، client_secret": "YOUR-CLIENT-SECRET" ، "Grant_type": "password" ، "username": "YOUR-USERNAME" ، "password": "YOUR-PASSSWORD"} " - يجب أن تتلقى كائن JSON يحتوي على رمز وصول ورمز تحديث. انسخ قيمة رمز الوصول للصقها في طلبات API الخاصة بك. لن تحتاج إلى رمز التحديث لهذه الأمثلة.
التوقيع على الهاش
الآن بعد أن أصبح لديك رمز وصول ، يمكنك البدء في تقديم طلبات API وإنشاء التوقيعات. سيوجهك هذا القسم عبر الطلبات الخمسة المتاحة في مجموعة Postman CSC ، مما يؤدي إلى إنشاء توقيع رقمي من تجزئة المستند.
- هناك حاجة إلى مكتبة PDF لمعالجة ملف PDF لإدخال التجزئة ثم تضمين PKCS#7 لاحقًا في مستند PDF. (على سبيل المثال ApachePDFBox في Java).
- مكتبة تشفير لإنشاء PKCS#7 من التوقيعات الأولية المستلمة من eSigner API (على سبيل المثال BouncyCastle في Java).
الحصول على معلومات CSC (اختياري)
- يمكنك استخدام معلومات CSC طلب الحصول على معلومات حول خدمة التوقيع السحابي الخاصة بـ SSL.com. لاحظ أنه ، بخلاف الآخرين في المجموعة ، لا يتطلب هذا الطلب رمز الوصول الخاص بك. لإرسال الطلب ، حدد معلومات CSC من واجهة برمجة تطبيقات CSC المجموعة ، ثم انقر فوق أرسل .
- ستظهر معلومات حول خدمة التوقيع السحابي في كائن JSON في Postman's استجابة الميدان.
- استخدم الأمر التالي للحصول على معلومات حول خدمة CSC API الخاصة بـ SSL.com. إذا كنت في بيئة رمل ، فاستخدم
https://cs-try.ssl.com/csc/v0/infoبدلا من ذلك.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - ستتلقى كائن JSON مع تفاصيل حول الخدمة:
قائمة أوراق اعتماد CSC
• قائمة أوراق اعتماد CSC سيقوم الطلب باسترداد بيانات الاعتماد التي ستستخدمها في طلبات API اللاحقة.
- أختار قائمة أوراق اعتماد CSC وانقر فوق ترخيص علامة التبويب.
- اختار رمز لحاملها من النوع القائمة ، الصق رمز الوصول الخاص بك في ملف رمز حقل ، ثم انقر فوق أرسل .
- سيظهر كائن JSON بقائمة بمعرفات بيانات الاعتماد المرتبطة بالمستخدم في ملف استجابة حقل. من المحتمل أن تحتوي قائمتك على قيمة واحدة. انسخ معرف بيانات الاعتماد والصقه في محرر نصوص لاستخدامه في الطلبات اللاحقة.
- أدخل الأمر التالي. (استبدل MY-ACCESS-TOKEN برمز الوصول الفعلي الخاص بك). إذا كنت في بيئة رمل ، فاستخدم
https://cs-try.ssl.com/csc/v0/credentials/listفي حين أن:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "التفويض: Bearer MY- رمز الوصول "\ --data-raw" {}في حالة استخدام شهادة eseal (شهادة توقيع المستند مع معلومات المؤسسة فقط ؛ المضمنة في حساب esigner.com المجاني الخاص بك) ، قم بتضمين "clientData": "DS_ESEAL" (ملاحظة: لا تتطلب eseals مصادقة OTP). الخيارات الأخرى لـ "clientData" هي "EVCS" لتوقيع رمز EV و "DS" (افتراضي) لتوقيع المستند IV أو IV + OV:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "التفويض: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" clientData ":" DS_ESEAL "}' - يجب أن تتلقى كائن JSON بقائمة بمعرفات بيانات الاعتماد المرتبطة بالمستخدم. من المحتمل أن تحتوي قائمتك على قيمة واحدة. انسخ معرف بيانات الاعتماد والصقه في محرر نصوص لاستخدامه في الطلبات اللاحقة.
معلومات اعتماد CSC (اختياري)
• معلومات اعتماد CSC سيعيد الطلب الشهادات والمعلومات الأخرى المرتبطة بمعرف بيانات الاعتماد ، وهو غير مطلوب للتوقيع.
- لاستخدام هذا الطلب ، حدد معلومات اعتماد CSC من المجموعة وانقر فوق ترخيص علامة التبويب.
- اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
- إختار ال الجسم ، ثم الصق معرف بيانات الاعتماد كقيمة لـ
credentialID.
- انقر على أرسل .
- سيظهر كائن JSON مع سلسلة شهادات التوقيع والمعلومات الأخرى في ملف استجابة الميدان.
- أدخل الأمر التالي. إذا كنت في بيئة رمل ، فاستخدم
https://cs-try.ssl.com/csc/v0/credentials/infoاستبدلMY-ACCESS-TOKENوMY-CREDENTIAL-IDبمعلوماتك الفعلية:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application / json" \ --header "التفويض: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID ":" MY-CREDENTIAL-ID "،" الشهادات ":" chain "،" certInfo ": true ،" authInfo ": true}' - يجب أن تتلقى كائن JSON مع سلسلة شهادة التوقيع ومعلومات أخرى:
تفويض أوراق الاعتماد
• تفويض أوراق الاعتماد طلب استرداد الإذن لتوقيع التجزئة.
- ابدأ بالاختيار تفويض أوراق الاعتماد من المجموعة والنقر فوق ترخيص علامة التبويب.
- اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
- إختار ال الجسم التبويب. الصق معرف بيانات الاعتماد الخاص بك كملف
credentialIDقيمة وتجزئة للمستند الذي ترغب في توقيعه على أنهhashالقيمة. استرجع وأدخل OTP من تطبيق المصادقة الخاص بك وأدخله كقيمة لـOTP، ثم انقر فوق أرسل زر. ملاحظة: OTP غير مطلوب لإغلاق الشهادات.
- سيظهر كائن JSON مع بيانات تنشيط التوقيع (SAD) في ملف استجابة حقل. انسخ هذه القيمة والصقها في محرر نصوص لاستخدامها في طلب توقيع التجزئة.
- استخدم الأمر التالي. يحل محل
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDوMY-HASHبمعلوماتك الفعلية. احصل على كلمة مرور لمرة واحدة من تطبيق 2FA واستخدمها كقيمة لـMY-OTP. ملاحظة: OTP غير مطلوب لإغلاق الشهادات.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application / json" \ --header "التفويض: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID ":" MY-CREDENTIAL-ID "،" numSignatures ": 1 ،" hash ": [" MY-HASH "] ،" OTP ":" MY-OTP "}" - يجب أن تتلقى كائن JSON مع بيانات تنشيط التوقيع (SAD). انسخ هذه القيمة والصقها في محرر نصوص لاستخدامها في طلب توقيع التجزئة.
علامة التجزئة
أنت الآن جاهز لتوقيع تجزئة المستند.
- أختار علامة التجزئة من المجموعة ، ثم حدد ملف ترخيص علامة التبويب.
- اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
- إختار ال الجسم التبويب. الصق معرف بيانات الاعتماد الخاص بك كملف
credentialIDالقيمة ، بيانات تنشيط التوقيع الخاصة بك مثلSADالقيمة ، وتجزئة للمستند الذي ترغب في توقيعه باسمhashالقيمة ، ثم انقر فوق أرسل .
- سيظهر كائن JSON بتوقيعك في ملف استجابة الميدان.
- أدخل الأمر التالي. يحل محل
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADوMY-HASHبمعلوماتك الفعلية:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application / json" \ --header "التفويض: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID ":" MY-CREDENTIAL-ID "،" SAD ":" MY-SAD "،" التجزئة ": [" MY-HASH "] ،" SignAlgo ": "1.2.840.113549.1.1.11"} " - يجب أن تتلقى كائن JSON يحتوي على توقيعك.
وقّع على ملف PDF
بالإضافة إلى توقيع تجزئات المستندات ، يمكنك أيضًا تحميل ملف PDF وتوقيعه.
عند التوقيع على ملف PDF ، ستتعامل مع طلبي POST:
- تحميل مستند PDF
- توقيع وثيقة PDF
يمكنك إعادة استخدام بيانات الاعتماد التي استردتها أعلاه مع قائمة أوراق اعتماد CSC طلب. قد تحتاج أيضًا إلى استرداد ملف وصول الرمز.
تحميل مستند PDF
- إختار ال تحميل مستند PDF اطلب وانقر فوق ترخيص علامة التبويب.
- اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
- إختار ال رؤوس علامة التبويب والصق معرف بيانات الاعتماد الخاص بك في ملف القيم العمود.
- إختار ال الجسم ثم انقر فوق × قرب
hello.pdfلإزالة اسم ملف العنصر النائب هذا.
- انقر على حدد ملف ، ثم انتقل إلى الملف الذي تريد تحميله.
- انقر على أرسل .
- حدد وانسخ ملف
idقيمة في الاستجابة لاستخدامها في الطلب التالي.
- استخدم الأمر التالي. يحل محل
MY-CREDENTIAL-ID,MY-ACCESS-TOKENو/PATH/TO/FILE.pdfبمعلوماتك الفعلية:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-ID: MY-CREDENTIAL-ID" \ --header "التفويض: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- ستتلقى كائن JSON بقيمة
id. انسخ هذه القيمة لاستخدامها في الطلب التالي.
ملاحظة: للتواقيع المرئية ، يرجى الرجوع إلى رؤوس طلبات HTTP التالية (/ v1 / pdf / upload):
|
معرف الاعتماد |
معرف الاعتماد الفريد المعين للمفتاح - إلزامي |
|
التوقيع - سبب |
أضف سبب التوقيع لإضافة مظهر التوقيع وأيضًا في قاموس التوقيع - اختياري ، على سبيل المثال ، أوافق على هذا المستند |
|
موقع التوقيع |
أضف موقع التوقيع في قاموس التوقيع - اختياري مثل هيوستن ، تكساس |
|
معلومات الاتصال |
إضافة معلومات الاتصال في قاموس التوقيع - اختياري مثل رقم الهاتف |
|
التوقيع-الحقل-الوظيفة |
موضع حقل التوقيع حيث يظهر التوقيع المرئي. التنسيق هو "س ، ص ، عرض ، ارتفاع" - اختياري |
|
رقم الصفحة |
رقم الصفحة حيث يتم رسم التوقيع - اختياري |
|
التوقيع باليد |
Base64 صورة PNG مشفرة لتوقيع اليد - اختياري |
توقيع وثيقة PDF
الآن يمكنك التوقيع على ملف PDF.
- إختار ال تحميل مستند PDF اطلب وانقر فوق ترخيص علامة التبويب.
- اختار رمز لحاملها من النوع القائمة ، ثم الصق رمز الوصول الخاص بك في ملف رمز الميدان.
- حدد علامة التبويب الجسم ، والصق في
idالقيمة من الخطوة السابقة ومرة واحدة من تطبيق المصادقة الخاص بك ، ثم انقر فوق أرسل .
- ستظهر بيانات PDF أدناه في ملف استجابة حقل. أختر حفظ في ملف من حفظ الاستجابة القائمة ، ثم قم بتسمية الملف.
- افتح الملف في Acrobat للتأكد من توقيع الملف.
- أدخل الأمر التالي. يحل محل
MY-CREDENTIAL-ID,MY-FILE-IDوOUTPUT-FILENAMEبمعلوماتك الفعلية. احصل على كلمة مرور لمرة واحدة (OTP) من تطبيق 2FA وأدخلها كـMY-OTP. ملاحظة: OTP غير مطلوب لإغلاق الشهادات:
curl --location --request POST 'https://ds.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"} '\ - -إخراج الإخراج- FILENAME - سيقوم cURL بتنزيل الملف الموقع وحفظه في اسم الملف الذي حددته:
- افتح ملف PDF في Acrobat أو Acrobat Reader للتحقق من صحة التوقيع.
