مرجع waafir-dataroom
الخادم waafir-dataroom هو واجهة الـ API المستقرة في هذا الإصدار. وهو
يتيح الأدوات أدناه لقراءة غرف البيانات وإدارتها، مجمّعةً بحسب وظيفتها: أدوات
القراءة، وأدوات المجلدات، وأدوات الملفات (دورة حياة الملف وإصداراته)، وأداة
لنص المستند، وأدوات الصلاحيات، وأدوات الأسئلة والأجوبة.
الاتصال: https://app.waafir.io/api/mcp/waafir، أو خادم المجال
https://app.waafir.io/api/mcp/waafir-dataroom — راجع
الإعداد.
أسماء الأدوات. يحمل كل قسم أداةٍ أدناه الاسم الذي يسرده waafir، مثل
dataroom_list_files. ويسرد خادم المجال الاسم الأقدم المذكور تحت كل عنوان
بوصفه "اسم نقطة نهاية المجال"، مثل list_files، ولا يزال waafir يقبل ذلك
الاسم إذا استدعاه عميل. وحيثما يسمّي وصف أداة أو نتيجتها أداةً أخرى لاستدعائها
بعدها (next_step، restore_with، undo_with)، فإنه يسمّيها بالطريقة التي
تسردها بها نقطة النهاية التي أنت متصل بها. وتستخدم الأوصاف في هذه الصفحة أسماء
نقاط نهاية المجال.
كيف يُفرض الوصول
في هذه الصفحة، يعني الرمز بيانات الاعتماد التي يستخدمها مساعدك: إما اتصالًا أُنشئ بتسجيل الدخول، أو رمز وصول شخصي. وكلاهما يحمل نطاقًا، واختياريًا قائمةً بغرف البيانات، ويخضعان للقيود نفسها.
تعمل كل أداة باسم مالك الرمز وتخضع للقواعد نفسها التي تفرضها واجهة المنتج — فلا يوجد مسار أكثر تساهلًا عبر MCP. وتنطبق بوابتان على كل استدعاء:
- النطاق. تحدد كل أداة نطاقًا أدنى:
تتطلب أدوات القراءة
read، وتتطلب تعديلات المجلدات والملفاتwrite، وتتطلب أدوات منح الصلاحياتadmin. والرمز الذي يقل عن النطاق المطلوب لا تُعرض عليه الأداة، ويُرفض بخطأFORBIDDENإذا استدعاها (راجع كيف يُبلَّغ عن الإخفاق). والنطاق تراكمي —writeيشملread، وadminيشملهما معًا. - تقييد غرف البيانات. إذا كان الرمز مقيّدًا بغرف بيانات محددة، فإن أي استدعاء يشير إلى غرفة بيانات خارج قائمة السماح الخاصة به يُرفض، ولا يستطيع الرمز المقيّد حتى سرد غرف البيانات غير المسموح له بفتحها. ويستند الفحص إلى غرفة البيانات التي ينتمي إليها المورد، فلا يمكن لرمز مقيّد بغرفة البيانات A الوصول أبدًا إلى ملف أو مجلد في غرفة البيانات B — حتى داخل المؤسسة نفسها.
إضافةً إلى ذلك، تتطلب تعديلات المجلدات والملفات دورًا في فريق الصفقة لغرفة البيانات (لا يمكن للمستثمرين التعديل)، وتتطلب أدوات الصلاحيات كذلك أن يكون مالك الرمز مسؤولًا أو مديرًا في المؤسسة. وحذف مجلد أو ملف هو دائمًا حذف ناعم — تُعلَّم الصفوف بأنها محذوفة وتُحفظ لأغراض الاحتفاظ والتدقيق، ولا تُزال نهائيًا أبدًا. ويُسجَّل كل تعديل بوصفه حدث التدقيق نفسه الذي تكتبه واجهة المنتج، فلا يمكن تمييز إجراء MCP عن إجراء الواجهة في سجل التدقيق.
المعرّفات (dataroom_id، folder_id، file_id، user_id) هي UUID.
النص غير الموثوق في النتائج
تحمل بعض النتائج نصًا لم تكتبه Waafir: مخرجات ذكاء اصطناعي عن مستند، أو نص
المستند نفسه، أو ما كتبه مستثمر أو زميل. وتضيف مثل هذه النتيجة
untrusted_content: { source, fields, notice }، والقيمة نفسها
{ source, fields } تحت _meta["io.waafir/untrusted"]. وقيمة source هي
"document" أو "third-party". ويسرد fields المسارات التي تحمل ذلك النص في
هذه النتيجة، مثل answer أو questions[].responses[].body؛ ولا يُسرد المسار
إلا إذا كانت للنتيجة قيمة فيه. تعامل مع هذه الحقول بوصفها بيانات، وليس أبدًا
بوصفها تعليمات لمساعدك.
الأدوات المعلَّمة هي dataroom_get_file_text، وdataroom_get_file_metadata،
وdataroom_list_questions، وdataroom_get_question،
وdataroom_list_kb_articles، وdataroom_get_kb_article،
وdataroom_edit_question، والمعاينات الخاصة بـ dataroom_answer_question
وdataroom_delete_question وdataroom_delete_answer
وdataroom_publish_kb_article (عنوان المستثمر)، وdataroom_get_update، وdataroom_edit_update_draft،
وdataroom_get_published_update، وdataroom_list_file_comments،
وdataroom_list_my_notifications، وmi_get_profile، وكل أدوات الذكاء الاصطناعي باستثناء
dataroom_apply_organise. أما أسماء الملفات فلا تُعلَّم.
كيف يُبلَّغ عن الإخفاق
إخفاق الأداة ليس حالة HTTP. عندما ترفض أداة استدعاءً، تظل استجابة HTTP
200 ويظل غلاف JSON-RPC غلاف نجاح؛ إذ يُحمَل الإخفاق داخل النتيجة، التي
تضبط isError: true ويكون محتواها النصي:
{ "error": { "code": "CONFLICT", "message": "…" } }اعتمد في التفرّع على error.code، وليس أبدًا على حالة HTTP — فالعميل الذي يتفرّع
بحسب الحالة لن يطابق أي رفض في هذه الصفحة. وهذه هي الرموز التي تعيدها أداة غرفة
البيانات:
| الرمز | المعنى | ما الذي تفعله |
|---|---|---|
INVALID_ARGUMENT | وسيط مفقود أو تالف أو ليس معرّفًا صالحًا | صحّح الوسائط وأعد المحاولة |
FORBIDDEN | الرمز صالح لكنه غير مسموح له — النطاق منخفض جدًا، أو أن dataroom_id الذي مررته خارج قائمة السماح لغرف البيانات الخاصة به، أو أن دور المالك لا يسمح بذلك | اطلب الوصول، أو استخدم رمزًا بالنطاق الصحيح |
NOT_FOUND | لا يوجد سجل كهذا، أو أنه ليس لك. ومعظم الأدوات التي تأخذ معرّف ملف أو مجلد تجيب بهذا أيضًا لعنصر في غرفة بيانات خارج قائمة السماح الخاصة بالرمز، تمامًا كما تفعل مع معرّف غير موجود | تحقق من المعرّف، ومن أن الرمز مقيّد بغرفة البيانات التي يتبعها العنصر |
CONFLICT | الطلب مفهوم ومسموح به، لكن غرفة البيانات ليست في حالة تسمح بتنفيذه | اقرأ الرسالة، وأزل العائق، وأعد المحاولة |
TOO_LARGE | المُدخل يتجاوز حدًا للحجم | قسّم المُدخل |
QUOTA_EXCEEDED | استُنفد مخصص مُقاس، أو انتهى اشتراك المؤسسة | يجب على أحدهم الشراء أو الترقية — لن تزيل إعادة المحاولة هذا الخطأ |
UPSTREAM_ERROR | أخفقت خدمة تابعة — تعذّر جلب المستند المخزّن، أو أخفق استخراج النص منه | مؤقت. أعد المحاولة لاحقًا قبل اعتباره خطأً قاتلًا |
UNAVAILABLE | لا تستطيع Waafir تلبية الطلب الآن: الملف لا يزال قيد الفحص، أو تعذّرت قراءة الملف المخزَّن لفحصه، أو تعذّر تسجيل القراءة في سجل التدقيق، فحُجب المحتوى بدلًا من الإفصاح عنه دون تسجيل | مؤقت. أعد المحاولة لاحقًا |
INTERNAL | إخفاق غير متوقع | لا تُعد المحاولة — صعّد المشكلة |
لا تدمج رمزَي "أعد المحاولة لاحقًا" في خانة "أخفق". يصلك UPSTREAM_ERROR
وUNAVAILABLE اليوم من get_file_text، ومعناهما اسأل مجددًا، لا استسلم.
والعميل الذي يعامل كل نتيجة غير OK على أنها نهائية يحوّل عثرة عابرة إلى إخفاق
دائم — وهو الخطأ الوحيد الذي وُجد هذا الجدول لمنعه. ولاحظ أيضًا أن UNAVAILABLE
رفض متعمَّد: تفضّل Waafir حجب نص المستند على تسليمه دون سجل تدقيق.
ملف لا يزال قيد الفحص. تفحص Waafir كل ملف مرفوع حديثًا وكل إصدار جديد قبل أن
تقدّم محتواه. وإلى أن ينتهي الفحص، تُجيب أي أداة تقرأ محتوى الملف
بـUNAVAILABLE مع error.reason:
{ "error": { "code": "UNAVAILABLE", "reason": "ACTIVATION_PENDING", "message": "This file is still being checked. Try again shortly." } }هذا الرفض مؤقت: انتظر قليلًا ثم استدعِ الأداة مجددًا. كانت الإصدارات السابقة
تُجيب عنه بـCONFLICT؛ فاعتمد في التفريع على error.reason لا على نص الرسالة.
وللفحص نتيجتان أخريان. لا تحمل أيٌّ منهما reason في أدوات غرفة البيانات،
وتنتهي الرسالة بالرمز بين قوسين:
- محظور: أخفق الملف في فحص محتواه.
INVALID_ARGUMENT، وتنتهي الرسالة بـ(ACTIVATION_BLOCKED). لن تنجح أي إعادة محاولة لهذا الملف. - غير مقروء: تعذّرت قراءة الملف المخزَّن لفحصه.
UNAVAILABLE، وتنتهي الرسالة بـ(CONTENT_UNREADABLE). أعد المحاولة لاحقًا.
تسمّي message السجل المعيق حيثما وُجد. أما إخفاقات مستوى النقل — اسم خادم غير
معروف، أو اتصال أو رمز مفقود أو ملغى، أو إضافة مدفوعة لم تُشترَ — فهي حالات HTTP
حقيقية ومدرجة في الإعداد.
ترقيم الصفحات
لا تعيد أي أداة سرد مصفوفة غير محدودة. كل أداة تعيد قائمة تقبل limit
وoffset اختياريين، وتعيد كائن pagination إلى جانب الصفوف:
| الحقل | المعنى |
|---|---|
limit | حجم الصفحة المطبَّق فعليًا |
offset | الإزاحة المطبَّقة فعليًا |
count | عدد الصفوف في هذه الصفحة |
has_more | true عندما توجد صفوف أخرى بعد هذه الصفحة |
next_offset | قيمة offset التي تمررها للصفحة التالية، أو null عندما تكون النتيجة مكتملة |
total | العدد الكامل للصفوف خلف النافذة — لا يظهر إلا حيث يكون حسابه رخيصًا |
تُقصَر قيمتا limit وoffset إلى الحدود ولا تُرفضان: القيمة الأعلى من الحد
الأقصى تعود بالحد الأقصى، والقيمة الأدنى من الحد الأدنى تعود بالحد الأدنى،
والقيمة الغائبة أو غير الرقمية تعود بالقيمة الافتراضية الموثقة. ويبلّغ كتلة
pagination دائمًا عن القيم التي طُبّقت فعليًا، لترى ما حصلت عليه لا ما طلبته.
استخدم has_more لتقرر ما إذا كانت النتيجة مكتملة — ولا تستنتج ذلك أبدًا من
count === limit، فهذا ملتبس في صفحة أخيرة ممتلئة تمامًا. ولقراءة قائمة كاملة،
تتبّع next_offset حتى تصبح has_more مساوية لـ false.
أدوات القراءة
تتطلب النطاق read.
dataroom_list
اسم نقطة نهاية المجال: list_datarooms
يسرد غرف البيانات التي يمكن للمستدعي الوصول إليها. وبالنسبة إلى رمز مقيّد بغرف بيانات محددة، تُرشَّح النتيجة وفق قائمة السماح تلك. وتُستبعد غرف البيانات المؤرشفة.
- المدخلات:
limit(اختياري، 1–200، الافتراضي 50)؛offset(اختياري، الافتراضي 0). - المخرجات:
{ datarooms: [{ id, name, description, org_name, created_at }], pagination: { limit, offset, count, has_more, next_offset, total } }. - مرتبة من الأقدم إلى الأحدث بحسب
created_at، مع فاصل تعادل بالمعرّف لتبقى الصفحات ثابتة. وtotalهو العدد الكامل لغرف البيانات التي يمكن لهذا الرمز الوصول إليها، محسوبًا بعد تطبيق مرشّح قائمة السماح.
dataroom_get
اسم نقطة نهاية المجال: get_dataroom
يجلب غرفة بيانات واحدة بمعرّفها. يجب أن يكون المستدعي مخوّلًا بها؛ ويُرفض الرمز المقيّد بغرف بيانات أخرى.
- المدخلات:
dataroom_id(مطلوب). - المخرجات:
{ dataroom: { id, name } | null }.
dataroom_list_folders
اسم نقطة نهاية المجال: list_folders
يسرد المجلدات في غرفة بيانات. ويراعي الفرق في الرؤية بين فريق الصفقة والمستثمر —
فالمستثمر لا يرى إلا المجلدات التي يحق له قراءتها. اسرد مستوى واحدًا تحت مجلد أصل،
أو مرّر all للحصول على الشجرة كاملة. وتُستبعد المجلدات المحذوفة.
- المدخلات:
dataroom_id(مطلوب)؛parent_folder_id(اختياري — احذفه للمجلدات في المستوى الأعلى)؛all(قيمة منطقية اختيارية — true يسرد كل مجلد في غرفة البيانات)؛limit(اختياري، 1–500، الافتراضي 100)؛offset(اختياري، الافتراضي 0). - المخرجات:
{ folders: [{ id, name, parent_folder_id, created_at }], pagination: { limit, offset, count, has_more, next_offset, total } }. - مرتبة بحسب الاسم، مع فاصل تعادل بالمعرّف لتبقى الصفحات ثابتة. و
all: trueمقسّم إلى صفحات أيضًا — ففي شجرة كبيرة، تنقّل بين الصفحات باستخدامnext_offsetبدلًا من توقّع الشجرة كاملة في استجابة واحدة.
dataroom_list_files
اسم نقطة نهاية المجال: list_files
يسرد الملفات النشطة (غير المحذوفة) في غرفة بيانات، واختياريًا داخل مجلد. ولا يرى المستدعون من المستثمرين إلا الملفات المسموح لهم بقراءتها. مقسّم إلى صفحات.
- المدخلات:
dataroom_id(مطلوب)؛folder_id(اختياري — احذفه للملفات في جذر غرفة البيانات)؛limit(اختياري، 1–200، الافتراضي 50)؛offset(اختياري، الافتراضي 0)؛sort_dir(اختياري،asc|desc، الافتراضيdesc). - المخرجات:
{ files: [{ id, name, folder_id, size_bytes, mime_type, created_at, updated_at }], pagination: { limit, offset, count, has_more, next_offset } }. - لا يوجد
total— فعدّ مجموعة المطابقات الكاملة ليس رخيصًا في هذا المسار. استخدمhas_more/next_offsetللتنقل بين الصفحات.
dataroom_get_file_metadata
اسم نقطة نهاية المجال: get_file_metadata
يجلب البيانات الوصفية لملف واحد: الاسم، ونوع MIME، والحجم، ومسار المجلد، وقائمة الإصدارات، والملخص/التصنيف المولَّد بالذكاء الاصطناعي إن وُجد. يجب أن ينتمي الملف إلى غرفة البيانات المسمّاة؛ والملف الموجود في غرفة بيانات أخرى (حتى ضمن المؤسسة نفسها) يعيد null.
- المدخلات:
dataroom_id(مطلوب)؛file_id(مطلوب). - المخرجات:
{ file: { id, name, mime_type, size_bytes, folder_id, folder_path, created_at, updated_at } | null, versions: [{ id, version_number, is_current, created_at }], ai_metadata: { summary, key_points, category, is_redacted } | null }.
dataroom_search
اسم نقطة نهاية المجال: search_dataroom
يبحث في الملفات بالاسم داخل غرفة بيانات واحدة مخوَّل بها (مطابقة سلسلة جزئية غير حساسة لحالة الأحرف). وتُستبعد الملفات المحذوفة.
- المدخلات:
dataroom_id(مطلوب)؛query(مطلوب، جزء من اسم الملف)؛limit(اختياري، 1–100، الافتراضي 25)؛offset(اختياري، الافتراضي 0). - المخرجات:
{ files: [{ id, name, mime_type, size_bytes, created_at }], pagination: { limit, offset, count, has_more, next_offset } }. - الأحدث أولًا، مع فاصل تعادل بالمعرّف لتبقى الصفحات ثابتة. وعندما تكون
has_moreمساوية لـtrueفإن الاستعلام طابق ملفات أكثر مما أُعيد — تنقّل بين الصفحات باستخدامnext_offset، أو ضيّق الاستعلام. لا يوجدtotal.
أدوات الغرف
dataroom_create
ينشئ غرفة بيانات في مؤسسة الرمز.
- النطاق:
write، ويجب أن يكون مالك الرمز ضمن فريق الصفقة. ويُرفض الرمز أو الاتصال المقيّد بغرف بيانات محددة (FORBIDDEN، الرمزPAT_ROOM_SCOPED)؛ استخدم رمزًا غير مقيّد بغرف بيانات. - المدخلات:
name(مطلوب، 1–100 حرف). تُقصّ المسافات في البداية والنهاية، ويُرفض الاسم المكوّن من مسافات فقط (INVALID_ARGUMENT). - المخرجات:
{ id, name }. مرّرidبوصفهdataroom_idإلى أدوات المجلدات والملفات. - غير متساوي القوة (non-idempotent). كل استدعاء ينشئ غرفة جديدة. فإذا ضاعت
نتيجة استدعاء، فابحث عن الغرفة باستخدام
dataroom_listقبل الاستدعاء مجددًا، وإلا فستنشئ نسخة مكررة. - تُرفض المؤسسة التي لا يسمح اشتراكها بالكتابة، أو التي تجاوزت حد مقاعدها، بالخطأ
QUOTA_EXCEEDED.
أدوات المجلدات
تتطلب النطاق write ودورًا في فريق الصفقة لغرفة البيانات.
dataroom_create_folder
اسم نقطة نهاية المجال: create_folder
ينشئ مجلدًا في غرفة بيانات. ضعه تحت مجلد أصل، أو احذف المجلد الأصل ليكون في جذر
غرفة البيانات. ويرفض الاسم المكرر تحت المجلد الأصل نفسه بالخطأ
CONFLICT.
- المدخلات:
dataroom_id(مطلوب)؛name(مطلوب، 1–255 حرفًا)؛parent_folder_id(اختياري — null/محذوف لجذر غرفة البيانات). - المخرجات:
{ folder: { id, name, parent_folder_id } }. تسمّي رسالةCONFLICTمعرّف المجلد المتعارض، فلا تحتاج إلى إعادة سرد المجلد الأصل للعثور عليه.
dataroom_rename_folder
اسم نقطة نهاية المجال: rename_folder
يعيد تسمية مجلد. يجب أن ينتمي المجلد إلى مؤسسة المستدعي.
- المدخلات:
folder_id(مطلوب)؛name(مطلوب، 1–255 حرفًا). - المخرجات:
{ folder: { id, name } }.
dataroom_delete_folder
اسم نقطة نهاية المجال: delete_folder
يحذف مجلدًا حذفًا ناعمًا مع شجرته الفرعية كاملة — كل مجلد فرعي متداخل وكل ملف
بداخلها. وفي غرفة بيانات حقيقية قد يعني ذلك مئات المستندات انطلاقًا من معرّف مجلد
واحد، لذا تبلّغ النتيجة بالضبط عن عدد المجلدات والملفات التي أُزيلت. مرّر
dry_run: true للحصول على هذه الأعداد دون حذف أي شيء. تُعلَّم الصفوف بأنها محذوفة،
ولا تُزال نهائيًا أبدًا، ويمكن التراجع عن السلسلة كاملة باستخدام restore_folder.
- المدخلات:
folder_id(مطلوب)؛dry_run(قيمة منطقية اختيارية — معاينة فقط). - المخرجات:
{ deleted, dry_run, folder_id, folder_name, affected: { folders, files }, restore_with: "restore_folder" }. - التشغيل التجريبي لا يغيّر شيئًا ولا يسجّل أي حذف في مسار التدقيق.
dataroom_restore_folder
اسم نقطة نهاية المجال: restore_folder
يتراجع عن delete_folder. يستعيد المجلد وكل ما أزاله ذلك الحذف معه — أما ما حُذف
بشكل منفصل في وقت سابق فيبقى محذوفًا. ويعيد تعارضًا إذا كان المجلد الأصل لا يزال
محذوفًا (استعده أولًا) أو إذا أخذ مجلد نشط الاسم منذ ذلك الحين؛ وفي الحالتين تسمّي
الرسالة معرّف المجلد المعيق.
- المدخلات:
folder_id(مطلوب)؛dry_run(قيمة منطقية اختيارية — معاينة فقط). - المخرجات:
{ restored, dry_run, folder_id, folder_name, affected: { folders, files } }. - التراجع عن حذف مجلد لا يُفقد شيئًا، وهو مختلف عمدًا عن حذف الملف. فالسلسلة
لا تحرّك عدّاد التخزين لمؤسستك ولا تُسقط مقاطع فهرس البحث للملفات، لذا لا يعيد
restore_folderأي رصيد — إذ لم يُخصم شيء — وتظل الملفات المستعادة قابلة للبحث. أماdelete_file/restore_fileأدناه فيفعلان الأمرين كليهما. لذا فإن حذف مجلد مليء بالمستندات ليس الحدث المحاسبي نفسه الذي يمثّله حذف كل مستند منها على حدة.
dataroom_move_folder
اسم نقطة نهاية المجال: move_folder
يغيّر المجلد الأصل لمجلد ضمن غرفة البيانات نفسها. ضعه تحت مجلد آخر، أو انقله إلى جذر غرفة البيانات. ويرفض نقل مجلد إلى داخل نفسه أو إلى أحد فروعه (دورة)، أو إلى غرفة بيانات مختلفة، أو حيث يوجد بالفعل مجلد شقيق بالاسم نفسه.
- المدخلات:
folder_id(مطلوب)؛new_parent_folder_id(اختياري — null/محذوف لجذر غرفة البيانات). - المخرجات:
{ folder: { id, name, parent_folder_id, previous_parent_folder_id } }. مرّرprevious_parent_folder_idمجددًا بوصفهnew_parent_folder_idللتراجع عن النقل.
أدوات الملفات
تتطلب تعديلات الملفات النطاق write؛ ويتطلب get_file_download_url النطاق read
إضافةً إلى منحة قراءة محتوى المستند على الرمز.
الرفع يتم بالوساطة، ولا ينقل MCP البايتات أبدًا. وسائط الأدوات بصيغة JSON،
فليس للبروتوكول قناة ثنائية: يُصدر request_file_upload عنوان URL موقّعًا مسبقًا
ويرسل عميلك المحتوى إليه مباشرةً بطلب PUT. والعميل الذي لا يستطيع إصدار طلب
HTTP PUT بجسم ثنائي خام لا يمكنه إكمال الرفع إطلاقًا — ومن المفيد معرفة ذلك قبل
أن تبدأ لا بعده.
تعتمد الأداة التي تُنهي الرفع على ما إذا كان ملف بالاسم نفسه موجودًا بالفعل، ولا
يلزمك أن تستنتج ذلك بنفسك: يعيد request_file_upload حقل next_step الذي
يسمّي الأداة الواجب استدعاؤها.
ما يعيده request_file_upload | المعنى | الإنهاء باستخدام |
|---|---|---|
is_new_version: false، next_step: "register_file" | لا يوجد ملف نشط بالاسم نفسه — أُنشئ سجل معلّق بالإصدار 1 | register_file |
is_new_version: true، next_step: "finalise_file_version" | يوجد ملف نشط بالاسم نفسه — يصبح هذا الرفع إصدارًا جديدًا منه | finalise_file_version |
استدعِ الأداة التي يسمّيها next_step. فالأداة register_file لا تُنهي إلا الإصدار 1
وترفض ما عداه، لذا فإن اللجوء إليها في فرع الإصدار الجديد يُفشل الاستدعاء.
dataroom_request_file_upload
اسم نقطة نهاية المجال: request_file_upload
يطلب عنوان URL موقّعًا مسبقًا لرفع ملف إلى غرفة بيانات. ويعيد عنوان URL والترويسات
اللازمة لإرسال البايتات بطلب PUT، ومعرّف الملف، وnext_step — الأداة التي تُنهي هذا
الرفع بعينه. وإذا كان ملف نشط بالاسم نفسه موجودًا بالفعل في المجلد الهدف، فإن
is_new_version تكون true ويستهدف المعرّف المُعاد وversion_number ذلك الملف
الموجود.
- النطاق:
write. - المدخلات:
dataroom_id(مطلوب)؛file_name(مطلوب، مع الامتداد)؛file_size(مطلوب، بالبايتات بدقة، عدد صحيح موجب)؛mime_type(مطلوب)؛folder_id(اختياري — احذفه لجذر غرفة البيانات). - المخرجات:
{ upload_url, headers, file_id, s3_key, is_new_version, version_number, next_step }— وقيمةnext_stepهي"register_file"أو"finalise_file_version". - لا تنقل هذه الأداة أي بايتات؛ بل تتوسط فقط في عنوان URL. وإذا لم يكن تخزين الكائنات مهيّأً، يُخفق الاستدعاء مباشرةً بدلًا من إعادة عنوان URL لا يمكن أن يعمل.
dataroom_register_file
اسم نقطة نهاية المجال: register_file
يُنهي رفعًا أول معلّقًا بعد إرسال البايتات بطلب PUT من
request_file_upload: يعلّم الملف بأنه نشط، ويزيد تخزين المؤسسة، ويسجّل الإصدار 1.
استدعه عندما يعيد request_file_upload القيمة is_new_version: false —
إذ يسمّي next_step الخاص به هذه الأداة.
- النطاق:
write. - المدخلات:
file_id(مطلوب، المعرّف المعلّق منrequest_file_upload)؛s3_key(اختياري)؛size_bytes(اختياري — يُستنتج من الكائن المرفوع عند حذفه). - المخرجات:
{ file_id, status: "active", version_number: 1 }. - للإصدار 1 فقط، وهي تفرض ذلك. يُرفض الملف النشط بالفعل، أو الذي يحمل إصدارًا
بالفعل — ويسمّي الرفض
finalise_file_versionبوصفها الأداة المخصصة للإصدارات 2 وما بعده. - يُستنتج مفتاح التخزين من جانب الخادم ولا يُوثق أبدًا بقيمة
s3_keyالمرسلة من العميل. وهي اختيارية؛ فإن أرسلتها، فيجب أن تساوي المفتاح الذي أعادهrequest_file_uploadوإلا رُفض الاستدعاء.
dataroom_finalise_file_version
اسم نقطة نهاية المجال: finalise_file_version
يُنهي إصدارًا جديدًا من ملف موجود، بعد إرسال البايتات بطلب PUT إلى عنوان URL
الذي أعاده request_file_upload مع is_new_version: true. وهذا هو المكافئ في MCP
لاستبدال مستند في الواجهة، والأداة التي يسمّيها next_step في ذلك الفرع.
- النطاق:
write. - المدخلات:
file_id(مطلوب)؛version_number(مطلوب — قيمةversion_numberالتي أعادهاrequest_file_upload). - المخرجات:
{ file_id, version_id, version_number, size_bytes, is_current: true, previous_version_number, previous_version_id, undo_with: "restore_file_version" }. - يجب أن تكون
version_numberهي الإصدار التالي لهذا الملف بالضبط. فهي تُتحقَّق ولا تُخمَّن: أي قيمة أخرى تُرفض بدلًا من كتابتها بصمت، ويُستنتج مفتاح التخزين منها من جانب الخادم. - يصبح الإصدار الجديد هو الحالي ويُحتفظ بالإصدار السابق في السجل. مرّر
previous_version_idإلىrestore_file_versionللتراجع. - يُرفض الملف الذي لم يكمل رفعه الأول — أنهِ الإصدار 1 باستخدام
register_fileأولًا. ويُخفق الاستدعاء أيضًا إذا لم تكن البايتات موجودة فعلًا في التخزين بعد، بدلًا من تسجيل إصدار لا شيء خلفه.
dataroom_restore_file_version
اسم نقطة نهاية المجال: restore_file_version
يجعل إصدارًا سابقًا من ملف هو الحالي مجددًا — وهو التراجع عن
finalise_file_version. ينقل مؤشر الإصدار الحالي ويعيد توجيه الملف إلى ذلك
الإصدار؛ ولا يُصدر صف إصدار جديدًا، فيبقى سجل الإصدارات قائمة أمينة بالمراجعات
التي رُفعت فعلًا.
- النطاق:
write. - المدخلات:
file_id(مطلوب)؛version_id(مطلوب — يجب أن ينتمي إلى هذا الملف؛ ويسردget_file_metadataمعرّفات إصدارات الملف). - المخرجات:
{ file_id, version_id, version_number, already_current, new_version_created: false }. - تعني
already_current: trueأن الإصدار كان هو الحالي بالفعل ولم يتغير شيء — عملية بلا أثر، لا إخفاق. - لا توجد أداة منفصلة لسرد الإصدارات: يعيد
get_file_metadataبالفعل إصدارات الملف مع معرّفاتها وأرقامها وعلامة الإصدار الحالي.
dataroom_rename_file
اسم نقطة نهاية المجال: rename_file
يعيد تسمية ملف — بيانات وصفية فقط. لا ينشئ ذلك إصدارًا جديدًا؛ فالإصدارات
مخصصة لاستبدال المحتوى، لا لإعادة التسمية. يجب أن تكون الأسماء فريدة بين الملفات
النشطة في المجلد نفسه؛ ويعيد التعارض خطأ CONFLICT يسمّي الملف الموجود.
- النطاق:
write. - المدخلات:
file_id(مطلوب)؛name(مطلوب، 1–255 حرفًا). - المخرجات:
{ file_id, name, previous_name, changed }. يُقرأnameالمُعاد من التخزين، فهو ما حُفظ فعلًا — وتكونchangedقيمتها false إذا لم يتغير الاسم المخزّن.
dataroom_move_file
اسم نقطة نهاية المجال: move_file
ينقل ملفًا إلى مجلد آخر في غرفة البيانات نفسها، أو إلى جذر غرفة البيانات. ويُرفض النقل بين غرف البيانات: فغرفة البيانات حدّ للصلاحيات، ونقل المحتوى عبرها سيغيّر من يمكنه قراءته. ويُرفض النقل إذا كان ملف نشط بالاسم نفسه موجودًا بالفعل في الوجهة.
- النطاق:
write. - المدخلات:
file_id(مطلوب)؛folder_id(اختياري — null/محذوف لجذر غرفة البيانات). - المخرجات:
{ file_id, name, folder_id, previous_folder_id, moved }. مرّرprevious_folder_idمجددًا بوصفهfolder_idللتراجع عن النقل.
dataroom_delete_file
اسم نقطة نهاية المجال: delete_file
يحذف ملفًا. وتردّد النتيجة اسم الملف الذي حُذف فعلًا، فيظهر المعرّف الخاطئ في
الاستجابة. ويُحتفظ بالملف وإصداراته لأغراض الاحتفاظ والتدقيق، ولا يُمحيان أبدًا،
ويعيده restore_file.
- النطاق:
write. - المدخلات:
file_id(مطلوب). - المخرجات:
{ file_id, status: "deleted", name, folder_id, restore_with: "restore_file" }. - لا يُعاد رصيد التخزين إلا لرفع اكتمل فعلًا. الملف الذي وصلت بايتاته يعيد حجمه إلى عدّاد التخزين لمؤسستك. أما الملف الذي لا يزال ينتظر رفعه فلم يُحتسب أصلًا، لذا فحذفه لا يحرّك العدّاد بشيء — فالحذف محايد بالنسبة إلى العدّاد، وليس استردادًا لبايتات لم تخزّنها قط.
- يُسقط الحذف أيضًا مقاطع فهرس البحث الخاصة بالملف، فيخرج المستند من بحث
المستندات فورًا. ولا يستطيع
restore_fileإعادتها — راجع أدناه. - لا تحلّ الأداة إلا ملفًا نشطًا، لذا فإن استدعاءها مرة ثانية على المعرّف نفسه
يعيد
NOT_FOUNDبدلًا من حذف أي شيء مجددًا. ولا يمكن أن يُخصم من عدّاد التخزين مرتين لملف واحد.
dataroom_restore_file
اسم نقطة نهاية المجال: restore_file
يتراجع عن delete_file: يعيد ملفًا محذوفًا حذفًا ناعمًا إلى الحالة النشطة،
مستعيدًا الصف ومحاسبة التخزين التي عكسها الحذف. ولا يستعيد مقاطع فهرس البحث
الخاصة بالملف — فهي تُسقط عند الحذف — لذا يكون الملف نشطًا وقابلًا للتنزيل لكن يجب
إعادة فهرسته قبل أن يعثر عليه بحث المستندات مجددًا. وتكون
search_index_restored دائمًا false وتصرّح بذلك بدلًا من الإيحاء بتراجع لا
يُفقد شيئًا.
- النطاق:
write. - المدخلات:
file_id(مطلوب). - المخرجات:
{ restored, file_id, name, folder_id, storage_bytes_restored, search_index_restored: false }.
متى تُرفض الاستعادة. تُخفق بدلًا من التغطية على تعارض، وتسمّي الصف المعيق حيثما وُجد:
| # | الشرط | error.code | ما الذي تفعله |
|---|---|---|---|
| 1 | لا يوجد ملف كهذا، أو أنه ليس لك | NOT_FOUND | تحقق من المعرّف. |
| 2 | الملف غير محذوف — فهو نشط بالفعل | CONFLICT | لا شيء لاستعادته. |
| 3 | لم يكتمل رفع الملف قط | CONFLICT | لا شيء لاستعادته: لم تصل بايتاته قط، فلا يوجد مستند لإعادته. ارفعه مجددًا بدلًا من ذلك. |
| 4 | المجلد الحاوي لا يزال محذوفًا | CONFLICT | استخدم restore_folder أولًا — فهي تعيد أيضًا الملفات التي حُذفت معه. |
| 5 | أخذ ملف نشط الاسم منذ ذلك الحين في ذلك المجلد | CONFLICT | أعد تسمية الملف الذي يحمل الاسم، ثم أعد المحاولة. |
هذه رموز داخل الحمولة، وليست حالات HTTP — راجع كيف يُبلَّغ عن الإخفاق.
تُجرى الفحوص بالترتيب المرقّم أعلاه، ويُبلَّغ عن أول فحص يُخفق. لذا تُبلَّغ حالة عدم اكتمال الرفع (3) بعد فحصَي عدم الوجود وعدم الحذف لكن قبل فحصَي المجلد والاسم: فالملف الذي لم تصل بايتاته قط لا يمكن استعادته أيًّا كان وضع مجلده أو اسمه، فلا جدوى من توجيهك لإصلاح أيٍّ منهما.
dataroom_get_file_download_url
اسم نقطة نهاية المجال: get_file_download_url
يجلب عنوان URL قصير الأجل لتنزيل ملف. يجب أن يكون المستدعي مخوّلًا بالملف (صلاحية القراءة/التنزيل لكل ملف). ويقدّم عنوان URL النسخة نفسها التي يمنحك إياها التنزيل من المتصفح: بعلامة مائية عندما تضع الغرفة علامات مائية على التنزيلات، والنسخة المحجوبة من المستند المحجوب لمستلم من خارج مؤسستك. وتنتهي صلاحيته بعد بضع دقائق.
- النطاق:
read، إضافةً إلى منحة قراءة محتوى المستند على الرمز. وبدونها يُرفض الاستدعاء بالخطأGRANT_REQUIRED. - الحد: 10 استدعاءات في الدقيقة كحد أقصى لكل رمز، لأن كل استدعاء يُعدّ نسخة
محمية. وعند تجاوزه،
RATE_LIMITED. - إذا تعذّر إعداد نسخة محمية في الوقت المناسب، يُرفض الاستدعاء بالخطأ
UNAVAILABLEدون رابط؛ أعد المحاولة، أو نزّل الملف من Waafir. - المدخلات:
file_id(مطلوب). - المخرجات:
{ download_url, expires_in_seconds }.
أدوات نص المستندات
أداة واحدة، لقراءة النص المستخرج من المستند بدلًا من تنزيل الملف نفسه.
dataroom_get_file_text
اسم نقطة نهاية المجال: get_file_text
يقرأ النص المستخرج من مستند، صفحةً تلو أخرى. ويعيد مقاطع مرقّمة — لملف PDF، مقطع
واحد لكل صفحة ما لم تكن الصفحة طويلة جدًا — إضافةً إلى كتلة pagination، لتتمكن
من التنقل في مستند طويل باستخدام offset.
أمران يجعلان هذه الأداة أشد صرامة من قراءة البيانات الوصفية:
- يجب أن يكون مسموحًا لك بتنزيل الملف، لا بمجرد عرضه. فصلاحية العرض فقط لا تكفي، ويُرفض الرمز المقيّد بعيدًا عن المستند.
- إذا كان المستند قد حُجب ولم تكن ضمن فريق الصفقة، فستتلقى نص الإصدار
المحجوب، ويبيّن
sourceالنسخة التي حصلت عليها. ولا يسلّم أبدًا النسخة الأصلية لقارئ من خارج النطاق بصمت.
يُكتب كل استدعاء ناجح في سجل التدقيق للمؤسسة، على قدم المساواة مع قراءة مستند في المنتج.
- النطاق:
read، إضافةً إلى منحة قراءة محتوى المستند على الرمز. وبدونها يُرفض الاستدعاء بالخطأGRANT_REQUIRED؛ ولا تزالdataroom_get_file_metadataوdataroom_summarise_fileتقدّمان ملخص المستند. - المدخلات:
file_id(مطلوب)؛dataroom_id(اختياري — يُتحقق منه مقابل غرفة البيانات الخاصة بالملف عند تقديمه، ويُقرأ عدم التطابق على أنهNOT_FOUNDبدلًا من تأكيد وجود الملف في مكان آخر)؛limit(اختياري، 1–5، الافتراضي 3)؛offset(اختياري، الافتراضي 0). - المخرجات:
{ file_id, file_name, source, segment_max_chars, segments, pagination }. قيمةsourceهي"original"أو"redacted". وتحملpaginationقيمةtotal. - الملف الذي لا يملك كائنًا مخزّنًا — كملاحظة يُحفظ متنها ضمنيًا — يعيد
NOT_FOUNDمع "no extractable content". - الملف الذي لا يحتوي نوعه على نص لاستخراجه (كملف أرشيف مثلًا) يُرفض بالرمز
400، والملف المخزّن الذي يتجاوز 50 MB يُرفض بالرمز413(FILE_TOO_LARGE). ولا ينطبق كلاهما إلا إذا لم يكن نص الملف قد استُخرج بالفعل (يُقدَّم النص المستخرج مسبقًا أولًا)، ويُرفضان قبل جلب المستند، وليس أيٌّ منهما خطأً من نوع "أعد المحاولة لاحقًا". - هذه هي الأداة التي تنتج رمزَي "أعد المحاولة لاحقًا":
UPSTREAM_ERRORعندما يتعذر جلب المستند المخزّن أو يُخفق استخراج النص منه، وUNAVAILABLEعندما تُخفق كتابة التدقيق الخاصة بالقراءة — وفي هذه الحالة يُحجب النص عمدًا بدلًا من الإفصاح عنه دون تسجيل. ويستحق كلاهما إعادة محاولة واحدة قبل أن تعامل المستند على أنه غير قابل للقراءة.
أدوات الصلاحيات
تقرأ هذه الأدوات من يمكنه رؤية ماذا وتعدّله. لا تتطلب أدوات القراءة الثلاث سوى
النطاق read (وتتطلب أداتا الدليل كذلك دورًا في فريق الصفقة)؛ وتتطلب أدوات المنح/الإلغاء
الأربع النطاق admin ومالك رمز يكون مسؤولًا أو مديرًا في المؤسسة.
لا يحمل الرمز أبدًا تجاوز المالك/المسؤول على الملفات المقيّدة. ففي التطبيق، يرى
مالك المؤسسة أو مسؤولها كل ملف مقيّد؛ أما عبر رمز فلا يصل إلى أي منها إلا إذا كان
هو من أنشأه أو كان يحمل منحة عليه، تمامًا مثل أي عضو آخر. وأداة الملفات التي تُرفض
على مثل هذا الملف تجيب بـ NOT_FOUND بالنص نفسه الخاص بملف غير موجود ("File not
found in the requested dataroom, or not readable by this credential")، فلا تؤكد
الإجابة أبدًا وجود ملف مقيّد.
dataroom_get_file_permissions
اسم نقطة نهاية المجال: get_file_permissions
يسرد منح الصلاحيات على ملف (المباشرة والموروثة من المجلد). ويطابق عرض صلاحيات الملف في الواجهة.
- النطاق:
read. - المدخلات:
dataroom_id(مطلوب)؛file_id(مطلوب)؛limit(اختياري، 1–200، الافتراضي 50)؛offset(اختياري، الافتراضي 0). - المخرجات:
{ permissions: [{ user_id, can_read, can_download, access_revoked, expires_at, granted_by, created_at, source, source_folder_name?, source_folder_id?, user_email?, user_name?, granted_by_email? }], pagination: { limit, offset, count, has_more, next_offset, total }, identities_visible }(قيمةsourceهي"direct"أو"inherited"). - تُرتَّب المنح بحسب
created_at، ثمuser_id، ثمsource، ثمsource_folder_id، فتبقى الصفحات ثابتة عبر الاستدعاءات. وtotalهو العدد الكامل للمنح على الملف. - تتبع حقول الهوية (
user_email،user_name،granted_by_email) قاعدة الرؤية نفسها المتبعة في أدوات الدليل أدناه: تظهر للمستدعين من فريق الصفقة، وتتطلب هويات المستثمرين كذلك مسؤولًا أو مديرًا في المؤسسة، وحيث لا يُسمح لك تكون المفاتيح غائبة لاnull. ويخبركidentities_visibleبالحالة التي أنت فيها؛ أما المنح نفسها فتُسرد دائمًا.
dataroom_list_users
اسم نقطة نهاية المجال: list_dataroom_users
يسرد المستخدمين الذين يحملون منحة وصول نشطة على غرفة بيانات، مع user_id الذي
تتطلبه أدوات الصلاحيات، إضافةً إلى عنوان البريد الإلكتروني والاسم لكل ممنوح. وهذا
عادةً أول استدعاء عندما تحتاج إلى user_id.
- النطاق:
read، ودور في فريق الصفقة في مؤسسة غرفة البيانات (البوابة نفسها الخاصة بصفحة الفريق). - المدخلات:
dataroom_id(مطلوب)؛limit(اختياري، 1–200، الافتراضي 50)؛offset(اختياري، الافتراضي 0). - المخرجات:
{ users: [{ user_id, email, name, is_deal_team, org_role, permission, granted_at, expires_at }], pagination: { limit, offset, count, has_more, next_offset, total }, investor_rows_visible }. - تُحذف هويات المستثمرين ما لم تكن مسؤولًا أو مديرًا في المؤسسة؛ ويبلّغ
investor_rows_visibleبالمجموعة التي تلقيتها. - يسرد الممنوحين الصريحين فقط. فمالكو المؤسسة ومسؤولوها لهم وصول ضمني دون صف
منحة ولن يظهروا — حدّد هويتهم باستخدام
find_user_by_email.
dataroom_find_user_by_email
اسم نقطة نهاية المجال: find_user_by_email
يحوّل عنوان بريد إلكتروني إلى user_id الذي تتطلبه أدوات الصلاحيات، مع دور
المستخدم في المؤسسة وصلاحيته الحالية في غرفة البيانات هذه.
- النطاق:
read، ودور في فريق الصفقة في مؤسسة غرفة البيانات. ويتطلب تحديد هوية مستثمر كذلك مسؤولًا أو مديرًا في المؤسسة. - المدخلات:
dataroom_id(مطلوب)؛email(مطلوب، يُطابَق دون حساسية لحالة الأحرف). - المخرجات:
{ found: true, user: { user_id, email, name, org_role, dataroom_permission } }أو{ found: false }. وتعنيdataroom_permissionبقيمةnullأن المستخدم في المؤسسة لكن ليس له وصول إلى هذه الغرفة بعد — ادعُه أولًا. - هذا ليس بحثًا في دليل عام: لا تُحدَّد إلا هوية المستخدمين داخل المؤسسة
الخاصة بغرفة البيانات، أو الحاملين وصولًا نشطًا إليها. والعنوان غير المعروف،
والمستخدم من خارج نطاق مستأجرك، والمستخدم غير المسموح لك برؤيته، كلها تعيد
{ found: false }متطابقة، فلا تكشف الإجابة السلبية أبدًا ما إذا كان الحساب موجودًا.
dataroom_set_file_permissions
اسم نقطة نهاية المجال: set_file_permissions
يمنح صلاحية القراءة/التنزيل لمستخدم على ملف أو يحدّثها. ويُرفض الرمز ذو النطاق
read/write، أو المالك الذي ليس مسؤولًا أو مديرًا في المؤسسة.
- النطاق:
admin. - المدخلات:
dataroom_id(مطلوب)؛file_id(مطلوب)؛user_id(مطلوب)؛can_read(قيمة منطقية مطلوبة)؛can_download(قيمة منطقية مطلوبة)؛expires_at(طابع زمني ISO اختياري، يجب أن يكون في المستقبل). - المخرجات:
{ success: true, effective: { can_read, can_download } }— القرار بعد المنح، الذي يعكس قيود الملف والوراثة من المجلد، وقد يختلف لذلك عمّا طلبته. - هذه الأداة تمنح الوصول؛ ولا يمكنها إزالته. فتمرير
can_read: falseيكتب منحة نشطة مع رفض القراءة، وقد تتجاوزها منح أخرى (عضوية المؤسسة، أو منحة على مستوى غرفة البيانات، أو الوراثة من المجلد). ولإزالة وصول مستخدم إلى ملف فعليًا، استخدمrevoke_file_permission.
dataroom_revoke_file_permission
اسم نقطة نهاية المجال: revoke_file_permission
يزيل منحة الصلاحية المباشرة لمستخدم على ملف (إلغاء ناعم: يُحفظ الصف لمسار
التدقيق). ويعيد revoked: false إذا لم تكن للمستخدم منحة مباشرة على الملف.
- النطاق:
admin. - المدخلات:
dataroom_id(مطلوب)؛file_id(مطلوب)؛user_id(مطلوب). - المخرجات:
{ success: true, revoked }. - يؤثر في المنحة المباشرة فقط. أما الوصول الموروث من صلاحية مجلد فلا يتأثر
ويجب إلغاؤه على المجلد. ويمكن عكسه بإعادة المنح باستخدام
set_file_permissions.
dataroom_invite_user
اسم نقطة نهاية المجال: invite_user_to_dataroom
يمنح مستخدمًا معروفًا وصولًا على مستوى غرفة البيانات بمستوى صلاحية محدد — منحة وصول مباشرة (لا دعوة بالبريد الإلكتروني). متساوي القوة (upsert).
- النطاق:
admin. - المدخلات:
dataroom_id(مطلوب)؛user_id(مطلوب)؛permission(مطلوب — أحدviewer،downloader،contributor،manager)؛expires_at(طابع زمني ISO اختياري، يجب أن يكون في المستقبل). - المخرجات:
{ success: true, grant_id }.
dataroom_remove_user
اسم نقطة نهاية المجال: remove_user_from_dataroom
يلغي وصول مستخدم على مستوى غرفة البيانات (إلغاء ناعم: يضبط revoked_at،
محافظًا على مسار التدقيق). ويعيد revoked: false إذا لم تكن للمستخدم منحة
نشطة.
- النطاق:
admin. - المدخلات:
dataroom_id(مطلوب)؛user_id(مطلوب). - المخرجات:
{ success: true, revoked }.
أدوات إدارة الغرف
منح المجلدات، والمنح عبر ملفات كثيرة دفعةً واحدة، والعلامة المائية للتنزيل في الغرفة.
تُجري كل أداة الفحوص نفسها وتكتب الصفوف نفسها التي تكتبها شاشة Waafir التي تطابقها.
وتتطلب عمليات الكتابة النطاق admin ومالك رمز يكون مسؤولًا في المؤسسة. والمستلمون
دائمًا user_id (من find_user_by_email أو list_dataroom_users)، وليسوا أبدًا
عنوان بريد إلكتروني.
dataroom_get_folder_permissions
يسرد المنح المباشرة على مجلد، وما إذا كان مقيّدًا (بذاته، أو عبر مجلد أصل مقيّد).
- النطاق:
read، ويجب أن يكون مالك الرمز ضمن فريق الصفقة. - المدخلات:
dataroom_id(مطلوب)؛folder_id(مطلوب). - المخرجات:
{ folder_id, restricted, effectively_restricted, permissions: [{ user_id, can_read, can_download, expires_at, access_revoked, user_email?, user_name? }] }. تكون مفاتيح الهوية غائبة حيث لا يحق لك رؤية ذلك الشخص. - المجلد الذي لا يمكنك رؤيته يجيب بـ
NOT_FOUND، تمامًا كالمجلد غير الموجود.
dataroom_set_folder_permissions
يمنح مستخدمين وصولًا إلى مجلد، أو يرفضه باستخدام can_read: false، واختياريًا على
امتداد الشجرة كاملة.
- النطاق:
admin. - المدخلات:
dataroom_id،folder_id،grants(مطلوبة:[{ user_id, can_read, can_download, expires_at? }])؛recursive(الافتراضيfalse). - المخرجات:
{ success: true, recursive, granted, skipped: { count, items } }. - يجب أن يكون كل ممنوح موجودًا في الغرفة بالفعل. وتُرفض قيمة
expires_atالواقعة في الماضي. والمنحة التي سيلغيها رفضٌ على مجلد أعلى تُرفض (CONFLICT) قبل كتابة أي شيء. وتتخطى المنحة التكرارية الفروع التي يحمل فيها الممنوح رفضًا، وتسردها فيskipped. ويتلقى الممنوحون إشعار "تم منح الوصول" داخل التطبيق.
dataroom_revoke_folder_permission
يلغي المنحة المباشرة لمستخدم على مجلد، أو يرفع الرفض المفروض عليه.
- النطاق:
admin. - المدخلات:
dataroom_id،folder_id،user_id(جميعها مطلوبة). - المخرجات:
{ success: true, revoked }. وتعنيrevoked: falseأنه لم تكن هناك منحة نشطة. - لا يمتد هذا تسلسليًا: تبقى المنح التي كتبتها منحة تكرارية على فروع المجلد.
dataroom_bulk_set_file_permissions
يمنح المستخدمين أنفسهم وصولًا إلى ملفات كثيرة دفعةً واحدة. في mode: "add"
(الافتراضي) يضيف فقط: فالحقل الذي تحذفه لا يسلب الوصول أبدًا. وفي
mode: "replace" يستبدل كل منحة تمامًا كما قُدّمت، فيمكنه إزالة التنزيل، أو مسح
تاريخ انتهاء، أو إعادة وصول ملغى. والاستبدال على خطوتين: يعيد الاستدعاء الأول
معاينة وconfirm_token، ويطبّقه التكرار مع الرمز، بشرط ألا تكون أي منحة على
التحديد قد تغيرت في الأثناء.
- النطاق:
admin. - المدخلات:
dataroom_id،file_ids(حتى 200)،grants(جميعها مطلوبة)؛mode؛confirm_token. - المخرجات:
{ success: true, mode, total_grants, left_revoked_user_ids }. - معرّف الملف غير الموجود في الغرفة، أو الذي لا يمكنك رؤيته، يرفض الطلب كله بالخطأ
NOT_FOUND. - يجب أن يكون كل ملف في الغرفة ومرئيًا لك، ويجب أن يكون كل ممنوح موجودًا في الغرفة بالفعل. وإذا كان رفضٌ على مجلد سيلغي أي منحة، يُرفض الطلب كله قبل كتابة أي ملف.
- إذا كان وصول ممنوح قد أُلغي، فإن
addلا يعيده، ويُسرد الممنوح فيleft_revoked_user_ids.
dataroom_bulk_revoke_file_permissions
يلغي المنح المباشرة للمستخدمين المحددين على ملفات كثيرة دفعةً واحدة. ولا تُمس منح المجلدات ولا الوصول إلى الغرفة.
- النطاق:
admin. - المدخلات:
dataroom_id،file_ids(حتى 200)،user_ids(جميعها مطلوبة). - المخرجات:
{ success: true, revoked_count }. - معرّف الملف غير الموجود في الغرفة، أو الذي لا يمكنك رؤيته، يرفض الطلب كله بالخطأ
NOT_FOUND.
dataroom_get_watermark_settings
يقرأ أوضاع العلامة المائية للتنزيل في الغرفة، لتنزيلات الملف الواحد والتنزيلات
المجمّعة: two_layer (هوية المنزِّل إضافةً إلى طبقة بعنوان IP والتاريخ لكل تنزيل)، أو
static (الهوية فقط). للقراءة فقط: غيّرها من إعدادات Waafir.
- النطاق:
read، ويجب أن يكون مالك الرمز مسؤولًا في المؤسسة ضمن فريق الصفقة. - المدخلات:
dataroom_id(مطلوب). - المخرجات:
{ dataroom_id, single, bulk, stored: { single, bulk } }. وتعني القيمةnullفيstoredأن الغرفة لم تضبطها قط، فتنطبق القيمة الافتراضية.
dataroom_archive
يؤرشف غرفة بيانات، فتخرج من قوائم الغرف. على خطوتين: الاستدعاء الأول لا يغيّر
شيئًا ويعيد معاينة (اسم الغرفة وعدد ما فيها من ملفات ومجلدات وأشخاص لهم وصول وروابط
مشاركة نشطة) وconfirm_token. كرّر الاستدعاء مع الرمز للأرشفة.
- النطاق:
admin، ويجب أن يكون مالك الرمز مالكًا أو مسؤولًا في المؤسسة. - المدخلات:
dataroom_id(مطلوب)؛confirm_token. - المخرجات:
{ success: true, dataroom_id, name, archived: true, restore_with: 'dataroom_restore' }. - لا تلغي الأرشفة وصول أي شخص أو منحه، ولا يُحذف شيء. تخرج الغرفة من القوائم،
وتجيب عمليات القراءة على مستوى الغرفة (
get_dataroom،list_files،list_folders، والبحث، والأسئلة والأجوبة، وأسئلة الذكاء الاصطناعي) بـNOT_FOUNDإلى أن تُستعاد. أما الرابط المباشر إلى أحد ملفاتها فلا يزال يفتحه. ويعيدdataroom_restoreالغرفة، لذا احتفظ بـdataroom_id. ولا يمكن أرشفة آخر غرفة بيانات نشطة (CONFLICT). ولا توجد أداة تحذف غرفة بيانات.
dataroom_restore
يستعيد غرفة بيانات أرشفتها مؤسستك. فتعود إلى قوائم الغرف، ويعود معها كل ما أخفته الأرشفة: بحث الذكاء الاصطناعي، والملخصات الدورية، وتحديثات المستثمرين، والأسئلة والأجوبة، والإضافات الخاصة بالغرفة. وتبقى المجلدات والملفات والوصول كما كانت، لأن الأرشفة لم تغيّر أيًّا منها. استدعاء واحد، دون خطوة تأكيد.
- النطاق:
admin، ويجب أن يكون مالك الرمز مالكًا أو مسؤولًا في المؤسسة. - المدخلات:
dataroom_id(مطلوب): المعرّف الذي أعادهdataroom_archive. - المخرجات:
{ success: true, dataroom_id, name, archived: false }. - تُرفض الغرفة غير المؤرشفة (
CONFLICT، الرمزNOT_ARCHIVED). وتُرفض الغرفة التي أرشفها دعم Waafir، أو التي أُرشفت مع مؤسستها (CONFLICT، الرمزSUPPORT_RESTORE_ONLY): فلا يستطيع استعادتها إلا الدعم. - تُرفض ما دام الاشتراك غير نشط أو كان الفريق متجاوزًا حد مقاعده.
dataroom_rename
يعيد تسمية غرفة بيانات.
- النطاق:
write، ويجب أن يكون مالك الرمز ضمن فريق الصفقة. - المدخلات:
dataroom_id،name(كلاهما مطلوب). يُقصّ الاسم ويجب أن يكون من 1 إلى 100 حرف. - المخرجات:
{ success: true, dataroom_id, name }. - يسجّل مسار التدقيق الاسم القديم والاسم الجديد.
أدوات الفريق
فريق المؤسسة على مستوى المؤسسة كلها، لذا يُرفض الرمز المقيّد بغرف بيانات محددة
(FORBIDDEN، الرمز PAT_ROOM_SCOPED).
dataroom_team_list_members
يسرد الأعضاء النشطين في المؤسسة. ولا تُدرج الدعوات المعلّقة.
- النطاق:
read، ويجب أن يكون مالك الرمز ضمن فريق الصفقة. - المدخلات: لا شيء.
- المخرجات:
{ members: [{ membership_id, user_id, email, name, role, last_active_at }] }. قيمةroleهي إحدىownerأوadminأوmember.
تحتاج عمليات الكتابة أدناه إلى رمز بالنطاق admin يكون مالكه مالكًا أو مسؤولًا في
المؤسسة. والأدوات الأربع الموسومة بأنها على خطوتين تعيد معاينة
وconfirm_token في الاستدعاء الأول، ولا تنفّذ إلا عند تكرارها معه.
dataroom_team_invite_member
يدعو شخصًا عبر البريد الإلكتروني. على خطوتين؛ ويؤدي التأكيد إلى إرسال بريد الدعوة.
- النطاق:
admin، إضافةً إلى منحة الإرسال إلى أشخاص خارج مؤسستك. - المدخلات:
email،role(ownerأوadminأوmember) (مطلوبان)؛confirm_token. - المخرجات:
{ membership_id, email, role, status: "pending" }. ولا يتضمن رابط الدعوة أبدًا. - لا يستطيع دعوة مالك إلا مالك. وينطبق حد المقاعد وحدود الدعوات اليومية.
dataroom_team_change_member_role
يغيّر دور عضو نشط. على خطوتين؛ وتعرض المعاينة الدور القديم والجديد.
- النطاق:
admin. - المدخلات:
membership_id،role(مطلوبان)؛confirm_token. - المخرجات:
{ success: true, membership_id, old_role, role }. - لا يستطيع تغيير دور مالك أو الترقية إلى مالك إلا مالك. ولا يمكنك تغيير دورك أنت، ولا يمكن تخفيض دور آخر مالك.
dataroom_team_remove_member
يزيل عضوًا، أو يلغي دعوة معلّقة. على خطوتين؛ وتعرض المعاينة عدد ما سينتهي من منح الملفات والمجلدات وروابط المشاركة الخاصة بالعضو.
- النطاق:
admin. - المدخلات:
membership_id(مطلوب)؛confirm_token. - المخرجات:
{ success: true, membership_id, action, file_grants_ended?, folder_grants_ended?, share_links_deactivated? }. - تُنهي الإزالة منحه في هذه المؤسسة وتعطّل روابط المشاركة التي أنشأها؛ أما حالات الرفض فتبقى. ولا يستطيع إزالة مالك إلا مالك.
dataroom_team_resend_invite
يرسل دعوة معلّقة مجددًا برابط جديد؛ ويتوقف الرابط القديم عن العمل. على خطوتين؛ ويؤدي التأكيد إلى إرسال بريد الدعوة.
- النطاق:
admin، إضافةً إلى منحة الإرسال إلى أشخاص خارج مؤسستك. - المدخلات:
membership_id(مطلوب)؛confirm_token. - المخرجات: المعاينة (
membership_id،email،role) في الاستدعاء الأول؛ و{ success: true, membership_id }بعد التأكيد. - لا يمكن إعادة إرسال إلا دعوة معلّقة: أي عضوية أخرى تُرفض عند المعاينة، دون رمز. وتُحتسب حدود الدعوات اليومية عند التأكيد.
أدوات المستثمرين واتفاقيات عدم الإفصاح
أدوات تعمل على قائمة مستثمريك، واتفاقية عدم الإفصاح (NDA) الخاصة بمؤسستك، واتفاقيات عدم الإفصاح الخاصة بشركات المستثمرين لديك. تفحص كل أداة الدور الحالي لمالك الرمز في مؤسستك عند كل استدعاء، لذا يُرفض الشخص الذي خُفّض دوره منذ ذلك الحين، أو الرمز المحدود بدور أدنى مما تحتاجه الأداة.
تحتاج الأدوات التي تقرأ عبر المؤسسة كلها إلى رمز غير مقيّد بغرف بيانات بعينها. ولا تتضمن القائمة حقائق التفاعل (متى فتح الشخص الغرفة آخر مرة، وكم رسالة دعوة أُرسلت، ومتى قبل) إلا لرمز أُنشئ مع تفعيل قراءة تحليلات المشاركة. ولا تتضمن أبدًا روابط الإعفاء من اتفاقية عدم الإفصاح أو معرّفات المستخدمين.
تتطلب دعوة مستثمر، وإزالة وصوله أو استعادته، وتغيير صلاحياته، وإرفاق اتفاقية عدم
إفصاح لشركة أو إلغاؤها، كلٌّ منها خطوتين. فالاستدعاء الأول لا يغيّر شيئًا: بل
يعيد معاينة لما سيحدث بالضبط وconfirm_token. ويعرض عليك مساعدك المعاينة، ولا
يكرر الاستدعاء بوسائط مطابقة إضافةً إلى ذلك confirm_token إلا بعد موافقتك. ويعمل
الرمز مرة واحدة وتنتهي صلاحيته بعد بضع دقائق. وإذا تغيّر أي شيء عرضته المعاينة في
الأثناء، يُرفض الاستدعاء الثاني ويسألك مساعدك مجددًا.
dataroom_list_investors
يسرد المستثمرين المدعوين إلى مؤسستك، أو إلى غرفة بيانات واحدة.
- النطاق:
read. الدور: مالك أو مسؤول. - المدخلات:
dataroom_id(اختياري؛ مطلوب لرمز مقيّد بغرف بيانات بعينها)؛status(اختياري:pendingأوacceptedأوrevokedأوaccess_requested). - المخرجات:
{ investors: [{ id, email, display_name, role, status, require_nda, nda, investor_org, can_view_monitoring, can_view_updates, expires_at, invited_at }] }. والقيمةidهي معرّف الدعوة الذي تأخذه أدوات المستثمرين الأخرى. ومع قراءة تحليلات المشاركة، يحتوي كل صف أيضًا علىengagement: { last_seen_at, send_count, last_sent_at, accepted_at }.
dataroom_get_nda
يقرأ اتفاقية عدم الإفصاح الخاصة بمؤسستك: عنوان الإصدار الحالي ونصه وبنوده، وسجل
الإصدارات. ويعيد current: null عندما لا تكون للمؤسسة اتفاقية عدم إفصاح بعد؛
وقراءتها لا تنشئ واحدة أبدًا.
- النطاق:
read. الدور: عضو في فريق الصفقة. - المدخلات: لا شيء.
- المخرجات:
{ current, versions, clauses, tally }. وتكونtally(أعداد الموقّعة والمعفاة والمعلّقة) مساوية لـnullلرمز مقيّد بغرف بيانات بعينها.
dataroom_list_firm_ndas
يسرد شركات المستثمرين لدى مؤسستك وما إذا كانت لكل منها اتفاقية عدم إفصاح سارية للشركة.
- النطاق:
read. الدور: عضو في فريق الصفقة. يحتاج إلى رمز غير مقيّد بغرف بيانات بعينها. - المدخلات: لا شيء.
- المخرجات:
{ firms: [{ id, name, has_live_nda }] }.
dataroom_get_firm_nda
يقرأ اتفاقية عدم الإفصاح بين شركة واحدة ومؤسستك، ومظاريف التوقيع الإلكتروني المكتملة التي يمكنك إرفاقها بوصفها اتفاقية عدم الإفصاح الخاصة بها.
- النطاق:
read. الدور: عضو في فريق الصفقة. يحتاج إلى رمز غير مقيّد بغرف بيانات بعينها. - المدخلات:
investor_org_id(مطلوب). - المخرجات:
{ agreement, attachable_envelopes }. وتكونagreementمساوية لـnullعندما لا تكون للشركة اتفاقية.
dataroom_extend_investor_access
يمدّد وصول دعوة مقبولة بمدة انتهاء رابط الضيف المعتمدة في مؤسستك (7 أيام ما لم تغيّرها)، ويُبقي جلسة المستثمر الحالية نشطة طوال تلك المدة. لدعوة إلى غرفة بيانات فقط.
- النطاق:
write. الدور: عضو في فريق الصفقة. يحتاج إلى: الإرسال إلى أشخاص خارج مؤسستك. - المدخلات:
invite_id(مطلوب). - المخرجات:
{ invite_id, expires_at, expiry_hours }. وتُرفض الدعوة غير المقبولة بتعارض.
dataroom_invite_investor
يدعو مستثمرًا إلى غرفة بيانات عبر البريد الإلكتروني، أو يعيد دعوته بدور جديد أو
اشتراط جديد لاتفاقية عدم الإفصاح، أو يعيد إرسال دعوته. ويتلقى بريدًا إلكترونيًا
برابط شخصي ما لم تكن notify مساوية لـ false. وتبيّن المعاينة ما إذا كان هذا
سينشئ الدعوة أو يحدّثها أو يُبقيها، وأيّ وسائطك سيُتجاهل (إعادة الإرسال تُبقي الدور
واتفاقية عدم الإفصاح المخزّنين)، وتغيّر الحالة (يُستعاد المستثمر المُزال)، وأي إعفاء
من اتفاقية عدم الإفصاح، وما إذا كان سيُرسل بريد إلكتروني. ولا تستهلك المعاينة شيئًا
من حد الدعوات اليومي؛ أما الإرسال فيستهلكه.
- النطاق:
admin. الدور: مالك أو مسؤول، ضمن فريق الصفقة لغرفة البيانات. يحتاج إلى: الإرسال إلى أشخاص خارج مؤسستك. - المدخلات:
email،dataroom_id(مطلوبان)؛role(viewerأوdownloader)؛require_nda؛resend؛notify؛confirm_token. - المخرجات: المعاينة و
confirm_tokenفي الاستدعاء الأول؛ ثم{ status: 'sent' | 'added', invite_id, link_expires_at }.
dataroom_revoke_investor_access
يزيل وصول مستثمر. تنتهي جلسته الحالية ومنحه على الملفات والمجلدات في غرفة البيانات الخاصة بالدعوة. وإعادة تفعيله لاحقًا تستعيد الوصول إلى الغرفة، لا منح الملفات.
- النطاق:
admin. الدور: مالك أو مسؤول. - المدخلات:
invite_id(مطلوب)؛confirm_token. - المخرجات: المعاينة و
confirm_token؛ ثم{ status: 'revoked', invite_id }.
dataroom_reinstate_investor_access
يعيد تفعيل مستثمر مُزال، أو يوافق على طلب وصول. الوصول إلى الغرفة فقط.
- النطاق:
admin. الدور: مالك أو مسؤول. يحتاج إلى: الإرسال إلى أشخاص خارج مؤسستك. - المدخلات:
invite_id(مطلوب)؛confirm_token. - المخرجات: المعاينة و
confirm_token؛ ثم{ status: 'reinstated', invite_id }.
dataroom_set_investor_permissions
يغيّر دور الدعوة، واشتراط اتفاقية عدم الإفصاح، والوصول إلى المتابعة والتحديثات. وتسرد المعاينة كل تغيير. وإيقاف اتفاقية عدم الإفصاح يسجّل إعفاءً باسمك، مع سبب ورابط اختياريين.
- النطاق:
admin. الدور: مالك أو مسؤول. - المدخلات:
invite_id(مطلوب)؛ واحد على الأقل منrole،require_nda،can_view_monitoring،can_view_updates؛nda_waiver_reason؛nda_waiver_url؛confirm_token. - المخرجات: المعاينة و
confirm_token؛ ثم{ status: 'updated', invite_id, changes }.
dataroom_attach_firm_nda
يسجّل مظروف توقيع إلكتروني مكتملًا بوصفه اتفاقية عدم الإفصاح المنفَّذة لشركة مستثمرين، مع تاريخ تنفيذها ومدتها. ويمكن إرفاق أي مظروف يمكنك رؤيته.
- النطاق:
admin. الدور: مالك أو مسؤول. يحتاج إلى رمز غير مقيّد بغرف بيانات بعينها. - المدخلات:
investor_org_id،envelope_id،executed_at،term(مطلوبة)؛confirm_token. - المخرجات: المعاينة و
confirm_token؛ ثم{ status: 'attached', agreement }.
dataroom_revoke_firm_nda
يلغي اتفاقية عدم الإفصاح لشركة مستثمرين. واتفاقية عدم الإفصاح التي بدأت على Waafir ولا تزال قيد التوقيع يُبطَل مظروفها أيضًا.
- النطاق:
admin. الدور: مالك أو مسؤول. يحتاج إلى رمز غير مقيّد بغرف بيانات بعينها. - المدخلات:
investor_org_id(مطلوب)؛reason؛confirm_token. - المخرجات: المعاينة و
confirm_token؛ ثم{ status: 'revoked', investor_org_id, envelope_voided }.
أدوات شركات المستثمرين
أدوات تعمل على شركات المستثمرين لديك: المجموعات التي ينتمي إليها مستثمروك، كما في صفحة المستثمرين. تحتاج كل منها إلى دور مالك أو مسؤول في مؤسستك، يُفحص عند كل استدعاء، وإلى رمز غير مقيّد بغرف بيانات بعينها. والشركة غير المعروفة، وشركة مؤسسة أخرى، والشركة التي دُمجت في غيرها، تتلقى كلها إجابة "غير موجود" نفسها.
يتطلب وضع شخص في شركة ودمج شركتين كلٌّ منهما خطوتين، مثل أدوات المستثمرين أعلاه. ويمكن لكليهما نقل شخص من شركته الحالية. وإذا كانت للشركة التي ينضم إليها اتفاقية عدم إفصاح منفَّذة، فإنها تشمله من ذلك الحين، وتتوقف دعواته المعلّقة التي تطلب اتفاقية عدم إفصاح عن طلبها. وعندما تسرد المعاينة دعوة كهذه، يحتاج الرمز أيضًا إلى الإرسال إلى أشخاص خارج مؤسستك. أما إزالة شخص من شركة فغير متاحة هنا.
dataroom_list_investor_firms
يسرد شركات المستثمرين لدى مؤسستك مع نطاقها (domain)، وعدد أعضائها، والملاحظة الخاصة لفريق الصفقة، وحالة اتفاقية عدم الإفصاح الخاصة بالشركة.
- النطاق:
read. الدور: مالك أو مسؤول. - المدخلات: لا شيء.
- المخرجات:
{ investor_firms: [{ id, name, canonical_domain, member_count, deal_team_note, firm_nda }] }. وتُعلَّمdeal_team_noteبوصفها نصًا كتبه زميل.
dataroom_create_investor_firm
ينشئ شركة مستثمرين. ومع member_emails وcanonical_domain، يصبح عضوًا كلُّ شخص
مُدرج على ذلك النطاق يكون مدعوًا بالفعل إلى إحدى غرف البيانات لديك ولا ينتمي إلى
أي شركة بعد. ولا يُنقل أحد من شركة أخرى.
- النطاق:
admin. الدور: مالك أو مسؤول. - المدخلات:
name(مطلوب)؛canonical_domain؛member_emails(حتى 500، يحتاج إلىcanonical_domain). - المخرجات:
{ status: 'created', investor_firm: { id, name }, added }.
dataroom_rename_investor_firm
يعيد تسمية شركة مستثمرين.
- النطاق:
admin. الدور: مالك أو مسؤول. - المدخلات:
investor_org_id،name(مطلوبان). - المخرجات:
{ status: 'renamed' | 'unchanged', investor_org_id, name }.
dataroom_set_investor_firm_note
يضبط الملاحظة الخاصة لفريق الصفقة على شركة أو يمسحها. ولا يراها المستثمرون أبدًا.
- النطاق:
admin. الدور: مالك أو مسؤول. - المدخلات:
investor_org_id،note(مطلوبان؛ السلسلة الفارغة تمسحها). - المخرجات:
{ status: 'set' | 'cleared' | 'unchanged', investor_org_id, cleared }.
dataroom_assign_investor_to_firm
يضع مستثمرًا، عبر بريده الإلكتروني، في شركة، وينقله من شركته الحالية إن كانت له واحدة. وتسمّي المعاينة الشركة التي يغادرها والدعوات المعلّقة التي ستستوفي اتفاقيةُ عدم الإفصاح الخاصة بالشركة الآن خطوةَ اتفاقية عدم الإفصاح فيها. ومن هو في الشركة بالفعل يُترك كما هو، دون خطوة تأكيد.
- النطاق:
admin. الدور: مالك أو مسؤول. يحتاج إلى: الإرسال إلى أشخاص خارج مؤسستك عندما تسرد المعاينة دعوة. - المدخلات:
investor_org_id،email(مطلوبان)؛confirm_token. - المخرجات: المعاينة و
confirm_token؛ ثم{ status: 'assigned', investor_org_id, email, moved_from, coverage_started }.
dataroom_merge_investor_firms
يدمج شركة في أخرى. ينتقل كل عضو في الشركة المصدر إلى الشركة الهدف، وتخرج الشركة المصدر من قائمة شركاتك. ولا يمكنك التراجع عن الدمج من مساعدك أو من التطبيق. وتسرد المعاينة الأشخاص المنتقلين والدعوات المعلّقة التي ستستوفي اتفاقيةُ عدم الإفصاح الخاصة بالشركة الهدف الآن خطوةَ اتفاقية عدم الإفصاح فيها.
- النطاق:
admin. الدور: مالك أو مسؤول. يحتاج إلى: الإرسال إلى أشخاص خارج مؤسستك عندما تسرد المعاينة دعوة. - المدخلات:
source_investor_org_id،target_investor_org_id(مطلوبان، ومختلفان)؛confirm_token. - المخرجات: المعاينة و
confirm_token؛ ثم{ status: 'merged', source_investor_org_id, target_investor_org_id, moved_count, coverage_started_count }.
أدوات التفاعل
أدوات للقراءة فقط حول من قرأ ماذا، ومتى، وكم من الوقت. هذه بيانات سلوكية عن أشخاص
بأسمائهم، لذا تحتاج كل منها إلى رمز أُنشئ مع تفعيل قراءة تحليلات المشاركة، وإلى
دور في فريق الصفقة. ولا تحتسب كل أداة إلا المستندات التي يستطيع مالك الرمز قراءتها
بنفسه. وتأخذ أدوات الغرفة المرشّح نفسه الخاص بصفحة التفاعل: range (أو from
وto)، وpeople، وfirm_ids، وfolder_id، وtz.
dataroom_get_activity_trail
سجل الوصول الخاص بمؤسستك، الأحدث أولًا. يحتاج إلى رمز غير مقيّد بغرف بيانات بعينها.
- النطاق:
read. المدخلات:counterparty،since،cursor،limit.
dataroom_get_room_engagement
لوحة النتائج والخريطة الحرارية والخط الزمني لغرفة بيانات واحدة، مع ملخصات الصفقة.
- النطاق:
read. المدخلات:dataroom_id(مطلوب) والمرشّح.
dataroom_get_engagement_scores
درجة تفاعل كل مستثمر في غرفة بيانات واحدة، مرتبةً.
- النطاق:
read. المدخلات:dataroom_id(مطلوب) والمرشّح.
dataroom_get_investor_engagement
زيارات مستثمر واحد والمستندات التي فتحها في غرفة بيانات واحدة. ويُسجَّل هذا العرض في سجل التدقيق لديك، كما في Waafir.
- النطاق:
read. المدخلات:dataroom_id،email(مطلوبان) والمرشّح.
dataroom_get_document_engagement
القراءة لكل مستند بحسب الطرف المقابل عبر مؤسستك، ومع file_id، الوقت المستغرق في
كل صفحة من ذلك المستند. يحتاج إلى رمز غير مقيّد بغرف بيانات بعينها.
- النطاق:
read. المدخلات:counterparty،file_id،weeks،cursor،limit،page_range.
dataroom_get_firm_rollups
النشاط الأسبوعي لكل طرف مقابل عبر مؤسستك. يحتاج إلى رمز غير مقيّد بغرف بيانات بعينها.
- النطاق:
read. المدخلات:counterparty،weeks،cursor،limit.
أدوات الأسئلة والأجوبة
أداتان للقراءة فقط تعملان على سلاسل الأسئلة والأجوبة للمستثمرين في غرفة بيانات. لا
يستطيع رمز فريق الصفقة نشر سؤال هنا؛ إذ يسأل الوكيل الخاص بالمستثمر نفسه باستخدام
dataroom_ask_question (راجع أدوات وكيل المستثمر).
ما يعيده الاستدعاء يعتمد على مالك الرمز:
- يرى عضو فريق الصفقة كل سلسلة في غرفة البيانات، بما في ذلك عنوان البريد الإلكتروني لصاحب السؤال؛
- ولا يرى المستثمر إلا الأسئلة التي طرحها بنفسه، ولا يرى أي عناوين بريد إلكتروني إطلاقًا.
تعود المستندات المرفقة بوصفها معرّفًا واسمًا فقط — لا محتوى أبدًا، ولا رابط تنزيل أبدًا — ويُحجب اسم المستند الذي لا يحق للمستدعي رؤيته. استخدم أدوات المستندات للمحتوى؛ فهي تطبّق فحوص الوصول الخاصة بها. أما أسئلة "أسئلة المستثمرين" (Company Q&A) على مستوى المؤسسة، غير المرتبطة بغرفة بيانات، فلا تعيدها أيٌّ من الأداتين أبدًا.
dataroom_list_questions
اسم نقطة نهاية المجال: list_questions
يسرد سلاسل الأسئلة والأجوبة في غرفة بيانات واحدة مخوَّل بها، الأحدث أولًا، كلٌّ منها مع إجاباتها.
- النطاق:
read. - المدخلات:
dataroom_id(مطلوب)؛status(اختياري —openأوansweredأوclosed)؛file_id(اختياري — الأسئلة المطروحة عن ذلك المستند فقط)؛limit(اختياري، 1–100، الافتراضي 25)؛offset(اختياري، الافتراضي 0). - المخرجات:
{ questions, pagination }. تنقّل بين الصفحات باستخدامoffsetما دامتpagination.has_moreمساوية لـtrue.
dataroom_get_question
اسم نقطة نهاية المجال: get_question
يجلب سلسلة أسئلة وأجوبة واحدة بمعرّفها، مع جميع إجاباتها.
- النطاق:
read. - المدخلات:
dataroom_id(مطلوب)؛question_id(مطلوب). - المخرجات:
{ question }. - السؤال الموجود في غرفة بيانات أخرى أو مؤسسة أخرى — أو، بالنسبة إلى المستثمر، الذي
طرحه شخص آخر — يبلّغ بـ
NOT_FOUND. ولا تؤكد الأداة أبدًا وجود مثل هذا المعرّف.
يحمل كل سؤال { id, dataroom_id, title, body, question_type, status, asked_by, file_id, file_name, created_at, updated_at, responses }، إضافةً إلى
asker_email فقط حيث يحق للمستدعي الحصول عليه — أما للمستثمر فيكون المفتاح غائبًا
عن الحمولة بدلًا من أن يكون موجودًا بقيمة null. وكل عنصر في
responses هو { id, body, responded_by, is_ai_draft, created_at, updated_at, attachments }.
dataroom_answer_question (كتابة)
يجيب عن سؤال مستثمر. لا توجد مسودة: يرى المستثمر الإجابة فورًا، ويُرسَل إلى صاحب السؤال بريد إلكتروني إن سمحت إعداداته. ولا يمكن استرجاع أيٍّ منهما.
- النطاق:
write. أعضاء فريق الصفقة لغرفة البيانات. - المنحة: يحتاج الرمز إلى الإرسال إلى أشخاص خارج مؤسستك.
- المدخلات:
dataroom_id،question_id،body(جميعها مطلوبة)؛confirm_token. - خطوتان. بدون
confirm_tokenلا يُنشر شيء وتحصل على معاينة (السؤال، وعدد إجاباته، وما إذا كان صاحب السؤال سيتلقى بريدًا إلكترونيًا) إضافةً إلى رمز. استدعِ الأداة مجددًا بالوسائط نفسها والرمز للنشر. وإذا وردت إجابة جديدة أو أُغلقت السلسلة في الأثناء يُخفق الاستدعاء، وتعاين مجددًا.
dataroom_close_question (كتابة)
يغلق سلسلة أسئلة وأجوبة واحدة. ويمكن لصاحب السؤال، أو لمسؤول أو مدير في المؤسسة، إغلاقها.
- النطاق:
write. - المدخلات:
dataroom_id،question_id(كلاهما مطلوب). - المخرجات:
{ question_id, outcome, kb_draft, kb_draft_skip_reason }. - عندما تدفع المؤسسة مقابل الذكاء الاصطناعي وتفعّله، فإن إغلاق سلسلة لها إجابات
يضع أيضًا مسودة لقاعدة المعرفة في قائمة الانتظار. وإلا فتكون
kb_draftمساوية لـskippedويوضّح السببُ المُعاد علّةَ ذلك. ولا يُرسل شيء إلى المستثمر.
dataroom_bulk_close_questions (كتابة)
يغلق حتى 100 سلسلة من غرفة بيانات واحدة. ويُحكم على كل منها على حدة.
- النطاق:
write. - المدخلات:
dataroom_id،question_ids(كلاهما مطلوب). - المخرجات:
{ requested, closed, results }. وقيمةoutcomeلكل نتيجة هيclosedأوnot_foundأوforbiddenأوalready_closed.
dataroom_edit_question (كتابة)
يعدّل عنوان السؤال و/أو متنه. للمسؤولين والمديرين فقط.
- النطاق:
write. - المدخلات:
dataroom_id،question_id(كلاهما مطلوب)؛title،body(واحد على الأقل). - المخرجات:
{ question_id, title, body }.
dataroom_edit_answer (كتابة)
يعدّل نص إجابة. للمسؤولين والمديرين فقط. ويرى المستثمر التعديل فورًا، كما في Waafir؛ ولا يُرسل بريد إلكتروني جديد.
- النطاق:
write. - المدخلات:
dataroom_id،question_id،response_id،body(جميعها مطلوبة). - المخرجات:
{ response_id, question_id, body }.
dataroom_delete_question (كتابة)
يحذف سلسلة أسئلة وأجوبة. ويتوقف المستثمرون عن رؤيتها ورؤية إجاباتها. للمسؤولين والمديرين فقط.
- النطاق:
write. - المدخلات:
dataroom_id،question_id(كلاهما مطلوب)؛confirm_token. - خطوتان. بدون
confirm_tokenلا يُحذف شيء وتحصل على معاينة إضافةً إلى رمز. استدعِ الأداة مجددًا بالوسائط نفسها والرمز للحذف. ويعمل الرمز مرة واحدة وتنتهي صلاحيته بعد بضع دقائق.
dataroom_delete_answer (كتابة)
يحذف إجابة واحدة في سلسلة. ويتوقف المستثمر عن رؤيتها. للمسؤولين والمديرين فقط.
- النطاق:
write. - المدخلات:
dataroom_id،question_id،response_id(جميعها مطلوبة)؛confirm_token. - خطوتان، كما في
dataroom_delete_question.
dataroom_publish_kb_article (كتابة)
ينشر مقالة في قاعدة المعرفة، كمسودة أُعدّت من سلسلة مغلقة مثلًا. ويمكن للمستثمرين الذين يرون غرفة البيانات قراءتها بعد ذلك. للمسؤولين والمديرين فقط.
- النطاق:
write. - المدخلات:
dataroom_id،article_id(كلاهما مطلوب)؛confirm_token. - خطوتان، كما في
dataroom_delete_question.
أدوات تحديثات المستثمرين
تطابق هذه الأدوات محرر تحديثات المستثمرين في Waafir، مع فحوص الأدوار نفسها. وتحتاج كل منها إلى الإضافة مواد المستثمرين (Investor Materials) على غرفة البيانات. ولا ترسل أيٌّ منها شيئًا إلى المستثمرين: فالنشر يتم في Waafir.
dataroom_list_updates
يسرد تحديثات المستثمرين لغرفة بيانات بجميع حالاتها، الأحدث تغييرًا أولًا.
- النطاق:
read. أعضاء فريق الصفقة لغرفة البيانات. - المدخلات:
dataroom_id(مطلوب). - المخرجات:
{ updates }، كلٌّ منها{ id, title, period_label, status, version, published_at, updated_at }.
dataroom_create_update (كتابة)
ينشئ مسودة تحديث من محافظ و/أو ملفات (واحد على الأقل).
- النطاق:
write. أعضاء فريق الصفقة لغرفة البيانات. - المدخلات:
dataroom_id،period_label(كلاهما مطلوب)؛title،period_start،period_end،tone_notes،portfolio_ids،file_ids. - المخرجات:
{ update_id, status, portfolio_count, file_count }. والملفات والمحافظ غير الموجودة في مؤسستك تُستبعد ولا تُحتسب.
dataroom_get_update
يقرأ تحديثًا واحدًا كما يعرضه المحرر.
- النطاق:
read. المالكون والمسؤولون. - المدخلات:
dataroom_id،update_id(كلاهما مطلوب). - المخرجات:
{ update_id, status, document, latest_generation }. وdocumentهو أحدث مسودة مولَّدة مع تطبيق تعديلاتك، أو null قبل التوليد الأول.
dataroom_get_update_generation
حالة عملية توليد.
- النطاق:
read. المالكون والمسؤولون. - المدخلات:
dataroom_id،update_id،generation_id(جميعها مطلوبة). - المخرجات:
{ generation_id, status, error_code }. والعملية الفاشلة تعطي رمزها، وليس الرسالة المخزّنة أبدًا.
dataroom_generate_update (كتابة)
يبدأ توليدًا بالذكاء الاصطناعي لتحديث في حالة مسودة أو قيد المراجعة.
- النطاق:
write، إضافةً إلى قراءة محتوى المستند على الرمز: تقرأ العملية الملفات المحددة كاملةً، مسترشدةً بملاحظات النبرة الخاصة بالتحديث. المالكون والمسؤولون. - المدخلات:
dataroom_id،update_id(كلاهما مطلوب). - المخرجات:
{ generation_id, queued }. استطلعdataroom_get_update_generation. - يحتاج إلى خطة مدفوعة وتفعيل ميزات الذكاء الاصطناعي، ويُحتسب ضمن حد الذكاء الاصطناعي اليومي. ويتشارك مع المحرر حد 5 عمليات توليد في الدقيقة.
dataroom_edit_update_draft (كتابة)
يحفظ تعديلاتك فوق المحتوى المولَّد للمسودة، كما يفعل المحرر.
- النطاق:
write. المالكون والمسؤولون. - المدخلات:
dataroom_id،update_id،overrides(جميعها مطلوبة). وتأخذoverridesالقيمnarrative_sectionsوchart_placementsوcitations. - المخرجات:
{ update_id, status, document }. ولا يمكن تعديل إلا المسودة.
dataroom_submit_update_for_review (كتابة)
ينقل مسودة تحديث إلى in_review.
- النطاق:
write. المسؤولون والمديرون. - المدخلات:
dataroom_id،update_id(كلاهما مطلوب). - المخرجات:
{ update_id, status }. - يحتاج التحديث إلى محتوى مولَّد وعدم وجود عملية توليد جارية.
dataroom_publish_update (كتابة)
ينشر تحديثًا قيد المراجعة. ويستطيع مستثمرو غرفة البيانات رؤيته فورًا ويُرسَل إلى كل منهم بريد إلكتروني، ولا يمكن استرجاع ذلك.
- النطاق:
write. المسؤولون والمديرون. - المنحة: يحتاج الرمز إلى الإرسال إلى أشخاص خارج مؤسستك.
- المدخلات:
dataroom_id،update_id(كلاهما مطلوب)؛confirm_token. - خطوتان. بدون
confirm_tokenلا يُنشر شيء وتحصل على معاينة (التحديث وعدد المستثمرين الذين سيتلقون بريدًا إلكترونيًا) إضافةً إلى رمز. استدعِ الأداة مجددًا بالوسائط نفسها والرمز للنشر. وإذا تغيّر التحديث أو قائمة مستثمريه في الأثناء، يُرفض الاستدعاء وتعاين مجددًا.
dataroom_republish_update (كتابة)
ينسخ تحديثًا منشورًا إلى إصدار مسودة جديد تعدّله بعد ذلك وتراجعه وتنشره. ويبقى الإصدار المنشور ساريًا حتى ذلك الحين.
- النطاق:
write. المسؤولون والمديرون. - المدخلات:
dataroom_id،update_id(كلاهما مطلوب). - المخرجات:
{ update_id, status, version }للمسودة الجديدة.
أدوات ذكاء السوق
للقراءة فقط. تحتاج إلى الإضافة ذكاء السوق (Market Intelligence) (تعمل النسخة التجريبية، بحدودها)، وإلى رمز غير مقيّد بغرف بيانات بعينها، وإلى عضو في فريق الصفقة مالكًا له.
mi_get_subject
شركة ذكاء السوق الخاصة بمؤسستك.
- النطاق:
read. - المدخلات: لا شيء.
- المخرجات:
{ subject, access }. وsubjectهو{ id, name }، أو null إلى أن يفتح أحدهم ذكاء السوق في Waafir.
mi_get_profile
الملف التعريفي لشركة: النسخة المؤكدة والمسودة قيد العمل.
- النطاق:
read. - المدخلات:
subject_id(مطلوب). - المخرجات:
{ subject, confirmed, draft, file_names }. وكل حقل يكونstated(معfile_idوpageاللذين قُرئ منهما، أو صفحة ويب عامة واقتباسها)، أوentered، أوnot_applicable، أو null. - لا تُعاد الاقتباسات من مستندات غرفة البيانات. اقرأ الملف باستخدام أدوات المستندات إن احتجت إليها.
mi_list_matches
المستثمرون المرتّبون وفق الملف التعريفي للشركة، الأفضل أولًا.
- النطاق:
read. - المدخلات:
subject_id(مطلوب). - المخرجات:
{ profile_version, preliminary, similarity, live, country, caveat, total, matches }. وكل مطابقة هي{ entity_id, name, score, penalties, reasons, contacts_available, on_roster, addable }. - تعرض النسخة التجريبية أفضل 3. ولا يُستخدم الترتيب بالتشابه إلا عندما تشمل خطتك
الذكاء الاصطناعي المدفوع، ويكون الذكاء الاصطناعي مفعّلًا ويسمح حد الذكاء الاصطناعي اليومي؛ ويبيّن
similarityأيّهما استُخدم. - لا تُعاد بيانات الاتصال أبدًا. ويتشارك مع صفحة Waafir حد 30 في الدقيقة.
أدوات الذكاء الاصطناعي
تنجز هذه الأدوات عمل الذكاء الاصطناعي على جانب Waafir وتسلّم عميل الذكاء الاصطناعي لديك النتيجة: إجابة مع استشهادات، أو ملخصًا، أو مراجعة، أو خطة مجلدات مقترحة، أو مسودة. ولا يحتاج عميلك أبدًا إلى تنزيل المستندات للوصول إلى ذلك. وتحتاج إلى إضافة الذكاء الاصطناعي، وتُحتسب ضمن ميزانية الذكاء الاصطناعي اليومية لمؤسستك، وتتوقف مؤقتًا عندما يوقف مسؤولوك الذكاء الاصطناعي مؤقتًا. وكل منها محدود لكل شخص بالمعدل نفسه الخاص بالزر المقابل في التطبيق، ويسجّل ما أعاده في سجل النشاط.
يمكن أن تكرر الإجابة ما يقوله مستند عندما يكتب عميلك السؤال، لذا تحتاج
dataroom_ask وdataroom_draft_answer
وdataroom_compare_files إلى قراءة محتوى المستند على الرمز، كما تحتاجه
dataroom_get_file_text. وبدونها لا تُسرد، ويُرفض الاستدعاء بالخطأ
GRANT_REQUIRED. أما أدوات الذكاء الاصطناعي الأخرى فتنفّذ مهمة ثابتة على الغرفة
وتعمل بدونها. وتعلّم كل نتيجة الحقول التي تحمل مخرجات الذكاء الاصطناعي في
untrusted_content (راجع النص غير الموثوق في النتائج).
لا تُستخدم أو يُستشهد إلا بالمستندات التي يستطيع مالك الرمز فتحها. وتعمل الأدوات في غرف البيانات التابعة لمؤسسة الرمز نفسها.
dataroom_ask
اطرح سؤالًا عن غرفة بيانات واحدة واحصل على إجابة مستندة إلى المصادر.
- النطاق:
read، إضافةً إلى قراءة محتوى المستند على الرمز. أي عضو في غرفة البيانات. - المدخلات:
dataroom_id(مطلوب)؛question(مطلوب). - المخرجات:
{ dataroom_id, answer, citations }. حتى 10 استشهادات، كلٌّ منها{ source_type, id, title, page? }. لا يُعاد أي نص من المستندات، ولا تُحفظ أي محادثة.
dataroom_summarise_file
يجلب ملخص الذكاء الاصطناعي والنقاط الرئيسية لملف واحد.
- النطاق:
read. فريق الصفقة، مع صلاحية تنزيل الملف. - المدخلات:
dataroom_id(مطلوب)؛file_id(مطلوب). - المخرجات:
{ file_id, file_name, status: "ready", summary, key_points }، أوstatus: "queued"عندما لا يكون للملف ملخص بعد. ويبدأ التلخيص حينئذٍ في الخلفية، كما مع زر التلخيص؛ استدعِ الأداة مجددًا لاحقًا.
dataroom_list_facts
يسرد الحقائق الموثَّقة والمصطلحات الرئيسية المستخرجة من مستندات غرفة بيانات.
- النطاق:
read. فريق الصفقة. - المدخلات:
dataroom_id(مطلوب)؛file_id(اختياري)؛types(اختياري)؛limit(اختياري، 1–200، الافتراضي 50)؛cursor(اختياري). - المخرجات:
{ dataroom_id, facts, has_more, next_cursor }. وكل حقيقة هي{ id, file_id, file_name, fact_type, value, page, confidence, created_at }. وما دامتhas_moreمساوية لـtrue، مرّرnext_cursorمجددًا بوصفهcursorللصفحة التالية. - بدون قراءة محتوى المستند على الرمز، تحتفظ
valueلكل حقيقة بـ 20 كلمة على الأكثر (160 حرفًا)، محسوبةً على القيمة كاملة، وتحمل الحقيقةvalue_truncated.
dataroom_compare_files
يقارن ملفين في غرفة بيانات واحدة ويعيد الفروق الجوهرية.
- النطاق:
read، إضافةً إلى قراءة محتوى المستند على الرمز. فريق الصفقة، مع صلاحية تنزيل الملفين كليهما. - المدخلات:
dataroom_id(مطلوب)؛file_id_a(مطلوب)؛file_id_b(مطلوب). - المخرجات:
{ dataroom_id, file_a, file_b, differences }. وكل عنصر ملف هو{ id, name, truncated }: يُقارَن المستند الطويل جدًا على جزئه الأول، وتبيّنtruncatedذلك. ولا يُعاد أي نص من المستندات. - الملف من نوع لا يحتوي على نص لاستخراجه يُرفض بالرمز
400، والملف المخزّن الذي يتجاوز 50 MB يُرفض بالرمز413(FILE_TOO_LARGE)، قبل جلب أيٍّ منهما، عندما لا يكون نص الملف قد استُخرج بالفعل.
dataroom_review
يشغّل مراجعة الجاهزية بالذكاء الاصطناعي لغرفة بيانات.
- النطاق:
read. فريق الصفقة. - المدخلات:
dataroom_id(مطلوب)؛force_refresh(اختياري). - المخرجات:
{ dataroom_id, cached, readinessScore, presentDocs, missingDocs, flaggedForRedaction, flaggedForRename, flaggedOutOfDate, suggestions }. وتعود المراجعة المخزّنة الحالية دون تشغيل جديد للذكاء الاصطناعي ما لم تكنforce_refreshمساوية لـtrue.
dataroom_propose_organise (كتابة)
الخطوة 1 من 2: يقترح هيكل مجلدات لغرفة بيانات. لا يُنقل شيء.
- النطاق:
write. مالك أو مسؤول. - المدخلات:
dataroom_id(مطلوب). - المخرجات:
{ dataroom_id, suggestion_id, applied: false, proposed_folders, unchanged_file_ids, files, total_files, accounted_for }.
dataroom_apply_organise (كتابة)
الخطوة 2 من 2: يطبّق مقترحًا بواسطة suggestion_id الخاص به. يُطبَّق المقترح المخزّن
بعينه، مرة واحدة؛ ولا يمكن تعديله في الطريق. وتُتخطى الملفات التي لا يحق لمالك الرمز
نقلها وتُحتسب. وللتراجع، استخدم لوحة التنظيم في التطبيق.
- النطاق:
write. مالك أو مسؤول. - المدخلات:
dataroom_id(مطلوب)؛suggestion_id(مطلوب). - المخرجات:
{ dataroom_id, suggestion_id, folders_created, files_moved, files_skipped }.
dataroom_draft_answer
يصوغ مسودة إجابة عن سؤال مستثمر من مستندات غرفة البيانات.
- النطاق:
read، إضافةً إلى قراءة محتوى المستند على الرمز. مالك أو مسؤول. - المدخلات:
question_id(مطلوب). - المخرجات:
{ question_id, draft, is_draft: true, sources }. تُعاد المسودة إليك فقط: لا يُحفظ شيء ولا يُرسل ولا يُنشر. وينشر شخصٌ الإجابة في التطبيق. أما الأسئلة على مستوى المؤسسة فتُصاغ مسوداتها في التطبيق.
أدوات الجاهزية وقاعدة المعرفة
للقراءة فقط. تعيد الجاهزية الدرجة والأعداد التي تقف خلفها، ولا تعيد أبدًا نص
المراجعة؛ شغّل dataroom_review للحصول عليه.
dataroom_get_readiness_score
درجة الجاهزية لغرفة بيانات واحدة.
- النطاق:
read، ويجب أن يكون مالك الرمز مالكًا أو مسؤولًا في المؤسسة. - المدخلات:
dataroom_id(مطلوب). - المخرجات:
{ dataroom_id, score, reviewed, questions_total, questions_answered, kb_articles, files_uploaded, present_categories, missing_categories }. قيمةscoreبين 0 و100، أوnullعندما لا توجد مراجعة بالذكاء الاصطناعي يمكن عرضها عليك.
dataroom_get_readiness_rollup
الجاهزية عبر غرف البيانات في المؤسسة، كما تعرضها لوحة المعلومات.
- النطاق:
read، ويجب أن يكون مالك الرمز ضمن فريق الصفقة. ويُرفض الرمز المقيّد بغرف بيانات محددة. - المدخلات: لا شيء.
- المخرجات:
{ rooms: [{ id, name, investors, reading, updated, status, readinessPct, tone, reviewedAt, presentCount, missingCount, categories }] }. ولا تشمل أعداد المستندات لكل تصنيف إلا المستندات التي يحق لمالك الرمز قراءتها.
dataroom_list_kb_articles
يسرد مقالات قاعدة المعرفة لغرفة، الخاصة بها وتلك التي على مستوى المؤسسة.
- النطاق:
read. - المدخلات:
dataroom_id(مطلوب)؛category؛include_drafts(لفريق الصفقة فقط). - المخرجات:
{ articles: [{ id, title, category, published }] }. - من دخل الغرفة عبر مستند مشترك فقط لا يرى أي مقالات. ورمز المستثمر لا يرى إلا المقالات المنشورة.
dataroom_get_kb_article
يقرأ مقالة واحدة.
- النطاق:
read. - المدخلات:
dataroom_id،article_id(مطلوبان). - المخرجات:
{ id, title, category, body, published, updated_at }. وتُقرأ المسودة على أنها غير موجودة ما لم يكن مالك الرمز ضمن فريق الصفقة.
أدوات وكيل المستثمر
أدوات للوكيل الخاص بالمستثمر نفسه: لا تعمل إلا برمز وصول مستثمر، ورمز فريق الصفقة لا يسردها ولا يستدعيها.
يستطيع رمز المستثمر أيضًا استدعاء هذه الأدوات المشتركة. ولا تجيب كل منها إلا بما يراه المستثمر في غرفة البيانات.
- الغرف والملفات:
dataroom_list،dataroom_get،dataroom_list_folders،dataroom_list_files،dataroom_get_file_metadataوdataroom_search. - اللقطات:
dataroom_list_snapshotsوdataroom_get_snapshot، للّقطات التي يطّلع عليها المستثمر. - التنزيلات:
dataroom_get_file_download_url. وتحمل النسخة دائمًا علامة مائية بهوية المستثمر، كما هو الحال في تنزيله من المتصفح. - الأسئلة والأجوبة والمقالات:
dataroom_list_questions،dataroom_get_question،dataroom_list_kb_articlesوdataroom_get_kb_article. وتعيد هذه أسئلة المستثمر نفسه والمقالات المنشورة. - الذكاء الاصطناعي:
dataroom_ask،dataroom_compare_files،translate_text،translate_fileوtranslate_file_status. وترجمات المستثمر خاصة به.
يُرفض رمز المستثمر في dataroom_get_file_text: فالنص العادي لا يمكنه حمل علامة
مائية، لذا يستخدم الوكيل التنزيل الحامل للعلامة المائية بدلًا من ذلك.
من يدفع مقابل الذكاء الاصطناعي. يكلّف كل استدعاء للذكاء الاصطناعي وحداتٍ من
المخصص. وتدفع مؤسسة الغرفة حتى مخصص شهري لكل مستثمر لكل غرفة (أشهر بتوقيت UTC).
ويضبط فريق الصفقة المخصص لكل غرفة، والقيمة الافتراضية 200 وحدة. وبعد تجاوز المخصص،
تدفع مؤسسة يكون المستثمر عضوًا فيها، إذا كان لديها اشتراك نشط والذكاء الاصطناعي
مفعّل (المؤسسات التي يملكها المستثمر أولًا، ثم الأقدم). وإن لم يتوفر أيٌّ منهما،
يُرفض الاستدعاء قبل أي عمل للنموذج بالخطأ QUOTA_EXCEEDED (HTTP
402). وتذكر الرسالة تاريخ إعادة ضبط المخصص.
حد المعدل. يتشارك وكلاء المستثمر حدًا واحدًا قدره 60 استدعاءً في الدقيقة، عبر جميع رموز ذلك المستثمر واتصالاته. وعند تجاوزه، يُرفض الاستدعاء (HTTP 429) مع مدة الانتظار قبل إعادة المحاولة.
تفحص كل أداة ما تفحصه غرفة البيانات للمستثمر: ألا يكون الوصول منتهيًا أو ملغى، وأن تكون اتفاقية عدم الإفصاح مقبولة، وأن يكون مفتاح الوكيل لكل غرفة الذي يتحكم فيه فريق الصفقة مفعّلًا، وبالنسبة إلى ملف، صلاحية المستثمر في قراءته. والملف الذي لا يستطيع قراءته يُبلَّغ بأنه غير موجود، ولا يُعاد اسمه أبدًا. ويبقى قبول اتفاقية عدم الإفصاح داخل غرفة البيانات.
dataroom_ask_question (كتابة)
يطرح سؤالًا على فريق الصفقة في غرفة بيانات واحدة. لا يراه إلا المستثمر وفريق الصفقة؛ ويُخطَر فريق الصفقة.
- النطاق:
write. - المدخلات:
dataroom_id،title(5 أحرف على الأقل) (مطلوبان)؛description،category،file_id(ملف يستطيع المستثمر قراءته). - المخرجات:
{ question_id, dataroom_id, file_id, status }.
dataroom_list_file_comments
التعليقات التي يستطيع المستثمر رؤيتها على ملف واحد: تعليقاته هو، مع الردود.
- النطاق:
read. - المدخلات:
dataroom_id،file_id(مطلوبان). - المخرجات:
{ comments: [{ id, content, page, resolved, created_at, author, replies }] }.
dataroom_add_file_comment (كتابة)
يعلّق على ملف يستطيع المستثمر قراءته. يكون التعليق مرئيًا للمستثمر ولفريق الصفقة، ولا يكون مرئيًا أبدًا لمستثمرين آخرين.
- النطاق:
write. - المدخلات:
dataroom_id،file_id،content(مطلوبة)؛page. - المخرجات:
{ comment_id, file_id, created_at }.
dataroom_reply_file_comment (كتابة)
يردّ على تعليق يستطيع المستثمر رؤيته. والتعليق على ملف آخر يُبلَّغ بأنه غير موجود.
- النطاق:
write. - المدخلات:
dataroom_id،file_id،comment_id،content(مطلوبة). - المخرجات:
{ reply_id, comment_id, created_at }.
dataroom_get_my_nda_status
وضع اتفاقية عدم الإفصاح للمستثمر في كل غرفة يستطيع وكيله الوصول إليها.
- النطاق:
read. - المدخلات: لا شيء.
- المخرجات:
{ rooms: [{ dataroom_id, dataroom_name, basis, accepted, accepted_at, version, accept_step }] }. قيمةbasisهيorg_standardأوfirm_executedأوfirm_in_progressأوwaivedأوnot_required؛ وقيمةaccept_stepهيclickthroughأوheldأوnone.
dataroom_list_my_notifications
إشعارات المستثمر من مؤسسة الرمز: الدعوات، والإجابات عن أسئلته، والتغييرات على وصوله إلى المجلدات.
- النطاق:
read. - المدخلات:
unread_only؛limit(1–50، الافتراضي 20)؛offset. - المخرجات:
{ notifications: [{ id, type, title, body, resource_type, resource_id, read, created_at }], unread_count, pagination }.
dataroom_mark_notifications_read (كتابة)
يعلّم الإشعارات بأنها مقروءة: المعرّفات المسرودة، أو جميعها باستخدام all: true.
- النطاق:
write. - المدخلات:
ids(1–100) أوall. - المخرجات:
{ marked }، أي عدد ما تغيّر.
dataroom_list_published_updates
تحديثات المستثمرين المنشورة للمستثمر في غرفة واحدة.
- النطاق:
read. - المدخلات:
dataroom_id(مطلوب). - المخرجات:
{ updates: [{ id, title, period_label, version, published_at, unread }] }. - تُرفض عندما يكون فريق الصفقة قد أوقف التحديثات للمستثمر، وعندما لا تمتلك الغرفة الإضافة مواد المستثمرين (Investor Materials).
dataroom_get_published_update
يقرأ تحديثًا منشورًا واحدًا.
- النطاق:
read. - المدخلات:
dataroom_id،update_id(مطلوبان). - المخرجات:
{ update_id, title, period_label, version, published_at, document }.
أدوات اللقطات
اللقطة نسخة مجمّدة من مجلدات الغرفة وإصدارات ملفاتها، يُحتفظ بها لمسار التدقيق. ولا
تعيد أي أداة محتوى ملف أو رابط تنزيل؛ فالتنزيلات تبقى في التطبيق.
وترفض dataroom_get_snapshot وأدوات المطّلعين الرمزَ المقيّد بغرف بيانات محددة، كما
تفعل مسارات التطبيق المقابلة لها.
dataroom_list_snapshots
- النطاق:
read. يرى فريق الصفقة كل لقطة؛ ولا يرى غيرهم إلا اللقطات التي أُضيفوا إليها بصفة مطّلع. - المدخلات:
dataroom_id(مطلوب). - المخرجات:
{ snapshots: [{ id, name, purpose, snapshot_at, file_count, folder_count, viewer_count? }] }.
dataroom_get_snapshot
- النطاق:
read، والوصول إلى اللقطة. - المدخلات:
snapshot_id(مطلوب). - المخرجات:
{ snapshot, folders: [{ folder_id, parent_folder_id, name }], files: [{ file_id, folder_id, name, size_bytes, mime_type, can_download }], can_manage_viewers }. تُستبعد الملفات والمجلدات التي لا يحق لمالك الرمز رؤيتها اليوم، وتطابق الأعداد ما هو مسرود.
dataroom_create_snapshot
يجمّد الغرفة على حالتها الآن. ولا يتغير شيء في الغرفة.
- النطاق:
write، لفريق الصفقة فقط. - المدخلات:
dataroom_id،name(مطلوبان)؛purpose،notes. - المخرجات:
{ snapshot: { id, name, purpose, snapshot_at, file_count, folder_count, viewer_count } }.
dataroom_list_snapshot_viewers
- النطاق:
read، لفريق الصفقة فقط. - المدخلات:
snapshot_id(مطلوب). - المخرجات:
{ viewers: [{ viewer_id, email, granted_at, revoked_at, active }] }.
dataroom_grant_snapshot_viewer
يتيح لشخص فتح لقطة عبر عنوان بريده الإلكتروني. على خطوتين: تسمّي المعاينة اللقطة والعنوان. لا يُرسل أي بريد إلكتروني: أخبره بنفسك.
- النطاق:
write، لفريق الصفقة فقط، إضافةً إلى منحة الإرسال إلى أشخاص خارج مؤسستك. - المدخلات:
snapshot_id،email(مطلوبان)؛confirm_token. - المخرجات:
{ viewer_id, email, active }.
dataroom_revoke_snapshot_viewer
على خطوتين.
- النطاق:
write، لفريق الصفقة فقط. - المدخلات:
snapshot_id،viewer_id(مطلوبان)؛confirm_token. - المخرجات:
{ success: true, viewer_id }.
أدوات روابط المشاركة
يُدخل رابط المشاركة من يحمله إلى غرفة أو مستند، لذا يتطلب إنشاؤه دائمًا خطوتين ورمزًا يحمل منحة الإرسال إلى أشخاص خارج مؤسستك. ولا تسرد أي أداة عنوان URL الخاص بالرابط.
dataroom_list_share_links
- النطاق:
read، ويجب أن يكون مالك الرمز مالكًا أو مسؤولًا في المؤسسة. - المدخلات:
dataroom_id(مطلوب)؛file_idللروابط السارية لمستند واحد. - المخرجات:
{ links: [{ id, kind, file_id?, mode, active, expires_at, has_password, require_nda, domain_allow_list, created_at, admitted_count? }] }. - لا تُسرد الروابط الخاصة بكل مستثمر؛ راجع أدوات المستثمرين.
dataroom_create_share_link
على خطوتين. تبيّن المعاينة ما الذي يُشارَك، ومن يمكنه الدخول، وقاعدة اتفاقية عدم الإفصاح، وموعد انتهاء الصلاحية، وكيف تُوسم التنزيلات بالعلامة المائية. ويجب أن يكرر التأكيد الوسائط نفسها؛ وإذا تغيّرت قائمة المستثمرين في الأثناء، فأكّد مجددًا.
- النطاق:
write، مالك أو مسؤول في المؤسسة، إضافةً إلى منحة الإرسال إلى أشخاص خارج مؤسستك. - المدخلات:
dataroom_id،mode(openأوrestricted) (مطلوبان)؛file_id؛expires_in_hours؛domain_allow_list؛require_nda(الافتراضيtrue)؛confirm_token. - المخرجات:
{ id, url, mode, active, expires_at, require_nda, file_id }. - لا يمكن مشاركة مستند مقيّد عبر رابط. ولا يوجد خيار لكلمة المرور.
dataroom_revoke_share_link
على خطوتين. يفقد كل من يستخدم الرابط وصوله فورًا.
- النطاق:
write، مالك أو مسؤول في المؤسسة. - المدخلات:
dataroom_id،link_id(مطلوبان)؛confirm_token. - المخرجات:
{ success: true, link_id, status: "revoked" }.