Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

Справочник по waafir-dataroom

Сервер waafir-dataroom — стабильная поверхность API в этом релизе. Он предоставляет перечисленные ниже инструменты для чтения ваших комнат данных и управления ими, сгруппированные по назначению: инструменты чтения, инструменты папок, инструменты файлов (жизненный цикл файла и версии файла), инструмент текста документа, инструменты прав доступа и инструменты Q&A.

Подключение: 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), он называет его так, как его указывает эндпоинт, к которому вы подключены. В описаниях на этой странице используются имена эндпоинта области.

Как обеспечивается контроль доступа

На этой странице токен означает учётные данные, которые использует ваш ассистент: подключение, созданное через вход в систему, или личный токен доступа. Оба несут область доступа (scope) и, при необходимости, список комнат данных и ограничены одинаково.

Каждый инструмент выполняется от имени владельца токена и ограничен теми же правилами, которые применяет интерфейс продукта, — более слабого пути через 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Сбой нижестоящего сервиса — не удалось получить сохранённый документ или извлечь из него текстВременная ошибка. Повторите попытку позже, прежде чем считать её фатальной
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_moretrue, если за пределами этой страницы есть ещё строки
next_offsetoffset, который нужно передать для следующей страницы, или 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 (необязательный boolean — 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 }.

Имя на эндпоинте области: 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 инструментам папок и файлов.
  • Не идемпотентен. Каждый вызов создаёт новую комнату. Если результат вызова был потерян, найдите комнату через 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 (необязательный boolean — только предпросмотр).
  • Выходные данные: { 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 (необязательный boolean — только предпросмотр).
  • Выходные данные: { 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"Активного файла с тем же именем нет — создана ожидающая запись с версией 1register_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 МБ — с 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 (обязательный boolean); can_download (обязательный boolean); 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, поиск, Q&A, вопросы к ИИ) отвечают NOT_FOUND, пока она не будет восстановлена. Прямая ссылка на один из её файлов по-прежнему его открывает. dataroom_restore возвращает комнату, поэтому сохраните dataroom_id. Последнюю активную комнату данных архивировать нельзя (CONFLICT). Инструмента, удаляющего комнату данных, не существует.

dataroom_restore

Восстанавливает комнату данных, которую архивировала ваша организация. Она возвращается в списки комнат, и всё, что скрыло архивирование, возвращается вместе с ней: поиск с ИИ, дайджесты, обновления для инвесторов, Q&A и дополнения комнаты. Папки, файлы и доступ остаются такими, какими были, потому что архивирование ничего из этого не меняло. Один вызов, без шага подтверждения.

  • Область доступа: 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

Инструменты для работы со списком ваших инвесторов, NDA вашей организации и NDA ваших инвестиционных фирм. Каждый из них при каждом вызове проверяет текущую роль владельца токена в вашей организации, поэтому человек, которого с тех пор понизили, или токен, ограниченный уровнем ниже роли, нужной инструменту, получает отказ.

Инструментам, читающим данные по всей организации, нужен токен, не ограниченный конкретными комнатами данных. Список инвесторов включает факты вовлечённости (когда человек последний раз открывал комнату, сколько писем с приглашением было отправлено, когда он принял приглашение) только для токена, созданного с включённым разрешением «Читать аналитику взаимодействия». Он никогда не включает ссылки на отказ от NDA или идентификаторы пользователей.

Приглашение инвестора, удаление или восстановление его доступа, изменение его прав, а также прикрепление или отзыв 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

Читает 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 }. 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 записывает отказ от 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 инвестиционной фирмы. Если NDA, начатое в Waafir, всё ещё ожидает подписи, его конверт также аннулируется.

  • Область доступа: admin. Роль: владелец или администратор. Нужен токен, не ограниченный конкретными комнатами данных.
  • Входные данные: investor_org_id (обязательно); reason; confirm_token.
  • Выходные данные: предпросмотр и confirm_token; затем { status: 'revoked', investor_org_id, envelope_voided }.

Инструменты инвестиционных фирм

Инструменты для работы с вашими инвестиционными фирмами — группами, к которым принадлежат ваши инвесторы, как на странице «Инвесторы». Каждому нужна роль владельца или администратора в вашей организации, проверяемая при каждом вызове, и токен, не ограниченный конкретными комнатами данных. Неизвестная фирма, фирма другой организации и фирма, которая была поглощена при слиянии, — все получают одинаковый ответ «не найдено».

Включение человека в фирму и слияние двух фирм выполняются в два шага, как и инструменты инвесторов выше. Оба действия могут вывести человека из его текущей фирмы. Если у фирмы, в которую он вступает, есть исполненное 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.

Инструменты Q&A

Два инструмента только для чтения для веток Q&A инвесторов в комнате данных. Токен команды сделки не может публиковать здесь вопрос; собственный агент инвестора задаёт вопрос через dataroom_ask_question (см. Инструменты агента инвестора).

Результат вызова зависит от того, кому принадлежит токен:

  • участник команды сделки видит все ветки в комнате данных, включая адрес электронной почты автора вопроса;
  • инвестор видит только вопросы, которые задал сам, и никаких адресов электронной почты.

Прикреплённые документы возвращаются только как идентификатор и имя — никогда содержимое, никогда ссылка для скачивания, — а имя документа, который вызывающему видеть не разрешено, скрывается. Для получения содержимого используйте инструменты документов; они применяют собственные проверки доступа. Вопросы раздела «Вопросы и ответы компании» на уровне всей организации, не привязанные к комнате данных, не возвращаются ни одним из этих инструментов.

dataroom_list_questions

Имя на эндпоинте области: list_questions

Перечисляет ветки Q&A в одной разрешённой комнате данных, сначала новые, каждую с её ответами.

  • Область доступа: 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

Получает одну ветку Q&A по идентификатору со всеми её ответами.

  • Область доступа: 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 (запись)

Закрывает одну ветку Q&A. Закрыть её может автор вопроса либо администратор или менеджер организации.

  • Область доступа: 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 (запись)

Удаляет ветку Q&A. Инвесторы перестают видеть её и её ответы. Только администраторы и менеджеры.

  • Область доступа: 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)

Только для чтения. Им нужно дополнение «Рыночная аналитика» (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 МБ — с 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. Применяется ровно сохранённое предложение, один раз; изменить его по пути нельзя. Файлы, которые владельцу токена перемещать не разрешено, пропускаются и подсчитываются. Чтобы отменить, используйте панель упорядочивания (Organise) в приложении.

  • Область доступа: 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

Готовность по комнатам данных организации, как её показывает «Обзор» (Dashboard).

  • Область доступа: 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. Копия всегда помечается водяным знаком с идентификационными данными инвестора, как и при скачивании в его браузере.
  • Q&A и статьи: 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) с указанием времени ожидания перед повторной попыткой.

Каждый инструмент проверяет то же, что комната данных проверяет для инвестора: доступ не истёк и не отозван, 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 (запись)

Помечает уведомления как прочитанные: указанные идентификаторы или все с 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 ссылки.

  • Область доступа: 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" }.