واجهة Signx البرمجية

البدء السريع

1. 1

   أنشئ مفتاحاً

   من الإعدادات، ثم مفاتيح API، أنشئ مفتاحاً لكل نظام يتصل بـ Signx. يظهر المفتاح كاملاً مرة واحدة فقط، فاحفظه في أسرار ذلك النظام فوراً.

2. 2

   اعثر على القالب

   ترسل الواجهة قوالب أنشأتها مسبقاً في Signx. اعرضها لتحصل على معرّف القالب الذي تريده.

3. 3

   اقرأ أدواره وحقوله

   يخبرك القالب بالأدوار التي توقّعه وبالحقول التي تملؤها أنت. تحتاج إلى معرّفات الاثنين لإرساله.

4. 4

   أرسله

   أرسل معرّف القالب ومستلماً لكل دور وقيم حقولك. يرسل Signx إلى كل موقّع رابطه الخاص بالبريد، تماماً كما لو أرسلته من التطبيق.

5. 5

   تابعه حتى ملف PDF الموقّع

   تحقق من حالة المستند حتى يكتمل، ثم نزّل ملف PDF الموقّع ومعه سجل التدقيق.

المصادقة

يحمل كل طلب مفتاح API الخاص بمساحة العمل كرمز Bearer. تبدأ المفاتيح بـ sgx_.

العنوان الأساسي

https://api.signx.ae/api/v1/public

الترويسة

Authorization: Bearer sgx_…

اللغة

أرسل Accept-Language: ar أو en. تعود رسائل الأخطاء وأسماء القوالب بتلك اللغة.

حد الطلبات

60 طلباً في الدقيقة لكل مفتاح.

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

curl https://api.signx.ae/api/v1/public/templates \
  -H "Authorization: Bearer $SIGNX_API_KEY" \
  -H "Accept-Language: en"

عرض القوالب

GET/templates

قوالب مساحة العمل مرتبة بالاسم، 20 في الصفحة افتراضياً. مرّر page و limit (حتى 50) للتنقل بين الصفحات.

curl "https://api.signx.ae/api/v1/public/templates?page=1&limit=20" \
  -H "Authorization: Bearer $SIGNX_API_KEY"

{
  "data": [
    {
      "id": "3f6c1a2e-8b4d-4c9a-9e21-7d5b0a4f1c88",
      "name": "Employment contract",
      "signatoryCount": 2,
      "fieldCount": 14,
      "updatedAt": "2026-10-01T09:12:44.000Z"
    }
  ],
  "page": 1,
  "totalPages": 1,
  "totalItems": 1
}

قراءة قالب

GET/templates/{templateId}

أدوار الموقّعين وحقول قالب واحد.

معرّف كل موقّع هو ما تمرّره في recipients[].signatoryId. ومفتاح كل حقل هو ما تمرّره تحت answers، لكن فقط للحقول التي قيمة assignedTo فيها sender: أما البقية فيملؤها الموقّع المذكور في assignedTo.

curl https://api.signx.ae/api/v1/public/templates/3f6c1a2e-8b4d-4c9a-9e21-7d5b0a4f1c88 \
  -H "Authorization: Bearer $SIGNX_API_KEY"

{
  "id": "3f6c1a2e-8b4d-4c9a-9e21-7d5b0a4f1c88",
  "name": "Employment contract",
  "signatoryCount": 2,
  "fieldCount": 14,
  "updatedAt": "2026-10-01T09:12:44.000Z",
  "signatories": [
    {
      "id": "sig-employee",
      "roleLabel": { "ar": "الموظف", "en": "Employee" },
      "party": "external",
      "order": 1
    },
    {
      "id": "sig-hr",
      "roleLabel": { "ar": "مدير الموارد البشرية", "en": "HR manager" },
      "party": "internal",
      "order": 2
    }
  ],
  "fields": [
    {
      "key": "employee_name",
      "label": { "ar": "اسم الموظف", "en": "Employee name" },
      "type": "text",
      "required": true,
      "assignedTo": "sender"
    },
    {
      "key": "employee_signature",
      "label": { "ar": "توقيع الموظف", "en": "Employee signature" },
      "type": "signature",
      "required": true,
      "assignedTo": "sig-employee"
    }
  ]
}

إرسال مستند

POST/documents

ينشئ مستنداً من قالب ويرسله للتوقيع فوراً. الاستجابة هي المستند الجديد، بالشكل نفسه الذي تعيده متابعته.

كل استدعاء ناجح يُحتسب مستنداً واحداً عبر API. تشمل Business مئة مستند في كل شهر فوترة، ولا حد في Enterprise. الإرسال من التطبيق لا يُحتسب منها أبداً.

محتوى الطلب

templateIduuidمطلوب

القالب المراد إرساله، من عرض القوالب.

recipientsarrayمطلوب

مدخل واحد لكل دور توقيع في القالب.

recipients[].signatoryIdstringمطلوب

الدور الذي يشغله هذا المستلم: معرّف موقّع من قراءة القالب.

recipients[].namestring

لدور خارجي: اسم الموقّع.

recipients[].emailstring

لدور خارجي: العنوان الذي يُرسل إليه رابط التوقيع.

recipients[].phonestring

لدور خارجي: رقم هاتف اختياري بالصيغة الدولية.

recipients[].membershipIduuid

لدور داخلي: عضو مساحة العمل الذي يوقّع.

recipients[].anyHolderboolean

لدور داخلي: أرسله إلى المسمى الوظيفي للدور بدلاً من شخص واحد. يحق لأي شاغل حالي التوقيع، ويكفي توقيع أولهم.

recipients[].branchIduuid

مع anyHolder: لا يوقّع إلا الشاغلون المعيّنون في هذا الفرع.

recipients[].orderinteger

ترتيب هذا الدور في التوقيع، بدءاً من 1. اتركه لتحتفظ بترتيب القالب.

signingMode"parallel" | "sequential"

مع parallel يوقّع الجميع في الوقت نفسه، ومع sequential يُرسل إلى كل موقّع بدوره. القيمة الافتراضية parallel.

answersobject

قيمك للحقول المسندة إلى المرسل، بمفتاح كل حقل.

branchIdstring

الفرع، للقالب الذي يطلبه.

expiresInDaysinteger

عدد الأيام حتى تنتهي صلاحية الروابط غير الموقّعة، من 1 إلى 365.

messagestring

ملاحظة تُضاف إلى كل دعوة توقيع، حتى 2000 حرف.

curl -X POST https://api.signx.ae/api/v1/public/documents \
  -H "Authorization: Bearer $SIGNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "3f6c1a2e-8b4d-4c9a-9e21-7d5b0a4f1c88",
    "signingMode": "sequential",
    "recipients": [
      {
        "signatoryId": "sig-employee",
        "name": "Reem Al Hosani",
        "email": "reem@example.ae"
      },
      {
        "signatoryId": "sig-hr",
        "membershipId": "c3f1e9c8-6c2f-4a71-9d3e-2b8a0f7c1234"
      }
    ],
    "answers": {
      "employee_name": "Reem Al Hosani",
      "basic_salary": 14500
    },
    "expiresInDays": 14,
    "message": "Please sign before Thursday."
  }'

{
  "id": "9a2e4c71-5f3b-4d08-a6c2-1e8b7d9f0a35",
  "name": "Employment contract",
  "status": "sent",
  "sentAt": "2026-10-14T11:02:10.000Z",
  "expiresAt": "2026-10-28T11:02:10.000Z",
  "completedAt": null,
  "recipients": [
    {
      "signatoryId": "sig-employee",
      "name": "Reem Al Hosani",
      "email": "reem@example.ae",
      "state": "pending",
      "signedAt": null
    },
    {
      "signatoryId": "sig-hr",
      "name": "Salem Al Marri",
      "email": "salem@example.ae",
      "state": "waiting",
      "signedAt": null
    }
  ],
  "signedPdfUrl": null
}

متابعة مستند

GET/documents/{documentId}

أين وصل المستند: حالته، وحالة كل مستلم ووقت توقيعه. للاستجابة الشكل نفسه الذي يعيده الإرسال. استعلم عنه على فترات معقولة، كل بضع دقائق لا كل بضع ثوانٍ.

curl https://api.signx.ae/api/v1/public/documents/9a2e4c71-5f3b-4d08-a6c2-1e8b7d9f0a35 \
  -H "Authorization: Bearer $SIGNX_API_KEY"

تنزيل ملف PDF الموقّع

GET/documents/{documentId}/signed-pdf

يحوّلك (302) إلى رابط قصير الأجل لملف PDF الموقّع ومعه سجل التدقيق. اتبع التحويل واحفظ الملف فوراً، لأن الرابط تنتهي صلاحيته. يعيد 404 حتى يكتمل المستند.

curl -L -o signed.pdf \
  https://api.signx.ae/api/v1/public/documents/9a2e4c71-5f3b-4d08-a6c2-1e8b7d9f0a35/signed-pdf \
  -H "Authorization: Bearer $SIGNX_API_KEY"

الحالات

حالة المستند

awaiting_fill

بانتظار زميل ليملأه. لم يُبلَّغ أي موقّع بعد.

sent

أُرسل. لدى الموقّعين روابطهم ولم يوقّع أحد بعد.

partially_signed

وقّع بعضهم، أو وقّع الجميع وما زال ملف PDF الموقّع قيد الإنشاء.

completed

وقّع الجميع وملف PDF الموقّع جاهز للتنزيل.

voided

ألغته مساحة العمل. لم تعد الروابط تعمل.

expired

انتهت صلاحية الروابط قبل أن يوقّع الجميع.

حالة المستلم

waiting

لم يُرسل إليه بعد: لم يوقّع من يسبقه في الترتيب المتسلسل.

pending

الرابط لديه ولم يوقّع.

signed

وقّع.

declined

رفض التوقيع.

الأخطاء والحدود

الأخطاء بصيغة JSON وفيها رمز حالة HTTP ورسالة باللغة التي طلبتها. اعرض الرسالة، لكن قرّر ما تفعله بناءً على الحالة والرمز، لا على نص الرسالة أبداً.

400Bad Request

محتوى الطلب غير صالح: حقل ناقص، أو حقل غير معروف، أو قيمة من نوع خاطئ. تذكر الرسالة اسم الحقل.

401Unauthorized

المفتاح ناقص أو خاطئ أو مُبطَل، أو غادر العضو الذي أنشأه مساحة العمل.

402PLAN_API_LIMIT

استُهلكت مستندات API لشهر الفوترة هذا. لم يُرسل شيء. الإرسال من التطبيق ما زال يعمل.

402PLAN_FEATURE_UNAVAILABLE

لم تعد باقة مساحة العمل تشمل واجهة API.

403Forbidden

العضو الذي أنشأ المفتاح لا يملك صلاحية إرسال المستندات.

404Not Found

لا يوجد قالب أو مستند بهذا المعرّف في مساحة العمل، أو ملف PDF الموقّع لم يجهز بعد.

429Too Many Requests

أكثر من 60 طلباً في دقيقة من هذا المفتاح. انتظر دقيقة ثم أعد المحاولة.

{
  "statusCode": 402,
  "code": "PLAN_API_LIMIT",
  "plan": "business",
  "limit": 100,
  "used": 100,
  "upgradeTo": "enterprise",
  "message": "You've reached your 100 API documents/month limit. Upgrade to Enterprise for full API access."
}