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

إنشاء جلسات التوقيع الإلكتروني وإدارتها وتتبعها لأسئلة العقود.

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

تستخدم جميع هياكل الطلبات والاستجابات أسماء حقول بتنسيق snake_case.

Endpoints

POST/api/v1/forms/:id/signing-sessionsGET/api/v1/forms/:id/signing-sessionsGET/api/v1/signing-sessions/:sessionIdPOST/api/v1/signing-sessions/:sessionId/voidPOST/api/v1/signing-sessions/:sessionId/resend/:slotNumberGET/api/v1/signing-sessions/:sessionId/documentsGET/api/v1/signing-sessions/:sessionId/documents/:docIdGET/api/v1/signing-sessions/:sessionId/auditGET/api/v1/s/:shortCodePOST/api/v1/s/:shortCode/verify-password

إنشاء جلسة

POST/api/v1/forms/:id/signing-sessions

ينشئ جلسة توقيع جديدة لنموذج يحتوي على سؤال عقد واحد أو أكثر. يُرجع الجلسة مع روابط توقيع فريدة لكل فتحة موقِّع.

معاملات المسار

idstring

معرّف النموذج

هيكل الطلب

signersarray

مصفوفة من إعدادات الموقِّعين، واحدة لكل فتحة. يمكن أن يتضمن كل كائن slot_number (عدد صحيح)، وfirst_name (نص)، وlast_name (نص)، وemail (نص). جميع الحقول اختيارية باستثناء slot_number.

signing_orderstring

"sequential" أو "any". القيمة الافتراضية هي ترتيب التوقيع الافتراضي للسؤال.

expiry_daysinteger

عدد الأيام قبل انتهاء صلاحية الجلسة. الافتراضي: 30.

passwordstring

كلمة مرور لحماية روابط التوقيع.

hide_other_signersboolean

إخفاء الحقول التي ملأها الموقِّعون الآخرون. الافتراضي: false.

require_email_verificationboolean

اشتراط التحقق من البريد الإلكتروني قبل التوقيع. الافتراضي: false.

copy_modestring

"ask" أو "always" أو "disabled". الافتراضي: "ask".

notify_emailsarray

مصفوفة من عناوين البريد الإلكتروني التي تتلقى إشعارات الحالة.

notify_eventsarray

مصفوفة من أنواع الأحداث: "each_signature"، "all_complete"، "decline"، "expiry".

send_signing_emailsboolean

إرسال رسائل طلب التوقيع إلى الموقِّعين الذين لديهم عناوين بريد إلكتروني. الافتراضي: false.

custom_email_bodystring

قالب بريد إلكتروني مخصص. يدعم المتغيرات: {slot_firstName}، {slot_lastName}، {slot_link}، {expiryDate}.

الاستجابة

json

{
  "id": "ses_abc123def456",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "status": "active",
  "signing_order": "sequential",
  "total_slots": 2,
  "total_signed": 0,
  "expires_at": "2026-04-25T00:00:00.000Z",
  "hide_other_signers": false,
  "copy_mode": "ask",
  "signer_links": [
    {
      "slot_number": 1,
      "slot_label": "Buyer",
      "short_code": "xK9f2",
      "signing_url": "https://nue.fm/s/xK9f2",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "status": "pending"
    },
    {
      "slot_number": 2,
      "slot_label": "Seller",
      "short_code": "mP3a7",
      "signing_url": "https://nue.fm/s/mP3a7",
      "first_name": null,
      "last_name": null,
      "email": null,
      "status": "pending"
    }
  ],
  "created_at": "2026-03-26T10:00:00.000Z"
}

أمثلة على الكود

bash

curl -X POST "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signers": [
      {"slot_number": 1, "first_name": "John", "last_name": "Smith", "email": "john@example.com"},
      {"slot_number": 2, "first_name": "Jane", "last_name": "Doe"}
    ],
    "signing_order": "sequential",
    "expiry_days": 30,
    "send_signing_emails": true
  }'

عرض الجلسات

GET/api/v1/forms/:id/signing-sessions

يُرجع جميع جلسات التوقيع لنموذج ما.

معاملات الاستعلام

statusstring

التصفية حسب الحالة: "active"، "fully_signed"، "declined"، "voided"، "expired".

pageinteger

رقم الصفحة (الافتراضي: 1)

per_pageinteger

عدد النتائج في الصفحة (الافتراضي: 20)

الاستجابة

json

{
  "sessions": [
    {
      "id": "ses_abc123def456",
      "status": "active",
      "total_slots": 2,
      "total_signed": 1,
      "signing_order": "sequential",
      "expires_at": "2026-04-25T00:00:00.000Z",
      "created_at": "2026-03-26T10:00:00.000Z"
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

أمثلة على الكود

bash

curl -X GET "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

الحصول على جلسة

GET/api/v1/signing-sessions/:sessionId

يُرجع جلسة توقيع واحدة بتفاصيلها الكاملة، بما في ذلك روابط الموقِّعين وحالاتهم.

الاستجابة

يُرجع كائن الجلسة نفسه الذي تُرجعه نقطة نهاية الإنشاء، مع الحالات والطوابع الزمنية المحدّثة لكل رابط موقِّع.

أمثلة على الكود

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

إبطال جلسة

POST/api/v1/signing-sessions/:sessionId/void

يُبطل جلسة توقيع نشطة. تُلغى صلاحية جميع روابط التوقيع المعلّقة. يُخطر الأطراف الذين وقّعوا وتُوسم ملفات PDF بعلامة مائية "VOIDED".

هيكل الطلب

reasonstring

سبب إبطال الجلسة.

الاستجابة

json

{
  "id": "ses_abc123def456",
  "status": "voided",
  "voided_at": "2026-03-27T15:30:00.000Z",
  "void_reason": "Terms changed, new agreement required"
}

أمثلة على الكود

bash

curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/void" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Terms changed, new agreement required"}'

إعادة إرسال طلب التوقيع

POST/api/v1/signing-sessions/:sessionId/resend/:slotNumber

يعيد إرسال بريد طلب التوقيع إلى موقِّع محدد. يجب أن يكون لدى الموقِّع عنوان بريد إلكتروني مُعدّ.

الاستجابة

json

{
  "success": true,
  "sent_to": "john@example.com",
  "slot_number": 1
}

أمثلة على الكود

bash

curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/resend/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

عرض المستندات الموقَّعة

GET/api/v1/signing-sessions/:sessionId/documents

يُرجع قائمة بالمستندات الموقَّعة لجلسة مكتملة. يقابل كل مستند سؤال عقد واحدًا في النموذج.

الاستجابة

json

{
  "documents": [
    {
      "id": "doc_xyz789",
      "question_id": "q_abc123",
      "question_title": "Service Agreement",
      "document_url": "https://storage.nueform.io/signed/doc_xyz789.pdf",
      "document_hash": "sha256:a1b2c3d4e5f6...",
      "generated_at": "2026-03-28T12:00:00.000Z"
    }
  ]
}

أمثلة على الكود

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

الحصول على مستند موقَّع

GET/api/v1/signing-sessions/:sessionId/documents/:docId

ينزّل مستندًا موقَّعًا محددًا كملف PDF.

الاستجابة

يُرجع ملف PDF مع Content-Type: application/pdf.

أمثلة على الكود

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123/documents/doc_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o signed-document.pdf

الحصول على مسار التدقيق

GET/api/v1/signing-sessions/:sessionId/audit

يُرجع مسار التدقيق الكامل لجلسة توقيع، بما في ذلك أحداث العرض والتوقيعات وحالات الرفض وأحداث النظام.

الاستجابة

json

{
  "entries": [
    {
      "id": "aud_001",
      "action": "session_created",
      "timestamp": "2026-03-26T10:00:00.000Z",
      "actor_email": "owner@company.com",
      "ip_address": "192.168.1.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_002",
      "action": "document_viewed",
      "slot_number": 1,
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:44:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_003",
      "action": "signed",
      "slot_number": 1,
      "actor_name": "John Smith",
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:45:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    }
  ]
}

أمثلة على الكود

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/audit" \
  -H "Authorization: Bearer YOUR_API_KEY"

تحليل الرمز المختصر

GET/api/v1/s/:shortCode

نقطة نهاية عامة (لا تتطلب مصادقة). تحلّل رمز توقيع مختصرًا إلى سياق النموذج والجلسة اللازم لعرض تجربة التوقيع.

الاستجابة

json

{
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "session_id": "ses_abc123def456",
  "slot_number": 1,
  "slot_label": "Buyer",
  "status": "pending",
  "requires_password": true,
  "requires_email_verification": false,
  "signing_order": "sequential",
  "is_turn": true
}

أمثلة على الكود

bash

curl -X GET "https://api.nueform.io/api/v1/s/xK9f2"

التحقق من كلمة المرور

POST/api/v1/s/:shortCode/verify-password

نقطة نهاية عامة. تتحقق من كلمة المرور لجلسة توقيع محمية بكلمة مرور. تُرجع رمز وصول مؤقتًا عند النجاح.

هيكل الطلب

passwordstring

كلمة مرور الجلسة.

الاستجابة

json

{
  "success": true,
  "access_token": "tmp_abc123..."
}

استجابة الخطأ (401)

json

{
  "error": "Invalid password"
}

أمثلة على الكود

bash

curl -X POST "https://api.nueform.io/api/v1/s/xK9f2/verify-password" \
  -H "Content-Type: application/json" \
  -d '{"password": "mySecretPass123"}'

آخر تحديث: 24 أغسطس 2026