Waafir
هذه الصفحة ترجمة آلية في انتظار المراجعة البشرية. قد تحتوي على أخطاء.

مرجع 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_idstring (UUID)نعمالملف المراد توقيعه. يجب أن ينتمي إلى مؤسستك.
signatoriesarrayنعممن 1 إلى 50 من { "email": string, "name"?: string }. يُقبل أي بريد إلكتروني — لا يحتاج الموقّعون إلى أن يكونوا مستخدمين في Waafir؛ وتتلقى العناوين الخارجية رابط توقيع للضيوف.
transaction_idstring (UUID)لامُهمل ويُتجاهل. يُقبل حتى تستمر التكاملات القائمة في العمل؛ توقّف عن إرساله.
sendbooleanلاعند ضبطه على true، يُفتح المغلف للتوقيع فورًا، على خطوتين (انظر أدناه). يحتاج إلى رمز مفعّل فيه الإرسال إلى أشخاص خارج مؤسستك.
confirm_tokenstringلافقط مع send: true: الرمز المأخوذ من استدعاء المعاينة.
confirm_sendbooleanلامُهمل ويُتجاهل: أصبح send: true يأخذ الآن confirm_token.
signing_mode"parallel" | "sequential"لاترتيب التوقيع. "parallel" هو الافتراضي: يمكن للموقّعين التوقيع بأي ترتيب، ويرسل الإرسال بريدًا إلكترونيًا إليهم جميعًا دفعة واحدة. أما "sequential" فيرسل البريد إلى الأول فقط، ويُطلق كل موقّع بعد أن يوقّع جميع من سبقوه؛ ويُرفض التوقيع خارج الدور بالرمز CONFLICT. حذفه — أو كتابته خطأً signingMode — يعني "parallel".
field_layoutarrayلاتجاوز لتخطيط وضع الحقول؛ احذفه لاستخدام التخطيط الافتراضي.
observersarrayلاما يصل إلى 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 (كتابة)

وقّع خانة الموقّع المعلّقة الخاصة بك — أي الخانة التي يطابق بريدها الإلكتروني المستخدم الذي يملك الرمز. التوقيع لا يستهلك الحصة (فقد احتُسب المغلف بالفعل عند إرساله). يحتاج إلى رمز مفعّل فيه توقيع المستندات.

يتطلب التوقيع استدعاءين، حتى يعرض عليك مساعدك ما أنت على وشك توقيعه قبل توقيع أي شيء:

  1. المعاينة. استدعِ دون confirm_token. لا يُوقَّع شيء. تكون النتيجة dry_run: true مع المغلف، وdocuments بالترتيب، و document_hash واحد يغطيها جميعًا، وsigner، وfields التي قدّمتها، وبيان الموافقة، وconfirm_token وexpires_at الخاص به.
  2. التأكيد. بعد موافقة الشخص، استدعِ مرة أخرى بوسائط مطابقة مع ذلك confirm_token. هذا الاستدعاء هو الذي يوقّع.

يعمل confirm_token مرة واحدة، لهذا الرمز ولهذه الوسائط فقط، وتنتهي صلاحيته بعد خمس دقائق. إذا تغيّر المغلف أو مستنداته أو موقعك في ترتيب التوقيع أو حقولك في الأثناء، يُرفض التأكيد وتعيد المعاينة.

الحقلالنوعمطلوبالوصف
envelope_idstring (UUID)نعمالمغلف المراد توقيعه.
consent_affirmedbooleanنعميجب أن يكون حرفيًا true — تأكيد صريح لبيان الموافقة. لا توجد قيمة افتراضية؛ وحذفه، أو تمرير false، يُفشل الاستدعاء عند حدود البروتوكول.
fieldsobjectلاقيم التعبئة مفهرسة بتسمية الحقل؛ ويُملأ الاسم والتاريخ افتراضيًا عند حذفهما.
confirm_tokenstringلااحذفه للمعاينة. ومرّر الرمز الذي أعادته المعاينة للتوقيع.

يُرجع التأكيد { envelope }، أي المغلف بالشكل نفسه المقيّد بقائمة السماح الذي يُرجعه esign_create_envelope.

الأخطاء التي قد تراها: FORBIDDEN إذا لم تكن موقّعًا معلّقًا على المغلف، وأيضًا CONFLICT إذا لم يكن المغلف مفتوحًا للتوقيع — أو، في مغلف sequential، إذا لم يوقّع موقّع سابق بعد. هذه قيم error.code داخل الحمولة، وليست حالات HTTP — راجع الإعداد.

يضيف التأكيد على خطوتين حالات الرفض التالية، ولكلٍّ منها (code: …) في الرسالة:

error.codecode:ما يجب فعله
FORBIDDENGRANT_REQUIREDلا يستطيع الرمز التوقيع. أنشئ رمزًا جديدًا مع تفعيل توقيع المستندات.
INVALID_ARGUMENTCONFIRM_TOKEN_MALFORMEDاستدعِ مرة أخرى دون confirm_token للحصول على واحد.
CONFLICTCONFIRM_TOKEN_INVALIDانتهت صلاحية الرمز، أو استُخدم، أو يخص رمزًا آخر. أعد المعاينة.
CONFLICTCONFIRM_ARGS_MISMATCHتختلف الوسائط عن وسائط المعاينة. أعد المعاينة.
CONFLICTCONFIRM_STATE_CHANGEDتغيّر المغلف منذ المعاينة. أعد المعاينة واعرضها على الشخص.
CONFLICTDOCUMENT_NOT_PINNEDأُرسل المغلف قبل تثبيت المستندات. وقّعه في Waafir من بريد التوقيع الإلكتروني.
UNAVAILABLECONFIRM_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_idstring (UUID)نعمالمغلف المراد مراجعته.
signatoriesarrayنعمقائمة الموقّعين الكاملة التي ينبغي أن ينتهي إليها المغلف، بترتيب التوقيع: من 1 إلى 50 من { "email": string, "name"?: string }. وهي تحل محل القائمة الحالية.
signing_mode"parallel" | "sequential"لاتغيير ترتيب التوقيع. حذفه يعني الإبقاء على الوضع الحالي؛ ولا يُعاد ضبطه إلى "parallel".
observersarrayلاقائمة المراقبين (النسخ) الكاملة، حتى 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).