مرجع واجهة برمجة التطبيقات ABSign REST: الإصدار 2 من نقاط النهاية والمصادقة ودليل التكامل

مقدمة إلى ABSign API v2

تعد ABSign REST API v2 هي الواجهة البرمجية الرسمية لدمج إمكانات التوقيع الإلكتروني على مستوى المؤسسة في أنظمة عملك ومنصات التداول وسير عمل إدارة المستندات. بناءً على مبادئ REST مع حمولات طلب JSON والاستجابة، تتصل واجهة برمجة التطبيقات (API) بسلاسة مع أي حزمة تقنية قادرة على إجراء مكالمات HTTPS – بدءًا من تطبيقات Python وNode.js إلى خدمات Java Spring Boot وأنظمة PHP Laravel وتطبيقات .NET Core. نقطة النهاية الأساسية لجميع مكالمات v2 API هي https://www.abroadsign.com/api/v2/، الذي يحل محل نقطة النهاية القديمة الإصدار 1 ويقدم أمانًا محسنًا وتغطية موسعة لأحداث خطاف الويب وتحسين تحديد المعدل لعمليات تكامل المؤسسات ذات الحجم الكبير.

تعتمد المؤسسات في أكثر من 180 دولة على ABSign API لأتمتة سير عمل توقيع المستندات التي تشمل عقود شحن البضائع، وخطابات اعتماد التمويل التجاري، والإقرارات الجمركية، واتفاقيات سلسلة التوريد متعددة الأطراف، ومستندات المشتريات الخاصة بالمؤسسات. يقدم الإصدار الثاني دعمًا أصليًا لعمليات المستندات المجمعة، ودمج القوالب المتقدم، وإرساء الطابع الزمني لـ blockchain، وميزات التعاون في الوقت الفعلي التي تتيح احتفالات متزامنة متعددة التوقيع من أي متصفح أو جهاز محمول دون مطالبة المشاركين بتثبيت برامج متخصصة أو إنشاء حسابات ABSign. سواء كنت شركة ناشئة تقوم ببناء أول تدفق لتأهيل عميلك أو مؤسسة تستبدل البنية التحتية للتعاقد الورقي بالكامل، توفر ABSign API العناصر الأساسية للتوقيع الرقمي المؤتمت بالكامل والمتوافق قانونيًا على نطاق عالمي.

المصادقة وتكوين الأمن

يعد تأمين الوصول إلى واجهة برمجة التطبيقات (API) أمرًا بالغ الأهمية عند التعامل مع التوقيعات الرقمية الملزمة قانونًا. يستخدم ABSign API v2 المصادقة المستندة إلى مفتاح API جنبًا إلى جنب مع تشفير النقل TLS 1.3، مما يضمن تشفير كل طلب واستجابة أثناء النقل ومحصن ضد الاعتراض أو هجمات الوسيط. يتم إنشاء جميع مفاتيح واجهة برمجة التطبيقات من لوحة معلومات ABSign ضمن الإعدادات، مع نطاقات أذونات دقيقة تتبع مبدأ الامتيازات الأقل – يتلقى كل تكامل الأذونات التي يحتاجها بالضبط، لا أكثر. لا يتم أبدًا نقل المفاتيح في عناوين URL، بل في رؤوس HTTP فقط، ويجب أن تقوم أنظمتك بتخزينها في متغيرات البيئة أو منصات مخصصة لإدارة الأسرار مثل AWS Secrets Manager أو HashiCorp Vault أو Azure Key Vault بدلاً من تضمينها في مستودعات التعليمات البرمجية المصدر أو ملفات التكوين المخصصة لأنظمة التحكم في الإصدار.

• رأس الرمز المميز لحامله: يجب أن يتضمن كل طلب API Authorization: Bearer YOUR_API_KEY header. لا تقم أبدًا بترميز مفاتيح واجهة برمجة التطبيقات (API) في التعليمات البرمجية المصدرية للتطبيق؛ استخدام متغيرات البيئة أو أنظمة إدارة الأسرار لإدخال بيانات الاعتماد في وقت التشغيل.
• تطبيق TLS 1.3: يجب أن تستخدم كافة اتصالات API TLS 1.3. سيتم رفض الاتصالات التي تحاول استخدام إصدارات TLS الأقدم باستجابة 400 طلب غير صحيح. ويضمن ذلك عدم عرض محتوى المستند وبيانات التوقيع مطلقًا عبر قنوات غير مشفرة.
• نطاقات الإذن: يتم تحديد نطاق مفاتيح واجهة برمجة التطبيقات (API) لعمليات محددة – document.read، document.write، templates.read، templates.write، Signers.manage، webhooks.admin، وorganization.read. قم بتعيين النطاقات المطلوبة فقط لكل حالة استخدام تكامل للحد من نصف قطر الانفجار في حالة اختراق المفتاح.
• سياسة التناوب الرئيسية: تنفيذ التناوب الآلي للمفاتيح وفقًا لجدول زمني مدته 90 يومًا. تدعم لوحة معلومات ABSign تدوير المفاتيح بدون توقف من خلال مفهوم المفاتيح الأساسية والثانوية، مما يسمح لك بتدوير بيانات الاعتماد دون تعطيل سير عمل التوقيع أثناء الرحلة.
• القائمة المسموح بها لعنوان IP: يمكن لحسابات المؤسسة تقييد الوصول إلى واجهة برمجة التطبيقات (API) لعناوين IP محددة أو نطاقات CIDR. قم بتمكين القائمة المسموح بها لعناوين IP من صفحة إعدادات الأمان لعمليات التكامل من خادم إلى خادم حيث تكون عناوين IP للاتصال معروفة ومستقرة.

“لقد أدى تنفيذ TLS 1.3 ونطاق مفتاح واجهة برمجة التطبيقات (API) إلى تقليل نتائج التدقيق الأمني ​​لدينا إلى الصفر. وقد تم تصميم ABSign API مع أخذ متطلبات أمان المؤسسة في الاعتبار – وقد ظهر ذلك في كل تفاصيل عملية التكامل.”

— رئيس قسم أمن المعلومات، شركة تجارة السلع العالمية

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

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

مجموعة نقطة النهاية	المسار الأساسي	العمليات الرئيسية	حالة الاستخدام الشائع
وثائق	/documents	إنشاء، قراءة، قائمة، تحديث، تنزيل، أرشفة، حذف	بدء التوقيع واسترجاع المستندات المكتملة
القوالب	/templates	إنشاء، قراءة، تحديث، حذف، استنساخ، قائمة	سير عمل المستندات الموحدة
الموقعون	/signers	دعوة، إعادة إرسال دعوة، إلغاء، التحقق من الهوية	إدارة حفلات التوقيع
التوقيعات	/signatures	تطبيق، والتحقق، والتحقق من الحالة، واسترداد مسار التدقيق	استكمال والتحقق من صحة التوقيعات
خطافات الويب	/webhooks	إنشاء، قائمة، حذف، اختبار، تمكين/تعطيل	إشعارات الأحداث في الوقت الحقيقي
المنظمات	/organizations	القراءة والتحديث والإعدادات وأعضاء الفريق	تكوين المسؤول والامتثال
سجلات التدقيق	/audit-logs	قائمة، تصفية، تصدير، تنزيل PDF	تقارير الامتثال والطب الشرعي
العمليات السائبة	/bulk	إنشاء دفعة، الحالة، إلغاء الدفعة	معالجة المستندات بكميات كبيرة

نمط تكامل دورة حياة الوثيقة

يتبع نمط تكامل واجهة برمجة التطبيقات (API) الأكثر شيوعًا دورة حياة المستند بدءًا من الإنشاء ومرورًا بتجميع التوقيع وحتى الأرشفة. يوضح سير العمل الشامل هذا كيف تتفاعل أنظمتك مع ABSign API في كل مرحلة، مما يتيح عمليات التوقيع الآلية بالكامل دون تدخل يدوي أو نفقات إدارية. يعد فهم دورة الحياة هذه أمرًا ضروريًا لبناء عمليات تكامل موثوقة تتعامل مع سيناريوهات الفشل بأمان وتحافظ على اتساق البيانات عبر الأنظمة الموزعة.

الخطوة 1: إنشاء المستند وتجميع القالب

ابدأ بإنشاء مستند إما من قالب تم تكوينه مسبقًا أو من محتوى HTML أو PDF أولي يتم إرساله مباشرةً إلى واجهة برمجة التطبيقات (API). بالنسبة للإنشاء المستند إلى القالب، قم بتمرير قيم متغيرات القالب في نص الطلب لتخصيص محتوى المستند لكل مناسبة توقيع محددة مع الحفاظ على اتساق العلامة التجارية وتوحيد البند القانوني. تستجيب واجهة برمجة التطبيقات (API) على الفور بمعرف المستند الذي يخزنه نظامك لجميع العمليات اللاحقة على هذا المستند. يدعم إنشاء المستندات الوضع الدفعي، حيث يمكنك إرسال ما يصل إلى 500 مستند في استدعاء واحد لواجهة برمجة التطبيقات (API) لمعالجة قوائم الانتظار التي تحتاج إلى بدء عشرات أو مئات من عمليات سير عمل التوقيع في وقت واحد خلال فترات ذروة التداول.

• استخدم POST /documents مع template_id و template_data للإنشاء من قالب، أو إرساله content_html أو content_pdf_base64 للمحتوى الخام.
• اضبط signing_sequence ل sequential للتوقيع متعدد الأطراف المطلوب أو parallel عندما تتمكن جميع الأطراف من التوقيع في وقت واحد لتقليل وقت الانتظار.
• تحديد expiry_days للتحكم في المدة التي تظل فيها دعوة التوقيع نشطة قبل انتهاء صلاحية المستند تلقائيًا وتطلب التجديد.
• يُمكَِن block_download_until_completed لمنع الوصول المبكر إلى المستند بينما لا يزال أي توقيع مطلوب معلقًا.

الخطوة 2: تكوين المُوقع وإرسال سير العمل

بعد إنشاء مستند، قم بإضافة الموقعين المطلوبين مع تحديد عناوين بريدهم الإلكتروني وأسماء العرض وموقعهم في تسلسل التوقيع. بالنسبة لعمليات التكامل التي تتطلب ضمانًا معززًا للهوية – مثل معاملات التمويل التجاري عالية القيمة أو وثائق الاستيراد والتصدير المنظمة – قم بتمكين identity_verification_required علامة لتفويض التحقق من الهوية البيومترية أو الهوية الحكومية قبل قبول التوقيع. قم بإرسال المستند إلى جميع الموقعين من خلال استدعاء API واحد، وتقوم منصة ABSign تلقائيًا بإنشاء دعوات بريد إلكتروني منسقة بشكل احترافي مع روابط مستندات مخصصة، وإشعارات انتهاء الصلاحية، وتعليمات توقيع واضحة باللغة المفضلة للمستلم.

• إضافة الموقعين عبر POST /documents/{document_id}/signers مع البريد الإلكتروني والاسم والدور (signer, witnessأو 抄送 ل سي سي).
• تكوين reminder_schedule لإرسال رسائل بريد إلكتروني تذكيرية تلقائيًا على فترات 24 ساعة و72 ساعة إلى الموقعين الذين لم يتصرفوا بعد.
• تعيين redirect_url_after_signed لتوجيه الموقعين إلى صفحة إكمال مخصصة في نظامك بعد الانتهاء من التوقيع.
• يُمكَِن signer_authentication تتطلب التحقق من البريد الإلكتروني لمرة واحدة (OTP) أو الرسائل النصية القصيرة (SMS) كطبقة إضافية لتأكيد هوية المُوقع.

الخطوة 3: الإكمال المستند إلى Webhook والمعالجة النهائية

يقدم نظام Webhook ABSign إشعارات الأحداث في الوقت الفعلي إلى نقطة نهاية HTTPS التي تم تكوينها عندما يتخذ الموقّع إجراءً أو تتغير حالة دورة حياة المستند. بدلاً من استقصاء واجهة برمجة التطبيقات (API) بشكل متكرر للتحقق من حالة المستند – الأمر الذي يستهلك حصتك المحددة للمعدل ويضيف زمن الوصول – قم بتكوين خطافات الويب لتلقي إشعارات الدفع التي تؤدي إلى تشغيل العمليات النهائية تلقائيًا. عند استلام document.completed في هذا الحدث، يقوم نظامك باسترداد حزمة المستندات المكتملة بما في ذلك ملف PDF الموقع وشهادة تجزئة التشفير ومثبت الطابع الزمني لـ blockchain ووثيقة سجل التدقيق الكاملة التي تعمل كدليل أساسي في النزاعات القانونية أو عمليات تدقيق الامتثال.

---

أحداث Webhook ومرجع الإشعارات في الوقت الفعلي

تعد خطافات الويب بمثابة العمود الفقري لبنيات التكامل الآلي. يدعم الإصدار الثاني من ABSign API تغطية شاملة للأحداث عبر دورة حياة المستند بأكملها، مما يمكّن أنظمتك من الاستجابة فورًا عند حدوث تغييرات في الحالة بدلاً من الاعتماد على فترات الاستقصاء التي تهدر حصة واجهة برمجة التطبيقات وتقدم زمن انتقال غير ضروري في سير العمل الخاص بك. يتضمن كل تسليم خطاف ويب حمولة JSON مع بيانات خاصة بالحدث ورأس توقيع HMAC-SHA256 الذي يجب أن تتحقق منه نقطة النهاية الخاصة بك قبل معالجة الإشعار لمنع الأحداث المخادعة من تشغيل إجراءات غير مصرح بها في أنظمتك.

نوع الحدث	حالة الزناد	حقول الحمولة الرئيسية	استجابة التكامل
document.created	تمت إضافة مستند جديد إلى النظام الأساسي	document_id، العنوان، create_at، create_by	التسجيل في نظام التتبع الداخلي
document.sent	تم إرسال الوثيقة إلى الموقعين	document_id، الموقعون[]، انتهاء الصلاحية، الموضوع	تحديث حالة لوحة معلومات سير العمل
signer.viewed	يقوم المُوقع بفتح رابط المستند	document_id،signer_id، view_at، ip_address	تسجيل المشاركة وتشغيل الموقت
signer.completed	يقدم الموقع توقيعه	document_id،signer_id،sign_at،sign_hash	التحقق من الانتهاء، وإخطار المصب
document.completed	تم الحصول على جميع التوقيعات المطلوبة	document_id، Complete_at، download_url، Audit_trail_url	تشغيل خطوة سير العمل التالية
document.expired	تم تجاوز الموعد النهائي للتوقيع	معرف المستند، منتهية الصلاحية، التوقيعات_في انتظار[]	بدء التجديد أو تنبيه فريق العمليات
document.declined	يرفض الموقّع التوقيع صراحةً	document_id،signer_id،رفض_at،السبب	عمليات التنبيه والتصعيد
document Voided	تم إلغاء الوثيقة من قبل المنشئ	document_id، voided_by، voided_at، السبب	إغلاق السجلات الداخلية والإخطار

حدود الأسعار والحصص وتحسين الأداء

يفرض ABSign API v2 حدودًا للمعدلات لضمان استقرار النظام الأساسي والتخصيص العادل للموارد عبر جميع مستهلكي واجهة برمجة التطبيقات. تقتصر حسابات الطبقة القياسية على 1000 طلب في الدقيقة لكل مفتاح واجهة برمجة التطبيقات، بينما تتلقى حسابات المؤسسات حدودًا مرتفعة يتم التفاوض عليها بناءً على متطلبات التكامل الموثقة وحجم المعاملات المتوقعة. يتم الإبلاغ عن حالة حد السعر في كل استجابة لواجهة برمجة التطبيقات (API) من خلال X-RateLimit-Remaining و X-RateLimit-Reset رؤوس الاستجابة، مما يمكّن التكامل الخاص بك من تنفيذ التقييد الاستباقي بدلاً من انتظار 429 استجابة لتحفيز سلوك التراجع. بالنسبة للعمليات الدفعية كبيرة الحجم التي تعالج آلاف المستندات، استخدم الملف المخصص /bulk نقاط النهاية التي تم تصميمها خصيصًا للإنتاجية المجمعة مع حصص أعلى في الدقيقة وخفض الحمل لكل مستند.

• شاشة X-RateLimit-Remaining رأس على كل استجابة وطلبات الإيقاف المؤقت عند الاقتراب من الصفر لتجنب تلقي 429 استجابات كثيرة جدًا للطلبات التي توقف المعالجة لنافذة إعادة التعيين.
• استخدم Retry-After قيمة الرأس لانتظار المدة المحددة قبل استئناف الطلبات بدلاً من تنفيذ فترات نوم عشوائية قد تكون قصيرة جدًا أو طويلة بشكل غير ضروري.
• لمعالجة المستندات بالجملة، تفضل POST /bulk نقاط النهاية على الفردية POST /documents المكالمات – توفر العمليات المجمعة ما يصل إلى 10 أضعاف تحسين الإنتاجية لسير العمل كبير الحجم.
• قم بتنفيذ التراجع الأسي مع عدم الاستقرار لجميع منطق إعادة المحاولة للتعامل مع الأخطاء العابرة من جانب الخادم دون إرباك النظام الأساسي أثناء فترات الاسترداد.
• استخدم Conditional Requests مع If-Modified-Since أو ETag الرؤوس عند استرداد حالة المستند لتجنب نقل البيانات غير الضرورية وتقليل زمن الوصول لعمليات التحقق من الحالة.

“نقوم بمعالجة أكثر من 50000 مستند شحن شهريًا من خلال ABSign API. إن نقطة نهاية العمليات المجمعة جنبًا إلى جنب مع التعامل المناسب مع خطاف الويب يعني أن سير عمل التوقيع بالكامل يعمل مع زمن وصول أقل من دقيقة – دون التدخل تمامًا بعد استدعاء واجهة برمجة التطبيقات الأولية.”

— مهندس المنصة الرئيسي، شبكة شحن البضائع العالمية

حزم SDK الرسمية والبدء السريع

تحتفظ ABSign بحزم SDK الرسمية للغات وأطر البرمجة الأكثر اعتماداً على نطاق واسع، حيث يوفر كل منها هياكل بيانات باللغة الأصلية، ومنطق إعادة المحاولة التلقائي مع التراجع الأسي للفشل العابر، وتعريفات النوع الشاملة لسلامة وقت الترجمة، وإعدادات عميل HTTP التي تم تكوينها مسبقًا والتي تتوافق مع متطلبات أمان واجهة برمجة التطبيقات. حزم SDK مفتوحة المصدر ومتاحة على GitHub، حيث نرحب بمساهمات المجتمع للغات الإضافية ويراجعها فريق ABSign الهندسي. يتم إصدار جميع حزم SDK الرسمية بالتزامن مع واجهة برمجة التطبيقات (API) لضمان بقاء توقيعات أسلوب SDK وسلوكها متسقين مع نقاط نهاية REST الأساسية.

• بايثون SDK: التثبيت عبر pip install abroadsign-api. دعم كامل للمزامنة/الانتظار لتطبيقات Python الحديثة، مع مساعدي التكامل التلقائي لأنظمة المهام الخلفية المستندة إلى Django وFastAPI وCelery. تم تضمين تلميحات النوع الكامل ودعم الإكمال التلقائي لـ IDE.
• Node.js / TypeScript SDK: التثبيت عبر npm install abroadsign-api. حزمة TypeScript مكتوبة بالكامل مع تعريفات كاملة للأنواع لجميع كائنات الطلب والاستجابة. يتضمن دعمًا أصليًا للبرامج الوسيطة لـ Express.js، ومسارات واجهة برمجة التطبيقات Next.js، والوظائف بدون خادم على AWS Lambda وVercel.
• جافا / ربيع التمهيد SDK: إحداثيات Maven متاحة على Maven Central. متوافق مع Spring Boot 2.x و3.x، مع دعم التكوين التلقائي ووثائق Javadoc الشاملة لفرق تطوير Java الخاصة بالمؤسسات.
• PHP SDK: حزمة متوافقة مع PSR ومتوافقة مع تطبيقات Laravel وSymfony وتطبيقات PHP 8.1+ المستقلة. يتضمن مزود خدمة Laravel لتكوين حقن التبعية السلس من خلال حاوية خدمة Laravel.
• .NET / C# SDK: توافق .NET Standard 2.0 الذي يدعم .NET Framework و.NET Core و.NET 5+ على أنظمة التشغيل Windows وLinux وmacOS. يتضمن تكامل حقن التبعية ASP.NET Core مع نمط HttpClientFactory.

---

الشروع في العمل: أول تكامل لواجهة برمجة التطبيقات (API).

ابدأ التكامل الخاص بك عن طريق الوصول إلى بيئة الحماية ABSign API، التي توفر مرآة واجهة برمجة التطبيقات (API) كاملة الوظائف مع بيانات اختبار معزولة لا تؤثر على خزائن مستندات الإنتاج أو يتم احتسابها مقابل حصص الإنتاج. قم بإنشاء بيانات اعتماد Sandbox API الخاصة بك من لوحة المعلومات ضمن الإعدادات، وابدأ في إجراء استدعاءات API على الفور لاستكشاف إنشاء المستندات وتكوين المُوقع وتسليم خطاف الويب في بيئة آمنة. يحاكي صندوق الحماية تلقائيًا مراسم التوقيع، حتى تتمكن من اختبار سير العمل الكامل من البداية إلى النهاية دون انتظار الموقّعين البشريين الحقيقيين لاتخاذ الإجراءات أثناء دورات التطوير وضمان الجودة. ملكنا بوابة وثائق API التفاعلية يوفر مستكشفًا مباشرًا لواجهة برمجة التطبيقات (API) حيث يمكنك تنفيذ الطلبات مباشرةً في المتصفح، وفحص حمولات الطلب والاستجابة، وإنشاء مقتطفات تعليمات برمجية جاهزة للاستخدام لأي نقطة نهاية بأي من لغات SDK المدعومة.

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

هل أنت مستعد لبناء التكامل الخاص بك؟ قم بزيارة بوابة وثائق API للحصول على مراجع نقاط النهاية الكاملة وتنزيلات SDK وأمثلة التعليمات البرمجية للعمل. للأسئلة حول متطلبات واجهة برمجة التطبيقات (API) الخاصة بالمؤسسة، أو بنية التكامل المخصصة، أو قياس الإنتاج، اتصل بفريق التكامل الفني لدينا لتحديد موعد جلسة مراجعة مجانية للهندسة المعمارية مع أحد كبار مهندسي واجهة برمجة التطبيقات (API) لدينا.