مرجع waafir-esign
يتيح الخادم waafir-esign خدمة التوقيع الإلكتروني الأصلية من Waafir لعميل ذكاء
اصطناعي متصل: أنشئ مغلفًا على ملف في مؤسستك، واجعل موقّعيه يوقّعون (أو يرفضون)،
وتتبّع الحالة، ونزّل ملف PDF الموقّع. التوقيعات من نوع AES (PAdES) وفق eIDAS،
ويُنتجها محرك التوقيع الخاص بـ Waafir؛ ويسجّل كل توقيع موافقة الموقّع (عنوان IP، ووكيل
المستخدم، والطابع الزمني) في سجل تدقيق يكشف أي عبث، ويُخزَّن ملف PDF الموقّع بوصفه
أحدث إصدار من الملف المصدر.
الاتصال: https://app.waafir.io/api/mcp/waafir، أو خادم المجال
https://app.waafir.io/api/mcp/waafir-esign — راجع
الإعداد. أسماء الأدوات متطابقة على كليهما. تتطلب أدوات القراءة نطاق read،
على اتصال أُنشئ بتسجيل الدخول أو على
رمز PAT؛ أما الإنشاء والإرسال
والرفض ومراجعة الموقّعين والإبطال فتتطلب نطاق write. ويتطلب التوقيع
write وإذنًا بتوقيع المستندات: يُوافَق عليه في شاشة الموافقة بالنسبة إلى الاتصال،
أو يُفعَّل عند إنشاء الرمز (راجع
السماح لرمز بتوقيع المستندات)؛
وبدونه تُخفى esign_sign من قائمة الأدوات، وتُرفض إذا استُدعيت. لا يمكن للاتصال أو الرمز المقصور على غرف بيانات محددة
العمل إلا مع المغلفات المنشأة على ملفات في تلك الغرف — وهو الحدّ نفسه الذي تفرضه أدوات
غرفة البيانات.
حصة شهرية من المغلفات
يُحتسب التوقيع الإلكتروني بالمغلف — فالمستند الواحد / مهمة التوقيع الواحدة تُحتسب مرة واحدة، مهما كان عدد موقّعيها. ويسحب خادم MCP هذا وواجهة التوقيع داخل التطبيق كلاهما من رصيد شهري مشترك واحد:
- يتطلب الوصول إضافة E-Signatures أو اشتراكًا نشطًا في
Waafir. وبدون أي منهما، يُرفض كل طلب إلى
waafir-esignعند المدخل بالخطأ HTTP 402، قبل تشغيل أي أداة — وهو رفض على الطبقة 1. يظهرADDON_NOT_PURCHASEDداخل نصmessageفي تلك الاستجابة؛ وهو ليس حقلًا منفصلًا قابلًا للقراءة آليًا، لذا تفرّع بناءً على الحالة 402، لا على رمز. أما علىwaafirفتُخفى أدواتesign_بدلًا من ذلك من قائمة الأدوات، ويُرفض استدعاء إحداها على الطبقة 2 بالرمزQUOTA_EXCEEDEDورسالة تسمّي الأداة، وتحمل أيضًاADDON_NOT_PURCHASED. - تتضمن خطتك حزمة شهرية من المغلفات: Starter 10، وPremium 50، وEnterprise 50 لكل مقعد نشط (شهر تقويمي).
- تضيف كل وحدة مشتراة من إضافة E-Signatures 100 مغلف شهريًا فوق حزمة خطتك؛ وتتراكم الوحدات على أي خطة.
- الحصة سقف صارم: عندما ترسل مغلفًا عند بلوغ الحد، يُرفض الإرسال برمز
النقل
QUOTA_EXCEEDED، مما يدفعك إلى شراء وحدات إضافية أو الترقية — ولا يُفرض أبدًا أي رسم تلقائي لكل مغلف. ويذكر نص الرسالة أيضًا رمزًا داخليًا هوESIGN_QUOTA_EXCEEDED؛ وهذا نص وصفي، لذا تفرّع بناءً علىerror.code، الذي قيمتهQUOTA_EXCEEDED. وعملية الإنشاء معsend: trueالتي تصطدم بالسقف تُبقي المسودة مع ذلك — أرسلها حين يتوفر لديك هامش بدلًا من إنشائها مجددًا.
تُستهلك الحصة عند إرسال المغلف (فتحه للتوقيع)، لا لكل توقيع — لذا فإن التوقيع
والرفض لا يستهلكان الحصة أبدًا. وكذلك القراءات والتنزيلات. تحقق من الهامش المتبقي في
أي وقت باستخدام esign_quota_status.
اتفاقية عدم الإفصاح الخاصة بك، موقّعة إلكترونيًا
عندما تحمّل مؤسستك اتفاقية عدم الإفصاح (NDA) الخاصة بها (المستثمرون ← NDA ← حمّل NDA خاصك، راجع قابلية التخصيص)، يوقّعها كل مستثمر في أداة التوقيع الخاصة بـ Waafir: يختار المستثمر المسجّل الدخول وقّع على NDA فيُفتح المستند في علامة تبويب جديدة؛ أما زائر رابط المشاركة فيتلقى رابط التوقيع بالبريد الإلكتروني على العنوان الذي أدخله. لا تُحتسب مغلفات اتفاقية عدم الإفصاح هذه من الحصة الشهرية، ولا يمكن إرسال قالب اتفاقية عدم الإفصاح نفسه كمغلف عادي.
الأدوات
مفاتيح الوسائط والنتائج على هذا الخادم بصيغة
snake_case— وهو الاصطلاح نفسه الذي تستخدمه جميع خوادم Waafir MCP الأخرى.file_id،envelope_id،signing_mode،field_layout،consent_affirmed،confirm_send،download_url،has_more.
تغيير جذري — كان
waafir-esignيقبل سابقًا وسائط بصيغةcamelCase. لم تعدfileIdوenvelopeIdوsigningModeوfieldLayoutوconsentAffirmedمقبولة؛ ولكل منها الآن تهجئة بصيغةsnake_case، مدرجة في الجداول أدناه. ولم يتغيرconfirm_send— فقد كان بصيغة snake_case أصلًا.حيث كانت التهجئة الملغاة وسيطًا مطلوبًا فإنها تُرفض، ولا تُقبل بصمت: فالاستدعاء الذي لا يزال يرسل
fileIdإلىesign_create_envelopeيفشل في التحقق من الوسائط مع تسميةfile_idبوصفه المفتاح المفقود. وحيث كانت اختيارية فإنها تُسقط بصمت، تمامًا كأي مفتاح آخر غير معروف — راجع نمطي الفشل أدناه. حدّث استدعاءاتك لتستخدم التهجئات الواردة في هذه الصفحة.
يفشل المفتاح المكتوب خطأً بإحدى طريقتين، وإحداهما صامتة. الوسيط غير المعروف يُسقط، ولا يُرفض أبدًا، لذا فإن ما يحدث بعد ذلك يعتمد فقط على ما إذا كان المفتاح الذي قصدته مطلوبًا:
-
مفتاح مطلوب ← يُرفض الاستدعاء. يكون الوسيط ببساطة مفقودًا. وهذه هي الحالة الواضحة والآمنة، وهي تشمل
esign_create_envelope(file_id)، وesign_get_envelope، وesign_sign(envelope_idوconsent_affirmed)، وesign_decline، وesign_void_envelope، وesign_revise_signers(envelope_idوsignatories) وesign_download_signed— بما في ذلك كل تهجئة camelCase ملغاة لتلك المفاتيح.لا يحمل هذا الرفض أي
error.code. يُتحقق من الوسائط مقابل المخطط المنشور للأداة قبل تشغيلها، لذا فإن المفتاح المطلوب المفقود — أو المفتاح ذا النوع الخاطئ — يعود بوصفه نتيجة خطأ يولّدها الخادم بنفسه: تُوسم الاستجابة بأنها خطأ ويسمّي نصها الوسيط المخالف، لكن لم تُشغَّل أي أداة، لذا لا شيء يملأ حقلerror.codeفي الطبقة 2. لا تتفرّع بناءً علىINVALID_ARGUMENTعند فشل في شكل الوسائط — بل اقرأ الرسالة. ولا يزالINVALID_ARGUMENTهو ما تحصل عليه عند رفض تثيره الأداة بعد بدء تشغيلها، مثلconfirm_tokenمشوّه. -
مفتاح اختياري ← ينجح الاستدعاء ويفعل شيئًا آخر. تحصل على
200ونتيجة سليمة الشكل تجيب عن سؤال مختلف:- مرشحات
esign_list_envelopesاختيارية، لذا يُتجاهلfileIdالشارد وتتلقى القائمة غير المصفّاة لكل مغلف يستطيع الرمز رؤيته — أي مجموعة أشمل تُعاد كما لو كانت الإجابة المصفّاة. - في
esign_create_envelope، يؤدي إسقاطsigningMode: "sequential"إلى إبقاء المغلف على وضعه الافتراضيparallel. ثم يؤدي إرساله إلى إرسال طلب توقيع ملزم قانونيًا بالبريد الإلكتروني إلى جميع الموقّعين دفعة واحدة، وهو بالضبط ما كان طلبsequentialيهدف إلى منعه. ويُسقطfieldLayoutبالطريقة نفسها.
- مرشحات
ولأن المفتاح الاختياري المُسقط لا يمكنه الإعلان عن نفسه، تحقق من أن النتيجة تعكس ما طلبته — فالمغلف المنشأ يُبلغ عن signing_mode الخاص به، ولا تكون
esign_list_envelopes مصفّاة إلا إذا كتبت اسم المرشح بشكل صحيح.
esign_create_envelope (كتابة)
أنشئ مغلفًا على ملف في مؤسستك، مع تسمية موقّعيه. يُقبل أي عنوان بريد إلكتروني — لا يحتاج الموقّع إلى حساب في Waafir. تتحدد طريقة الوصول إلى كل موقّع عند إرسال المغلف، بحسب ما إذا كان لذلك العنوان حساب في Waafir بالفعل: يوقّع صاحب الحساب داخل الجلسة (إشعار داخل التطبيق إضافةً إلى بريد إلكتروني يربط بشاشة التوقيع)، بينما يُرسل إلى الجميع غيره رابط توقيع للضيوف بالبريد الإلكتروني. والمعيار هو وجود الحساب، لا العضوية في مؤسستك، لذا فإن الموقّع الذي ينتمي إلى مؤسسة أخرى يوقّع أيضًا داخل الجلسة. ويتلقى كل موقّع معلّق واحدة فقط من الطريقتين — لا كلتاهما أبدًا، ولا أيٌّ منهما أبدًا.
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
file_id | string (UUID) | نعم | الملف المراد توقيعه. يجب أن ينتمي إلى مؤسستك. |
signatories | array | نعم | من 1 إلى 50 من { "email": string, "name"?: string }. يُقبل أي بريد إلكتروني — لا يحتاج الموقّعون إلى أن يكونوا مستخدمين في Waafir؛ وتتلقى العناوين الخارجية رابط توقيع للضيوف. |
transaction_id | string (UUID) | لا | مُهمل ويُتجاهل. يُقبل حتى تستمر التكاملات القائمة في العمل؛ توقّف عن إرساله. |
send | boolean | لا | عند ضبطه على true، يُفتح المغلف للتوقيع فورًا، على خطوتين (انظر أدناه). يحتاج إلى رمز مفعّل فيه الإرسال إلى أشخاص خارج مؤسستك. |
confirm_token | string | لا | فقط مع send: true: الرمز المأخوذ من استدعاء المعاينة. |
confirm_send | boolean | لا | مُهمل ويُتجاهل: أصبح send: true يأخذ الآن confirm_token. |
signing_mode | "parallel" | "sequential" | لا | ترتيب التوقيع. "parallel" هو الافتراضي: يمكن للموقّعين التوقيع بأي ترتيب، ويرسل الإرسال بريدًا إلكترونيًا إليهم جميعًا دفعة واحدة. أما "sequential" فيرسل البريد إلى الأول فقط، ويُطلق كل موقّع بعد أن يوقّع جميع من سبقوه؛ ويُرفض التوقيع خارج الدور بالرمز CONFLICT. حذفه — أو كتابته خطأً signingMode — يعني "parallel". |
field_layout | array | لا | تجاوز لتخطيط وضع الحقول؛ احذفه لاستخدام التخطيط الافتراضي. |
observers | array | لا | ما يصل إلى 20 مراقبًا (نسخة) من { "email": string, "name"?: string }. يتلقى المراقب بالبريد الإلكتروني نسخة من طلب التوقيع ومن كل تذكير، مع رابط للقراءة فقط لمتابعة حالته. لا يوقّع المراقبون أبدًا ولا تُرسل إليهم النسخة الموقّعة. |
يعمل send: true على خطوتين، لأن الإرسال يبعث رسائل بريد إلكتروني حقيقية لطلب توقيع
ملزم قانونيًا إلى كل عنوان مدرج لحظة نجاحه. الاستدعاء الأول لا ينشئ شيئًا ولا يرسل
شيئًا: بل يُرجع معاينة (الموقّعين، وعدد المراقبين، وحصتك) إضافةً إلى confirm_token.
استدعِ مرة أخرى بوسائط مطابقة مع الرمز للإنشاء والإرسال. يعمل الرمز مرة واحدة
وتنتهي صلاحيته بعد بضع دقائق. وبدون الإذن، يُرفض send: true
بالرمز FORBIDDEN (GRANT_REQUIRED)؛ أنشئ المغلف دون send
وأرسله من Waafir بدلًا من ذلك.
ويتبع esign_revise_signers الخطوتين نفسيهما، ويحتاج إلى الإذن نفسه، عندما
يكون من شأنه إرسال بريد إلكتروني إلى شخص ما: موقّع أو مراقب جديد على مغلف مُرسل.
يُرجع المغلف. حقوله هي بالضبط id وfile_id وstatus و
signing_mode وcreated_by وsigned_output_name و
signed_output_version_count وfield_layout وpacket_page_count و
expires_at — فالنتيجة قائمة سماح مُعيّنة يدويًا، لذا لا يُنقل أي شيء آخر.
والطوابع الزمنية سلاسل نصية بتنسيق ISO-8601.
يجب إرسال مسودة المغلف قبل أن يتمكن أي شخص من التوقيع. يستهلك الإرسال مغلفًا واحدًا من حصتك الشهرية — عند السقف، يُرجع send الخطأ
QUOTA_EXCEEDED ويبقى المغلف مسودة يمكنك إرسالها لاحقًا. ويمكن استدعاء
المغلف المُرسل خطأً باستخدام esign_void_envelope.
ملف لا يزال قيد الفحص. إذا كان الملف رفعًا جديدًا أو إصدارًا جديدًا لم تُنهِ
Waafir فحصه بعد، يُجيب الاستدعاء بـUNAVAILABLE مع
error.reason: "ACTIVATION_PENDING" والرسالة
This file is still being checked. Try again shortly. لا يُنشأ شيء؛ استدعِ
الأداة مجددًا بعد انتظار قصير.
esign_list_envelopes (قراءة)
اعرض مغلفات مؤسستك، الأحدث أولًا، مع موقّعي كل مغلف وحالاتهم. مرشح اختياري: file_id. (transaction_id مُهمل ويُتجاهل.)
ولأنها اختيارية، تُسقط تهجئة camelCase الملغاة بصمت
ويُرجع الاستدعاء القائمة غير المصفّاة بدلًا من خطأ؛ راجع ملاحظة المفاتيح
أعلاه.
مُرقّمة الصفحات — يجب أن يكون limit (اختياري، من 1 إلى 100، الافتراضي 25) وoffset (اختياري،
الافتراضي 0) أرقامًا؛ والقيمة من نوع آخر تفشل في التحقق من الوسائط
كأي عدم تطابق آخر في النوع. والرقم الواقع خارج النطاق
يُقصّ إلى الحد، ولا يُرفض — فيصبح limit: 10000 هو 100، ويصبح offset: -2
0. يُرجع:
{ envelopes: [...],
pagination: { limit, offset, count, has_more, next_offset, total },
filtered_by_pat_scope: boolean }استخدم has_more للتمييز بين نتيجة مقتطعة ونتيجة كاملة، وتابع
next_offset حتى يصبح null؛ ولا تستنتج وجود صفحات إضافية من
count === limit أبدًا. وtotal هو عدد المغلفات التي يستطيع هذا الرمز رؤيتها.
تكون قيمة filtered_by_pat_scope هي true عندما يكون الرمز مقصورًا على غرف بيانات
محددة وقيّدت قائمة السماح تلك النتيجة — تُطبَّق نافذة الصفحات بعد التصفية، لذا تكون
الصفحات دقيقة دائمًا. وهي قيمة منطقية عن عمد وليست عددًا للمغلفات المخفية: فالإبلاغ
عن عدد ما حُجب سيكشف وجود المغلفات التي مُنع الرمز من رؤيتها وحجمها.
esign_get_envelope (قراءة)
احصل على مغلف واحد مع موقّعيه وحالاتهم
(pending / signed / declined). المُدخل: envelope_id. إلى جانب حقول أداة
الإنشاء المذكورة أعلاه، يحمل المغلف created_at
وupdated_at وsignatories (لكلٍّ منهم
{ id, email, name, status, signed_at }).
esign_sign (كتابة)
وقّع خانة الموقّع المعلّقة الخاصة بك — أي الخانة التي يطابق بريدها الإلكتروني المستخدم الذي يملك الرمز. التوقيع لا يستهلك الحصة (فقد احتُسب المغلف بالفعل عند إرساله). يحتاج إلى رمز مفعّل فيه توقيع المستندات.
يتطلب التوقيع استدعاءين، حتى يعرض عليك مساعدك ما أنت على وشك توقيعه قبل توقيع أي شيء:
- المعاينة. استدعِ دون
confirm_token. لا يُوقَّع شيء. تكون النتيجةdry_run: trueمع المغلف، وdocumentsبالترتيب، وdocument_hashواحد يغطيها جميعًا، وsigner، وfieldsالتي قدّمتها، وبيان الموافقة، وconfirm_tokenوexpires_atالخاص به. - التأكيد. بعد موافقة الشخص، استدعِ مرة أخرى بوسائط مطابقة مع
ذلك
confirm_token. هذا الاستدعاء هو الذي يوقّع.
يعمل confirm_token مرة واحدة، لهذا الرمز ولهذه الوسائط فقط، وتنتهي صلاحيته بعد خمس
دقائق. إذا تغيّر المغلف أو مستنداته أو موقعك في ترتيب التوقيع أو حقولك في الأثناء،
يُرفض التأكيد وتعيد المعاينة.
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
envelope_id | string (UUID) | نعم | المغلف المراد توقيعه. |
consent_affirmed | boolean | نعم | يجب أن يكون حرفيًا true — تأكيد صريح لبيان الموافقة. لا توجد قيمة افتراضية؛ وحذفه، أو تمرير false، يُفشل الاستدعاء عند حدود البروتوكول. |
fields | object | لا | قيم التعبئة مفهرسة بتسمية الحقل؛ ويُملأ الاسم والتاريخ افتراضيًا عند حذفهما. |
confirm_token | string | لا | احذفه للمعاينة. ومرّر الرمز الذي أعادته المعاينة للتوقيع. |
يُرجع التأكيد { envelope }، أي المغلف بالشكل نفسه المقيّد بقائمة السماح الذي
يُرجعه esign_create_envelope.
الأخطاء التي قد تراها: FORBIDDEN إذا لم تكن موقّعًا معلّقًا على
المغلف، وأيضًا CONFLICT إذا لم يكن المغلف مفتوحًا للتوقيع — أو، في مغلف
sequential، إذا لم يوقّع موقّع سابق بعد. هذه قيم error.code داخل الحمولة،
وليست حالات HTTP — راجع
الإعداد.
يضيف التأكيد على خطوتين حالات الرفض التالية، ولكلٍّ منها (code: …) في
الرسالة:
error.code | code: | ما يجب فعله |
|---|---|---|
FORBIDDEN | GRANT_REQUIRED | لا يستطيع الرمز التوقيع. أنشئ رمزًا جديدًا مع تفعيل توقيع المستندات. |
INVALID_ARGUMENT | CONFIRM_TOKEN_MALFORMED | استدعِ مرة أخرى دون confirm_token للحصول على واحد. |
CONFLICT | CONFIRM_TOKEN_INVALID | انتهت صلاحية الرمز، أو استُخدم، أو يخص رمزًا آخر. أعد المعاينة. |
CONFLICT | CONFIRM_ARGS_MISMATCH | تختلف الوسائط عن وسائط المعاينة. أعد المعاينة. |
CONFLICT | CONFIRM_STATE_CHANGED | تغيّر المغلف منذ المعاينة. أعد المعاينة واعرضها على الشخص. |
CONFLICT | DOCUMENT_NOT_PINNED | أُرسل المغلف قبل تثبيت المستندات. وقّعه في Waafir من بريد التوقيع الإلكتروني. |
UNAVAILABLE | CONFIRM_UNAVAILABLE | التأكيد غير متاح لفترة وجيزة. حاول مرة أخرى بعد قليل. |
إذا كان تخطيط المغلف يتضمن حقولًا مطلوبة ولم يوفّرها fields، يُرفض الاستدعاء
بالرمز INVALID_ARGUMENT ورسالة تتضمن
(code: MISSING_REQUIRED_FIELDS). لا تسمّي الرسالة التسميات المفقودة؛ بينما تسمّيها
شاشة التوقيع داخل التطبيق. املأها واستدعِ مرة أخرى.
esign_decline (كتابة)
ارفض خانتك المعلّقة (نهائي — يصبح المغلف declined).
المُدخل: envelope_id. يُرجع { id, status: "declined" }. لا يستهلك أي حصة.
esign_void_envelope (كتابة)
استدعاء مغلف أُرسل خطأً. هذا هو العلاج عندما يُرسل طلب توقيع ما كان ينبغي إرساله: يتوقف المغلف عن قبول التوقيعات، وتُبطَل فورًا جميع روابط توقيع الضيوف القائمة، ولا يعود بإمكان الموقّعين المعلّقين اتخاذ أي إجراء.
المُدخل: envelope_id. يُرجع المغلف المُبطَل، بالشكل نفسه المقيّد بقائمة السماح الذي
يُرجعه esign_create_envelope.
- نهائي. لا يمكن إعادة إرسال المغلف المُبطَل — أنشئ مغلفًا جديدًا بدلًا من ذلك.
- تُحفظ التوقيعات المسجّلة بالفعل وسجل التدقيق الكامل؛ فالإبطال لا يمحو ما وُقّع بالفعل.
- لا يجوز إلا عندما يكون المغلف
draftأوsentأوpartially_signed. أي حالة أخرى تُرجعCONFLICT، والمغلف الذي انتهت صلاحيته يُبلغ عن ذلك بدلًا من حالة قديمة. - من يجوز له الإبطال: الشخص الذي أنشأ طلب التوقيع فقط، أو مالك أو مسؤول
المؤسسة. ويحصل أي شخص آخر على
FORBIDDEN؛ أما المستدعي الذي ليس طرفًا في المغلف على الإطلاق فيحصل علىNOT_FOUND، بحيث لا تؤكد الأداة أبدًا وجود مغلف لمن لا ينبغي أن يعلم به. - لا يستهلك الإبطال أي حصة — ولا يستردّ أي حصة. تُحتسب الحصة عند إرسال المغلف.
esign_revise_signers (كتابة، هدّامة)
صحّح من يُطلب منهم التوقيع، دون إبطال المغلف وإنفاق مغلف ثانٍ من حصتك: بريد إلكتروني مكتوب خطأً، أو طرف مقابل منسي، أو ترتيب توقيع خاطئ. يحتفظ المغلف بمعرّفه وسجل تدقيقه ووحدة حصته. لا يستهلك أي حصة.
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
envelope_id | string (UUID) | نعم | المغلف المراد مراجعته. |
signatories | array | نعم | قائمة الموقّعين الكاملة التي ينبغي أن ينتهي إليها المغلف، بترتيب التوقيع: من 1 إلى 50 من { "email": string, "name"?: string }. وهي تحل محل القائمة الحالية. |
signing_mode | "parallel" | "sequential" | لا | تغيير ترتيب التوقيع. حذفه يعني الإبقاء على الوضع الحالي؛ ولا يُعاد ضبطه إلى "parallel". |
observers | array | لا | قائمة المراقبين (النسخ) الكاملة، حتى 20. حذفها يعني الإبقاء على المراقبين الحاليين؛ والمراقب الذي تستبعده يُزال ويتوقف رابطه للقراءة فقط عن العمل. |
إنها هدّامة. يُزال الموقّع الذي تستبعده من signatories:
تُسحب دعوته ويتوقف رابط توقيعه عن العمل فورًا،
ولا يُبلَّغ بذلك. وتُحذف أي حقول وُضعت له. أما الموقّع الموجود بالفعل على المغلف
فيحتفظ برابطه ولا يُرسل إليه بريد إلكتروني مجددًا. ويُدعى الموقّع الجديد فورًا إذا
كان المغلف قد أُرسل بالفعل. والأداة موسومة بـ destructiveHint: true، لذا فإن العميل
الذي يطلب تأكيد الاستدعاءات الهدّامة سيسأل قبل تشغيلها.
- فقط حتى التوقيع الأول. بمجرد أن يوقّع أي شخص، تُجمَّد قائمة الموقّعين
ووضع التوقيع: يُرفض الاستدعاء بالرمز
CONFLICT(code: ESIGN_SIGNERS_FROZEN)، والعلاج هو الإبطال وإنشاء مغلف جديد. ويُرفض المغلف المنتهي الصلاحية بالرمزCONFLICTكذلك. - تغيير المراقبين فقط. مرّر قائمة الموقّعين دون تغيير (والوضع)
مع قائمة
observersجديدة. تجوز إزالة مراقب في أي وقت، حتى بعد التوقيع أو الاكتمال. ولا تجوز إضافة مراقب إلا ما دام المغلف مسودة أو قيد التوقيع. - من يجوز له مراجعة مغلف مُرسل: الشخص الذي أنشأ طلب التوقيع فقط، أو مالك أو
مسؤول المؤسسة؛ ويحصل أي شخص آخر على
FORBIDDEN. ويمكن لأي شخص يستطيع رؤية المسودة مراجعتها. - تحمل حالات الرفض الأخرى سببها في الرسالة: العنوان المكرر
(
ESIGN_DUPLICATE_SIGNATORY) أو القائمة الفارغة (ESIGN_EMPTY_ROSTER) يُرجعانINVALID_ARGUMENT؛ وإضافة موقّع أو مراقب جديد على مغلف مُرسل عندما لا تستطيع قراءة كل مستند يشمله المغلف تُرجعFORBIDDEN.
يُرجع المغلف بالشكل نفسه الذي يُرجعه
esign_get_envelope، إضافةً إلى ملخص revision لما
تغيّر (وobserver_revision عند تمرير المراقبين).
esign_list_my_pending_signatures (قراءة)
اعرض المغلفات التي تنتظر توقيعك أنت في هذه المؤسسة: كل مغلف مفتوح فيه خانة موقّع
معلّقة تطابق البريد الإلكتروني لمالك الرمز. وهذه أكثر عمليات القراءة فائدة قبل
esign_sign.
لا مُدخلات. يُرجع
{ envelopes: [{ id, file_id, document_name, status, created_at }] }.
مقصور على مؤسسة هذا الرمز، وإذا كان الرمز مقيّدًا، على قائمة السماح الخاصة به من غرف البيانات — لا تُعرض أبدًا التوقيعات المعلّقة في مؤسسات أخرى، حتى لو كنت موقّعًا فيها.
esign_download_signed (قراءة)
احصل على عنوان URL قصير الأجل وموقّع مسبقًا لتنزيل ملف PDF الموقّع. المُدخل:
envelope_id. يُرجع { download_url, expires_in_seconds }. يجب أن يتضمن المغلف
توقيعًا مسجّلًا واحدًا على الأقل؛ كما يتوفر ملف PDF الموقّع في المنتج بوصفه أحدث
إصدار من الملف المصدر. يحتاج إلى رمز مفعّل فيه قراءة محتوى المستند؛ وبدونه
يُرفض الاستدعاء بالرمز GRANT_REQUIRED.
esign_quota_status (قراءة)
لا مُدخلات. يُرجع { quota, used, remaining } للشهر التقويمي الحالي
— إجمالي حصة المغلفات (حزمة الخطة + الوحدات المشتراة)، والمغلفات المُرسلة،
والهامش المتبقي قبل السقف.
esign_remind (كتابة)
المُدخل envelope_id. يرسل بريدًا إلكترونيًا مجددًا إلى كل موقّع معلّق في مغلف قيد
التوقيع، ونسخة إلى كل مراقب، مرة واحدة في الساعة كحد أقصى لكل مغلف. يحتاج إلى الإرسال إلى أشخاص خارج مؤسستك، ويتم على خطوتين: الاستدعاء الأول لا يرسل شيئًا
ويُرجع من سيُرسل إليهم البريد، والمراقبين بأسمائهم، إضافةً إلى confirm_token؛ ثم
استدعِ مرة أخرى به. وإضافة مراقب في الأثناء تُفشل التأكيد.
لأعضاء فريق الصفقة فقط.
esign_resend_signatory (كتابة)
المُدخلات envelope_id وsignatory_id. يمسح عنوانًا ارتدّ بريده أو تم كتمه
ويرسل بريدًا إلكترونيًا إلى ذلك الموقّع مجددًا. الإذن نفسه والخطوتان نفسهما كما في esign_remind.
esign_send_draft (كتابة)
المُدخل envelope_id. يرسل مسودة محفوظة: يتلقى كل موقّع بالبريد الإلكتروني طلب توقيع
ملزمًا قانونيًا، ويتلقى كل مراقب نسخة، ويُستخدم مغلف واحد من
الحصة. الإذن نفسه والخطوتان نفسهما؛ وتسمّي المعاينة الموقّعين،
والمراقبين، وحصتك، والقائمة والمراقبون الذين عاينتهم هم
من يُرسل إليهم فعلًا. وتسرد النتيجة أي عنوان suppressed لم يُرسل إليه
البريد.
esign_preview (قراءة)
المُدخل envelope_id. يُرجع المغلف كما تعرضه لوحة التوقيع الخاصة به:
{ envelope_id, status, file_id, document_name, is_creator, signers, placed, fields, shows_signed_output, shows_live_source }. تكون قيمة document_name هي null عندما
لا يجوز لك قراءة المستند. لا يُرجع أي محتوى من المستند. لأعضاء فريق الصفقة
فقط.
esign_verify (قراءة)
المُدخل envelope_id. يُرجع ملخص الشهادة والسلامة الذي تعرضه صفحة التحقق في Waafir.
لأعضاء فريق الصفقة فقط.
الصلاحية القانونية
التوقيعات هي توقيعات إلكترونية متقدمة (PAdES) وفق eIDAS، وصالحة لاتفاقيات عدم الإفصاح والعقود بموجب ESIGN/UETA الأمريكيين وeIDAS الأوروبي. تُسجَّل موافقة الموقّع (IP، ووكيل المستخدم، والطابع الزمني) في سجل التدقيق الخاص بـ Waafir، القائم على الإلحاق فقط والمتسلسل بالتجزئة، وقت التوقيع. وتُسجَّل المغلفات المنشأة أو المرسلة عبر خادم MCP هذا في ذلك السجل بوصفها إجراءات بدأها رمز، بحيث يمكن دائمًا تمييز الإرسال الذي بدأه وكيل عن الإرسال الذي أجراه شخص في التطبيق. ولا تشمل هذه الإصدارة التوقيعات المؤهلة (QES).