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 requierenwrite, y las herramientas que conceden permisos requierenadmin. A un token por debajo del alcance requerido no se le muestra la herramienta, y se rechaza con un errorFORBIDDENsi la invoca (consulte Cómo se informa de un fallo). El alcance es acumulativo:writeincluyeread, yadminincluye 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ódigo | Significado | Qué hacer |
|---|---|---|
INVALID_ARGUMENT | Falta un argumento, está mal formado o no es un id válido | Corrija los argumentos y vuelva a intentarlo |
FORBIDDEN | El 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 permite | Solicite acceso o use un token con el alcance adecuado |
NOT_FOUND | No 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 existe | Compruebe el id y que el token esté restringido a la sala de datos del elemento |
CONFLICT | Entendido y permitido, pero la sala de datos no está en un estado en el que se pueda hacer | Lea el mensaje, resuelva el impedimento y vuelva a intentarlo |
TOO_LARGE | La entrada supera un límite de tamaño | Divida la entrada |
QUOTA_EXCEEDED | Se ha agotado una asignación medida, o la suscripción de la organización ha vencido | Alguien debe comprar o ampliar: volver a intentarlo no lo resolverá |
UPSTREAM_ERROR | Ha fallado un servicio posterior: no se pudo obtener el documento almacenado o falló la extracción de texto | Transitorio. Vuelva a intentarlo más tarde antes de tratarlo como definitivo |
UNAVAILABLE | Waafir 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 registro | Transitorio. Vuelva a intentarlo más tarde |
INTERNAL | Un fallo inesperado | No 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:
| Campo | Significado |
|---|---|
limit | el tamaño de página realmente aplicado |
offset | el desplazamiento realmente aplicado |
count | cuántas filas hay en esta página |
has_more | true cuando existen más filas después de esta página |
next_offset | el offset que debe pasar para la página siguiente, o null cuando el resultado está completo |
total | el 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.totales 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: truetambién se pagina: en un árbol grande, recórralo connext_offseten 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, predeterminadodesc). - 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. Usehas_more/next_offsetpara 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 }.
dataroom_search
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_moreestrue, la consulta coincidió con más archivos de los devueltos: pagine connext_offseto acote la consulta. No haytotal.
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ódigoPAT_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 }. Paseidcomodataroom_ida 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_listantes 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 deCONFLICTnombra 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_folderno 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 nuevoprevious_parent_folder_idcomonew_parent_folder_idpara 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 devuelve | Significado | Finalizar 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 1 | register_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 él | finalise_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_stepes"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 derequest_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_versioncomo 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_keydel cliente. Es opcional; si lo envía, debe ser igual a la clave que devolviórequest_file_uploado 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; elversion_numberque 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_numberdebe 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_idarestore_file_versionpara 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_metadatalista los ids de versión del archivo). - Salida:
{ file_id, version_id, version_number, already_current, new_version_created: false }. already_current: truesignifica 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_metadataya 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 }. Elnamedevuelto se lee de nuevo del almacenamiento, por lo que es lo que realmente se guardó;changedes 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 nuevoprevious_folder_idcomofolder_idpara 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_fileno 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_FOUNDen 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ón | error.code | Qué hacer |
|---|---|---|---|
| 1 | No existe ese archivo, o no es suyo | NOT_FOUND | Compruebe el id. |
| 2 | El archivo no está eliminado: ya está activo | CONFLICT | No hay nada que restaurar. |
| 3 | La subida del archivo nunca se completó | CONFLICT | No hay nada que restaurar: sus bytes nunca llegaron, así que no hay ningún documento que recuperar. Súbalo de nuevo. |
| 4 | La carpeta que lo contiene sigue eliminada | CONFLICT | Primero restore_folder, que también recupera los archivos eliminados con ella. |
| 5 | Un archivo activo ha tomado desde entonces el nombre en esa carpeta | CONFLICT | Cambie 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 conGRANT_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
UNAVAILABLEy 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
sourceindica 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 conGRANT_REQUIRED;dataroom_get_file_metadataydataroom_summarise_filesiguen 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 comoNOT_FOUNDen 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 }.sourcees"original"o"redacted".paginationincluye untotal. - Un archivo sin objeto almacenado —una nota, cuyo cuerpo se guarda en línea—
devuelve
NOT_FOUNDcon «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 un413(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_ERRORcuando no se puede obtener el documento almacenado o falla la extracción de texto, yUNAVAILABLEcuando 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 }(sourcees"direct"o"inherited"). - Las concesiones se ordenan por
created_at, después poruser_id, después porsourcey después porsource_folder_id, de modo que las páginas son estables entre llamadas.totales 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 sernull.identities_visiblele 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_visibleindica 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 }. Undataroom_permissiondenullsignifica 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: falseescribe 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, userevoke_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 deviewer,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(predeterminadofalse). - Salida:
{ success: true, recursive, granted, skipped: { count, items } }. - Cada beneficiario debe estar ya en la sala. Se rechaza un
expires_atpasado. 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 enskipped. 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: falsesignifica 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
addno lo restablece, y el beneficiario se lista enleft_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 } }. Unnullenstoredsignifica 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) respondenNOT_FOUNDhasta que se restaure. Un enlace directo a uno de sus archivos sigue abriéndolo.dataroom_restorerecupera la sala, así que conserve eldataroom_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ódigoNOT_ARCHIVED). Una sala archivada por el soporte de Waafir, o junto con su organización, se rechaza (CONFLICT, códigoSUPPORT_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 }] }.rolees uno deowner,adminomember.
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,adminomember) (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,revokedoaccess_requested). - Salida:
{ investors: [{ id, email, display_name, role, status, require_nda, nda, investor_org, can_view_monitoring, can_view_updates, expires_at, invited_at }] }. Elides el id de invitación que reciben las demás herramientas de inversores. Con Leer análisis de participación, cada fila incluye ademásengagement: { 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) esnullpara 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 }.agreementesnullcuando 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(viewerodownloader);require_nda;resend;notify;confirm_token. - Salida: la vista previa y
confirm_tokenen 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 derole,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_notese 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, necesitacanonical_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,answeredoclosed);file_id(opcional; solo las preguntas formuladas sobre ese documento);limit(opcional, 1–100, predeterminado 25);offset(opcional, predeterminado 0). - Salida:
{ questions, pagination }. Pagine conoffsetmientraspagination.has_moreseatrue.
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_tokenno 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_draftesskippedy 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 }. Eloutcomede cada resultado esclosed,not_found,forbiddenoalready_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_tokenno 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 }.documentes 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ódicamentedataroom_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).overridesadmitenarrative_sections,chart_placementsycitations. - 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_tokenno 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 }.subjectes{ 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 esstated(con elfile_idy lapagede donde se leyó, o una página web pública y su cita),entered,not_applicableo 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;
similarityindica 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 }, ostatus: "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 }. Mientrashas_moreseatrue, pase de nuevonext_cursorcomocursorpara la página siguiente. - Sin Leer contenido de documentos en el token, el
valuede cada hecho conserva como máximo 20 palabras (160 caracteres), contadas sobre el valor completo, y el hecho incluyevalue_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, ytruncatedlo 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 un413(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 queforce_refreshseatrue.
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 }.scoreva de 0 a 100, o esnullcuando 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_metadataydataroom_search. - Instantáneas:
dataroom_list_snapshotsydataroom_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_articlesydataroom_get_kb_article. Devuelven las preguntas del propio inversor y los artículos publicados. - IA:
dataroom_ask,dataroom_compare_files,translate_text,translate_fileytranslate_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 }] }.basisesorg_standard,firm_executed,firm_in_progress,waivedonot_required;accept_stepesclickthrough,heldonone.
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) oall. - 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 }.
Herramientas de enlaces compartidos
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.
dataroom_list_share_links
- Alcance:
read, y el propietario del token debe ser propietario o administrador de la organización. - Entradas:
dataroom_id(obligatorio);file_idpara 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.
dataroom_create_share_link
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(openorestricted) (obligatorios);file_id;expires_in_hours;domain_allow_list;require_nda(predeterminadotrue);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.
dataroom_revoke_share_link
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" }.