طلبات التوقيع

طلب التوقيع يرسل قالبًا منشورًا إلى أطرافه الموقّعة ويتابعه حتى الاكتمال.

الإرسال للتوقيع

curl -X POST https://api.instaspace.ai/api/v1/esign/submissions \
  -H "Authorization: Bearer isk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "0b9f6f2e-…",
    "submitters": [
      { "role": "First Party", "name": "Dana Client", "email": "dana@client.com" },
      { "role": "Second Party", "name": "Sami Counsel", "email": "sami@yourfirm.com" }
    ],
    "values": { "client_name": "Client Co. LLC" },
    "message": "Please sign before Friday.",
    "sendEmail": true,
    "idempotencyKey": "crm-deal-4821"
  }'

• submitters — مستلم واحد بالضبط لكل دور يعرّفه القالب (حتى 10).
• values — اختياري. مفاتيحه هي مفاتيح المتغيّرات (قوالب flow) أو أسماء الحقول (قوالب coordinate)؛ راجع قراءة بنية القالب.
• message — مذكّرة اختيارية تُحمَل في بريد التوقيع، لذا فهي تنطبق فقط حين تكون sendEmail مفعّلة.
• sendEmail — قيمته الافتراضية true. وحين تكون false، لا يُراسَل الموقّعون بالبريد؛ فتشارك روابط التوقيع بنفسك.
• idempotencyKey — اختياري، ويجدر بك إرساله دائمًا. فإعادة إرسال طلب بمفتاح استُخدم من قبل تعيد طلب التوقيع الأصلي بدلًا من إرسال جولة بريد مكرّرة، ولا تُحتسَب من حصتك الشهرية مرة أخرى. وهو أيضًا وسيلتك لاستعادة استجابة ضاعت في الطريق: أعد النداء نفسه بدل أن تخمّن هل نفذ الأول أم لا.

والاستجابة هي طلب التوقيع:

{
  "id": "7c1d34…",
  "templateId": "0b9f6f2e-…",
  "templateName": "Mutual NDA",
  "status": "pending",
  "submitters": [
    {
      "role": "First Party",
      "name": "Dana Client",
      "email": "dana@client.com",
      "status": "awaiting",
      "completedAt": null
    }
  ],
  "hasSignedDocument": false,
  "createdAt": "2026-08-06T12:00:00.000Z",
  "completedAt": null
}

استطلاع الحالة

curl https://api.instaspace.ai/api/v1/esign/submissions/{id} \
  -H "Authorization: Bearer isk_live_..."

تنتقل حالة الطلب status عبر pending ← opened ← completed، أو تنتهي بـdeclined أو expired أو voided. ويحمل كل موقّع حالته الخاصة (awaiting، opened، completed، declined).

أوقف الاستطلاع عند أي من الحالات النهائية الأربع، لا عند completed وحدها. فبإمكان الموقّع أن يرفض من صفحة التوقيع، وبإمكان مساحة العمل أن تُبطل الطلب، وبإمكان الطلب أن تنتهي صلاحيته — والمستطلِع الذي ينتظر completed وحدها يظل يسأل إلى الأبد عن طلب انتهى فعلًا.

وتصبح hasSignedDocument مفعّلة في العملية نفسها التي تضبط status: completed، فلا توجد لحظة يُقرأ فيها الطلب مكتملًا بينما المستند لم يصبح جاهزًا بعد.

إرسال تذكير

curl -X POST https://api.instaspace.ai/api/v1/esign/submissions/{id}/remind \
  -H "Authorization: Bearer isk_live_..."

التوقيع تسلسلي، لذا يُذكِّر هذا النداء أيًّا كان الموقّع الذي حان دوره حاليًا — الهدف نفسه الذي يختاره إجراء "إعادة الإرسال" داخل التطبيق. ولا وسيلة لاختيار مستلم مختلف؛ ولا يأخذ النداء جسمًا.

{ "reminded": true, "recipient": { "email": "dana@client.com" } }

وحين يكون الطلب مكتملًا أو مرفوضًا أو منتهي الصلاحية أو مُبطَلًا أصلًا (أو حين يكون كل موقّع قد تصرّف فعلًا)، تظل الإجابة 200 بدل خطأ:

{ "reminded": false, "reason": "no_pending_signer" }

فيستطيع تكامل غير مراقَب أن يستدعيها دوريًا ويعامل "لا شيء لفعله" أمرًا اعتياديًا لا فشلًا يحتاج معالجة خاصة.

وتذكير الموقّع نفسه مرة أخرى خلال 15 دقيقة يعيد 429 مع ترويسة Retry-After بدل إرسال بريد ثانٍ:

{
  "statusCode": 429,
  "message": "A reminder was already sent to this signer recently",
  "code": "reminder_cooldown",
  "retryAfterSeconds": 612
}

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

curl "https://api.instaspace.ai/api/v1/esign/submissions?status=pending&limit=25" \
  -H "Authorization: Bearer isk_live_..."

الأحدث أولًا. ويمكن التصفية اختياريًا بـstatus وtemplateId، والتصفّح بـlimit (من 1 إلى 100، والافتراضي 25) وoffset:

{ "submissions": [], "total": 0, "limit": 25, "offset": 0 }

وهذه هي وسيلة التكامل غير المراقَب للمطابقة. فإن انتهت مهلة نداء الإرسال فلن تعرف هل نفذ أم لا — أعِده بالمفتاح idempotencyKey نفسه، فيعيد الطلب الأصلي بدل إرسال طلب ثانٍ، أو ابحث عنه هنا.

قراءة حصتك المتبقية

curl https://api.instaspace.ai/api/v1/esign/usage \
  -H "Authorization: Bearer isk_live_..."

{
  "signatureRequests": {
    "limit": 50,
    "used": 12,
    "remaining": 38,
    "periodStart": "2026-08-01T00:00:00.000Z"
  }
}

وتكون قيمة limit وremaining النص "unlimited" في خطة المؤسسات. وقراءة الاستهلاك لا تُحتسَب أبدًا — فاقرأها قبل أي دفعة بدل أن تكتشف السقف عبر إرسال فاشل.

تنزيل المستند الموقّع

بمجرّد أن تصبح hasSignedDocument مفعّلة — وقبل ذلك تعيد نقطة النهاية 404:

curl -L -o signed.pdf \
  https://api.instaspace.ai/api/v1/esign/submissions/{id}/document \
  -H "Authorization: Bearer isk_live_..."

تحصل على ملف PDF الموقّع وقد أُلحقت به شهادة التدقيق — هويات الموقّعين وعناوين IP والطوابع الزمنية وبصمات المستند — في ملف واحد. ويُسجَّل التنزيل في سجلّ تدقيق مساحة العمل بهوية مفتاح الواجهة لديك.