Waafir
本页面为机器翻译,尚待人工审核,可能存在错误。

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 编写的文本:基于文档的 AI 输出、文档自身的文本,或者投资者或同事所写的内容。此类结果会添加 untrusted_content: { source, fields, notice },并在 _meta["io.waafir/untrusted"] 下添加相同的 { source, fields }。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 之外的所有 AI 工具。文件名不带此标记。

失败的报告方式

工具失败不是 HTTP 状态。 当工具拒绝调用时,HTTP 响应仍然是 200,JSON-RPC 信封仍然是成功信封;失败信息包含在结果内部,该结果设置了 isError: true,其文本内容为:

{ "error": { "code": "CONFLICT", "message": "…" } }

请根据 error.code 进行分支,绝不要根据 HTTP 状态:按状态切换的客户端永远匹配不到本页上的任何拒绝。以下是数据室工具返回的代码:

代码含义处理方法
INVALID_ARGUMENT某个参数缺失、格式错误或不是有效的 id修正参数后重试
FORBIDDEN令牌有效但不被允许:权限范围过低、您传入的 dataroom_id 不在其数据室允许列表中,或所有者的角色不允许申请访问权限,或使用具有正确权限范围的令牌
NOT_FOUND没有这样的记录,或该记录不属于您。大多数接受文件或文件夹 id 的工具,对于令牌允许列表之外的数据室中的项目也会返回此代码,与 id 不存在时完全相同检查 id,并确认令牌的范围包含该项目所在的数据室
CONFLICT请求已被理解且被允许,但数据室当前的状态无法执行该操作阅读消息,解决阻塞问题后重试
TOO_LARGE输入超出大小限制拆分输入
QUOTA_EXCEEDED计量额度已用完,或组织的订阅已失效需要有人购买或升级:重试无法解决
UPSTREAM_ERROR下游服务失败:无法获取已存储的文档,或对其进行文本提取失败暂时性错误。请稍后重试,再将其视为致命错误
UNAVAILABLEWaafir 暂时无法处理此请求:文件仍在检查中,已存储的文件无法读取以进行检查,或者读取操作无法记录到审计日志,因此内容被暂扣,而不是在未记录的情况下披露暂时性错误。请稍后重试
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 从旧到新排序,并以 id 作为次级排序依据,使分页保持稳定。total 是此令牌可以访问的数据室总数,在应用允许列表筛选后计算。

dataroom_get

领域端点名称:get_dataroom

按 id 获取单个数据室。调用者必须获得该数据室的授权;限定于其他数据室的令牌会被拒绝。

  • 输入: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 } }。
  • 按名称排序,并以 id 作为次级排序依据,使分页保持稳定。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 类型、大小、文件夹路径、版本列表,以及 AI 摘要/类别(如有)。文件必须属于指定的数据室;其他数据室中的文件(即使属于同一组织)会返回 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 }。

领域端点名称: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 } }。
  • 最新的在前,并以 id 作为次级排序依据,使分页保持稳定。当 has_more 为 true 时,表示查询匹配的文件多于返回的文件:请使用 next_offset 分页,或缩小查询范围。没有 total。

数据室工具

dataroom_create

在令牌所属的组织中创建数据室。

  • 权限范围:write,并且令牌所有者必须属于交易团队。限定于特定数据室的令牌或连接会被拒绝(FORBIDDEN,代码 PAT_ROOM_SCOPED);请使用未限定数据室的令牌或连接。
  • 输入:name(必填,1–100 个字符)。首尾空格会被去除,仅由空格组成的名称会被拒绝(INVALID_ARGUMENT)。
  • 输出:{ id, name }。将 id 作为 dataroom_id 传给文件夹和文件工具。
  • 非幂等。每次调用都会创建一个新的数据室。如果某次调用的结果丢失,请先使用 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 消息会指明冲突文件夹的 id,因此您无需重新列出父文件夹来查找它。

dataroom_rename_folder

领域端点名称:rename_folder

重命名文件夹。该文件夹必须属于调用者的组织。

  • 输入:folder_id(必填);name(必填,1–255 个字符)。
  • 输出:{ folder: { id, name } }。

dataroom_delete_folder

领域端点名称:delete_folder

软删除一个文件夹及其整个子树:所有嵌套的子文件夹以及其中的每个文件。在真实的数据室中,一个文件夹 id 可能涉及数百份文档,因此结果会准确报告删除了多少个文件夹和文件。传入 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。恢复该文件夹以及那次删除随之移除的所有内容;任何更早单独删除的内容仍保持删除状态。如果父文件夹仍处于已删除状态(请先恢复它),或者已有一个现存文件夹占用了该名称,则会返回冲突;在这两种情况下,消息都会指明造成阻塞的文件夹的 id。

  • 输入: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 到该 URL。无法发出带原始二进制正文的 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。返回用于 PUT 字节的 URL 和请求头、文件 id,以及 next_step(即完成此次上传的工具)。如果目标文件夹中已存在同名的有效文件,is_new_version 为 true,返回的 id 和 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 提供的 URL 之后,完成待处理的首次上传:将文件标记为有效、增加组织的存储用量,并记录版本 1。当 request_file_upload 返回 is_new_version: false 时调用它,其 next_step 会指明此工具。

  • 权限范围:write。
  • 输入:file_id(必填,来自 request_file_upload 的待处理 id);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 到 request_file_upload(返回 is_new_version: true)提供的 URL 之后,完成现有文件的新版本。这相当于在界面中替换文档的 MCP 操作,也是 next_step 在该分支上指明的工具。

  • 权限范围:write。
  • 输入:file_id(必填);version_number(必填,即 request_file_upload 返回的 version_number)。
  • 输出:{ 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 即可撤消。
  • 尚未完成首次上传的文件会被拒绝:请先用 register_file 完成版本 1。如果字节实际上尚未进入存储,调用也会失败,而不会记录一个背后没有内容的版本。

dataroom_restore_file_version

领域端点名称:restore_file_version

将文件的某个较早版本重新设为当前版本,即 finalise_file_version 的撤消操作。它会移动当前版本标记,并将文件重新指向该版本;它不会生成新的版本记录,因此版本历史始终如实反映实际上传过的修订。

  • 权限范围:write。
  • 输入:file_id(必填);version_id(必填,必须属于此文件;get_file_metadata 会列出文件的版本 id)。
  • 输出:{ file_id, version_id, version_number, already_current, new_version_created: false }。
  • already_current: true 表示该版本本来就是当前版本,没有任何变化:这是空操作,而不是失败。
  • 没有单独的列出版本的工具:get_file_metadata 已经返回文件的各个版本及其 id、编号和当前标记。

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

删除文件。结果会回显实际被删除的文件的名称,因此错误的 id 会在响应中一目了然。该文件及其版本会为留存和审计而保留,永远不会被抹除,restore_file 可以将其恢复。

  • 权限范围:write。
  • 输入:file_id(必填)。
  • 输出:{ file_id, status: "deleted", name, folder_id, restore_with: "restore_file" }。
  • 只有实际完成的上传才会退还存储额度。字节已落地的文件会将其大小退还给您组织的存储计数器。仍在等待上传的文件从一开始就没有被计费,因此删除它不会改变计数器:此次删除对计数器没有影响,而不是退还您从未存储过的字节。
  • 删除还会丢弃该文件的搜索索引分块,因此该文档会立即从文档搜索中消失。restore_file 无法恢复这些分块,见下文。
  • 该工具只会解析现存文件,因此对同一 id 第二次调用会返回 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检查 id。
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 中。被授予者会收到应用内的“Access Granted”通知。

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 }。
  • 只要有一个文件 id 不在该数据室中,或您无法看到它,整个请求都会以 NOT_FOUND 被拒绝。
  • 每个文件都必须在该数据室中且对您可见,每位被授予者都必须已在该数据室中。如果文件夹上的拒绝规则会抵消任何授予,整个请求会在写入任何文件之前被拒绝。
  • 如果某位被授予者的访问权限已被撤销,add 不会恢复它,该被授予者会被列在 left_revoked_user_ids 中。

dataroom_bulk_revoke_file_permissions

一次性撤销指定用户在多个文件上的直接授予。文件夹授予和数据室访问权限不受影响。

  • 权限范围:admin。
  • 输入:dataroom_id、file_ids(最多 200 个)、user_ids(均为必填)。
  • 输出:{ success: true, revoked_count }。
  • 只要有一个文件 id 不在该数据室中,或您无法看到它,整个请求都会以 NOT_FOUND 被拒绝。

dataroom_get_watermark_settings

读取数据室针对单文件下载和批量下载的下载水印模式:two_layer(下载者身份,加上每次下载的 IP 和日期层),或 static(仅身份)。只读:请在 Waafir 设置中更改。

  • 权限范围:read,且令牌所有者必须是交易团队中的组织管理员。
  • 输入:dataroom_id(必填)。
  • 输出:{ dataroom_id, single, bulk, stored: { single, bulk } }。stored 中的 null 表示该数据室从未设置过此项,因此适用默认值。

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、搜索、问答、AI 提问)都会返回 NOT_FOUND。直接指向其中某个文件的链接仍然可以打开。dataroom_restore 可以恢复该数据室,因此请保留 dataroom_id。最后一个活跃的数据室无法归档(CONFLICT)。没有任何工具可以删除数据室。

dataroom_restore

恢复您组织已归档的数据室。它会回到数据室列表中,归档所隐藏的一切也会随之恢复:AI 搜索、摘要、投资者更新、问答以及该数据室的附加功能。文件夹、文件和访问权限都保持原样,因为归档没有改变其中任何一项。只需一次调用,没有确认步骤。

  • 权限范围:admin,且令牌所有者必须是组织所有者或管理员。
  • 输入:dataroom_id(必填):即 dataroom_archive 返回的 id。
  • 输出:{ 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 工具

针对您的投资者名册、您组织的 NDA 以及您的投资者公司的 NDA 的工具。每个工具在每次调用时都会检查令牌所有者在您组织中的当前角色,因此此后被降级的人,或权限上限低于工具所需角色的令牌,都会被拒绝。

跨整个组织读取的工具需要不限定于特定数据室的令牌。只有对开启了 读取参与度分析 的令牌,名册才会包含参与度信息(某人最后一次打开数据室的时间、发出了多少封邀请电子邮件、他们何时接受)。它永远不包含 NDA 豁免链接或用户 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 是其他投资者工具所使用的邀请 id。如果开启了 读取参与度分析,每一行还会包含 engagement: { last_seen_at, send_count, last_sent_at, accepted_at }。

dataroom_get_nda

读取您组织的 NDA:当前版本的标题、正文和条款,以及版本历史。当组织还没有 NDA 时返回 current: null;读取操作永远不会创建 NDA。

  • 权限范围:read。角色:交易团队成员。
  • 输入:无。
  • 输出:{ current, versions, clauses, tally }。对于限定于特定数据室的令牌,tally(已签署、已豁免和待处理的数量)为 null。

dataroom_list_firm_ndas

列出您组织的投资者公司,以及每家公司是否有有效的公司 NDA。

  • 权限范围:read。角色:交易团队成员。需要不限定于特定数据室的令牌。
  • 输入:无。
  • 输出:{ firms: [{ id, name, has_live_nda }] }。

dataroom_get_firm_nda

读取某家公司与您组织之间的 NDA,以及您可以作为其 NDA 附加的已完成电子签名信封。

  • 权限范围:read。角色:交易团队成员。需要不限定于特定数据室的令牌。
  • 输入:investor_org_id(必填)。
  • 输出:{ agreement, attachable_envelopes }。当该公司没有 NDA 时,agreement 为 null。

dataroom_extend_investor_access

按照您组织的访客链接有效期(除非您更改过,否则为 7 天)延长已接受邀请的访问权限,并让投资者的当前会话保持同样长的时间。仅适用于数据室邀请。

  • 权限范围:write。角色:交易团队成员。需要:发送给组织外的人员。
  • 输入:invite_id(必填)。
  • 输出:{ invite_id, expires_at, expiry_hours }。未被接受的邀请会以冲突被拒绝。

dataroom_invite_investor

通过电子邮件邀请投资者加入数据室,以新的角色或 NDA 要求重新邀请他们,或重新发送其邀请。除非 notify 为 false,否则他们会收到一封包含个人链接的电子邮件。预览会说明此操作是创建、更新还是保留邀请,您的哪些参数将被忽略(重新发送会保留已存储的角色和 NDA),状态变化(已移除的投资者会被恢复),任何 NDA 豁免,以及是否会发出电子邮件。预览不会消耗每日邀请上限;发送才会。

  • 权限范围: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

更改邀请的角色、NDA 要求,以及监控和更新的访问权限。预览会列出每项更改。关闭 NDA 会以您的名义记录一项豁免,并可附带原因和链接。

  • 权限范围: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

将已完成的电子签名信封记录为某家投资者公司已签署的 NDA,并附上其签署日期和期限。您能看到的任何信封都可以附加。

  • 权限范围:admin。角色:所有者或管理员。需要不限定于特定数据室的令牌。
  • 输入:investor_org_id、envelope_id、executed_at、term(必填);confirm_token。
  • 输出:预览和 confirm_token;之后返回 { status: 'attached', agreement }。

dataroom_revoke_firm_nda

撤销投资者公司的 NDA。对于在 Waafir 上发起且仍在等待签署的 NDA,其信封也会被作废。

  • 权限范围:admin。角色:所有者或管理员。需要不限定于特定数据室的令牌。
  • 输入:investor_org_id(必填);reason;confirm_token。
  • 输出:预览和 confirm_token;之后返回 { status: 'revoked', investor_org_id, envelope_voided }。

投资者公司工具

针对您的投资者公司的工具:即您的投资者所属的群组,与“投资者”页面上的相同。每个工具都要求您在组织中拥有所有者或管理员角色(每次调用时都会检查),并且需要不限定于特定数据室的令牌。未知的公司、其他组织的公司以及已被合并掉的公司,都会得到相同的未找到回答。

将某人放入某家公司以及合并两家公司,都与上面的投资者工具一样分两步进行。两者都可能将某人移出其当前所在的公司。如果他们加入的公司有已签署的 NDA,该 NDA 从此会覆盖他们,并且他们要求 NDA 的待处理邀请将不再要求 NDA。当预览列出此类邀请时,令牌还需要 发送给组织外的人员。此处不提供将某人从公司中移除的功能。

dataroom_list_investor_firms

列出您组织的投资者公司,包括其域名、成员数量、交易团队的私人备注以及公司的 NDA 状态。

  • 权限范围: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

通过电子邮件将投资者放入某家公司,如果其当前已属于某家公司,则将其移出。预览会列出其离开的公司,以及该公司的 NDA 现在将满足其 NDA 步骤的待处理邀请。已在该公司中的人保持不变,没有确认步骤。

  • 权限范围:admin。角色:所有者或管理员。需要:当预览列出邀请时,需要 发送给组织外的人员。
  • 输入:investor_org_id、email(必填);confirm_token。
  • 输出:预览和 confirm_token;之后返回 { status: 'assigned', investor_org_id, email, moved_from, coverage_started }。

dataroom_merge_investor_firms

将一家公司合并到另一家公司。源公司的每位成员都会移至目标公司,源公司会从您的公司列表中移除。您无法通过助手或应用撤销合并。预览会列出将被移动的人员,以及目标公司的 NDA 现在将满足其 NDA 步骤的待处理邀请。

  • 权限范围: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 提问(请参阅投资者智能体工具)。

调用返回的内容取决于令牌的所有者是谁:

  • 交易团队成员可以看到数据室中的每个线程,包括提问者的电子邮件地址;
  • 投资者只能看到自己提出的问题,并且完全看不到电子邮件地址。

附加的文档只以 id 和名称 的形式返回:绝不返回内容,也绝不返回下载链接;调用者无权查看的文档的名称会被隐藏。如需内容,请使用文档工具;它们会执行各自的访问检查。不附属于数据室的组织级公司问答问题,这两个工具都永远不会返回。

dataroom_list_questions

领域端点名称:list_questions

列出一个已授权数据室中的问答线程(最新的在前),每个线程都附带其回答。

  • 权限范围:read。
  • 输入:dataroom_id(必填);status(可选:open、answered 或 closed);file_id(可选:仅限针对该文档提出的问题);limit(可选,1–100,默认 25);offset(可选,默认 0)。
  • 输出:{ questions, pagination }。当 pagination.has_more 为 true 时,使用 offset 翻页。

dataroom_get_question

领域端点名称:get_question

按 id 获取一个问答线程及其所有回答。

  • 权限范围:read。
  • 输入:dataroom_id(必填);question_id(必填)。
  • 输出:{ question }。
  • 位于其他数据室或其他组织中的问题(对于投资者而言,还包括由其他人提出的问题)会报告 NOT_FOUND。该工具绝不会确认此类 id 的存在。

每个问题都带有 { 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 }。
  • 当组织为 AI 付费并已开启 AI 时,关闭一个有回答的线程还会将一份知识库草稿加入队列。否则 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 中的投资者更新编辑器相对应,执行相同的角色检查。每个工具都需要数据室启用 投资者资料 附加功能。它们都不会向投资者发送任何内容:发布在 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(写入)

为处于草稿或审核中状态的更新启动 AI 生成。

  • 权限范围:write,且令牌需开启 读取文档内容:该运行会在更新的语气说明指导下完整读取所选文件。所有者和管理员。
  • 输入:dataroom_id、update_id(均为必填)。
  • 输出:{ generation_id, queued }。请轮询 dataroom_get_update_generation。
  • 需要付费套餐并开启 AI 功能,并计入每日 AI 限额。它与编辑器共享每分钟 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 }。

市场情报工具

只读。它们需要 市场情报 附加功能(预览版可用,但有其限制)、一个不限定于特定数据室的令牌,并且令牌所有者须为交易团队成员。

mi_get_subject

您组织的市场情报公司。

  • 权限范围:read。
  • 输入:无。
  • 输出:{ subject, access }。subject 为 { id, name };在有人于 Waafir 中打开市场情报之前为 null。

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 名。只有当您的套餐为 AI 付费、AI 已开启且每日 AI 限额允许时,才会使用相似度排序;similarity 会说明使用的是哪种排序。
  • 永远不会返回联系方式。它与 Waafir 页面共享每分钟 30 次的限制。

AI 工具

这些工具在 Waafir 一侧完成 AI 工作,并将结果交给您的 AI 客户端:带引用的回答、摘要、审查、建议的文件夹方案或草稿。您的客户端无需下载文档即可得到这些结果。它们需要 AI 附加功能,计入您组织的每日 AI 预算,并会在管理员暂停 AI 时暂停。每个工具按人限速,速率与应用中对应按钮相同,并会在活动日志中记录其返回的内容。

当由您的客户端编写问题时,回答可能会复述文档的内容,因此 dataroom_ask、dataroom_draft_answer 和 dataroom_compare_files 需要令牌开启 读取文档内容,与 dataroom_get_file_text 相同。没有它时,这些工具不会被列出,调用会以 GRANT_REQUIRED 被拒绝。其他 AI 工具对数据室执行固定任务,无需此项即可工作。每个结果都会在 untrusted_content 中标出包含 AI 输出的字段(请参阅结果中的不可信文本)。

只有令牌所有者能够打开的文档才会被使用或引用。这些工具只在令牌所属组织的数据室中工作。

dataroom_ask

就某个数据室提出问题,并获得有依据的回答。

  • 权限范围:read,且令牌需开启 读取文档内容。数据室的任何成员。
  • 输入:dataroom_id(必填);question(必填)。
  • 输出:{ dataroom_id, answer, citations }。最多 10 条引用,每条为 { source_type, id, title, page? }。不返回任何文档文本,也不会保存聊天对话。

dataroom_summarise_file

获取单个文件的 AI 摘要和要点。

  • 权限范围: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

对数据室运行 AI 就绪度审查。

  • 权限范围:read。交易团队。
  • 输入:dataroom_id(必填);force_refresh(可选)。
  • 输出:{ dataroom_id, cached, readinessScore, presentDocs, missingDocs, flaggedForRedaction, flaggedForRename, flaggedOutOfDate, suggestions }。除非 force_refresh 为 true,否则会直接返回已存储的当前审查结果,而不会重新运行 AI。

dataroom_propose_organise(写入)

两步中的第 1 步:为数据室建议一个文件夹结构。不会移动任何内容。

  • 权限范围:write。所有者或管理员。
  • 输入:dataroom_id(必填)。
  • 输出:{ dataroom_id, suggestion_id, applied: false, proposed_folders, unchanged_file_ids, files, total_files, accounted_for }。

dataroom_apply_organise(写入)

两步中的第 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;如果没有可以向您展示的 AI 审查,则为 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。这些工具返回投资者自己的问题和已发布的文章。
  • AI:dataroom_ask、dataroom_compare_files、translate_text、translate_file 和 translate_file_status。投资者的翻译仅对其本人可见。

投资者令牌会被拒绝使用 dataroom_get_file_text:纯文本无法携带水印,因此智能体改用带水印的下载。

谁为 AI 付费。 每次 AI 调用都会消耗额度单位。数据室所属组织为每位投资者在每个数据室中支付最多一个月度额度(按 UTC 月计)。交易团队按数据室设置该额度,默认为 200 个单位。超出额度后,如果投资者所属的某个组织拥有有效订阅并已开启 AI,则由该组织付费(优先由投资者拥有的组织付费,其次是最早的组织)。两者都不满足时,调用会在任何模型工作开始之前以 QUOTA_EXCEEDED(HTTP 402)被拒绝。消息会给出额度重置的日期。

速率限制。 一位投资者的所有智能体共享每分钟 60 次调用的限制,涵盖该投资者的所有令牌和连接。超出后,调用会被拒绝(HTTP 429),并告知重试前需要等待的时间。

每个工具都会执行数据室针对该投资者所做的检查:访问权限未过期或被撤销、NDA 已接受、交易团队已开启该数据室的智能体开关,并且对于文件,还要检查投资者对其拥有读取权限。投资者无法读取的文件会报告为不存在,且绝不会返回其名称。接受 NDA 仍需在数据室中进行。

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

投资者在其智能体可访问的每个数据室中的 NDA 状态。

  • 权限范围: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(写入)

将通知标记为已读:列出的 id,或使用 all: true 标记全部。

  • 权限范围:write。
  • 输入:ids(1–100)或 all。
  • 输出:{ marked },即发生变更的数量。

dataroom_list_published_updates

在某个数据室中向该投资者发布的投资者更新。

  • 权限范围:read。
  • 输入:dataroom_id(必填)。
  • 输出:{ updates: [{ id, title, period_label, version, published_at, unread }] }。
  • 当交易团队已为该投资者关闭更新,或该数据室没有 投资者资料附加功能时,会被拒绝。

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。

  • 权限范围: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? }] }。
  • 不会列出每位投资者专属的链接;请参阅投资者工具。

分两步。预览会说明共享的内容、谁可以进入、NDA 规则、过期时间以及下载如何添加水印。确认调用必须重复相同的参数;如果在此期间投资者列表发生了变化,请再次确认。

  • 权限范围: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 }。
  • 受限文档不能通过链接共享。没有密码选项。

分两步。所有使用该链接的人都会立即失去访问权限。

  • 权限范围:write,组织所有者或管理员。
  • 输入:dataroom_id、link_id(必填);confirm_token。
  • 输出:{ success: true, link_id, status: "revoked" }。