Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

Referencia de waafir-dataroom

El servidor waafir-dataroom es la superficie de API estable de esta versión. Expone las herramientas que se describen a continuación para leer y gestionar sus salas de datos, agrupadas según lo que hacen: herramientas de lectura, herramientas de carpetas, herramientas de archivos (ciclo de vida y versiones de archivos), una herramienta de texto de documentos, herramientas de permisos y herramientas de preguntas y respuestas (Q&A).

Conexión: https://app.waafir.io/api/mcp/waafir, o el servidor del área https://app.waafir.io/api/mcp/waafir-dataroom — consulte Configuración.

Nombres de las herramientas. Cada herramienta aparece a continuación bajo el nombre que lista waafir, como dataroom_list_files. El servidor del área lista el nombre anterior que se indica bajo cada encabezado como «Nombre en el endpoint del área», como list_files, y waafir sigue aceptando ese nombre si un cliente lo invoca. Cuando la descripción o el resultado de una herramienta nombra otra herramienta a la que llamar a continuación (next_step, restore_with, undo_with), la nombra tal como la lista el endpoint al que está conectado. Las descripciones de esta página usan los nombres del endpoint del área.

Cómo se aplica el acceso

En esta página, token significa la credencial que usa su asistente: una conexión creada al iniciar sesión, o un token de acceso personal. Ambos llevan un alcance y, opcionalmente, una lista de salas de datos, y están limitados de la misma manera.

Cada herramienta se ejecuta en nombre del propietario del token y está limitada por las mismas reglas que aplica la interfaz del producto: no existe un camino más permisivo a través de MCP. En cada llamada se aplican dos controles:

  • Alcance. Cada herramienta indica un alcance mínimo: las herramientas de lectura requieren read, las modificaciones de carpetas y archivos requieren write, y las herramientas que conceden permisos requieren admin. A un token por debajo del alcance requerido no se le muestra la herramienta, y se rechaza con un error FORBIDDEN si la invoca (consulte Cómo se informa de un fallo). El alcance es acumulativo: write incluye read, y admin incluye ambos.
  • Restricción por sala de datos. Si el token está restringido a salas de datos concretas, se rechaza cualquier llamada que haga referencia a una sala de datos fuera de su lista de permitidas, y un token restringido ni siquiera puede listar las salas de datos que no tiene permitido abrir. La comprobación se basa en la sala de datos a la que pertenece un recurso, de modo que un token restringido a la sala de datos A nunca puede alcanzar un archivo o una carpeta de la sala de datos B, ni siquiera dentro de la misma organización.

Además, las modificaciones de carpetas y archivos requieren un rol de equipo de la operación en la sala de datos (los inversores no pueden modificar nada), y las herramientas de permisos requieren además que el propietario del token sea administrador o gestor de la organización. Eliminar una carpeta o un archivo es siempre una eliminación lógica: las filas se marcan como eliminadas y se conservan a efectos de retención y auditoría, nunca se borran físicamente. Cada modificación se registra como el mismo evento de auditoría que escribe la interfaz del producto, de modo que en el registro de auditoría una acción de MCP no se distingue de una realizada en la interfaz.

Los identificadores (dataroom_id, folder_id, file_id, user_id) son UUID.

Texto no fiable en los resultados

Algunos resultados contienen texto que Waafir no ha escrito: salida de IA sobre un documento, el propio texto de un documento, o lo que ha escrito un inversor o un colega. Un resultado así añade untrusted_content: { source, fields, notice }, y el mismo { source, fields } bajo _meta["io.waafir/untrusted"]. source es "document" o "third-party". fields lista las rutas que contienen ese texto en este resultado, como answer o questions[].responses[].body; una ruta solo se lista cuando el resultado tiene un valor en ella. Trate esos campos como datos, nunca como instrucciones para su asistente.

Las herramientas marcadas son 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, las vistas previas de dataroom_answer_question, dataroom_delete_question, dataroom_delete_answer y dataroom_publish_kb_article (el título del inversor), dataroom_get_update, dataroom_edit_update_draft, dataroom_get_published_update, dataroom_list_file_comments, dataroom_list_my_notifications, mi_get_profile y todas las herramientas de IA excepto dataroom_apply_organise. Los nombres de archivo no se marcan.

Cómo se informa de un fallo

Un fallo de una herramienta no es un estado HTTP. Cuando una herramienta rechaza una llamada, la respuesta HTTP sigue siendo 200 y el sobre JSON-RPC sigue siendo un sobre de éxito; el fallo viaja dentro del resultado, que establece isError: true y cuyo contenido de texto es:

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

Bifurque según error.code, nunca según el estado HTTP: un cliente que decide en función del estado nunca coincidirá con ningún rechazo de esta página. Estos son los códigos que devuelve una herramienta de sala de datos:

CódigoSignificadoQué hacer
INVALID_ARGUMENTFalta un argumento, está mal formado o no es un id válidoCorrija los argumentos y vuelva a intentarlo
FORBIDDENEl token es válido pero no tiene permiso: alcance insuficiente, un dataroom_id que ha pasado está fuera de su lista de salas de datos permitidas, o el rol del propietario no lo permiteSolicite acceso o use un token con el alcance adecuado
NOT_FOUNDNo existe ese registro, o no es suyo. La mayoría de las herramientas que reciben un id de archivo o de carpeta también responden esto para un elemento de una sala de datos fuera de la lista de permitidas del token, exactamente igual que para un id que no existeCompruebe el id y que el token esté restringido a la sala de datos del elemento
CONFLICTEntendido y permitido, pero la sala de datos no está en un estado en el que se pueda hacerLea el mensaje, resuelva el impedimento y vuelva a intentarlo
TOO_LARGELa entrada supera un límite de tamañoDivida la entrada
QUOTA_EXCEEDEDSe ha agotado una asignación medida, o la suscripción de la organización ha vencidoAlguien debe comprar o ampliar: volver a intentarlo no lo resolverá
UPSTREAM_ERRORHa fallado un servicio posterior: no se pudo obtener el documento almacenado o falló la extracción de textoTransitorio. Vuelva a intentarlo más tarde antes de tratarlo como definitivo
UNAVAILABLEWaafir no puede atender la solicitud ahora mismo: el archivo aún se está comprobando, el archivo almacenado no se pudo leer para su comprobación, o la lectura no se pudo registrar en el registro de auditoría, por lo que el contenido se retuvo en lugar de divulgarse sin registroTransitorio. Vuelva a intentarlo más tarde
INTERNALUn fallo inesperadoNo lo reintente: escálelo

No agrupe los dos códigos de «reintentar más tarde» bajo «fallido». UPSTREAM_ERROR y UNAVAILABLE le llegan hoy desde get_file_text, y significan vuelva a preguntar, no abandone. Un cliente que trata todo resultado distinto de OK como definitivo convierte un fallo pasajero en un fallo permanente, el único error que esta tabla existe para evitar. Tenga en cuenta también que UNAVAILABLE es un rechazo deliberado: Waafir prefiere retener el texto de un documento antes que entregarlo sin un registro de auditoría.

Un archivo que aún se está comprobando. Waafir comprueba cada archivo recién subido y cada nueva versión antes de servir su contenido. Hasta que termina la comprobación, una herramienta que lee el contenido del archivo responde UNAVAILABLE con un error.reason:

{ "error": { "code": "UNAVAILABLE", "reason": "ACTIVATION_PENDING", "message": "This file is still being checked. Try again shortly." } }

Es transitorio: espere un momento y vuelva a llamar. Las versiones anteriores respondían con CONFLICT; ramifique según error.reason, no según el mensaje. La comprobación tiene otros dos resultados. En las herramientas de sala de datos no llevan reason, y el mensaje termina con el código entre paréntesis:

  • Bloqueado: el archivo no superó la comprobación de su contenido. INVALID_ARGUMENT, con un mensaje que termina en (ACTIVATION_BLOCKED). Ningún reintento con este archivo puede tener éxito.
  • Ilegible: el archivo almacenado no se pudo leer para comprobarlo. UNAVAILABLE, con un mensaje que termina en (CONTENT_UNREADABLE). Vuelva a intentarlo más tarde.

El message nombra el registro que lo impide siempre que lo haya. Los fallos a nivel de transporte —un nombre de servidor desconocido, una conexión o un token inexistente o revocado, un complemento de pago no adquirido— sí son estados HTTP reales y se enumeran en Configuración.

Paginación

Ninguna herramienta de listado devuelve un array sin límite. Toda herramienta que devuelve una lista acepta un limit y un offset opcionales, y devuelve un objeto pagination junto a las filas:

CampoSignificado
limitel tamaño de página realmente aplicado
offsetel desplazamiento realmente aplicado
countcuántas filas hay en esta página
has_moretrue cuando existen más filas después de esta página
next_offsetel offset que debe pasar para la página siguiente, o null cuando el resultado está completo
totalel número total de filas detrás de la ventana; solo está presente cuando calcularlo es barato

limit y offset se ajustan, no se rechazan: un valor por encima del máximo se devuelve como el máximo, un valor por debajo del mínimo como el mínimo, y un valor ausente o no numérico como el valor predeterminado documentado. El bloque pagination siempre informa de los valores realmente aplicados, de modo que puede ver lo que obtuvo y no lo que pidió.

Use has_more para decidir si un resultado está completo; nunca lo deduzca de count === limit, que es ambiguo en una última página exactamente llena. Para leer una lista completa, siga next_offset hasta que has_more sea false.


Herramientas de lectura

Requieren el alcance read.

dataroom_list

Nombre en el endpoint del área: list_datarooms

Lista las salas de datos a las que puede acceder quien llama. Para un token restringido a salas de datos concretas, el resultado se filtra según esa lista de permitidas. Las salas de datos archivadas se excluyen.

  • Entradas: limit (opcional, 1–200, predeterminado 50); offset (opcional, predeterminado 0).
  • Salida: { datarooms: [{ id, name, description, org_name, created_at }], pagination: { limit, offset, count, has_more, next_offset, total } }.
  • Ordenadas de la más antigua a la más reciente por created_at, con desempate por id para que las páginas sean estables. total es el número total de salas de datos que este token puede alcanzar, contado después de aplicar el filtro de la lista de permitidas.

dataroom_get

Nombre en el endpoint del área: get_dataroom

Obtiene una única sala de datos por id. Quien llama debe estar autorizado para ella; un token restringido a otras salas de datos se rechaza.

  • Entradas: dataroom_id (obligatorio).
  • Salida: { dataroom: { id, name } | null }.

dataroom_list_folders

Nombre en el endpoint del área: list_folders

Lista las carpetas de una sala de datos. Respeta la visibilidad del equipo de la operación frente a la del inversor: un inversor solo ve las carpetas que puede leer. Lista un nivel bajo una carpeta principal, o pase all para obtener el árbol completo. Las carpetas eliminadas se excluyen.

  • Entradas: dataroom_id (obligatorio); parent_folder_id (opcional; omítalo para las carpetas de nivel superior); all (booleano opcional; true lista todas las carpetas de la sala de datos); limit (opcional, 1–500, predeterminado 100); offset (opcional, predeterminado 0).
  • Salida: { folders: [{ id, name, parent_folder_id, created_at }], pagination: { limit, offset, count, has_more, next_offset, total } }.
  • Ordenadas por nombre, con desempate por id para que las páginas sean estables. all: true también se pagina: en un árbol grande, recórralo con next_offset en lugar de esperar el árbol completo en una sola respuesta.

dataroom_list_files

Nombre en el endpoint del área: list_files

Lista los archivos activos (no eliminados) de una sala de datos, opcionalmente dentro de una carpeta. Quienes llaman como inversores solo ven los archivos que tienen permiso para leer. Paginada.

  • Entradas: dataroom_id (obligatorio); folder_id (opcional; omítalo para los archivos de la raíz de la sala de datos); limit (opcional, 1–200, predeterminado 50); offset (opcional, predeterminado 0); sort_dir (opcional, asc | desc, predeterminado desc).
  • Salida: { files: [{ id, name, folder_id, size_bytes, mime_type, created_at, updated_at }], pagination: { limit, offset, count, has_more, next_offset } }.
  • Sin total: contar el conjunto completo de coincidencias no es barato en esta ruta. Use has_more / next_offset para paginar.

dataroom_get_file_metadata

Nombre en el endpoint del área: get_file_metadata

Obtiene los metadatos de un único archivo: nombre, tipo MIME, tamaño, ruta de la carpeta, lista de versiones y resumen/categoría de IA si existen. El archivo debe pertenecer a la sala de datos indicada; un archivo de otra sala de datos (incluso de la misma organización) devuelve null.

  • Entradas: dataroom_id (obligatorio); file_id (obligatorio).
  • Salida: { 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 }.

Nombre en el endpoint del área: search_dataroom

Busca archivos por nombre dentro de una única sala de datos autorizada (coincidencia de subcadena sin distinguir mayúsculas y minúsculas). Los archivos eliminados se excluyen.

  • Entradas: dataroom_id (obligatorio); query (obligatorio, subcadena del nombre de archivo); limit (opcional, 1–100, predeterminado 25); offset (opcional, predeterminado 0).
  • Salida: { files: [{ id, name, mime_type, size_bytes, created_at }], pagination: { limit, offset, count, has_more, next_offset } }.
  • Los más recientes primero, con desempate por id para que las páginas sean estables. Cuando has_more es true, la consulta coincidió con más archivos de los devueltos: pagine con next_offset o acote la consulta. No hay total.

Herramientas de salas

dataroom_create

Crea una sala de datos en la organización del token.

  • Alcance: write, y el propietario del token debe pertenecer al equipo de la operación. Un token o una conexión limitados a salas de datos concretas se rechazan (FORBIDDEN, código PAT_ROOM_SCOPED); use uno que no esté limitado a salas de datos.
  • Entradas: name (obligatorio, de 1 a 100 caracteres). Los espacios iniciales y finales se recortan, y un nombre formado solo por espacios se rechaza (INVALID_ARGUMENT).
  • Salida: { id, name }. Pase id como dataroom_id a las herramientas de carpetas y archivos.
  • No es idempotente. Cada llamada crea una sala nueva. Si se perdió el resultado de una llamada, busque la sala con dataroom_list antes de volver a llamar, o creará un duplicado.
  • Una organización cuya suscripción no permite escrituras, o que supera su límite de puestos, se rechaza con QUOTA_EXCEEDED.

Herramientas de carpetas

Requieren el alcance write y un rol de equipo de la operación en la sala de datos.

dataroom_create_folder

Nombre en el endpoint del área: create_folder

Crea una carpeta en una sala de datos. Anídela bajo una carpeta principal u omita la carpeta principal para la raíz de la sala de datos. Rechaza un nombre duplicado bajo la misma carpeta principal con un CONFLICT.

  • Entradas: dataroom_id (obligatorio); name (obligatorio, 1–255 caracteres); parent_folder_id (opcional; null u omitido para la raíz de la sala de datos).
  • Salida: { folder: { id, name, parent_folder_id } }. El mensaje de CONFLICT nombra el id de la carpeta en conflicto, de modo que no necesita volver a listar la carpeta principal para encontrarla.

dataroom_rename_folder

Nombre en el endpoint del área: rename_folder

Cambia el nombre de una carpeta. La carpeta debe pertenecer a la organización de quien llama.

  • Entradas: folder_id (obligatorio); name (obligatorio, 1–255 caracteres).
  • Salida: { folder: { id, name } }.

dataroom_delete_folder

Nombre en el endpoint del área: delete_folder

Elimina de forma lógica una carpeta y todo su subárbol: cada subcarpeta anidada y cada archivo que contienen. En una sala de datos real, eso pueden ser cientos de documentos a partir de un único id de carpeta, por lo que el resultado informa exactamente de cuántas carpetas y archivos se eliminaron. Pase dry_run: true para obtener esos recuentos sin eliminar nada. Las filas se marcan como eliminadas, nunca se borran físicamente, y toda la cascada se puede deshacer con restore_folder.

  • Entradas: folder_id (obligatorio); dry_run (booleano opcional; solo vista previa).
  • Salida: { deleted, dry_run, folder_id, folder_name, affected: { folders, files }, restore_with: "restore_folder" }.
  • Una ejecución de prueba no cambia nada y no registra ninguna eliminación en el registro de auditoría.

dataroom_restore_folder

Nombre en el endpoint del área: restore_folder

Deshace un delete_folder. Restaura la carpeta y todo lo que esa eliminación quitó con ella; lo que se eliminó por separado, antes, sigue eliminado. Devuelve un conflicto si la carpeta principal sigue eliminada (restáurela primero) o si una carpeta activa ha tomado desde entonces ese nombre; en ambos casos el mensaje nombra el id de la carpeta que lo impide.

  • Entradas: folder_id (obligatorio); dry_run (booleano opcional; solo vista previa).
  • Salida: { restored, dry_run, folder_id, folder_name, affected: { folders, files } }.
  • Deshacer la eliminación de una carpeta es sin pérdidas, y deliberadamente distinto de la eliminación de un archivo. La cascada no modifica el contador de almacenamiento de su organización ni descarta los fragmentos del índice de búsqueda de los archivos, por lo que restore_folder no abona nada —no se cargó nada— y los archivos restaurados siguen siendo localizables en las búsquedas. delete_file / restore_file, más abajo, hacen ambas cosas. Por tanto, eliminar una carpeta llena de documentos no es el mismo evento contable que eliminar cada uno de esos documentos.

dataroom_move_folder

Nombre en el endpoint del área: move_folder

Cambia la carpeta principal de una carpeta dentro de la misma sala de datos. Anídela bajo otra carpeta o muévala a la raíz de la sala de datos. Rechaza mover una carpeta dentro de sí misma o de una descendiente (ciclo), a otra sala de datos, o adonde ya exista una carpeta hermana con el mismo nombre.

  • Entradas: folder_id (obligatorio); new_parent_folder_id (opcional; null u omitido para la raíz de la sala de datos).
  • Salida: { folder: { id, name, parent_folder_id, previous_parent_folder_id } }. Pase de nuevo previous_parent_folder_id como new_parent_folder_id para deshacer el movimiento.

Herramientas de archivos

Las modificaciones de archivos requieren el alcance write; get_file_download_url requiere read más Leer contenido de documentos en el token.

La subida se gestiona mediante intermediación, y MCP nunca transporta los bytes. Los argumentos de las herramientas son JSON, por lo que el protocolo no tiene canal binario: request_file_upload genera una URL prefirmada y su cliente envía el contenido directamente a ella con PUT. Un cliente que no puede emitir un HTTP PUT con un cuerpo binario sin procesar no puede completar una subida en absoluto; conviene saberlo antes de empezar y no después.

Qué herramienta finaliza la subida depende de si ya existe un archivo con ese nombre, y no tiene que averiguarlo usted: request_file_upload devuelve un campo next_step que nombra la herramienta a la que llamar.

request_file_upload devuelveSignificadoFinalizar con
is_new_version: false, next_step: "register_file"No hay ningún archivo activo con el mismo nombre: se creó un registro pendiente en la versión 1register_file
is_new_version: true, next_step: "finalise_file_version"Existe un archivo activo con el mismo nombre: esta subida se convierte en una nueva versión de élfinalise_file_version

Llame a la herramienta que nombra next_step. register_file solo finaliza la versión 1 y rechaza cualquier otra cosa, por lo que recurrir a ella en la rama de nueva versión hace que la llamada falle.

dataroom_request_file_upload

Nombre en el endpoint del área: request_file_upload

Solicita una URL de subida prefirmada para un archivo de una sala de datos. Devuelve la URL y las cabeceras a las que enviar los bytes con PUT, el id del archivo y next_step, la herramienta que finaliza esta subida concreta. Si ya existe un archivo activo con el mismo nombre en la carpeta de destino, is_new_version es true y el id y el version_number devueltos apuntan a ese archivo existente.

  • Alcance: write.
  • Entradas: dataroom_id (obligatorio); file_name (obligatorio, con extensión); file_size (obligatorio, bytes exactos, entero positivo); mime_type (obligatorio); folder_id (opcional; omítalo para la raíz de la sala de datos).
  • Salida: { upload_url, headers, file_id, s3_key, is_new_version, version_number, next_step } — next_step es "register_file" o "finalise_file_version".
  • Esta herramienta no mueve ningún byte; solo gestiona la URL. Si el almacenamiento de objetos no está configurado, la llamada falla directamente en lugar de devolver una URL que no puede funcionar.

dataroom_register_file

Nombre en el endpoint del área: register_file

Finaliza una primera subida pendiente después de enviar con PUT los bytes desde request_file_upload: marca el archivo como activo, incrementa el almacenamiento de la organización y registra la versión 1. Llámela cuando request_file_upload haya devuelto is_new_version: false: su next_step nombra esta herramienta.

  • Alcance: write.
  • Entradas: file_id (obligatorio, el id pendiente de request_file_upload); s3_key (opcional); size_bytes (opcional; si se omite, se deriva del objeto subido).
  • Salida: { file_id, status: "active", version_number: 1 }.
  • Solo la versión 1, y lo hace cumplir. Se rechaza un archivo que ya está activo o que ya tiene una versión; el rechazo nombra finalise_file_version como la herramienta para las versiones 2 y posteriores.
  • La clave de almacenamiento se deriva en el servidor y nunca se confía en el s3_key del cliente. Es opcional; si lo envía, debe ser igual a la clave que devolvió request_file_upload o la llamada se rechaza.

dataroom_finalise_file_version

Nombre en el endpoint del área: finalise_file_version

Finaliza una nueva versión de un archivo existente, después de enviar con PUT los bytes a la URL que devolvió request_file_upload con is_new_version: true. Es el equivalente en MCP de sustituir un documento en la interfaz, y la herramienta que nombra next_step en esa rama.

  • Alcance: write.
  • Entradas: file_id (obligatorio); version_number (obligatorio; el version_number que devolvió request_file_upload).
  • Salida: { file_id, version_id, version_number, size_bytes, is_current: true, previous_version_number, previous_version_id, undo_with: "restore_file_version" }.
  • version_number debe ser exactamente la siguiente versión de este archivo. Se valida, no se adivina: cualquier otro valor se rechaza en lugar de escribirse silenciosamente, y la clave de almacenamiento se deriva de él en el servidor.
  • La nueva versión pasa a ser la actual y la anterior se conserva en el historial. Pase previous_version_id a restore_file_version para deshacerlo.
  • Se rechaza un archivo que no ha completado su primera subida: finalice primero la versión 1 con register_file. La llamada también falla si los bytes aún no están realmente en el almacenamiento, en lugar de registrar una versión sin nada detrás.

dataroom_restore_file_version

Nombre en el endpoint del área: restore_file_version

Vuelve a convertir en actual una versión anterior de un archivo; es la acción inversa de finalise_file_version. Mueve el marcador de versión actual y vuelve a apuntar el archivo a esa versión; no genera una nueva fila de versión, de modo que el historial de versiones sigue siendo una lista fiel de las revisiones que realmente se subieron.

  • Alcance: write.
  • Entradas: file_id (obligatorio); version_id (obligatorio; debe pertenecer a este archivo; get_file_metadata lista los ids de versión del archivo).
  • Salida: { file_id, version_id, version_number, already_current, new_version_created: false }.
  • already_current: true significa que la versión ya era la actual y no cambió nada: una operación sin efecto, no un fallo.
  • No existe una herramienta independiente para listar versiones: get_file_metadata ya devuelve las versiones del archivo con sus ids, números e indicador de versión actual.

dataroom_rename_file

Nombre en el endpoint del área: rename_file

Cambia el nombre de un archivo: solo metadatos. No crea una nueva versión; las versiones sirven para sustituir contenido, no para cambiar etiquetas. Los nombres deben ser únicos entre los archivos activos de la misma carpeta; una coincidencia devuelve un CONFLICT que nombra el archivo existente.

  • Alcance: write.
  • Entradas: file_id (obligatorio); name (obligatorio, 1–255 caracteres).
  • Salida: { file_id, name, previous_name, changed }. El name devuelto se lee de nuevo del almacenamiento, por lo que es lo que realmente se guardó; changed es false si el nombre almacenado no cambió.

dataroom_move_file

Nombre en el endpoint del área: move_file

Mueve un archivo a otra carpeta de la misma sala de datos, o a la raíz de la sala de datos. Los movimientos entre salas de datos se rechazan: una sala de datos es un límite de permisos, y reubicar contenido a través de él cambiaría quién puede leerlo. Rechaza un movimiento cuando ya hay un archivo activo con el mismo nombre en el destino.

  • Alcance: write.
  • Entradas: file_id (obligatorio); folder_id (opcional; null u omitido para la raíz de la sala de datos).
  • Salida: { file_id, name, folder_id, previous_folder_id, moved }. Pase de nuevo previous_folder_id como folder_id para deshacer el movimiento.

dataroom_delete_file

Nombre en el endpoint del área: delete_file

Elimina un archivo. El resultado repite el nombre del archivo que realmente se eliminó, de modo que un id equivocado se ve en la respuesta. El archivo y sus versiones se conservan a efectos de retención y auditoría, nunca se borran, y restore_file lo recupera.

  • Alcance: write.
  • Entradas: file_id (obligatorio).
  • Salida: { file_id, status: "deleted", name, folder_id, restore_with: "restore_file" }.
  • El almacenamiento solo se abona de nuevo por una subida que realmente se completó. Un archivo cuyos bytes llegaron devuelve su tamaño al contador de almacenamiento de su organización. Un archivo que aún espera su subida nunca se cobró, por lo que eliminarlo no mueve el contador: la eliminación es neutra para el contador, no un reembolso de bytes que nunca almacenó.
  • La eliminación también descarta los fragmentos del índice de búsqueda del archivo, por lo que el documento sale de inmediato de la búsqueda de documentos. restore_file no puede recuperarlos; consulte más abajo.
  • La herramienta solo resuelve un archivo activo, por lo que llamarla una segunda vez con el mismo id devuelve NOT_FOUND en lugar de volver a eliminar nada. El contador de almacenamiento no puede cargarse dos veces por un mismo archivo.

dataroom_restore_file

Nombre en el endpoint del área: restore_file

Deshace un delete_file: devuelve un archivo eliminado de forma lógica al estado activo, restaurando la fila y la contabilidad de almacenamiento que la eliminación revirtió. No restaura los fragmentos del índice de búsqueda del archivo —se descartan al eliminarlo—, por lo que el archivo queda activo y descargable, pero debe volver a indexarse antes de que la búsqueda de documentos lo encuentre de nuevo. search_index_restored es siempre false y lo indica así en lugar de sugerir que deshacer no tiene pérdidas.

  • Alcance: write.
  • Entradas: file_id (obligatorio).
  • Salida: { restored, file_id, name, folder_id, storage_bytes_restored, search_index_restored: false }.

Cuándo se rechaza una restauración. Falla en lugar de ocultar un conflicto, y nombra la fila que lo impide cuando la hay:

#Condiciónerror.codeQué hacer
1No existe ese archivo, o no es suyoNOT_FOUNDCompruebe el id.
2El archivo no está eliminado: ya está activoCONFLICTNo hay nada que restaurar.
3La subida del archivo nunca se completóCONFLICTNo hay nada que restaurar: sus bytes nunca llegaron, así que no hay ningún documento que recuperar. Súbalo de nuevo.
4La carpeta que lo contiene sigue eliminadaCONFLICTPrimero restore_folder, que también recupera los archivos eliminados con ella.
5Un archivo activo ha tomado desde entonces el nombre en esa carpetaCONFLICTCambie el nombre del archivo que tiene ese nombre y vuelva a intentarlo.

Son códigos dentro de la carga útil, no estados HTTP; consulte Cómo se informa de un fallo.

Las comprobaciones se ejecutan en el orden numerado arriba, y se le informa de la primera que falla. Por tanto, el caso de subida nunca completada (3) se notifica después de las comprobaciones de no encontrado y no eliminado, pero antes de las de carpeta y nombre: un archivo cuyos bytes nunca llegaron no puede restaurarse sea cual sea la situación de su carpeta o su nombre, así que no tiene sentido enviarle a resolver ninguna de ellas.

dataroom_get_file_download_url

Nombre en el endpoint del área: get_file_download_url

Obtiene una URL de descarga de corta duración para un archivo. Quien llama debe estar autorizado para el archivo (el permiso de lectura/descarga por archivo). La URL sirve la misma copia que le da la descarga desde el navegador: con marca de agua cuando la sala aplica marca de agua a las descargas, y la copia con supresión de datos de un documento con supresión de datos para un destinatario de fuera de su organización. Caduca al cabo de unos minutos.

  • Alcance: read, más Leer contenido de documentos en el token. Sin ello, la llamada se rechaza con GRANT_REQUIRED.
  • Límite: como máximo 10 llamadas por minuto por token, porque cada una prepara una copia protegida. Por encima, RATE_LIMITED.
  • Si no se puede preparar a tiempo una copia protegida, la llamada se rechaza con UNAVAILABLE y sin enlace; vuelva a intentarlo o descárguelo en Waafir.
  • Entradas: file_id (obligatorio).
  • Salida: { download_url, expires_in_seconds }.

Herramientas de texto de documentos

Una sola herramienta, para leer el texto extraído de un documento en lugar de descargar el propio archivo.

dataroom_get_file_text

Nombre en el endpoint del área: get_file_text

Lee el texto extraído de un documento, página a página. Devuelve segmentos numerados —en un PDF, un segmento por página salvo que la página sea muy larga— más un bloque pagination, de modo que puede recorrer un documento largo con offset.

Dos cosas hacen que esto sea más estricto que una lectura de metadatos:

  • Debe tener permiso para descargar el archivo, no solo para verlo. El permiso de solo visualización no es suficiente, y un token restringido fuera del alcance del documento se rechaza.
  • Si el documento ha pasado por supresión de datos y usted no pertenece al equipo de la operación, recibe el texto de la versión con supresión de datos, y source indica qué artefacto obtuvo. Nunca entrega en silencio el original a un lector del perímetro.

Cada llamada correcta se escribe en el registro de auditoría de la organización, en las mismas condiciones que la lectura de un documento en el producto.

  • Alcance: read, más Leer contenido de documentos en el token. Sin ello, la llamada se rechaza con GRANT_REQUIRED; dataroom_get_file_metadata y dataroom_summarise_file siguen proporcionando el resumen del documento.
  • Entradas: file_id (obligatorio); dataroom_id (opcional; si se proporciona, se valida contra la propia sala de datos del archivo, y una discrepancia se interpreta como NOT_FOUND en lugar de confirmar que el archivo existe en otro lugar); limit (opcional, 1–5, predeterminado 3); offset (opcional, predeterminado 0).
  • Salida: { file_id, file_name, source, segment_max_chars, segments, pagination }. source es "original" o "redacted". pagination incluye un total.
  • Un archivo sin objeto almacenado —una nota, cuyo cuerpo se guarda en línea— devuelve NOT_FOUND con «no extractable content».
  • Un archivo cuyo tipo no tiene texto que extraer (un archivo comprimido, por ejemplo) se rechaza con un 400, y un archivo almacenado de más de 50 MB con un 413 (FILE_TOO_LARGE). Ambos se aplican solo cuando el texto del archivo no se ha extraído ya (el texto ya extraído se sirve primero), se rechazan antes de obtener el documento, y ninguno es un error de reintentar más tarde.
  • Esta es la herramienta que produce los dos códigos de reintentar más tarde: UPSTREAM_ERROR cuando no se puede obtener el documento almacenado o falla la extracción de texto, y UNAVAILABLE cuando falla la escritura de auditoría de la lectura, en cuyo caso el texto se retiene deliberadamente en lugar de divulgarse sin registro. Ambos merecen un reintento antes de considerar el documento ilegible.

Herramientas de permisos

Estas herramientas leen y modifican quién puede ver qué. Las tres herramientas de lectura solo requieren el alcance read (las dos herramientas de directorio requieren además un rol de equipo de la operación); las cuatro herramientas de concesión/revocación requieren el alcance admin y un propietario del token que sea administrador o gestor de la organización.

Un token nunca lleva la excepción de propietario/administrador sobre los archivos restringidos. En la aplicación, un propietario o administrador de la organización ve todos los archivos restringidos; mediante un token, solo llega a uno si lo creó o tiene una concesión sobre él, exactamente igual que cualquier otro miembro. Una herramienta de archivos rechazada sobre un archivo así responde NOT_FOUND con el mismo texto que un archivo que no existe («File not found in the requested dataroom, or not readable by this credential»), de modo que la respuesta nunca confirma que haya un archivo restringido.

dataroom_get_file_permissions

Nombre en el endpoint del área: get_file_permissions

Lista las concesiones de permisos sobre un archivo (directas y heredadas de la carpeta). Refleja la vista de permisos de archivo de la interfaz.

  • Alcance: read.
  • Entradas: dataroom_id (obligatorio); file_id (obligatorio); limit (opcional, 1–200, predeterminado 50); offset (opcional, predeterminado 0).
  • Salida: { 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 es "direct" o "inherited").
  • Las concesiones se ordenan por created_at, después por user_id, después por source y después por source_folder_id, de modo que las páginas son estables entre llamadas. total es el número total de concesiones del archivo.
  • Los campos de identidad (user_email, user_name, granted_by_email) siguen la misma regla de visibilidad que las herramientas de directorio de abajo: aparecen para quienes llaman desde el equipo de la operación, las identidades de inversores requieren además un administrador o gestor de la organización, y cuando no tiene permiso las claves están ausentes en lugar de ser null. identities_visible le indica en qué caso se encuentra; las concesiones en sí siempre se listan.

dataroom_list_users

Nombre en el endpoint del área: list_dataroom_users

Lista los usuarios que tienen una concesión de acceso activa sobre una sala de datos, con el user_id que requieren las herramientas de permisos más la dirección de correo electrónico y el nombre de cada beneficiario. Suele ser la primera llamada cuando necesita un user_id.

  • Alcance: read, y un rol de equipo de la operación en la organización de la sala de datos (el mismo control que la página del equipo).
  • Entradas: dataroom_id (obligatorio); limit (opcional, 1–200, predeterminado 50); offset (opcional, predeterminado 0).
  • Salida: { 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 }.
  • Las identidades de inversores se omiten salvo que sea administrador o gestor de la organización; investor_rows_visible indica qué conjunto recibió.
  • Solo lista los beneficiarios explícitos. Los propietarios y administradores de la organización tienen acceso implícito sin fila de concesión y no aparecerán; resuélvalos con find_user_by_email.

dataroom_find_user_by_email

Nombre en el endpoint del área: find_user_by_email

Resuelve una dirección de correo electrónico en el user_id que requieren las herramientas de permisos, junto con el rol del usuario en la organización y su permiso actual en esta sala de datos.

  • Alcance: read, y un rol de equipo de la operación en la organización de la sala de datos. Resolver un inversor requiere además un administrador o gestor de la organización.
  • Entradas: dataroom_id (obligatorio); email (obligatorio, se compara sin distinguir mayúsculas y minúsculas).
  • Salida: { found: true, user: { user_id, email, name, org_role, dataroom_permission } } o { found: false }. Un dataroom_permission de null significa que el usuario está en la organización pero aún no tiene acceso a esta sala: invítelo primero.
  • No es una búsqueda en un directorio global: solo se resuelven los usuarios de la propia organización de la sala de datos o que tienen acceso activo a ella. Una dirección desconocida, un usuario fuera de su espacio y un usuario que no tiene permiso para ver devuelven todos un { found: false } idéntico, de modo que una respuesta negativa nunca revela si existe una cuenta.

dataroom_set_file_permissions

Nombre en el endpoint del área: set_file_permissions

Concede o actualiza el permiso de lectura/descarga de un usuario sobre un archivo. Se rechaza un token read/write, o un propietario que no sea administrador o gestor de la organización.

  • Alcance: admin.
  • Entradas: dataroom_id (obligatorio); file_id (obligatorio); user_id (obligatorio); can_read (booleano obligatorio); can_download (booleano obligatorio); expires_at (marca de tiempo ISO opcional, debe estar en el futuro).
  • Salida: { success: true, effective: { can_read, can_download } }: la decisión posterior a la concesión, que refleja las restricciones del archivo y la herencia de la carpeta y, por tanto, puede diferir de lo que solicitó.
  • Esta herramienta concede acceso; no puede retirarlo. Pasar can_read: false escribe una concesión activa con la lectura denegada, que otras concesiones (pertenencia a la organización, una concesión sobre la sala de datos, herencia de carpeta) aún pueden anular. Para retirar realmente el acceso de un usuario a un archivo, use revoke_file_permission.

dataroom_revoke_file_permission

Nombre en el endpoint del área: revoke_file_permission

Elimina la concesión de permiso directa de un usuario sobre un archivo (revocación lógica: la fila se conserva para el registro de auditoría). Devuelve revoked: false si el usuario no tenía ninguna concesión directa sobre el archivo.

  • Alcance: admin.
  • Entradas: dataroom_id (obligatorio); file_id (obligatorio); user_id (obligatorio).
  • Salida: { success: true, revoked }.
  • Afecta solo a la concesión directa. El acceso heredado de un permiso de carpeta no se ve afectado y debe revocarse en la carpeta. Reversible volviendo a conceder con set_file_permissions.

dataroom_invite_user

Nombre en el endpoint del área: invite_user_to_dataroom

Concede a un usuario conocido acceso a nivel de sala de datos con un nivel de permiso determinado: una concesión de acceso directa (no una invitación por correo electrónico). Idempotente (upsert).

  • Alcance: admin.
  • Entradas: dataroom_id (obligatorio); user_id (obligatorio); permission (obligatorio; uno de viewer, downloader, contributor, manager); expires_at (marca de tiempo ISO opcional, debe estar en el futuro).
  • Salida: { success: true, grant_id }.

dataroom_remove_user

Nombre en el endpoint del área: remove_user_from_dataroom

Revoca el acceso a nivel de sala de datos de un usuario (revocación lógica: establece revoked_at, conservando el registro de auditoría). Devuelve revoked: false si el usuario no tenía ninguna concesión activa.

  • Alcance: admin.
  • Entradas: dataroom_id (obligatorio); user_id (obligatorio).
  • Salida: { success: true, revoked }.

Herramientas de administración de salas

Concesiones sobre carpetas, concesiones sobre muchos archivos a la vez y la marca de agua de descarga de la sala. Cada una ejecuta las mismas comprobaciones y escribe las mismas filas que la pantalla de Waafir que replica. Las escrituras requieren el alcance admin y un propietario del token que sea administrador de la organización. Los destinatarios son siempre un user_id (de find_user_by_email o list_dataroom_users), nunca una dirección de correo electrónico.

dataroom_get_folder_permissions

Lista las concesiones directas sobre una carpeta, e indica si está restringida (por sí misma o a través de una carpeta principal restringida).

  • Alcance: read, y el propietario del token debe pertenecer al equipo de la operación.
  • Entradas: dataroom_id (obligatorio); folder_id (obligatorio).
  • Salida: { folder_id, restricted, effectively_restricted, permissions: [{ user_id, can_read, can_download, expires_at, access_revoked, user_email?, user_name? }] }. Las claves de identidad están ausentes cuando no puede ver a esa persona.
  • Una carpeta que no puede ver responde NOT_FOUND, igual que una que no existe.

dataroom_set_folder_permissions

Concede a usuarios acceso a una carpeta, o lo deniega con can_read: false, opcionalmente en todo el árbol.

  • Alcance: admin.
  • Entradas: dataroom_id, folder_id, grants (obligatorios: [{ user_id, can_read, can_download, expires_at? }]); recursive (predeterminado false).
  • Salida: { success: true, recursive, granted, skipped: { count, items } }.
  • Cada beneficiario debe estar ya en la sala. Se rechaza un expires_at pasado. Una concesión que anularía una denegación en una carpeta superior se rechaza (CONFLICT) antes de escribir nada. Una concesión recursiva omite las carpetas hijas en las que el beneficiario tiene una denegación, y las lista en skipped. Los beneficiarios reciben la notificación en la aplicación «Acceso Otorgado».

dataroom_revoke_folder_permission

Revoca la concesión directa de un usuario sobre una carpeta, o levanta su denegación.

  • Alcance: admin.
  • Entradas: dataroom_id, folder_id, user_id (todos obligatorios).
  • Salida: { success: true, revoked }. revoked: false significa que no había ninguna concesión activa.
  • No se propaga en cascada: las concesiones que una concesión recursiva escribió en las descendientes de la carpeta se mantienen.

dataroom_bulk_set_file_permissions

Concede a los mismos usuarios acceso a muchos archivos a la vez. En mode: "add" (el predeterminado) solo añade: un campo que omita nunca retira acceso. En mode: "replace" sobrescribe cada concesión exactamente como se indica, por lo que puede retirar la descarga, borrar una caducidad o restablecer un acceso revocado. La sustitución tiene dos pasos: la primera llamada devuelve una vista previa y un confirm_token, y la repetición con el token la aplica, siempre que ninguna concesión de la selección haya cambiado entretanto.

  • Alcance: admin.
  • Entradas: dataroom_id, file_ids (hasta 200), grants (todos obligatorios); mode; confirm_token.
  • Salida: { success: true, mode, total_grants, left_revoked_user_ids }.
  • Un id de archivo que no está en la sala, o que no puede ver, hace que se rechace la solicitud completa con NOT_FOUND.
  • Todos los archivos deben estar en la sala y ser visibles para usted, y cada beneficiario debe estar ya en la sala. Si una denegación de carpeta anulara alguna concesión, se rechaza la solicitud completa antes de escribir ningún archivo.
  • Si se revocó el acceso de un beneficiario, un add no lo restablece, y el beneficiario se lista en left_revoked_user_ids.

dataroom_bulk_revoke_file_permissions

Revoca las concesiones directas de los usuarios indicados sobre muchos archivos a la vez. Las concesiones sobre carpetas y el acceso a la sala no se modifican.

  • Alcance: admin.
  • Entradas: dataroom_id, file_ids (hasta 200), user_ids (todos obligatorios).
  • Salida: { success: true, revoked_count }.
  • Un id de archivo que no está en la sala, o que no puede ver, hace que se rechace la solicitud completa con NOT_FOUND.

dataroom_get_watermark_settings

Lee los modos de marca de agua de descarga de la sala, para descargas de un solo archivo y descargas masivas: two_layer (la identidad de quien descarga más una capa con la IP y la fecha de cada descarga) o static (solo la identidad). Solo lectura: cámbielos en la configuración de Waafir.

  • Alcance: read, y el propietario del token debe ser administrador de la organización y pertenecer al equipo de la operación.
  • Entradas: dataroom_id (obligatorio).
  • Salida: { dataroom_id, single, bulk, stored: { single, bulk } }. Un null en stored significa que la sala nunca lo configuró, por lo que se aplica el valor predeterminado.

dataroom_archive

Archiva una sala de datos, de modo que sale de las listas de salas. Dos pasos: la primera llamada no cambia nada y devuelve una vista previa (el nombre de la sala y cuántos archivos, carpetas, personas con acceso y enlaces compartidos activos tiene) y un confirm_token. Repita la llamada con el token para archivarla.

  • Alcance: admin, y el propietario del token debe ser propietario o administrador de la organización.
  • Entradas: dataroom_id (obligatorio); confirm_token.
  • Salida: { success: true, dataroom_id, name, archived: true, restore_with: 'dataroom_restore' }.
  • Archivar no revoca el acceso ni las concesiones de nadie, y no se elimina nada. La sala sale de las listas, y las lecturas a nivel de sala (get_dataroom, list_files, list_folders, búsqueda, preguntas y respuestas, preguntas a la IA) responden NOT_FOUND hasta que se restaure. Un enlace directo a uno de sus archivos sigue abriéndolo. dataroom_restore recupera la sala, así que conserve el dataroom_id. La última sala de datos activa no se puede archivar (CONFLICT). No existe ninguna herramienta que elimine una sala de datos.

dataroom_restore

Restaura una sala de datos que su organización archivó. Vuelve a las listas de salas y todo lo que el archivado ocultó vuelve con ella: búsqueda con IA, resúmenes periódicos, actualizaciones para inversores, preguntas y respuestas y los complementos de la sala. Las carpetas, los archivos y el acceso quedan como estaban, porque el archivado no cambió nada de ello. Una sola llamada, sin paso de confirmación.

  • Alcance: admin, y el propietario del token debe ser propietario o administrador de la organización.
  • Entradas: dataroom_id (obligatorio): el id que devolvió dataroom_archive.
  • Salida: { success: true, dataroom_id, name, archived: false }.
  • Una sala que no está archivada se rechaza (CONFLICT, código NOT_ARCHIVED). Una sala archivada por el soporte de Waafir, o junto con su organización, se rechaza (CONFLICT, código SUPPORT_RESTORE_ONLY): solo el soporte puede restaurarla.
  • Se rechaza mientras la suscripción esté inactiva o el equipo supere su límite de puestos.

dataroom_rename

Cambia el nombre de una sala de datos.

  • Alcance: write, y el propietario del token debe pertenecer al equipo de la operación.
  • Entradas: dataroom_id, name (ambos obligatorios). El nombre se recorta y debe tener entre 1 y 100 caracteres.
  • Salida: { success: true, dataroom_id, name }.
  • El registro de auditoría guarda el nombre anterior y el nuevo.

Herramientas del equipo

El equipo de la organización abarca toda la organización, por lo que un token limitado a salas de datos concretas se rechaza (FORBIDDEN, código PAT_ROOM_SCOPED).

dataroom_team_list_members

Lista los miembros activos de la organización. No incluye las invitaciones pendientes.

  • Alcance: read, y el propietario del token debe pertenecer al equipo de la operación.
  • Entradas: ninguna.
  • Salida: { members: [{ membership_id, user_id, email, name, role, last_active_at }] }. role es uno de owner, admin o member.

Las escrituras siguientes necesitan un token con alcance admin cuyo propietario sea propietario o administrador de la organización. Las cuatro marcadas como de dos pasos devuelven una vista previa y un confirm_token en la primera llamada, y solo actúan cuando se repiten con él.

dataroom_team_invite_member

Invita a alguien por correo electrónico. Dos pasos; al confirmar se envía el correo de invitación.

  • Alcance: admin, más la concesión Enviar a personas fuera de tu organización.
  • Entradas: email, role (owner, admin o member) (obligatorios); confirm_token.
  • Salida: { membership_id, email, role, status: "pending" }. Nunca el enlace de invitación.
  • Solo un propietario puede invitar a un propietario. Se aplican el límite de puestos y los límites diarios de invitaciones.

dataroom_team_change_member_role

Cambia el rol de un miembro activo. Dos pasos; la vista previa muestra el rol anterior y el nuevo.

  • Alcance: admin.
  • Entradas: membership_id, role (obligatorios); confirm_token.
  • Salida: { success: true, membership_id, old_role, role }.
  • Solo un propietario puede cambiar el rol de un propietario o ascender a propietario. No puede cambiar su propio rol, y el último propietario no puede ser degradado.

dataroom_team_remove_member

Elimina a un miembro o revoca una invitación pendiente. Dos pasos; la vista previa muestra cuántas de las concesiones sobre archivos y carpetas y de los enlaces compartidos del miembro terminan.

  • Alcance: admin.
  • Entradas: membership_id (obligatorio); confirm_token.
  • Salida: { success: true, membership_id, action, file_grants_ended?, folder_grants_ended?, share_links_deactivated? }.
  • La eliminación pone fin a sus concesiones en esta organización y desactiva los enlaces compartidos que creó; las denegaciones se mantienen. Solo un propietario puede eliminar a un propietario.

dataroom_team_resend_invite

Vuelve a enviar una invitación pendiente con un enlace nuevo; el enlace anterior deja de funcionar. Dos pasos; al confirmar se envía el correo de invitación.

  • Alcance: admin, más la concesión Enviar a personas fuera de tu organización.
  • Entradas: membership_id (obligatorio); confirm_token.
  • Salida: la vista previa (membership_id, email, role) en la primera llamada; { success: true, membership_id } una vez confirmada.
  • Solo se puede reenviar una invitación pendiente: cualquier otra membresía se rechaza en la vista previa, sin token. Los límites diarios de invitaciones se descuentan al confirmar.

Herramientas de inversores y NDA

Herramientas sobre su lista de inversores, el NDA de su organización y los NDA de sus firmas inversoras. Cada una comprueba en cada llamada el rol actual del propietario del token en su organización, de modo que se rechaza a una persona que haya sido degradada desde entonces o un token limitado por debajo del rol que necesita la herramienta.

Las herramientas que leen en toda la organización necesitan un token que no esté limitado a salas de datos concretas. La lista incluye datos de participación (cuándo abrió alguien la sala por última vez, cuántos correos de invitación se enviaron, cuándo aceptó) solo para un token creado con Leer análisis de participación activado. Nunca incluye enlaces de exención del NDA ni ids de usuario.

Invitar a un inversor, retirar o restablecer su acceso, cambiar sus permisos y adjuntar o revocar un NDA de firma requieren cada uno dos pasos. La primera llamada no cambia nada: devuelve una vista previa de exactamente lo que ocurrirá y un confirm_token. Su asistente le muestra la vista previa y, solo cuando usted está de acuerdo, repite la llamada con argumentos idénticos más ese confirm_token. Un token funciona una sola vez y caduca al cabo de unos minutos. Si algo de lo que mostraba la vista previa ha cambiado entretanto, la segunda llamada se rechaza y su asistente vuelve a preguntarle.

dataroom_list_investors

Lista los inversores invitados a su organización o a una sala de datos.

  • Alcance: read. Rol: propietario o administrador.
  • Entradas: dataroom_id (opcional; obligatorio para un token limitado a salas de datos concretas); status (opcional: pending, accepted, revoked o access_requested).
  • Salida: { investors: [{ id, email, display_name, role, status, require_nda, nda, investor_org, can_view_monitoring, can_view_updates, expires_at, invited_at }] }. El id es el id de invitación que reciben las demás herramientas de inversores. Con Leer análisis de participación, cada fila incluye además engagement: { last_seen_at, send_count, last_sent_at, accepted_at }.

dataroom_get_nda

Lee el NDA de su organización: el título, el texto y las cláusulas de la versión actual, y el historial de versiones. Devuelve current: null cuando la organización aún no tiene NDA; leerlo nunca crea uno.

  • Alcance: read. Rol: un miembro del equipo de la operación.
  • Entradas: ninguna.
  • Salida: { current, versions, clauses, tally }. tally (recuentos de firmados, eximidos y pendientes) es null para un token limitado a salas de datos concretas.

dataroom_list_firm_ndas

Lista las firmas inversoras de su organización e indica si cada una tiene un NDA de firma vigente.

  • Alcance: read. Rol: un miembro del equipo de la operación. Necesita un token no limitado a salas de datos concretas.
  • Entradas: ninguna.
  • Salida: { firms: [{ id, name, has_live_nda }] }.

dataroom_get_firm_nda

Lee el NDA de una firma con su organización, y los sobres de firma electrónica completados que podría adjuntar como su NDA.

  • Alcance: read. Rol: un miembro del equipo de la operación. Necesita un token no limitado a salas de datos concretas.
  • Entradas: investor_org_id (obligatorio).
  • Salida: { agreement, attachable_envelopes }. agreement es null cuando la firma no tiene ninguno.

dataroom_extend_investor_access

Amplía el acceso de una invitación aceptada según la caducidad de enlaces de invitado de su organización (7 días salvo que la haya cambiado), y mantiene activa durante ese tiempo la sesión actual del inversor. Solo para una invitación a una sala de datos.

  • Alcance: write. Rol: un miembro del equipo de la operación. Necesita: Enviar a personas fuera de tu organización.
  • Entradas: invite_id (obligatorio).
  • Salida: { invite_id, expires_at, expiry_hours }. Una invitación que no está aceptada se rechaza con un conflicto.

dataroom_invite_investor

Invita a un inversor a una sala de datos por correo electrónico, vuelve a invitarlo con un nuevo rol o requisito de NDA, o reenvía su invitación. Recibe un correo con un enlace personal salvo que notify sea false. La vista previa indica si esto crea, actualiza o conserva la invitación, cuáles de sus argumentos se ignorarán (un reenvío conserva el rol y el NDA almacenados), el cambio de estado (un inversor retirado se restablece), cualquier exención del NDA y si se envía un correo. Generar la vista previa no consume nada del límite diario de invitaciones; el envío sí.

  • Alcance: admin. Rol: propietario o administrador, en el equipo de la operación de la sala de datos. Necesita: Enviar a personas fuera de tu organización.
  • Entradas: email, dataroom_id (obligatorios); role (viewer o downloader); require_nda; resend; notify; confirm_token.
  • Salida: la vista previa y confirm_token en la primera llamada; después { status: 'sent' | 'added', invite_id, link_expires_at }.

dataroom_revoke_investor_access

Retira el acceso de un inversor. Terminan su sesión actual y sus concesiones sobre archivos y carpetas en la sala de datos de la invitación. Restablecerlo más tarde recupera el acceso a la sala, no las concesiones sobre archivos.

  • Alcance: admin. Rol: propietario o administrador.
  • Entradas: invite_id (obligatorio); confirm_token.
  • Salida: la vista previa y confirm_token; después { status: 'revoked', invite_id }.

dataroom_reinstate_investor_access

Restablece a un inversor retirado o aprueba una solicitud de acceso. Solo el acceso a la sala.

  • Alcance: admin. Rol: propietario o administrador. Necesita: Enviar a personas fuera de tu organización.
  • Entradas: invite_id (obligatorio); confirm_token.
  • Salida: la vista previa y confirm_token; después { status: 'reinstated', invite_id }.

dataroom_set_investor_permissions

Cambia el rol de una invitación, el requisito de NDA y el acceso a la supervisión y a las actualizaciones. La vista previa enumera cada cambio. Desactivar el NDA registra una exención a su nombre, con un motivo y un enlace opcionales.

  • Alcance: admin. Rol: propietario o administrador.
  • Entradas: invite_id (obligatorio); al menos uno de role, require_nda, can_view_monitoring, can_view_updates; nda_waiver_reason; nda_waiver_url; confirm_token.
  • Salida: la vista previa y confirm_token; después { status: 'updated', invite_id, changes }.

dataroom_attach_firm_nda

Registra un sobre de firma electrónica completado como el NDA formalizado de una firma inversora, con su fecha de formalización y su plazo. Se puede adjuntar cualquier sobre que usted pueda ver.

  • Alcance: admin. Rol: propietario o administrador. Necesita un token no limitado a salas de datos concretas.
  • Entradas: investor_org_id, envelope_id, executed_at, term (obligatorios); confirm_token.
  • Salida: la vista previa y confirm_token; después { status: 'attached', agreement }.

dataroom_revoke_firm_nda

Revoca el NDA de una firma inversora. Si un NDA iniciado en Waafir sigue pendiente de firma, su sobre también se anula.

  • Alcance: admin. Rol: propietario o administrador. Necesita un token no limitado a salas de datos concretas.
  • Entradas: investor_org_id (obligatorio); reason; confirm_token.
  • Salida: la vista previa y confirm_token; después { status: 'revoked', investor_org_id, envelope_voided }.

Herramientas de firmas inversoras

Herramientas sobre sus firmas inversoras: los grupos a los que pertenecen sus inversores, como en la página Inversores. Cada una necesita un rol de propietario o administrador en su organización, comprobado en cada llamada, y un token que no esté limitado a salas de datos concretas. Una firma desconocida, una firma de otra organización y una firma que se fusionó en otra reciben todas la misma respuesta de no encontrado.

Incluir a alguien en una firma y fusionar dos firmas requieren cada uno dos pasos, como las herramientas de inversores anteriores. Ambas pueden sacar a una persona de su firma actual. Si la firma a la que se une tiene un NDA formalizado, este le cubre a partir de ese momento, y sus invitaciones pendientes que piden un NDA dejan de pedirlo. Cuando la vista previa enumera una invitación así, el token necesita también Enviar a personas fuera de tu organización. Aquí no se puede quitar a alguien de una firma.

dataroom_list_investor_firms

Lista las firmas inversoras de su organización con su dominio, número de miembros, la nota privada del equipo de la operación y el estado del NDA de la firma.

  • Alcance: read. Rol: propietario o administrador.
  • Entradas: ninguna.
  • Salida: { investor_firms: [{ id, name, canonical_domain, member_count, deal_team_note, firm_nda }] }. deal_team_note se marca como texto escrito por un colega.

dataroom_create_investor_firm

Crea una firma inversora. Con member_emails y canonical_domain, cada persona listada de ese dominio que ya esté invitada a una de sus salas de datos y que aún no pertenezca a ninguna firma pasa a ser miembro. No se saca a nadie de otra firma.

  • Alcance: admin. Rol: propietario o administrador.
  • Entradas: name (obligatorio); canonical_domain; member_emails (hasta 500, necesita canonical_domain).
  • Salida: { status: 'created', investor_firm: { id, name }, added }.

dataroom_rename_investor_firm

Cambia el nombre de una firma inversora.

  • Alcance: admin. Rol: propietario o administrador.
  • Entradas: investor_org_id, name (obligatorios).
  • Salida: { status: 'renamed' | 'unchanged', investor_org_id, name }.

dataroom_set_investor_firm_note

Establece o borra la nota privada del equipo de la operación sobre una firma. Los inversores nunca la ven.

  • Alcance: admin. Rol: propietario o administrador.
  • Entradas: investor_org_id, note (obligatorios; una cadena vacía la borra).
  • Salida: { status: 'set' | 'cleared' | 'unchanged', investor_org_id, cleared }.

dataroom_assign_investor_to_firm

Incluye a un inversor, por correo electrónico, en una firma, sacándolo de su firma actual si tiene una. La vista previa nombra la firma que abandona y las invitaciones pendientes cuyo paso de NDA quedaría cubierto ahora por el NDA de la firma. A quien ya está en la firma se le deja como está, sin paso de confirmación.

  • Alcance: admin. Rol: propietario o administrador. Necesita: Enviar a personas fuera de tu organización cuando la vista previa enumera una invitación.
  • Entradas: investor_org_id, email (obligatorios); confirm_token.
  • Salida: la vista previa y confirm_token; después { status: 'assigned', investor_org_id, email, moved_from, coverage_started }.

dataroom_merge_investor_firms

Fusiona una firma en otra. Todos los miembros de la firma de origen pasan a la firma de destino, y la firma de origen sale de su lista de firmas. No puede deshacer una fusión desde su asistente ni desde la aplicación. La vista previa enumera las personas que se trasladan y las invitaciones pendientes cuyo paso de NDA quedaría cubierto ahora por el NDA de la firma de destino.

  • Alcance: admin. Rol: propietario o administrador. Necesita: Enviar a personas fuera de tu organización cuando la vista previa enumera una invitación.
  • Entradas: source_investor_org_id, target_investor_org_id (obligatorios y distintos); confirm_token.
  • Salida: la vista previa y confirm_token; después { status: 'merged', source_investor_org_id, target_investor_org_id, moved_count, coverage_started_count }.

Herramientas de participación

Herramientas de solo lectura sobre quién leyó qué, cuándo y durante cuánto tiempo. Son datos de comportamiento sobre personas identificadas, por lo que todas necesitan un token creado con Leer análisis de participación activado y un rol de equipo de la operación. Cada una cuenta solo los documentos que el propio propietario del token puede leer. Las herramientas de sala admiten el mismo filtro que la página de participación: range (o from y to), people, firm_ids, folder_id y tz.

dataroom_get_activity_trail

El registro de accesos de su organización, del más reciente al más antiguo. Necesita un token no limitado a salas de datos concretas.

  • Alcance: read. Entradas: counterparty, since, cursor, limit.

dataroom_get_room_engagement

El marcador, el mapa de calor y la cronología de una sala de datos, con sus resúmenes agregados de la operación.

  • Alcance: read. Entradas: dataroom_id (obligatorio) y el filtro.

dataroom_get_engagement_scores

La puntuación de participación de cada inversor en una sala de datos, ordenada.

  • Alcance: read. Entradas: dataroom_id (obligatorio) y el filtro.

dataroom_get_investor_engagement

Las visitas de un inversor y los documentos que abrió en una sala de datos. La consulta se registra en su registro de auditoría, como ocurre en Waafir.

  • Alcance: read. Entradas: dataroom_id, email (obligatorios) y el filtro.

dataroom_get_document_engagement

Lectura por documento y por contraparte en toda su organización y, con file_id, el tiempo dedicado a cada página de ese documento. Necesita un token no limitado a salas de datos concretas.

  • Alcance: read. Entradas: counterparty, file_id, weeks, cursor, limit, page_range.

dataroom_get_firm_rollups

Actividad semanal por contraparte en toda su organización. Necesita un token no limitado a salas de datos concretas.

  • Alcance: read. Entradas: counterparty, weeks, cursor, limit.

Herramientas de preguntas y respuestas

Dos herramientas de solo lectura sobre los hilos de preguntas y respuestas de inversores en una sala de datos. Un token del equipo de la operación no puede publicar una pregunta aquí; el propio agente de un inversor pregunta con dataroom_ask_question (consulte Herramientas del agente del inversor).

Lo que devuelve una llamada depende de quién es el propietario del token:

  • un miembro del equipo de la operación ve todos los hilos de la sala de datos, incluida la dirección de correo electrónico de quien pregunta;
  • un inversor solo ve las preguntas que formuló él mismo, y ninguna dirección de correo electrónico.

Los documentos adjuntos se devuelven solo con id y nombre —nunca el contenido, nunca un enlace de descarga— y se oculta el nombre de un documento que quien llama no puede ver. Use las herramientas de documentos para el contenido; aplican sus propias comprobaciones de acceso. Ninguna de las dos herramientas devuelve nunca las preguntas de Preguntas y respuestas de la empresa (Company Q&A) de toda la organización, que no están asociadas a una sala de datos.

dataroom_list_questions

Nombre en el endpoint del área: list_questions

Lista los hilos de preguntas y respuestas de una sala de datos autorizada, de los más recientes a los más antiguos, cada uno con sus respuestas.

  • Alcance: read.
  • Entradas: dataroom_id (obligatorio); status (opcional; open, answered o closed); file_id (opcional; solo las preguntas formuladas sobre ese documento); limit (opcional, 1–100, predeterminado 25); offset (opcional, predeterminado 0).
  • Salida: { questions, pagination }. Pagine con offset mientras pagination.has_more sea true.

dataroom_get_question

Nombre en el endpoint del área: get_question

Obtiene un hilo de preguntas y respuestas por id, con todas sus respuestas.

  • Alcance: read.
  • Entradas: dataroom_id (obligatorio); question_id (obligatorio).
  • Salida: { question }.
  • Una pregunta de otra sala de datos o de otra organización —o, para un inversor, una formulada por otra persona— devuelve NOT_FOUND. La herramienta nunca confirma que ese id exista.

Cada pregunta incluye { id, dataroom_id, title, body, question_type, status, asked_by, file_id, file_name, created_at, updated_at, responses }, más asker_email solo cuando quien llama tiene derecho a verlo; para un inversor, la clave está ausente de la carga útil en lugar de estar presente con valor null. Cada entrada de responses es { id, body, responded_by, is_ai_draft, created_at, updated_at, attachments }.

dataroom_answer_question (escritura)

Responde a la pregunta de un inversor. No hay borrador: el inversor ve la respuesta de inmediato, y quien pregunta recibe un correo electrónico si su configuración lo permite. Ninguna de las dos cosas se puede deshacer.

  • Alcance: write. Miembros del equipo de la operación de la sala de datos.
  • Concesión: el token necesita Enviar a personas fuera de tu organización.
  • Entradas: dataroom_id, question_id, body (todos obligatorios); confirm_token.
  • Dos pasos. Sin confirm_token no se publica nada y obtiene una vista previa (la pregunta, cuántas respuestas tiene, si se enviará un correo a quien pregunta) más un token. Vuelva a llamar con los mismos argumentos y el token para publicar. Una respuesta nueva o un hilo cerrado entretanto hacen que la llamada falle, y vuelve a obtener una vista previa.

dataroom_close_question (escritura)

Cierra un hilo de preguntas y respuestas. Puede cerrarlo quien preguntó, o un administrador o gestor de la organización.

  • Alcance: write.
  • Entradas: dataroom_id, question_id (ambos obligatorios).
  • Salida: { question_id, outcome, kb_draft, kb_draft_skip_reason }.
  • Cuando la organización paga por la IA y la tiene activada, cerrar un hilo que tiene respuestas también pone en cola un borrador para la base de conocimiento. En caso contrario, kb_draft es skipped y el motivo explica por qué. No se envía nada al inversor.

dataroom_bulk_close_questions (escritura)

Cierra hasta 100 hilos de una sala de datos. Cada uno se evalúa por separado.

  • Alcance: write.
  • Entradas: dataroom_id, question_ids (ambos obligatorios).
  • Salida: { requested, closed, results }. El outcome de cada resultado es closed, not_found, forbidden o already_closed.

dataroom_edit_question (escritura)

Edita el título o el cuerpo de una pregunta, o ambos. Solo administradores y gestores.

  • Alcance: write.
  • Entradas: dataroom_id, question_id (ambos obligatorios); title, body (al menos uno).
  • Salida: { question_id, title, body }.

dataroom_edit_answer (escritura)

Edita el texto de una respuesta. Solo administradores y gestores. El inversor ve la edición de inmediato, como en Waafir; no se envía ningún correo nuevo.

  • Alcance: write.
  • Entradas: dataroom_id, question_id, response_id, body (todos obligatorios).
  • Salida: { response_id, question_id, body }.

dataroom_delete_question (escritura)

Elimina un hilo de preguntas y respuestas. Los inversores dejan de verlo, a él y a sus respuestas. Solo administradores y gestores.

  • Alcance: write.
  • Entradas: dataroom_id, question_id (ambos obligatorios); confirm_token.
  • Dos pasos. Sin confirm_token no se elimina nada y obtiene una vista previa más un token. Vuelva a llamar con los mismos argumentos y el token para eliminar. Un token funciona una sola vez y caduca al cabo de unos minutos.

dataroom_delete_answer (escritura)

Elimina una respuesta de un hilo. El inversor deja de verla. Solo administradores y gestores.

  • Alcance: write.
  • Entradas: dataroom_id, question_id, response_id (todos obligatorios); confirm_token.
  • Dos pasos, como en dataroom_delete_question.

dataroom_publish_kb_article (escritura)

Publica un artículo de la base de conocimiento, por ejemplo un borrador creado a partir de un hilo cerrado. A partir de entonces, los inversores que pueden ver la sala de datos pueden leerlo. Solo administradores y gestores.

  • Alcance: write.
  • Entradas: dataroom_id, article_id (ambos obligatorios); confirm_token.
  • Dos pasos, como en dataroom_delete_question.

Herramientas de actualizaciones para inversores

Reflejan el editor de actualizaciones para inversores de Waafir, con las mismas comprobaciones de rol. Todas necesitan el complemento Materiales para inversores (Investor Materials) en la sala de datos. Ninguna envía nada a los inversores: la publicación se hace en Waafir.

dataroom_list_updates

Lista las actualizaciones para inversores de una sala de datos en todos los estados, empezando por el cambio más reciente.

  • Alcance: read. Miembros del equipo de la operación de la sala de datos.
  • Entradas: dataroom_id (obligatorio).
  • Salida: { updates }, cada una { id, title, period_label, status, version, published_at, updated_at }.

dataroom_create_update (escritura)

Crea una actualización en borrador a partir de carteras o archivos, o de ambos (al menos uno).

  • Alcance: write. Miembros del equipo de la operación de la sala de datos.
  • Entradas: dataroom_id, period_label (ambos obligatorios); title, period_start, period_end, tone_notes, portfolio_ids, file_ids.
  • Salida: { update_id, status, portfolio_count, file_count }. Los archivos y las carteras que no pertenecen a su organización se excluyen y no se cuentan.

dataroom_get_update

Lee una actualización tal como la muestra el editor.

  • Alcance: read. Propietarios y administradores.
  • Entradas: dataroom_id, update_id (ambos obligatorios).
  • Salida: { update_id, status, document, latest_generation }. document es el último borrador generado con sus ediciones aplicadas, o null antes de la primera generación.

dataroom_get_update_generation

El estado de una ejecución de generación.

  • Alcance: read. Propietarios y administradores.
  • Entradas: dataroom_id, update_id, generation_id (todos obligatorios).
  • Salida: { generation_id, status, error_code }. Una ejecución fallida indica su código, nunca el mensaje almacenado.

dataroom_generate_update (escritura)

Inicia una generación con IA de una actualización en borrador o en revisión.

  • Alcance: write, más Leer contenido de documentos en el token: la ejecución lee los archivos seleccionados completos, guiada por las notas de tono de la actualización. Propietarios y administradores.
  • Entradas: dataroom_id, update_id (ambos obligatorios).
  • Salida: { generation_id, queued }. Consulte periódicamente dataroom_get_update_generation.
  • Necesita un plan de pago y las funciones de IA activadas, y cuenta para el límite diario de IA. Comparte el límite del editor de 5 generaciones por minuto.

dataroom_edit_update_draft (escritura)

Guarda sus ediciones sobre el contenido generado de un borrador, como hace el editor.

  • Alcance: write. Propietarios y administradores.
  • Entradas: dataroom_id, update_id, overrides (todos obligatorios). overrides admite narrative_sections, chart_placements y citations.
  • Salida: { update_id, status, document }. Solo se puede editar un borrador.

dataroom_submit_update_for_review (escritura)

Pasa una actualización en borrador a in_review.

  • Alcance: write. Administradores y gestores.
  • Entradas: dataroom_id, update_id (ambos obligatorios).
  • Salida: { update_id, status }.
  • La actualización necesita contenido generado y ninguna generación en curso.

dataroom_publish_update (escritura)

Publica una actualización en revisión. Los inversores de la sala de datos pueden verla de inmediato y cada uno recibe un correo electrónico, lo cual no se puede deshacer.

  • Alcance: write. Administradores y gestores.
  • Concesión: el token necesita Enviar a personas fuera de tu organización.
  • Entradas: dataroom_id, update_id (ambos obligatorios); confirm_token.
  • Dos pasos. Sin confirm_token no se publica nada y obtiene una vista previa (la actualización y a cuántos inversores se enviará un correo) más un token. Vuelva a llamar con los mismos argumentos y el token para publicar. Si la actualización o su lista de inversores cambió entretanto, la llamada se rechaza y vuelve a obtener una vista previa.

dataroom_republish_update (escritura)

Copia una actualización publicada en una nueva versión en borrador que después edita, revisa y publica. La versión publicada sigue visible hasta entonces.

  • Alcance: write. Administradores y gestores.
  • Entradas: dataroom_id, update_id (ambos obligatorios).
  • Salida: { update_id, status, version } del nuevo borrador.

Herramientas de Inteligencia de Mercado

Solo lectura. Necesitan el complemento Inteligencia de Mercado (Market Intelligence) (una versión preliminar funciona, con sus límites), un token que no esté limitado a salas de datos concretas y un miembro del equipo de la operación como propietario.

mi_get_subject

La empresa de Inteligencia de Mercado de su organización.

  • Alcance: read.
  • Entradas: ninguna.
  • Salida: { subject, access }. subject es { id, name }, o null hasta que alguien haya abierto Inteligencia de Mercado en Waafir.

mi_get_profile

El perfil de una empresa: la versión confirmada y el borrador de trabajo.

  • Alcance: read.
  • Entradas: subject_id (obligatorio).
  • Salida: { subject, confirmed, draft, file_names }. Cada campo es stated (con el file_id y la page de donde se leyó, o una página web pública y su cita), entered, not_applicable o null.
  • No se devuelven las citas de documentos de la sala de datos. Lea el archivo con las herramientas de documentos si las necesita.

mi_list_matches

Los inversores clasificados para el perfil de la empresa, de mejor a peor.

  • Alcance: read.
  • Entradas: subject_id (obligatorio).
  • Salida: { profile_version, preliminary, similarity, live, country, caveat, total, matches }. Cada coincidencia es { entity_id, name, score, penalties, reasons, contacts_available, on_roster, addable }.
  • Una versión preliminar muestra los 3 primeros. La clasificación por similitud solo se usa cuando su plan incluye IA de pago, la IA está activada y el límite diario de IA lo permite; similarity indica cuál de los dos casos se aplica.
  • Nunca se devuelven datos de contacto. Comparte el límite de la página de Waafir de 30 por minuto.

Herramientas de IA

Estas herramientas realizan el trabajo de IA en el lado de Waafir y entregan a su cliente de IA el resultado: una respuesta con citas, un resumen, una revisión, un plan de carpetas propuesto o un borrador. Su cliente nunca tiene que descargar los documentos para llegar a ello. Necesitan el complemento de IA, cuentan para el presupuesto diario de IA de su organización y se pausan cuando sus administradores pausan la IA. Cada una está limitada por persona a la misma frecuencia que el botón correspondiente de la aplicación, y registra lo que devolvió en el registro de actividad.

Una respuesta puede repetir lo que dice un documento cuando es su cliente quien redacta la pregunta, por lo que dataroom_ask, dataroom_draft_answer y dataroom_compare_files necesitan Leer contenido de documentos en el token, igual que dataroom_get_file_text. Sin ello no se listan, y una llamada se rechaza con GRANT_REQUIRED. Las demás herramientas de IA ejecutan una tarea fija sobre la sala y funcionan sin ello. Cada resultado marca los campos que contienen salida de IA en untrusted_content (consulte Texto no fiable en los resultados).

Solo se usan o citan documentos que el propietario del token puede abrir. Las herramientas funcionan en salas de datos de la propia organización del token.

dataroom_ask

Formula una pregunta sobre una sala de datos y obtiene una respuesta fundamentada.

  • Alcance: read, más Leer contenido de documentos en el token. Cualquier miembro de la sala de datos.
  • Entradas: dataroom_id (obligatorio); question (obligatorio).
  • Salida: { dataroom_id, answer, citations }. Hasta 10 citas, cada una { source_type, id, title, page? }. No se devuelve texto de documentos ni se guarda ninguna conversación de chat.

dataroom_summarise_file

Obtiene el resumen de IA y los puntos clave de un archivo.

  • Alcance: read. Equipo de la operación, con acceso de descarga al archivo.
  • Entradas: dataroom_id (obligatorio); file_id (obligatorio).
  • Salida: { file_id, file_name, status: "ready", summary, key_points }, o status: "queued" cuando el archivo aún no tiene resumen. El resumen se inicia entonces en segundo plano, como con el botón Resumir; vuelva a llamar más tarde.

dataroom_list_facts

Lista los hechos verificados y los términos clave extraídos de los documentos de una sala de datos.

  • Alcance: read. Equipo de la operación.
  • Entradas: dataroom_id (obligatorio); file_id (opcional); types (opcional); limit (opcional, 1–200, predeterminado 50); cursor (opcional).
  • Salida: { dataroom_id, facts, has_more, next_cursor }. Cada hecho es { id, file_id, file_name, fact_type, value, page, confidence, created_at }. Mientras has_more sea true, pase de nuevo next_cursor como cursor para la página siguiente.
  • Sin Leer contenido de documentos en el token, el value de cada hecho conserva como máximo 20 palabras (160 caracteres), contadas sobre el valor completo, y el hecho incluye value_truncated.

dataroom_compare_files

Compara dos archivos de una sala de datos y obtiene las diferencias sustanciales.

  • Alcance: read, más Leer contenido de documentos en el token. Equipo de la operación, con acceso de descarga a ambos archivos.
  • Entradas: dataroom_id (obligatorio); file_id_a (obligatorio); file_id_b (obligatorio).
  • Salida: { dataroom_id, file_a, file_b, differences }. Cada entrada de archivo es { id, name, truncated }: un documento muy largo se compara en su primera parte, y truncated lo indica. No se devuelve texto de documentos.
  • Un archivo de un tipo sin texto que extraer se rechaza con un 400, y un archivo almacenado de más de 50 MB con un 413 (FILE_TOO_LARGE), antes de obtener ninguno de los dos, cuando el texto del archivo no se ha extraído ya.

dataroom_review

Ejecuta la revisión de preparación con IA de una sala de datos.

  • Alcance: read. Equipo de la operación.
  • Entradas: dataroom_id (obligatorio); force_refresh (opcional).
  • Salida: { dataroom_id, cached, readinessScore, presentDocs, missingDocs, flaggedForRedaction, flaggedForRename, flaggedOutOfDate, suggestions }. Una revisión almacenada vigente se devuelve sin una nueva ejecución de IA salvo que force_refresh sea true.

dataroom_propose_organise (escritura)

Paso 1 de 2: propone una estructura de carpetas para una sala de datos. No se mueve nada.

  • Alcance: write. Propietario o administrador.
  • Entradas: dataroom_id (obligatorio).
  • Salida: { dataroom_id, suggestion_id, applied: false, proposed_folders, unchanged_file_ids, files, total_files, accounted_for }.

dataroom_apply_organise (escritura)

Paso 2 de 2: aplica una propuesta mediante su suggestion_id. Se aplica exactamente la propuesta almacenada, una sola vez; no se puede editar por el camino. Los archivos que el propietario del token no puede mover se omiten y se cuentan. Para deshacerlo, use el panel Organizar de la aplicación.

  • Alcance: write. Propietario o administrador.
  • Entradas: dataroom_id (obligatorio); suggestion_id (obligatorio).
  • Salida: { dataroom_id, suggestion_id, folders_created, files_moved, files_skipped }.

dataroom_draft_answer

Redacta un borrador de respuesta a la pregunta de un inversor a partir de los documentos de la sala de datos.

  • Alcance: read, más Leer contenido de documentos en el token. Propietario o administrador.
  • Entradas: question_id (obligatorio).
  • Salida: { question_id, draft, is_draft: true, sources }. El borrador solo se le devuelve a usted: no se guarda, envía ni publica nada. Una persona publica la respuesta en la aplicación. Las preguntas a nivel de organización se redactan en la aplicación.

Herramientas de preparación y base de conocimiento

Solo lectura. La preparación devuelve la puntuación y los recuentos que la sustentan, nunca el texto de la revisión; ejecute dataroom_review para ello.

dataroom_get_readiness_score

La puntuación de preparación de una sala de datos.

  • Alcance: read, y el propietario del token debe ser propietario o administrador de la organización.
  • Entradas: dataroom_id (obligatorio).
  • Salida: { dataroom_id, score, reviewed, questions_total, questions_answered, kb_articles, files_uploaded, present_categories, missing_categories }. score va de 0 a 100, o es null cuando no hay ninguna revisión de IA que se le pueda mostrar.

dataroom_get_readiness_rollup

La preparación de todas las salas de datos de la organización, tal como la muestra el Panel de control.

  • Alcance: read, y el propietario del token debe pertenecer al equipo de la operación. Se rechaza un token limitado a salas de datos concretas.
  • Entradas: ninguna.
  • Salida: { rooms: [{ id, name, investors, reading, updated, status, readinessPct, tone, reviewedAt, presentCount, missingCount, categories }] }. Los recuentos de documentos por categoría solo incluyen los documentos que el propietario del token puede leer.

dataroom_list_kb_articles

Lista los artículos de la base de conocimiento de una sala, los suyos propios y los de toda la organización.

  • Alcance: read.
  • Entradas: dataroom_id (obligatorio); category; include_drafts (solo equipo de la operación).
  • Salida: { articles: [{ id, title, category, published }] }.
  • Quien ha sido admitido en la sala solo a través de un documento compartido no ve ningún artículo. Un token de inversor solo ve los artículos publicados.

dataroom_get_kb_article

Lee un artículo.

  • Alcance: read.
  • Entradas: dataroom_id, article_id (obligatorios).
  • Salida: { id, title, category, body, published, updated_at }. Un borrador se trata como no encontrado salvo que el propietario del token pertenezca al equipo de la operación.

Herramientas del agente del inversor

Herramientas para el propio agente de un inversor: solo funcionan con un token de acceso de inversor, y un token del equipo de la operación ni las lista ni las invoca.

Un token de inversor también puede invocar estas herramientas compartidas. Cada una responde solo con lo que el inversor ve en la sala de datos.

  • Salas y archivos: dataroom_list, dataroom_get, dataroom_list_folders, dataroom_list_files, dataroom_get_file_metadata y dataroom_search.
  • Instantáneas: dataroom_list_snapshots y dataroom_get_snapshot, para las instantáneas que el inversor puede ver.
  • Descargas: dataroom_get_file_download_url. La copia siempre lleva una marca de agua con la identidad del inversor, igual que su descarga desde el navegador.
  • Preguntas y respuestas y artículos: dataroom_list_questions, dataroom_get_question, dataroom_list_kb_articles y dataroom_get_kb_article. Devuelven las preguntas del propio inversor y los artículos publicados.
  • IA: dataroom_ask, dataroom_compare_files, translate_text, translate_file y translate_file_status. Las traducciones de un inversor son privadas para él.

Un token de inversor tiene vetado dataroom_get_file_text: el texto plano no puede llevar marca de agua, así que el agente usa en su lugar la descarga con marca de agua.

Quién paga la IA. Cada llamada de IA consume unidades de asignación. La organización de la sala paga hasta una asignación mensual por inversor y por sala (meses UTC). El equipo de la operación fija la asignación por sala, y el valor predeterminado es de 200 unidades. Superada la asignación, paga una organización de la que el inversor sea miembro, si tiene una suscripción activa y la IA activada (primero las organizaciones de las que el inversor es propietario, después la más antigua). Si no se da ninguno de los dos casos, la llamada se rechaza antes de cualquier trabajo del modelo con QUOTA_EXCEEDED (HTTP 402). El mensaje indica la fecha en que se restablece la asignación.

Límite de frecuencia. Los agentes de un inversor comparten un único límite de 60 llamadas por minuto, en todos los tokens y conexiones de ese inversor. Por encima, la llamada se rechaza (HTTP 429) indicando la espera antes de reintentar.

Cada herramienta comprueba lo mismo que comprueba la sala de datos para el inversor: que el acceso no haya caducado ni se haya revocado, que el NDA esté aceptado, que el interruptor del agente por sala del equipo de la operación esté activado y, para un archivo, que el inversor tenga acceso de lectura a él. Un archivo que no puede leer se notifica como no encontrado, y su nombre nunca se devuelve. La aceptación de un NDA se sigue haciendo en la sala de datos.

dataroom_ask_question (escritura)

Formula una pregunta al equipo de la operación en una sala de datos. Solo el inversor y el equipo de la operación la ven; el equipo de la operación recibe una notificación.

  • Alcance: write.
  • Entradas: dataroom_id, title (al menos 5 caracteres) (obligatorios); description, category, file_id (un archivo que el inversor puede leer).
  • Salida: { question_id, dataroom_id, file_id, status }.

dataroom_list_file_comments

Los comentarios que el inversor puede ver en un archivo: los suyos, con las respuestas.

  • Alcance: read.
  • Entradas: dataroom_id, file_id (obligatorios).
  • Salida: { comments: [{ id, content, page, resolved, created_at, author, replies }] }.

dataroom_add_file_comment (escritura)

Comenta un archivo que el inversor puede leer. Visible para el inversor y el equipo de la operación, nunca para otros inversores.

  • Alcance: write.
  • Entradas: dataroom_id, file_id, content (obligatorios); page.
  • Salida: { comment_id, file_id, created_at }.

dataroom_reply_file_comment (escritura)

Responde a un comentario que el inversor puede ver. Un comentario de otro archivo se notifica como no encontrado.

  • Alcance: write.
  • Entradas: dataroom_id, file_id, comment_id, content (obligatorios).
  • Salida: { reply_id, comment_id, created_at }.

dataroom_get_my_nda_status

La situación del NDA del inversor en cada sala a la que puede llegar su agente.

  • Alcance: read.
  • Entradas: ninguna.
  • Salida: { rooms: [{ dataroom_id, dataroom_name, basis, accepted, accepted_at, version, accept_step }] }. basis es org_standard, firm_executed, firm_in_progress, waived o not_required; accept_step es clickthrough, held o none.

dataroom_list_my_notifications

Las notificaciones del inversor procedentes de la organización del token: invitaciones, respuestas a sus preguntas y cambios en su acceso a carpetas.

  • Alcance: read.
  • Entradas: unread_only; limit (1–50, predeterminado 20); offset.
  • Salida: { notifications: [{ id, type, title, body, resource_type, resource_id, read, created_at }], unread_count, pagination }.

dataroom_mark_notifications_read (escritura)

Marca notificaciones como leídas: los ids listados, o todas con all: true.

  • Alcance: write.
  • Entradas: ids (1–100) o all.
  • Salida: { marked }, cuántas cambiaron.

dataroom_list_published_updates

Las actualizaciones para inversores publicadas para el inversor en una sala.

  • Alcance: read.
  • Entradas: dataroom_id (obligatorio).
  • Salida: { updates: [{ id, title, period_label, version, published_at, unread }] }.
  • Se rechaza cuando el equipo de la operación ha desactivado las actualizaciones para el inversor, y cuando la sala no tiene el complemento Materiales para inversores (Investor Materials).

dataroom_get_published_update

Lee una actualización publicada.

  • Alcance: read.
  • Entradas: dataroom_id, update_id (obligatorios).
  • Salida: { update_id, title, period_label, version, published_at, document }.

Herramientas de instantáneas

Una instantánea es una copia congelada de las carpetas y las versiones de archivos de una sala, que se conserva como registro de auditoría. Ninguna herramienta devuelve contenido de archivos ni un enlace de descarga; las descargas se siguen haciendo en la aplicación. dataroom_get_snapshot y las herramientas de lectores rechazan un token limitado a salas de datos concretas, como hacen sus rutas de la aplicación.

dataroom_list_snapshots

  • Alcance: read. El equipo de la operación ve todas las instantáneas; cualquier otra persona solo ve aquellas a las que se le añadió como lector.
  • Entradas: dataroom_id (obligatorio).
  • Salida: { snapshots: [{ id, name, purpose, snapshot_at, file_count, folder_count, viewer_count? }] }.

dataroom_get_snapshot

  • Alcance: read, y acceso a la instantánea.
  • Entradas: snapshot_id (obligatorio).
  • Salida: { snapshot, folders: [{ folder_id, parent_folder_id, name }], files: [{ file_id, folder_id, name, size_bytes, mime_type, can_download }], can_manage_viewers }. Los archivos y las carpetas que el propietario del token no puede ver hoy se excluyen, y los recuentos coinciden con lo que se lista.

dataroom_create_snapshot

Congela la sala tal como está ahora. No cambia nada en la sala.

  • Alcance: write, solo equipo de la operación.
  • Entradas: dataroom_id, name (obligatorios); purpose, notes.
  • Salida: { snapshot: { id, name, purpose, snapshot_at, file_count, folder_count, viewer_count } }.

dataroom_list_snapshot_viewers

  • Alcance: read, solo equipo de la operación.
  • Entradas: snapshot_id (obligatorio).
  • Salida: { viewers: [{ viewer_id, email, granted_at, revoked_at, active }] }.

dataroom_grant_snapshot_viewer

Permite que alguien abra una instantánea mediante su dirección de correo electrónico. Dos pasos: la vista previa nombra la instantánea y la dirección. No se envía ningún correo: avísele usted mismo.

  • Alcance: write, solo equipo de la operación, más la concesión Enviar a personas fuera de tu organización.
  • Entradas: snapshot_id, email (obligatorios); confirm_token.
  • Salida: { viewer_id, email, active }.

dataroom_revoke_snapshot_viewer

Dos pasos.

  • Alcance: write, solo equipo de la operación.
  • Entradas: snapshot_id, viewer_id (obligatorios); confirm_token.
  • Salida: { success: true, viewer_id }.

Un enlace compartido da acceso a una sala o a un documento a quien lo tenga, por lo que crear uno siempre requiere dos pasos y un token con la concesión Enviar a personas fuera de tu organización. Ninguna herramienta lista la URL de un enlace.

  • Alcance: read, y el propietario del token debe ser propietario o administrador de la organización.
  • Entradas: dataroom_id (obligatorio); file_id para los enlaces activos de un documento.
  • Salida: { links: [{ id, kind, file_id?, mode, active, expires_at, has_password, require_nda, domain_allow_list, created_at, admitted_count? }] }.
  • Los enlaces por inversor no se listan; consulte las herramientas de inversores.

Dos pasos. La vista previa indica qué se comparte, quién puede entrar, la regla del NDA, cuándo caduca y cómo se aplica la marca de agua a las descargas. La confirmación debe repetir los mismos argumentos; si la lista de inversores cambia entretanto, vuelva a confirmar.

  • Alcance: write, propietario o administrador de la organización, más la concesión Enviar a personas fuera de tu organización.
  • Entradas: dataroom_id, mode (open o restricted) (obligatorios); file_id; expires_in_hours; domain_allow_list; require_nda (predeterminado true); confirm_token.
  • Salida: { id, url, mode, active, expires_at, require_nda, file_id }.
  • Un documento restringido no se puede compartir mediante enlace. No hay opción de contraseña.

Dos pasos. Todas las personas que usan el enlace pierden el acceso de inmediato.

  • Alcance: write, propietario o administrador de la organización.
  • Entradas: dataroom_id, link_id (obligatorios); confirm_token.
  • Salida: { success: true, link_id, status: "revoked" }.