واجهة API سهل ساين: ادمج توقيع المستندات المتوافق مع الخليج في منتجك

إذا كنت تبني منتج SaaS، تقنية مالية، تقنية موارد بشرية، أو تقنية قانونية لعملاء خليجيين، سيحتاج مستخدموك في النهاية إلى توقيع المستندات. لديك ثلاثة خيارات: ألصق API أجنبياً على حزمتك واشرح قصة إقامة البيانات لكل عميل مؤسسي، ابنِ بنية تحتية PKI بنفسك وأحرق ١٢–١٨ شهراً على تشفير حلّه شخص آخر بالفعل، أو استدعِ API توقيع خليجي أصلي واشحن الميزة في فترة بعد الظهر. هذا هو الموجز التقني للخيار الثالث.

REST + JSON

API HTTP/JSON قياسي. مصادقة Bearer token. لا قفل SDK — كل نقطة نهاية على بعد curl واحدة

وثائق سهل ساين API، v1

مستضاف في الخليج

نقاط نهاية API، تخزين المستندات، وتسليم Webhooks كلها تعمل من بنية تحتية داخل المنطقة. لا نقل لـ PII العميل عبر الحدود افتراضياً

بنية سهل ساين التحتية، ٢٠٢٦

HMAC-SHA256

نظام توقيع Webhook مع طابع زمني + nonce. هجمات الإعادة مرفوضة من قِبل المتحقّق؛ نمط قياسي

نموذج أمان Webhook

دورة حياة التوقيع، مرتبطة بنقاط النهاية

كل معاملة توقيع تتبع نفس الشكل: إنشاء المستند، تكوين الموقّعين، إرسال للتوقيع، الحصول على تحديثات Webhook، جلب النتيجة المختومة. تكشف API بدائياً نظيفاً لكل خطوة.

Step ١

POST /v1/documents

ارفع PDF المصدر (multipart أو base64)، احصل على معرّف مستند. اختيارياً ألحق بيانات وصفية للارتباط الخاص بك.

Step ٢

POST /v1/documents/:id/signers

أضف موقّعين بالاسم، البريد الإلكتروني، الدور، وترتيب التوقيع. التوجيه المتسلسل أو المتوازي مكوَّن هنا.

Step ٣

POST /v1/documents/:id/send

حفّز تدفق التوقيع. الموقّعون يستلمون بريداً إلكترونياً بعلامة تجارية برابط فريد؛ التحقق بـ OTP يحكم حدث التوقيع نفسه.

Step ٤

Webhook يُفعَّل + GET /v1/documents/:id

اشترك في document.completed؛ اسحب PDF المختوم النهائي + شهادة الإكمال عبر نقطة نهاية get-document.

سطح نقاط النهاية

API v1 الكامل صغير بحسب التصميم — ثماني نقاط نهاية تغطي ٩٥٪ من احتياجات التكامل. القوالب و Webhooks تُطبَّق فوقها لأنماط أعلى إنتاجاً.

نقاط نهاية REST الأساسية

POST /v1/documents — رفع وإنشاء
PDF المصدر يدخل، معرّف المستند يخرج. يقبل رفع multipart حتى ٢٥ ميجابايت أو base64 في جسم JSON للملفات الأصغر. يُعيد المستند بحالة = draft.
GET /v1/documents — قائمة مُرقَّمة
اسرد مستنداتك بترقيم صفحات مبني على المؤشر. رشّح بالحالة، بريد الموقّع، نطاق التاريخ، أو علامة البيانات الوصفية.
GET /v1/documents/:id — جلب التفاصيل
يُعيد المستند بحالة التوقيع الحالية، سجل التدقيق، قائمة الموقّعين، و(عند الإكمال) رابط تنزيل PDF المختوم.
DELETE /v1/documents/:id — إبطال أو إلغاء
يُبطل مستنداً قيد التقدّم، يُخطر جميع الموقّعين. مكافئ — المكالمات المتكررة تُعيد نفس الحالة النهائية.
POST /v1/documents/:id/send — حفّز التوقيع
يبدأ تدفق التوقيع. يُعيد 202 Accepted مع روابط الموقّع. ترويسة Idempotency-Key مدعومة لمنع الإرسال المزدوج.
POST /v1/templates/:id/send — لقطة واحدة مبنية على قالب
أنشئ مستنداً من قالب مُكوَّن مسبقاً وأرسله للتوقيع في مكالمة واحدة. الأفضل للتدفقات القابلة للتكرار (التعيين، العقود المتكررة).
POST /v1/webhooks — تسجيل رابط Callback
اشترك في أحداث المستند. حمولات موقَّعة بـ HMAC-SHA256، تُرسَل مع إعادة المحاولة على تراجع (٢ث، ١٠ث، ٣٠ث، ٢د، ١٠د).
GET /v1/verify/:id — تحقق عام
افتح صفحة التحقق لمستند مكتمل. يمكن لأي شخص الوصول إليها؛ لا مصادقة مطلوبة. تشغّل رابط التحقق على شهادة الإكمال.

أحداث Webhook

Webhooks هو النمط الصحيح لتكاملات الإنتاج — استطلاع نقطة نهاية حالة المستند يهدر حصة API ويتأخر عن الوقت الحقيقي. يصدر سهل ساين ستة أحداث تغطّي دورة حياة التوقيع.

سطح أحداث Webhook. كل الأحداث تصل كطلبات POST موقَّعة بـ HMAC-SHA256 إلى نقطة النهاية المسجَّلة لديك. تحقق من التوقيع مقابل SAHLSIGN_WEBHOOK_SECRET في لوحة التحكم لديك.

Jurisdiction	Law	Cross-border transfer rule	Intensity
document.sent	بدأ تدفق التوقيع	يُفعَّل فوراً بعد اكتمال POST /send. الحمولة تتضمن روابط الموقّع (لا تكشفها من جهة العميل).	Moderate
document.viewed	موقّع فتح الرابط	يُفعَّل أول مرة يتبع فيها كل موقّع رابط توقيعه. مفيد لمنطق التذكير.	Moderate
document.signed	موقّع واحد اكتمل	يُفعَّل لكل موقّع في مستند متعدد الأطراف. يتضمن بريد الموقّع، IP، وكيل المستخدم، وطابع وقت التوقيع.	Restricted
document.completed	جميع الموقّعين انتهوا؛ PDF مختوم	حدث 'اكتمل التكامل'. PDF المختوم + روابط تنزيل شهادة الإكمال مُضمَّنة.	Strict
document.declined	موقّع رفض	يُفعَّل عندما يضغط أي موقّع على رفض. المستند ينتقل إلى حالة مُبطَل؛ التكامل يجب أن يتفاعل وفقاً لذلك.	Restricted
document.expired	نافذة التوقيع انقضت	للمستندات تاريخ انتهاء قابل للتهيئة (افتراضي ٣٠ يوماً). خطاف تنظيف لخلفيتك.	Moderate

تكامل توقيع إنتاجي مع سهل ساين عادةً ثلاثة أشياء من جانبك: مكالمة "أرسل للتوقيع" من تدفق إنشاء العقد في تطبيقك، معالج Webhook لـ document.completed، ومرجع مخزَّن يربط معرّف مستند سهل ساين بكائن مجالك. هذا هو البصمة كاملة.

— شكل التكامل الذي يستحق النسخ

لماذا تهمّ واجهة API خليجية أصلية لعملائك

معظم فِرق SaaS يعاملون إقامة البيانات كمربع مشتريات. للعملاء المؤسسيين الخليجيين هو متطلب امتثال صعب — والإجابة تؤثر على ما إذا كنت تغلق الصفقة.

Recommended

API سهل ساين

مستضاف في الخليج، واعٍ بالعربية، مسعّر بعملة إقليمية، مصمَّم مقابل أُطر PDPL.

تخزين المستندات، سجلات التدقيق، وتسليم Webhook كلها داخل المنطقة؛ لا نقل لـ PII العميل عبر الحدود افتراضياً
تسميات حقول عربية أصلية، قوالب RTL، شهادات إكمال ثنائية اللغة
الشهادة تستشهد بالقانون المحلي ذي الصلة (قطر ECTL المادة ٢٨، KSA ETL المادة ١٤، UAE FDL 46 المادة ٨)
تسعير بـ QAR / SAR / AED؛ نموذج لكل مستند بدون عدّ ظروف
الدعم والاستجابة للحوادث من مهندسين مقيمين في الخليج في منطقتك الزمنية
ملاحق معالجة بيانات متاحة تربط مع PDPPL، KSA PDPL، UAE PDPL — لا GDPR فقط

Alternative

API توقيع أجنبي

SDK ناضجة، علامة تجارية عالمية، لكن قصة النشر أصعب للمؤسسات الخليجية.

تخزين المستندات في مناطق الولايات المتحدة أو أوروبا؛ النقل عبر الحدود يحفّز أعمال DPA تحت كل PDPL خليجي
العربية كطبقة ترجمة؛ RTL ليس من الدرجة الأولى في استجابات API أو القوالب
الشهادة تستشهد بـ ESIGN / UETA / eIDAS؛ لا مرجع قانوني خليجي أصلي
تسعير بالدولار على نموذج حجم الظروف؛ تعرّض FX على كل فاتورة
الدعم في ساعات العمل الأمريكية/الأوروبية؛ تذاكر التكامل غالباً تمتد عبر دورة نوم
DPA مكتوب مقابل GDPR؛ الربط مع PDPL مشكلة العميل

المصادقة، حدود المعدل، والأرغوناوميات التشغيلية

أسئلة البنية التحتية المملة تميل إلى الظهور متأخراً وتسبّب أسى تكامل إذا لم تُصمَّم لها. هذا ما تحصل عليه في اليوم الأول.

المواصفات التشغيلية

المصادقة: Bearer tokens، لكل مستأجر + لكل بيئة
أنشئ مفاتيح API من لوحة التحكم؛ مجموعة واحدة لكل بيئة (staging / production). يمكن تحديد نطاق المفاتيح لنقاط نهاية محددة إذا كان تكاملك يحتاج فقط مجموعة فرعية.
حدود المعدل: ٣٠٠ طلب/دقيقة للاحترافية، ١٬٠٠٠ طلب/دقيقة للمؤسسات
صديق للانفجار؛ التقييد الناعم يُعيد 429 مع Retry-After. تسليم Webhook له حصة منفصلة عن إدخال API.
دعم Idempotency-Key على جميع نقاط النهاية المُعدِّلة
أعد محاولة إخفاقات الشبكة بأمان بدون إنشاء مستندات مكرّرة. نمط قياسي: ولّد UUID لكل عملية منطقية، ضمّنه كترويسة.
إعادة محاولة Webhook بتراجع أُسّي
التسليمات الفاشلة تُعاد المحاولة عند ٢ث، ١٠ث، ٣٠ث، ٢د، ١٠د، ثم تستسلم وتُظهر الفشل في لوحة التحكم. تحقّق من توقيع HMAC قبل المعالجة.
بيئة Sandbox مع تدفقات موقّع اختبارية
مضيف API منفصل للـ staging؛ لا تكلفة ظرف، PDF المختوم مُعلَّم TEST. شغّل مجموعة اختبار التكامل الكاملة بدون استخدام قابل للفوترة.
عقد v1 مستقر
API مُصدَّر في مسار URL. التغييرات الكاسرة تحصل على إصدار رئيسي جديد مع إشعار إيقاف. نقاط نهاية v1 ستكون مدعومة لـ ٢٤+ شهراً بعد أي إصدار v2.

رياضيات التسعير لعبء عمل ٥٠٠ مستند/شهر

فِرق الهندسة تقلّل وزن التكلفة على بنية التوقيع التحتية لأنها لا تعضّ حتى ينمو قاعدة العملاء. لتكامل متوسط الحجم (~٥٠٠ مستند/شهر)، الفجوة بين تسعير API الإقليمي والأجنبي ذات معنى.

التكلفة لكل مستند API عند حجم ٥٠٠ مستند/شهر

تسعير إرشادي لشريحة الحجم حيث تجلس معظم تكاملات SaaS الخليجية المتنامية. تسعير API الأجنبي محوّل إلى معدلات لكل ظرف مكافئة بالدولار.

سهل ساين

API أجنبي A

API أجنبي B

مستويات التسعير العامة، سهل ساين وواجهات API التوقيع الإلكتروني الأجنبية الرئيسية، ٢٠٢٦. المعدلات الدقيقة تعتمد على شروط العقد والالتزامات بالحجم.

عند ٥٠٠ مستند/شهر، الفرق بين ١ دولار/مستند و ٥ دولار/مستند هو ٢٤٬٠٠٠ دولار/سنة. عند ٢٬٠٠٠ مستند/شهر، هو ٩٦٬٠٠٠ دولار/سنة. عند الأحجام المؤسسية، الفجوة تدفع لمهندس.

البناء مقابل الشراء، محسوم بحسم

خيار "نبنيه بأنفسنا" هو أطول مسار. ختم PAdES-B-T، طابع زمني RFC 3161، إدارة الشهادات، بنية OTP التحتية، سلامة سلسلة التدقيق — كل واحد منها تحدٍّ هندسي صغير يتراكم. اثنا عشر شهراً بعد، لديك نسخة أسوأ مما يشحنه سهل ساين بالفعل، بالإضافة إلى عبء أمن وامتثال مستمر.

< يوم واحد

وقت التكامل النموذجي من إنشاء مفتاح API إلى أول مستند موقَّع مؤكَّد بـ Webhook. قرار منصة التوقيع كان مشروعاً يستغرق ربعاً. API الصحيح يحوّله إلى فترة بعد الظهر.

معايير تكامل عملاء سهل ساين، ٢٠٢٥

الخلاصة

لفريق منتج خليجي، اختيار API ليس أي منصة توقيع لديها أكثر الميزات — هو أيها يمكن لفريق مشتريات عميلك المؤسسي الموافقة عليها بدون مفاوضة DPA لـ ٩٠ يوماً. إقامة البيانات الخليجية، DPA المرتبطة بـ PDPL، القوالب العربية الأصلية، والاستشهادات بالقانون المحلي على الشهادة ليست مميّزات تسويقية. هي بوابة المشتريات.

ابنِ على API إقليمي والبوابة تنفتح افتراضياً. ابنِ على API أجنبي وتقضي العامَين القادمَين في شرح لماذا تعيش بيانات عقد عميلك في فرانكفورت أو فرجينيا.

قراءات ذات صلة

لماذا تهمّ الاستضافة الإقليمية للمستندات الحساسة — وعد الاستضافة الذي تشحن عليه واجهة API ولماذا يصمد أمام المشتريات.
كيف تتحقّق من PDF موقَّع — ما سيُشغّله مستهلكو واجهتك — وأطرافهم المقابلة — على ملفات PDF التي ينتجها تكاملك.
مستقبل الهوية والتوقيع في الشرق الأوسط — اتجاه خارطة طريق الواجهة مع تحوّل نفاذ وهوية الإمارات وQDI إلى هويات توقيع من الطبقة الأولى.