Справочник по 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 | Сбой нижестоящего сервиса — не удалось получить сохранённый документ или извлечь из него текст | Временная ошибка. Повторите попытку позже, прежде чем считать её фатальной |
UNAVAILABLE | Waafir сейчас не может выполнить запрос: файл ещё проверяется, сохранённый файл не удалось прочитать для проверки, или чтение не удалось записать в журнал аудита, поэтому содержимое было удержано, а не раскрыто без записи | Временная ошибка. Повторите попытку позже |
INTERNAL | Непредвиденный сбой | Не повторяйте — передайте выше |
Не сводите два кода «повторить позже» к «сбою». UPSTREAM_ERROR и
UNAVAILABLE сегодня приходят от get_file_text и означают спросите ещё раз,
а не сдавайтесь. Клиент, который считает любой результат, отличный от OK,
окончательным, превращает мимолётный сбой в постоянный — это та самая ошибка,
ради предотвращения которой существует эта таблица. Учтите также, что
UNAVAILABLE — это намеренный отказ: Waafir скорее удержит текст документа,
чем выдаст его без записи аудита.
Файл, который ещё проверяется. Waafir проверяет каждый только что
загруженный файл и каждую новую версию, прежде чем выдавать их содержимое. Пока
проверка не завершена, инструмент, читающий содержимое файла, отвечает
UNAVAILABLE с полем error.reason:
{ "error": { "code": "UNAVAILABLE", "reason": "ACTIVATION_PENDING", "message": "This file is still being checked. Try again shortly." } }Это временно: немного подождите и вызовите инструмент снова. Прежние версии
отвечали на это CONFLICT; ветвитесь по error.reason, а не по тексту
сообщения. У проверки есть ещё два исхода. В инструментах комнаты данных они не
несут reason, а сообщение заканчивается кодом в скобках:
- Заблокирован: файл не прошёл проверку содержимого.
INVALID_ARGUMENT, сообщение заканчивается на(ACTIVATION_BLOCKED). Ни одна повторная попытка с этим файлом не будет успешной. - Нечитаем: сохранённый файл не удалось прочитать для проверки.
UNAVAILABLE, сообщение заканчивается на(CONTENT_UNREADABLE). Повторите попытку позже.
Поле message называет блокирующую запись, если она есть. Сбои транспортного
уровня — неизвестное имя сервера, отсутствующее или отозванное подключение или
токен, некупленное платное дополнение — являются настоящими HTTP-статусами и
перечислены в разделе Настройка.
Пагинация
Ни один инструмент списков не возвращает неограниченный массив. Каждый
инструмент, возвращающий список, принимает необязательные limit и offset и
возвращает вместе со строками объект pagination:
| Поле | Значение |
|---|---|
limit | фактически применённый размер страницы |
offset | фактически применённое смещение |
count | сколько строк на этой странице |
has_more | true, если за пределами этой страницы есть ещё строки |
next_offset | offset, который нужно передать для следующей страницы, или null, если результат полный |
total | полное число строк за окном — присутствует, только если его дёшево вычислить |
limit и offset ограничиваются, а не отклоняются: значение выше максимума
возвращается как максимум, значение ниже минимума — как минимум, а
отсутствующее или нечисловое значение — как документированное значение по
умолчанию. Блок pagination всегда сообщает фактически применённые значения,
поэтому вы видите, что получили, а не что запросили.
Используйте has_more, чтобы определить, полон ли результат, — никогда не
выводите это из count === limit, что неоднозначно на точно заполненной
последней странице. Чтобы прочитать весь список, следуйте по next_offset, пока
has_more не станет false.
Инструменты чтения
Требуют области доступа read.
dataroom_list
Имя на эндпоинте области: list_datarooms
Перечисляет комнаты данных, к которым у вызывающего есть доступ. Для токена, ограниченного конкретными комнатами данных, результат фильтруется по этому списку разрешённых. Архивированные комнаты данных исключаются.
- Входные данные:
limit(необязательно, 1–200, по умолчанию 50);offset(необязательно, по умолчанию 0). - Выходные данные:
{ datarooms: [{ id, name, description, org_name, created_at }], pagination: { limit, offset, count, has_more, next_offset, total } }. - Упорядочено от старых к новым по
created_at, с дополнительной сортировкой по идентификатору, чтобы страницы были стабильными.total— полное число комнат данных, доступных этому токену, подсчитанное после применения фильтра по списку разрешённых.
dataroom_get
Имя на эндпоинте области: get_dataroom
Получает одну комнату данных по идентификатору. Вызывающий должен иметь к ней доступ; токен, ограниченный другими комнатами данных, отклоняется.
- Входные данные:
dataroom_id(обязательно). - Выходные данные:
{ dataroom: { id, name } | null }.
dataroom_list_folders
Имя на эндпоинте области: list_folders
Перечисляет папки в комнате данных. Учитывает разницу в видимости между
командой сделки и инвесторами — инвестор видит только те папки, которые ему
разрешено читать. Перечисляет один уровень под родительской папкой или, если
передать all, всё дерево. Удалённые папки исключаются.
- Входные данные:
dataroom_id(обязательно);parent_folder_id(необязательно — опустите для папок верхнего уровня);all(необязательный 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 }.
dataroom_search
Имя на эндпоинте области: search_dataroom
Ищет файлы по имени в пределах одной разрешённой комнаты данных (поиск подстроки без учёта регистра). Удалённые файлы исключаются.
- Входные данные:
dataroom_id(обязательно);query(обязательно, подстрока имени файла);limit(необязательно, 1–100, по умолчанию 25);offset(необязательно, по умолчанию 0). - Выходные данные:
{ files: [{ id, name, mime_type, size_bytes, created_at }], pagination: { limit, offset, count, has_more, next_offset } }. - Сначала новые, с дополнительной сортировкой по идентификатору, чтобы страницы
были стабильными. Если
has_moreравноtrue, запросу соответствует больше файлов, чем возвращено, — листайте черезnext_offsetили сузьте запрос.totalотсутствует.
Инструменты комнат
dataroom_create
Создаёт комнату данных в организации токена.
- Область доступа:
write, и владелец токена должен входить в команду сделки. Токен или подключение, ограниченные конкретными комнатами данных, получают отказ (FORBIDDEN, кодPAT_ROOM_SCOPED); используйте токен или подключение без ограничения по комнатам данных. - Входные данные:
name(обязательно, 1–100 символов). Начальные и конечные пробелы удаляются, а имя, состоящее только из пробелов, отклоняется (INVALID_ARGUMENT). - Выходные данные:
{ id, name }. Передавайтеidкакdataroom_idинструментам папок и файлов. - Не идемпотентен. Каждый вызов создаёт новую комнату. Если результат вызова
был потерян, найдите комнату через
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" | Активного файла с тем же именем нет — создана ожидающая запись с версией 1 | register_file |
is_new_version: true, next_step: "finalise_file_version" | Активный файл с тем же именем существует — эта загрузка становится его новой версией | finalise_file_version |
Вызывайте инструмент, который называет next_step. register_file завершает
только версию 1 и отклоняет всё остальное, поэтому обращение к нему в ветке
новой версии приведёт к сбою вызова.
dataroom_request_file_upload
Имя на эндпоинте области: request_file_upload
Запрашивает предподписанный URL загрузки для файла в комнате данных. Возвращает
URL и заголовки, по которым нужно отправить байты методом PUT, идентификатор
файла и next_step — инструмент, который завершает именно эту загрузку. Если в
целевой папке уже есть активный файл с тем же именем, is_new_version равно
true, а возвращённые идентификатор и version_number указывают на этот
существующий файл.
- Область доступа:
write. - Входные данные:
dataroom_id(обязательно);file_name(обязательно, с расширением);file_size(обязательно, точное число байтов, положительное целое);mime_type(обязательно);folder_id(необязательно — опустите для корня комнаты данных). - Выходные данные:
{ upload_url, headers, file_id, s3_key, is_new_version, version_number, next_step }—next_stepравно"register_file"или"finalise_file_version". - Этот инструмент не передаёт байты; он только выдаёт URL. Если объектное хранилище не настроено, вызов сразу завершается сбоем, а не возвращает URL, который не сможет работать.
dataroom_register_file
Имя на эндпоинте области: register_file
Завершает ожидающую первую загрузку после отправки байтов методом PUT по
данным из request_file_upload: помечает файл как активный, увеличивает объём
хранилища организации и записывает версию 1. Вызывайте его, когда
request_file_upload вернул is_new_version: false — его next_step называет
этот инструмент.
- Область доступа:
write. - Входные данные:
file_id(обязательно, ожидающий идентификатор изrequest_file_upload);s3_key(необязательно);size_bytes(необязательно — если не указан, определяется по загруженному объекту). - Выходные данные:
{ file_id, status: "active", version_number: 1 }. - Только версия 1, и это проверяется. Файл, который уже активен или уже
имеет версию, отклоняется — отказ называет
finalise_file_versionкак инструмент для версий 2 и выше. - Ключ хранилища определяется на стороне сервера, и
s3_keyклиента никогда не принимается на веру. Он необязателен; если вы его всё же передаёте, он должен совпадать с ключом, который вернулrequest_file_upload, иначе вызов отклоняется.
dataroom_finalise_file_version
Имя на эндпоинте области: finalise_file_version
Завершает новую версию существующего файла после отправки байтов методом PUT
на URL, который request_file_upload вернул с is_new_version: true. Это
MCP-эквивалент замены документа в интерфейсе и инструмент, который next_step
называет в этой ветке.
- Область доступа:
write. - Входные данные:
file_id(обязательно);version_number(обязательно — значениеversion_number, которое вернулrequest_file_upload). - Выходные данные:
{ file_id, version_id, version_number, size_bytes, is_current: true, previous_version_number, previous_version_id, undo_with: "restore_file_version" }. version_numberдолжен быть ровно следующей версией этого файла. Он проверяется, а не угадывается: любое другое значение отклоняется, а не записывается молча, и ключ хранилища определяется по нему на стороне сервера.- Новая версия становится текущей, а предыдущая сохраняется в истории. Чтобы
отменить, передайте
previous_version_idвrestore_file_version. - Файл, у которого не завершена первая загрузка, отклоняется — сначала завершите
версию 1 с помощью
register_file. Вызов также завершается сбоем, если байтов ещё фактически нет в хранилище, вместо того чтобы записать версию, за которой ничего нет.
dataroom_restore_file_version
Имя на эндпоинте области: restore_file_version
Снова делает текущей более раннюю версию файла — отмена
finalise_file_version. Инструмент перемещает отметку текущей версии и
перенаправляет файл на эту версию; он не создаёт новую строку версии,
поэтому история версий остаётся точным списком фактически загруженных
редакций.
- Область доступа:
write. - Входные данные:
file_id(обязательно);version_id(обязательно — должен принадлежать этому файлу;get_file_metadataперечисляет идентификаторы версий файла). - Выходные данные:
{ file_id, version_id, version_number, already_current, new_version_created: false }. already_current: trueозначает, что версия уже была текущей и ничего не изменилось, — это пустая операция, а не сбой.- Отдельного инструмента для перечисления версий нет:
get_file_metadataуже возвращает версии файла с их идентификаторами, номерами и признаком текущей.
dataroom_rename_file
Имя на эндпоинте области: rename_file
Переименовывает файл — только метаданные. Новая версия при этом не
создаётся; версии предназначены для замены содержимого, а не для смены
названия. Имена должны быть уникальны среди действующих файлов в одной папке;
совпадение возвращает CONFLICT с именем существующего файла.
- Область доступа:
write. - Входные данные:
file_id(обязательно);name(обязательно, 1–255 символов). - Выходные данные:
{ file_id, name, previous_name, changed }. Возвращаемоеnameсчитывается обратно из хранилища, поэтому это то, что было фактически сохранено, —changedравно false, если сохранённое имя не изменилось.
dataroom_move_file
Имя на эндпоинте области: move_file
Перемещает файл в другую папку в той же комнате данных или в корень комнаты данных. Перемещения между комнатами данных отклоняются: комната данных — это граница прав доступа, и перенос содержимого через неё изменил бы круг тех, кто может его читать. Отклоняет перемещение, если в папке назначения уже лежит действующий файл с тем же именем.
- Область доступа:
write. - Входные данные:
file_id(обязательно);folder_id(необязательно — null/не указано для корня комнаты данных). - Выходные данные:
{ file_id, name, folder_id, previous_folder_id, moved }. Передайтеprevious_folder_idобратно какfolder_id, чтобы отменить перемещение.
dataroom_delete_file
Имя на эндпоинте области: delete_file
Удаляет файл. Результат повторяет имя фактически удалённого файла, поэтому
ошибочный идентификатор виден в ответе. Файл и его версии сохраняются для
хранения и аудита, никогда не стираются, и restore_file возвращает его.
- Область доступа:
write. - Входные данные:
file_id(обязательно). - Выходные данные:
{ file_id, status: "deleted", name, folder_id, restore_with: "restore_file" }. - Объём хранилища возвращается только за фактически завершённую загрузку. Файл, байты которого были доставлены, возвращает свой размер на счётчик хранилища вашей организации. За файл, всё ещё ожидающий загрузки, изначально ничего не начислялось, поэтому его удаление никак не меняет счётчик, — удаление нейтрально для счётчика и не является возвратом байтов, которые вы никогда не хранили.
- Удаление также удаляет фрагменты поискового индекса файла, поэтому
документ сразу исчезает из поиска по документам.
restore_fileне может их вернуть — см. ниже. - Инструмент находит только действующий файл, поэтому повторный вызов с тем
же идентификатором возвращает
NOT_FOUND, а не удаляет что-либо снова. Счётчик хранилища не может быть уменьшен дважды за один файл.
dataroom_restore_file
Имя на эндпоинте области: restore_file
Отменяет delete_file: возвращает мягко удалённый файл в действующее
состояние, восстанавливая строку и учёт хранилища, который удаление отменило.
Инструмент не восстанавливает фрагменты поискового индекса файла — они
удаляются при удалении, — поэтому файл действует и доступен для скачивания, но
должен быть переиндексирован, прежде чем поиск по документам снова его найдёт.
search_index_restored всегда равно false и прямо сообщает об этом, а не
намекает на отмену без потерь.
- Область доступа:
write. - Входные данные:
file_id(обязательно). - Выходные данные:
{ restored, file_id, name, folder_id, storage_bytes_restored, search_index_restored: false }.
Когда восстановление отклоняется. Инструмент завершается сбоем, а не замазывает конфликт, и называет блокирующую строку, если она есть:
| # | Условие | error.code | Что делать |
|---|---|---|---|
| 1 | Такого файла нет, или он не ваш | NOT_FOUND | Проверьте идентификатор. |
| 2 | Файл не удалён — он уже действует | CONFLICT | Восстанавливать нечего. |
| 3 | Загрузка файла так и не завершилась | CONFLICT | Восстанавливать нечего: его байты так и не были доставлены, поэтому возвращать нечего. Вместо этого загрузите его снова. |
| 4 | Содержащая его папка всё ещё удалена | CONFLICT | Сначала restore_folder — это также вернёт файлы, удалённые вместе с ней. |
| 5 | Действующий файл с тех пор занял это имя в той папке | CONFLICT | Переименуйте файл, занимающий имя, и повторите попытку. |
Это коды внутри полезной нагрузки, а не HTTP-статусы — см. Как сообщается о сбое.
Проверки выполняются в указанном выше порядке, и вы получаете сообщение о первой из них, которая не пройдена. Поэтому случай с незавершённой загрузкой (3) сообщается после проверок «не найден» и «не удалён», но раньше проверок папки и имени: файл, байты которого так и не поступили, нельзя восстановить, какой бы ни была ситуация с его папкой или именем, поэтому нет смысла отправлять вас исправлять что-либо из этого.
dataroom_get_file_download_url
Имя на эндпоинте области: get_file_download_url
Получает кратковременный URL для скачивания файла. Вызывающий должен иметь право на файл (право на чтение/скачивание этого файла). URL отдаёт ту же копию, что и скачивание в браузере: с водяным знаком, если комната ставит водяные знаки на скачиваемые файлы, и копию с выполненным скрытием данных для документа со скрытием данных, если получатель находится вне вашей организации. Срок его действия истекает через несколько минут.
- Область доступа:
readплюс разрешение «Читать содержимое документов» на токене. Без него вызов отклоняется сGRANT_REQUIRED. - Лимит: не более 10 вызовов в минуту на токен, потому что каждый из них
готовит защищённую копию. При превышении —
RATE_LIMITED. - Если защищённую копию не удаётся подготовить вовремя, вызов отклоняется с
UNAVAILABLEи без ссылки; повторите попытку или скачайте файл в Waafir. - Входные данные:
file_id(обязательно). - Выходные данные:
{ download_url, expires_in_seconds }.
Инструменты текста документов
Один инструмент — для чтения извлечённого текста документа вместо скачивания самого файла.
dataroom_get_file_text
Имя на эндпоинте области: get_file_text
Читает извлечённый текст документа, по одной странице за раз. Возвращает
пронумерованные сегменты — для PDF по одному сегменту на страницу, если
страница не очень длинная, — плюс блок pagination, чтобы вы могли пройти по
длинному документу с помощью offset.
Две особенности делают его строже, чем чтение метаданных:
- Вам должно быть разрешено скачивать файл, а не просто просматривать его. Права только на просмотр недостаточно, а токен, которому доступ к документу ограничен, получает отказ.
- Если в документе выполнено скрытие данных и вы не входите в команду
сделки, вы получаете текст версии со скрытием данных, а
sourceсообщает, какой артефакт вы получили. Инструмент никогда молча не отдаёт оригинал читателю за периметром.
Каждый успешный вызов записывается в журнал аудита организации на тех же основаниях, что и чтение документа в продукте.
- Область доступа:
readплюс разрешение «Читать содержимое документов» на токене. Без него вызов отклоняется сGRANT_REQUIRED;dataroom_get_file_metadataиdataroom_summarise_fileпо-прежнему выдают резюме документа. - Входные данные:
file_id(обязательно);dataroom_id(необязательно — если указан, сверяется с собственной комнатой данных файла, а несовпадение воспринимается какNOT_FOUND, а не подтверждает, что файл существует в другом месте);limit(необязательно, 1–5, по умолчанию 3);offset(необязательно, по умолчанию 0). - Выходные данные:
{ file_id, file_name, source, segment_max_chars, segments, pagination }.sourceравно"original"или"redacted".paginationсодержитtotal. - Файл без сохранённого объекта — заметка, тело которой хранится встроенно, —
возвращает
NOT_FOUNDс «no extractable content». - Файл, тип которого не содержит извлекаемого текста (например, архив),
отклоняется с
400, а сохранённый файл размером более 50 МБ — с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 ссылки.
dataroom_list_share_links
- Область доступа:
read, и владелец токена должен быть владельцем или администратором организации. - Входные данные:
dataroom_id(обязательно);file_id— для действующих ссылок одного документа. - Выходные данные:
{ links: [{ id, kind, file_id?, mode, active, expires_at, has_password, require_nda, domain_allow_list, created_at, admitted_count? }] }. - Персональные ссылки инвесторов не перечисляются; см. инструменты инвесторов.
dataroom_create_share_link
В два шага. Предпросмотр сообщает, что именно предоставляется, кто может войти, правило 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 }. - Документом с ограниченным доступом нельзя поделиться по ссылке. Параметра пароля нет.
dataroom_revoke_share_link
В два шага. Все, кто пользуется ссылкой, немедленно теряют доступ.
- Область доступа:
write, владелец или администратор организации. - Входные данные:
dataroom_id,link_id(обязательно);confirm_token. - Выходные данные:
{ success: true, link_id, status: "revoked" }.