واجهة API سهل ساين (وصول مبكر): توقيع عربي أولاً داخل منتجك

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

الحالة، أكتوبر 2026: وصول مبكر. واجهة REST العامة الموصوفة أدناه غير متاحة للعموم بعد — وقد تتغيّر نقاط النهاية والأسماء والتسعير قبل الإطلاق. المتاح اليوم: الـ webhooks لأحداث التوقيع والعقود (يعدّها المالكون والمسؤولون من الإعدادات ← الـ Webhooks؛ وأسماء الأحداث الفعلية هي envelope.* وcontract.* وobligation.*، لا أسماء document.* المبيّنة أدناه). للانضمام إلى الوصول المبكر راسل sales@sahlsign.com.

REST + JSON

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

تصميم الواجهة المخطّط له (وصول مبكر)

يُؤكَّد كتابياً

موقع تخزين المستندات وسجلات التدقيق. إذا كان عملاؤك ملزمين بإبقاء البيانات داخل دولة محددة، أخبر سهل ساين قبل الاشتراك — نؤكد كتابياً أين تُخزَّن البيانات وما إذا كان بالإمكان تلبية هذا المتطلب

سياسة الخصوصية لسهل ساين

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.

تسميات حقول عربية أصلية، قوالب RTL، شهادات إكمال ثنائية اللغة
تُدرج كل شهادة إكمال الموقّعين والتسلسل الزمني للأحداث وبصمات المستند، مع رمز QR للتحقق منها عبر الإنترنت
تسعير بـ QAR / SAR / AED؛ نموذج لكل مستند بدون عدّ ظروف
الدعم والاستجابة للحوادث من مهندسين مقيمين في الخليج في منطقتك الزمنية
ملاحق معالجة بيانات متاحة تربط مع PDPPL، KSA PDPL، UAE PDPL — لا GDPR فقط

Alternative

API توقيع أجنبي

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

تخزين المستندات في مناطق الولايات المتحدة أو أوروبا؛ النقل عبر الحدود يحفّز أعمال DPA تحت كل PDPL خليجي
العربية كطبقة ترجمة؛ RTL ليس من الدرجة الأولى في استجابات API أو القوالب
تسعير بالدولار على نموذج حجم الظروف؛ تعرّض 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 ليس أي منصة توقيع لديها أكثر الميزات — هو أيها يمكن لفريق مشتريات عميلك المؤسسي الموافقة عليها بدون مفاوضة DPA لـ ٩٠ يوماً. إجابة مكتوبة وواضحة عن موقع البيانات، DPA المرتبطة بـ PDPL، القوالب العربية الأصلية، وشهادات الإكمال ثنائية اللغة ليست مميّزات تسويقية. هي بوابة المشتريات.

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

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

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