القوالب

تتعامل الواجهة مع القوالب المنشورة — تلك التي جهّزها فريقك ونشرها في قسم القوالب داخل التطبيق. أما المسودات والقوالب المؤرشفة فغير مرئية للواجهة.

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

سرد القوالب

curl "https://api.instaspace.ai/api/v1/esign/templates?search=nda" \
  -H "Authorization: Bearer isk_live_..."

المعامل search اختياري ويرشّح حسب الاسم.

{
  "templates": [
    {
      "id": "0b9f6f2e-…",
      "name": "Mutual NDA",
      "description": "Standard two-party NDA",
      "fillMode": "flow",
      "submitterRoles": ["First Party", "Second Party"],
      "fields": [{ "name": "Signature", "type": "signature", "required": true, "submitterRole": "First Party" }],
      "variables": [{ "key": "client_name", "label": "Client Name", "type": "text", "required": true }],
      "version": 3
    }
  ]
}

جلب قالب واحد

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

إذا كان القالب يعتمد المواضع الإحداثية، فتتضمن الاستجابة مستطيلات المواضع المتاحة لكل حقل ضمن fields[].areas:

{
  "id": "0b9f6f2e-8a7d-4c31-9e42-6d28f4ab7310",
  "name": "Mutual NDA",
  "description": "Standard two-party NDA",
  "fillMode": "coordinate",
  "submitterRoles": ["First Party", "Second Party"],
  "fields": [
    {
      "name": "First Party Signature",
      "type": "signature",
      "required": true,
      "submitterRole": "First Party",
      "areas": [{ "page": 3, "x": 0.1, "y": 0.78, "w": 0.34, "h": 0.08 }]
    },
    {
      "name": "Second Party Signature",
      "type": "signature",
      "required": true,
      "submitterRole": "Second Party",
      "areas": [{ "page": 3, "x": 0.56, "y": 0.78, "w": 0.34, "h": 0.08 }]
    }
  ],
  "variables": [],
  "version": 3
}

يصف كل عنصر في areas مستطيلًا واحدًا للحقل. يبدأ ترقيم page من 1. وتمثّل x وy الموضع الأفقي والرأسي المطبّع للمستطيل على الصفحة، بينما تمثّل w وh عرضه وارتفاعه المطبّعين. وتستخدم الإحداثيات الأربع النطاق من 0 إلى 1. تظهر areas للحقول ذات المواضع الإحداثية عندما تتوفر بيانات الموضع، وتُحذف الخاصية في غير ذلك.

وباستثناء مواضع الحقول هذه، التي لا تظهر إلا في استجابة جلب قالب واحد، يعيد الطلب الشكل نفسه الذي يعيده عنصر واحد في القائمة. وطلب قالب مسودة أو مؤرشف يعيد 404، تمامًا كمعرّف غير معروف.

قراءة بنية القالب

هناك عنصران في القالب يحدّدان ما ترسله في طلب التوقيع:

• submitterRoles — الأطراف الموقّعة. ويجب أن يسمّي طلب التوقيع مستلمًا واحدًا بالضبط لكل دور.
• fillMode يقرّر معنى values في الطلب:
  • flow — القالب مستند يحوي variables قابلة للملء (اسم العميل، والأتعاب، والتواريخ…). وتكون مفاتيح values لديك هي variables[].key، وتكتبها إنستاسبيس داخل نصّ المستند نفسه قبل الإرسال.
  • coordinate — القالب يحوي fields موضوعة بمواضع محدّدة. وتكون مفاتيح values لديك هي name الخاص بالحقل وتملأ تلك الحقول مسبقًا؛ وما تتركه منها يكمله الموقّع. ولا يمكن ملء حقول التوقيع مسبقًا أبدًا.