Referência do waafir-dataroom
O servidor waafir-dataroom é a superfície de API estável desta versão. Ele
expõe as ferramentas abaixo para ler e gerenciar suas salas de dados, agrupadas
pelo que fazem: ferramentas de leitura, ferramentas de pastas, ferramentas de
arquivos (ciclo de vida dos arquivos e versões de arquivos), uma ferramenta de
texto de documentos, ferramentas de permissões e ferramentas de perguntas e
respostas (Q&A).
Conexão: https://app.waafir.io/api/mcp/waafir, ou o servidor da área
https://app.waafir.io/api/mcp/waafir-dataroom — consulte
Configuração.
Nomes das ferramentas. Cada ferramenta é apresentada abaixo sob o nome que o
waafir lista, como dataroom_list_files. O servidor da área lista o nome mais
antigo indicado sob cada título como "Nome no endpoint da área", como
list_files, e o waafir ainda aceita esse nome se um cliente o chamar. Quando a
descrição ou o resultado de uma ferramenta indica outra ferramenta a ser chamada
em seguida (next_step, restore_with, undo_with), ela a nomeia da forma como
o endpoint ao qual você está conectado a lista. As descrições desta página usam
os nomes do endpoint da área.
Como o acesso é aplicado
Nesta página, token significa a credencial que o seu assistente usa: uma conexão criada ao entrar com sua conta, ou um token de acesso pessoal. Ambos carregam um escopo e, opcionalmente, uma lista de salas de dados, e são limitados da mesma forma.
Toda ferramenta é executada como o proprietário do token e é limitada pelas mesmas regras que a interface do produto aplica — não existe um caminho mais permissivo pelo MCP. Duas barreiras se aplicam a cada chamada:
- Escopo. Cada ferramenta declara um escopo mínimo:
as ferramentas de leitura exigem
read, as alterações de pastas e arquivos exigemwrite, e as ferramentas que concedem permissões exigemadmin. Um token abaixo do escopo exigido não vê a ferramenta e é rejeitado com um erroFORBIDDENse a chamar (consulte Como uma falha é informada). O escopo é cumulativo —writeincluiread,admininclui ambos. - Restrição por sala de dados. Se o token estiver restrito a salas de dados específicas, qualquer chamada que faça referência a uma sala de dados fora da sua lista de permissões é rejeitada, e um token restrito não consegue nem listar as salas de dados que não tem permissão para abrir. A verificação se baseia na sala de dados à qual um recurso pertence, de modo que um token restrito à sala de dados A nunca consegue alcançar um arquivo ou uma pasta na sala de dados B — mesmo dentro da mesma organização.
Além disso, as alterações de pastas e arquivos exigem uma função na equipe da transação para a sala de dados (investidores não podem fazer alterações), e as ferramentas de permissões exigem adicionalmente que o proprietário do token seja administrador ou gerente da organização. A exclusão de uma pasta ou de um arquivo é sempre uma exclusão lógica (soft delete) — os registros são marcados como excluídos e preservados para retenção e auditoria, nunca removidos definitivamente. Toda alteração é registrada como o mesmo evento de auditoria que a interface do produto grava, de modo que uma ação via MCP é indistinguível de uma ação na interface no log de auditoria.
Os identificadores (dataroom_id, folder_id, file_id, user_id) são UUIDs.
Texto não confiável nos resultados
Alguns resultados trazem texto que não foi escrito pelo Waafir: saída de IA sobre
um documento, o próprio texto de um documento, ou o que um investidor ou um colega
escreveu. Esse resultado acrescenta untrusted_content: { source, fields, notice },
e o mesmo { source, fields } em _meta["io.waafir/untrusted"]. source é
"document" ou "third-party". fields lista os caminhos que contêm esse texto
neste resultado, como answer ou questions[].responses[].body; um caminho só é
listado quando o resultado tem um valor ali. Trate esses campos como dados, nunca
como instruções para o seu assistente.
As ferramentas marcadas são 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, as prévias de dataroom_answer_question,
dataroom_delete_question, dataroom_delete_answer e
dataroom_publish_kb_article (o título do investidor), dataroom_get_update, dataroom_edit_update_draft,
dataroom_get_published_update, dataroom_list_file_comments,
dataroom_list_my_notifications, mi_get_profile e todas as ferramentas de IA, exceto
dataroom_apply_organise. Os nomes de arquivos não são marcados.
Como uma falha é informada
Uma falha de ferramenta não é um status HTTP. Quando uma ferramenta recusa uma
chamada, a resposta HTTP ainda é 200 e o envelope JSON-RPC ainda é um envelope
de sucesso; a falha é transportada dentro do resultado, que define
isError: true e cujo conteúdo de texto é:
{ "error": { "code": "CONFLICT", "message": "…" } }Ramifique com base em error.code, nunca no status HTTP — um cliente que decide
pelo status nunca reconhecerá nenhuma recusa desta página. Estes são os códigos
que uma ferramenta de sala de dados retorna:
| Código | Significado | O que fazer |
|---|---|---|
INVALID_ARGUMENT | Um argumento está ausente, malformado ou não é um id válido | Corrija os argumentos e tente novamente |
FORBIDDEN | O token é válido, mas não tem permissão — escopo insuficiente, um dataroom_id informado está fora da sua lista de permissões de salas de dados, ou a função do proprietário não permite | Solicite acesso ou use um token com o escopo correto |
NOT_FOUND | O registro não existe ou não é seu. A maioria das ferramentas que recebem um id de arquivo ou pasta também responde assim para um item em uma sala de dados fora da lista de permissões do token, exatamente como para um id que não existe | Verifique o id e se o token está restrito à sala de dados do item |
CONFLICT | Compreendido e permitido, mas a sala de dados não está em um estado em que isso possa ser feito | Leia a mensagem, resolva o bloqueio e tente novamente |
TOO_LARGE | A entrada excede um limite de tamanho | Divida a entrada |
QUOTA_EXCEEDED | Uma cota medida foi esgotada ou a assinatura da organização expirou | Alguém precisa comprar ou fazer upgrade — tentar novamente não resolve |
UPSTREAM_ERROR | Um serviço subsequente falhou — o documento armazenado não pôde ser obtido, ou a extração de texto falhou nele | Transitório. Tente novamente mais tarde antes de tratá-lo como fatal |
UNAVAILABLE | O Waafir não pode atender a solicitação agora: o arquivo ainda está sendo verificado, o arquivo armazenado não pôde ser lido para a verificação, ou a leitura não pôde ser registrada no log de auditoria, então o conteúdo foi retido em vez de ser divulgado sem registro | Transitório. Tente novamente mais tarde |
INTERNAL | Uma falha inesperada | Não tente novamente — escale |
Não reduza os dois códigos de "tente novamente mais tarde" a "falhou". UPSTREAM_ERROR
e UNAVAILABLE chegam até você hoje a partir de get_file_text, e significam pergunte
de novo, não desista. Um cliente que trata todo resultado diferente de OK como
definitivo transforma uma instabilidade passageira em uma falha permanente — o
único erro que esta tabela existe para evitar. Observe também que UNAVAILABLE é uma
recusa deliberada: o Waafir prefere reter o texto de um documento a entregá-lo
sem um registro de auditoria.
Um arquivo que ainda está sendo verificado. O Waafir verifica cada arquivo
recém-enviado e cada nova versão antes de servir o conteúdo. Até a verificação
terminar, uma ferramenta que lê o conteúdo do arquivo responde UNAVAILABLE com
um error.reason:
{ "error": { "code": "UNAVAILABLE", "reason": "ACTIVATION_PENDING", "message": "This file is still being checked. Try again shortly." } }É transitório: aguarde um pouco e chame de novo. Versões anteriores respondiam
com CONFLICT; ramifique por error.reason, não pela mensagem. A verificação
tem outros dois resultados. Nas ferramentas de sala de dados eles não trazem
reason, e a mensagem termina com o código entre parênteses:
- Bloqueado: o arquivo não passou na verificação de conteúdo.
INVALID_ARGUMENT, com a mensagem terminando em(ACTIVATION_BLOCKED). Nenhuma nova tentativa com este arquivo pode dar certo. - Ilegível: o arquivo armazenado não pôde ser lido para ser verificado.
UNAVAILABLE, com a mensagem terminando em(CONTENT_UNREADABLE). Tente novamente mais tarde.
A message indica o registro que está bloqueando sempre que houver um. Falhas no
nível de transporte — um nome de servidor desconhecido, uma conexão ou um token ausente ou revogado, um
complemento pago não adquirido — são status HTTP reais e estão listadas em
Configuração.
Paginação
Nenhuma ferramenta de listagem retorna um array ilimitado. Toda ferramenta que
retorna uma lista aceita limit e offset opcionais e retorna um objeto
pagination junto com as linhas:
| Campo | Significado |
|---|---|
limit | o tamanho de página efetivamente aplicado |
offset | o offset efetivamente aplicado |
count | quantas linhas há nesta página |
has_more | true quando existem mais linhas além desta página |
next_offset | o offset a informar para a próxima página, ou null quando o resultado está completo |
total | o número total de linhas por trás da janela — presente apenas onde é barato calculá-lo |
limit e offset são ajustados aos limites, não rejeitados: um valor acima do
máximo volta como o máximo, um valor abaixo do mínimo volta como o mínimo, e um valor
ausente ou não numérico volta como o padrão documentado. O bloco pagination
sempre informa os valores efetivamente aplicados, para que você veja o que
recebeu, e não o que pediu.
Use has_more para decidir se um resultado está completo — nunca deduza isso de
count === limit, que é ambíguo em uma última página exatamente cheia. Para ler
uma lista inteira, siga next_offset até que has_more seja false.
Ferramentas de leitura
Exigem o escopo read.
dataroom_list
Nome no endpoint da área: list_datarooms
Lista as salas de dados que o chamador pode acessar. Para um token restrito a salas de dados específicas, o resultado é filtrado por essa lista de permissões. Salas de dados arquivadas são excluídas.
- Entradas:
limit(opcional, 1–200, padrão 50);offset(opcional, padrão 0). - Saída:
{ datarooms: [{ id, name, description, org_name, created_at }], pagination: { limit, offset, count, has_more, next_offset, total } }. - Ordenado da mais antiga para a mais recente por
created_at, com desempate por id para que as páginas sejam estáveis.totalé o número total de salas de dados que este token consegue alcançar, contado depois que o filtro da lista de permissões é aplicado.
dataroom_get
Nome no endpoint da área: get_dataroom
Obtém uma única sala de dados pelo id. O chamador precisa ter autorização para ela; um token restrito a outras salas de dados é rejeitado.
- Entradas:
dataroom_id(obrigatório). - Saída:
{ dataroom: { id, name } | null }.
dataroom_list_folders
Nome no endpoint da área: list_folders
Lista as pastas de uma sala de dados. Respeita a visibilidade da equipe da
transação versus a do investidor — um investidor só vê as pastas que pode ler.
Lista um nível abaixo de uma pasta pai, ou informe all para a árvore inteira.
Pastas excluídas não são incluídas.
- Entradas:
dataroom_id(obrigatório);parent_folder_id(opcional — omita para as pastas de nível superior);all(booleano opcional — true lista todas as pastas da sala de dados);limit(opcional, 1–500, padrão 100);offset(opcional, padrão 0). - Saída:
{ folders: [{ id, name, parent_folder_id, created_at }], pagination: { limit, offset, count, has_more, next_offset, total } }. - Ordenado por nome, com desempate por id para que as páginas sejam estáveis.
all: truetambém é paginado — em uma árvore grande, percorra as páginas comnext_offsetem vez de esperar a árvore inteira em uma única resposta.
dataroom_list_files
Nome no endpoint da área: list_files
Lista os arquivos ativos (não excluídos) de uma sala de dados, opcionalmente dentro de uma pasta. Chamadores investidores só veem os arquivos que têm permissão para ler. Paginado.
- Entradas:
dataroom_id(obrigatório);folder_id(opcional — omita para os arquivos na raiz da sala de dados);limit(opcional, 1–200, padrão 50);offset(opcional, padrão 0);sort_dir(opcional,asc|desc, padrãodesc). - Saída:
{ files: [{ id, name, folder_id, size_bytes, mime_type, created_at, updated_at }], pagination: { limit, offset, count, has_more, next_offset } }. - Sem
total— contar o conjunto completo de correspondências não é barato neste caminho. Usehas_more/next_offsetpara paginar.
dataroom_get_file_metadata
Nome no endpoint da área: get_file_metadata
Obtém os metadados de um único arquivo: nome, tipo MIME, tamanho, caminho da pasta, lista de versões e resumo/categoria de IA, se houver. O arquivo precisa pertencer à sala de dados indicada; um arquivo em outra sala de dados (mesmo da mesma organização) retorna null.
- Entradas:
dataroom_id(obrigatório);file_id(obrigatório). - Saída:
{ 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
Nome no endpoint da área: search_dataroom
Pesquisa arquivos por nome dentro de uma única sala de dados autorizada (correspondência de substring sem diferenciar maiúsculas e minúsculas). Arquivos excluídos não são incluídos.
- Entradas:
dataroom_id(obrigatório);query(obrigatório, substring do nome do arquivo);limit(opcional, 1–100, padrão 25);offset(opcional, padrão 0). - Saída:
{ files: [{ id, name, mime_type, size_bytes, created_at }], pagination: { limit, offset, count, has_more, next_offset } }. - Mais recentes primeiro, com desempate por id para que as páginas sejam estáveis. Quando
has_moreétrue, a consulta encontrou mais arquivos do que os retornados — pagine comnext_offsetou restrinja a consulta. Não hátotal.
Ferramentas de salas
dataroom_create
Cria uma sala de dados na organização do token.
- Escopo:
write, e o proprietário do token precisa fazer parte da equipe da transação. Um token ou uma conexão limitado a salas de dados específicas é recusado (FORBIDDEN, códigoPAT_ROOM_SCOPED); use um que não esteja limitado a salas de dados. - Entradas:
name(obrigatório, 1–100 caracteres). Espaços no início e no fim são removidos, e um nome composto apenas de espaços é recusado (INVALID_ARGUMENT). - Saída:
{ id, name }. Informeidcomodataroom_idàs ferramentas de pastas e de arquivos. - Não é idempotente. Cada chamada cria uma nova sala. Se o resultado de uma chamada se perdeu,
procure a sala com
dataroom_listantes de chamar novamente, ou você criará uma duplicata. - Uma organização cuja assinatura não permite gravações, ou que está acima do seu
limite de assentos, é recusada com
QUOTA_EXCEEDED.
Ferramentas de pastas
Exigem o escopo write e uma função na equipe da transação para a sala de dados.
dataroom_create_folder
Nome no endpoint da área: create_folder
Cria uma pasta em uma sala de dados. Aninhe-a sob uma pasta pai, ou omita a pasta
pai para a raiz da sala de dados. Rejeita um nome duplicado sob a mesma pasta pai
com um CONFLICT.
- Entradas:
dataroom_id(obrigatório);name(obrigatório, 1–255 caracteres);parent_folder_id(opcional — null/omitido para a raiz da sala de dados). - Saída:
{ folder: { id, name, parent_folder_id } }. A mensagem deCONFLICTindica o id da pasta em conflito, então você não precisa listar novamente a pasta pai para encontrá-la.
dataroom_rename_folder
Nome no endpoint da área: rename_folder
Renomeia uma pasta. A pasta precisa pertencer à organização do chamador.
- Entradas:
folder_id(obrigatório);name(obrigatório, 1–255 caracteres). - Saída:
{ folder: { id, name } }.
dataroom_delete_folder
Nome no endpoint da área: delete_folder
Exclui logicamente uma pasta e toda a sua subárvore — cada subpasta aninhada e
cada arquivo dentro delas. Em uma sala de dados real, isso pode significar centenas
de documentos a partir de um único id de pasta, por isso o resultado informa
exatamente quantas pastas e arquivos foram removidos. Informe dry_run: true para
obter essas contagens sem excluir nada. Os registros são marcados como excluídos,
nunca removidos definitivamente, e toda a cascata pode ser desfeita com
restore_folder.
- Entradas:
folder_id(obrigatório);dry_run(booleano opcional — apenas prévia). - Saída:
{ deleted, dry_run, folder_id, folder_name, affected: { folders, files }, restore_with: "restore_folder" }. - Uma simulação (dry run) não altera nada e não registra nenhuma exclusão na trilha de auditoria.
dataroom_restore_folder
Nome no endpoint da área: restore_folder
Desfaz um delete_folder. Restaura a pasta e tudo o que aquela exclusão removeu
junto com ela — qualquer coisa excluída separadamente, antes, continua excluída.
Retorna um conflito se a pasta pai ainda estiver excluída (restaure-a primeiro) ou
se uma pasta ativa tiver passado a usar o nome desde então; nos dois casos, a
mensagem indica o id da pasta que está bloqueando.
- Entradas:
folder_id(obrigatório);dry_run(booleano opcional — apenas prévia). - Saída:
{ restored, dry_run, folder_id, folder_name, affected: { folders, files } }. - Desfazer a exclusão de uma pasta é sem perdas, e deliberadamente diferente da exclusão de um arquivo.
A cascata não altera o contador de armazenamento da sua organização e não descarta
os fragmentos do índice de pesquisa dos arquivos, então
restore_foldernão credita nada de volta — nada foi debitado — e os arquivos restaurados continuam pesquisáveis.delete_file/restore_file, abaixo, fazem as duas coisas. Excluir uma pasta cheia de documentos, portanto, não é o mesmo evento contábil que excluir cada um desses documentos.
dataroom_move_folder
Nome no endpoint da área: move_folder
Altera a pasta pai de uma pasta dentro da mesma sala de dados. Aninhe-a sob outra pasta, ou mova-a para a raiz da sala de dados. Rejeita mover uma pasta para dentro dela mesma ou de uma descendente (ciclo), para outra sala de dados, ou para onde já exista uma pasta irmã com o mesmo nome.
- Entradas:
folder_id(obrigatório);new_parent_folder_id(opcional — null/omitido para a raiz da sala de dados). - Saída:
{ folder: { id, name, parent_folder_id, previous_parent_folder_id } }. Informeprevious_parent_folder_idde volta comonew_parent_folder_idpara desfazer a movimentação.
Ferramentas de arquivos
As alterações de arquivos exigem o escopo write; get_file_download_url exige read
mais Ler conteúdo do documento no token.
O upload é intermediado, e o MCP nunca transporta os bytes. Os argumentos das
ferramentas são JSON, então o protocolo não tem canal binário: request_file_upload
gera uma URL pré-assinada e o seu cliente envia o conteúdo para ela diretamente com PUT. Um cliente que
não consegue emitir um HTTP PUT com um corpo binário bruto não consegue concluir um upload
— algo que vale a pena saber antes de começar, e não depois.
Qual ferramenta finaliza o upload depende de já existir ou não um arquivo com
aquele nome, e você não precisa descobrir isso: request_file_upload retorna um
campo next_step indicando a ferramenta a ser chamada.
request_file_upload retorna | Significado | Finalize com |
|---|---|---|
is_new_version: false, next_step: "register_file" | Não há arquivo ativo com o mesmo nome — um registro pendente foi criado na versão 1 | register_file |
is_new_version: true, next_step: "finalise_file_version" | Existe um arquivo ativo com o mesmo nome — este upload se torna uma nova versão dele | finalise_file_version |
Chame a ferramenta que next_step indicar. register_file só finaliza a versão 1 e
rejeita qualquer outra, então recorrer a ela no caminho de nova versão faz a chamada falhar.
dataroom_request_file_upload
Nome no endpoint da área: request_file_upload
Solicita uma URL de upload pré-assinada para um arquivo em uma sala de dados.
Retorna a URL e os cabeçalhos para enviar os bytes com PUT, o id do arquivo e
next_step — a ferramenta que finaliza este upload específico. Se já existir um
arquivo ativo com o mesmo nome na pasta de destino, is_new_version será true e o
id e o version_number retornados apontarão para esse arquivo existente.
- Escopo:
write. - Entradas:
dataroom_id(obrigatório);file_name(obrigatório, com extensão);file_size(obrigatório, bytes exatos, inteiro positivo);mime_type(obrigatório);folder_id(opcional — omita para a raiz da sala de dados). - Saída:
{ upload_url, headers, file_id, s3_key, is_new_version, version_number, next_step }—next_stepé"register_file"ou"finalise_file_version". - Esta ferramenta não move nenhum byte; ela apenas intermedeia a URL. Se o armazenamento de objetos não estiver configurado, a chamada falha imediatamente em vez de devolver uma URL que não pode funcionar.
dataroom_register_file
Nome no endpoint da área: register_file
Finaliza um primeiro upload pendente depois de enviar com PUT os bytes de
request_file_upload: marca o arquivo como ativo, incrementa o armazenamento da
organização e registra a versão 1. Chame-a quando request_file_upload tiver
retornado is_new_version: false — o next_step dela indica esta ferramenta.
- Escopo:
write. - Entradas:
file_id(obrigatório, o id pendente derequest_file_upload);s3_key(opcional);size_bytes(opcional — derivado do objeto enviado quando omitido). - Saída:
{ file_id, status: "active", version_number: 1 }. - Somente a versão 1, e ela impõe isso. Um arquivo que já está ativo, ou que
já tem uma versão, é rejeitado — a recusa indica
finalise_file_versioncomo a ferramenta para as versões 2 em diante. - A chave de armazenamento é derivada no servidor, e o
s3_keydo cliente nunca é considerado confiável. Ele é opcional; se você o enviar, ele precisa ser igual à chave querequest_file_uploadretornou, ou a chamada é rejeitada.
dataroom_finalise_file_version
Nome no endpoint da área: finalise_file_version
Finaliza uma nova versão de um arquivo existente, depois de enviar com PUT os bytes para a URL
que request_file_upload retornou com is_new_version: true. É o equivalente no MCP
a substituir um documento na interface, e a ferramenta que next_step indica
nesse caminho.
- Escopo:
write. - Entradas:
file_id(obrigatório);version_number(obrigatório — oversion_numberquerequest_file_uploadretornou). - Saída:
{ file_id, version_id, version_number, size_bytes, is_current: true, previous_version_number, previous_version_id, undo_with: "restore_file_version" }. version_numberprecisa ser exatamente a próxima versão deste arquivo. Ele é verificado, não adivinhado: qualquer outro valor é rejeitado em vez de gravado silenciosamente, e a chave de armazenamento é derivada dele no servidor.- A nova versão passa a ser a atual e a anterior é mantida no
histórico. Informe
previous_version_idarestore_file_versionpara desfazer. - Um arquivo que ainda não concluiu seu primeiro upload é rejeitado — finalize a versão 1
com
register_fileprimeiro. A chamada também falha se os bytes ainda não estiverem de fato no armazenamento, em vez de registrar uma versão sem nada por trás.
dataroom_restore_file_version
Nome no endpoint da área: restore_file_version
Torna uma versão anterior de um arquivo a atual novamente — o desfazer de
finalise_file_version. Move o marcador de versão atual e faz o arquivo apontar
para aquela versão; não gera uma nova linha de versão, então o histórico de
versões continua sendo uma lista fiel das revisões que foram realmente enviadas.
- Escopo:
write. - Entradas:
file_id(obrigatório);version_id(obrigatório — precisa pertencer a este arquivo;get_file_metadatalista os ids de versão do arquivo). - Saída:
{ file_id, version_id, version_number, already_current, new_version_created: false }. already_current: truesignifica que a versão já era a atual e nada mudou — uma operação sem efeito, não uma falha.- Não existe uma ferramenta separada para listar versões:
get_file_metadatajá retorna as versões do arquivo com seus ids, números e indicador de versão atual.
dataroom_rename_file
Nome no endpoint da área: rename_file
Renomeia um arquivo — somente metadados. Isso não cria uma nova versão; o
versionamento serve para substituição de conteúdo, não para mudança de rótulo. Os
nomes precisam ser únicos entre os arquivos ativos da mesma pasta; um conflito
retorna um CONFLICT indicando o arquivo existente.
- Escopo:
write. - Entradas:
file_id(obrigatório);name(obrigatório, 1–255 caracteres). - Saída:
{ file_id, name, previous_name, changed }. Onameretornado é lido de volta do armazenamento, então é o que foi realmente persistido —changedé false se o nome armazenado não mudou.
dataroom_move_file
Nome no endpoint da área: move_file
Move um arquivo para outra pasta na mesma sala de dados, ou para a raiz da sala de dados. Movimentações entre salas de dados são rejeitadas: uma sala de dados é uma fronteira de permissões, e realocar conteúdo através dela mudaria quem pode lê-lo. Rejeita uma movimentação quando já existe um arquivo ativo com o mesmo nome no destino.
- Escopo:
write. - Entradas:
file_id(obrigatório);folder_id(opcional — null/omitido para a raiz da sala de dados). - Saída:
{ file_id, name, folder_id, previous_folder_id, moved }. Informeprevious_folder_idde volta comofolder_idpara desfazer a movimentação.
dataroom_delete_file
Nome no endpoint da área: delete_file
Exclui um arquivo. O resultado repete o nome do arquivo que foi realmente
excluído, de modo que um id equivocado fica visível na resposta. O arquivo e suas
versões são mantidos para retenção e auditoria, nunca apagados, e restore_file o traz de volta.
- Escopo:
write. - Entradas:
file_id(obrigatório). - Saída:
{ file_id, status: "deleted", name, folder_id, restore_with: "restore_file" }. - O armazenamento só é creditado de volta para um upload que foi realmente concluído. Um arquivo cujos bytes chegaram devolve seu tamanho ao contador de armazenamento da sua organização. Um arquivo que ainda aguarda o upload nunca foi cobrado, então excluí-lo não altera o contador em nada — a exclusão é neutra para o contador, não um reembolso de bytes que você nunca armazenou.
- A exclusão também descarta os fragmentos do índice de pesquisa do arquivo, então o documento sai
da pesquisa de documentos imediatamente.
restore_filenão consegue trazê-los de volta — veja abaixo. - A ferramenta só resolve um arquivo ativo, então chamá-la uma segunda vez com o
mesmo id retorna
NOT_FOUNDem vez de excluir algo novamente. O contador de armazenamento não pode ser debitado duas vezes por um mesmo arquivo.
dataroom_restore_file
Nome no endpoint da área: restore_file
Desfaz um delete_file: traz de volta à ativa um arquivo excluído logicamente,
restaurando o registro e a contabilização de armazenamento que a exclusão
reverteu. Não restaura os fragmentos do índice de pesquisa do arquivo — eles
são descartados na exclusão —, então o arquivo fica ativo e disponível para
download, mas precisa ser reindexado antes que a pesquisa de documentos o
encontre novamente. search_index_restored é sempre false e deixa isso claro em
vez de sugerir um desfazer sem perdas.
- Escopo:
write. - Entradas:
file_id(obrigatório). - Saída:
{ restored, file_id, name, folder_id, storage_bytes_restored, search_index_restored: false }.
Quando uma restauração é recusada. Ela falha em vez de mascarar um conflito, e indica o registro que está bloqueando quando houver um:
| # | Condição | error.code | O que fazer |
|---|---|---|---|
| 1 | O arquivo não existe ou não é seu | NOT_FOUND | Verifique o id. |
| 2 | O arquivo não está excluído — ele já está ativo | CONFLICT | Não há nada a restaurar. |
| 3 | O upload do arquivo nunca foi concluído | CONFLICT | Não há nada a restaurar: os bytes nunca chegaram, então não há documento a trazer de volta. Faça o upload novamente. |
| 4 | A pasta que o contém ainda está excluída | CONFLICT | Use restore_folder primeiro — isso também traz de volta os arquivos excluídos junto com ela. |
| 5 | Um arquivo ativo passou a usar o nome naquela pasta | CONFLICT | Renomeie o arquivo que está com o nome e tente novamente. |
Esses são códigos no payload, não status HTTP — consulte Como uma falha é informada.
As verificações são executadas na ordem numerada acima, e você é informado da primeira que falhar. O caso de upload nunca concluído (3) é, portanto, informado depois das verificações de inexistência e de não exclusão, mas antes das verificações de pasta e de nome: um arquivo cujos bytes nunca chegaram não pode ser restaurado, qualquer que seja a situação da pasta ou do nome, então não faz sentido mandar você corrigir nenhuma delas.
dataroom_get_file_download_url
Nome no endpoint da área: get_file_download_url
Obtém uma URL de download de curta duração para um arquivo. O chamador precisa ter autorização para o arquivo (a permissão de leitura/download por arquivo). A URL fornece a mesma cópia que o download pelo navegador: com marca d'água quando a sala aplica marca d'água aos downloads, e a cópia tarjada de um documento tarjado para um destinatário de fora da sua organização. Ela expira após alguns minutos.
- Escopo:
read, mais Ler conteúdo do documento no token. Sem isso, a chamada é recusada comGRANT_REQUIRED. - Limite: no máximo 10 chamadas por minuto por token, porque cada uma prepara uma
cópia protegida. Acima disso,
RATE_LIMITED. - Se uma cópia protegida não puder ser preparada a tempo, a chamada é recusada com
UNAVAILABLEe sem link; tente novamente ou faça o download no Waafir. - Entradas:
file_id(obrigatório). - Saída:
{ download_url, expires_in_seconds }.
Ferramentas de texto de documentos
Uma ferramenta, para ler o texto extraído de um documento em vez de baixar o próprio arquivo.
dataroom_get_file_text
Nome no endpoint da área: get_file_text
Lê o texto extraído de um documento, uma página por vez. Retorna segmentos numerados
— para um PDF, um segmento por página, a menos que a página seja muito longa — mais um
bloco pagination, para que você possa percorrer um documento longo com offset.
Duas coisas tornam esta ferramenta mais rigorosa do que uma leitura de metadados:
- Você precisa ter permissão para baixar o arquivo, não apenas para visualizá-lo. A permissão somente de visualização não basta, e um token restrito em relação ao documento é recusado.
- Se o documento foi tarjado e você não faz parte da equipe da transação, você
recebe o texto da versão tarjada, e
sourceinforma qual artefato você recebeu. A ferramenta nunca entrega silenciosamente o original a um leitor de perímetro.
Toda chamada bem-sucedida é registrada no log de auditoria da organização, nas mesmas condições que a leitura de um documento no produto.
- Escopo:
read, mais Ler conteúdo do documento no token. Sem isso, a chamada é recusada comGRANT_REQUIRED;dataroom_get_file_metadataedataroom_summarise_fileainda fornecem o resumo do documento. - Entradas:
file_id(obrigatório);dataroom_id(opcional — validado em relação à própria sala de dados do arquivo quando informado, e uma divergência é lida comoNOT_FOUNDem vez de confirmar que o arquivo existe em outro lugar);limit(opcional, 1–5, padrão 3);offset(opcional, padrão 0). - Saída:
{ file_id, file_name, source, segment_max_chars, segments, pagination }.sourceé"original"ou"redacted".paginationtraz umtotal. - Um arquivo sem objeto armazenado — uma nota, cujo corpo é mantido inline — retorna
NOT_FOUNDcom "no extractable content". - Um arquivo cujo tipo não tem texto a extrair (um arquivo compactado, por exemplo) é recusado com um
400, e um arquivo armazenado com mais de 50 MB, com um413(FILE_TOO_LARGE). Ambos se aplicam apenas quando o texto do arquivo ainda não foi extraído (o texto já extraído é servido primeiro), são recusados antes de o documento ser buscado, e nenhum deles é um erro do tipo "tente novamente mais tarde". - Esta é a ferramenta que produz os dois códigos de tentar novamente mais tarde:
UPSTREAM_ERRORquando o documento armazenado não pode ser buscado ou a extração de texto falha nele, eUNAVAILABLEquando a gravação de auditoria da leitura falha — caso em que o texto é retido deliberadamente em vez de ser divulgado sem registro. Ambos merecem uma nova tentativa antes de você tratar o documento como ilegível.
Ferramentas de permissão
Estas leem e alteram quem pode ver o quê. As três ferramentas de leitura exigem apenas
o escopo read (as duas ferramentas de diretório exigem, além disso, uma função na equipe da transação); as
quatro ferramentas de concessão/revogação exigem o escopo admin e um proprietário do token que seja
administrador ou gerente da organização.
Um token nunca carrega a prerrogativa de proprietário/administrador sobre arquivos restritos. No
aplicativo, um proprietário ou administrador da organização vê todos os arquivos restritos; por meio de um token,
ele só alcança um deles se o tiver criado ou tiver uma concessão sobre ele, exatamente como qualquer
outro membro. Uma ferramenta de arquivo recusada em um arquivo assim responde NOT_FOUND com o
mesmo texto de um arquivo que não existe ("File not found in the requested
dataroom, or not readable by this credential"), de modo que a resposta nunca confirma
que um arquivo restrito está lá.
dataroom_get_file_permissions
Nome no endpoint da área: get_file_permissions
Lista as concessões de permissão em um arquivo (diretas e herdadas da pasta). Espelha a visualização de permissões de arquivo da interface.
- Escopo:
read. - Entradas:
dataroom_id(obrigatório);file_id(obrigatório);limit(opcional, 1–200, padrão 50);offset(opcional, padrão 0). - Saída:
{ permissions: [{ user_id, can_read, can_download, access_revoked, expires_at, granted_by, created_at, source, source_folder_name?, source_folder_id?, user_email?, user_name?, granted_by_email? }], pagination: { limit, offset, count, has_more, next_offset, total }, identities_visible }(sourceé"direct"ou"inherited"). - As concessões são ordenadas por
created_at, depoisuser_id, depoissource, depoissource_folder_id, para que as páginas sejam estáveis entre chamadas.totalé a contagem completa de concessões no arquivo. - Os campos de identidade (
user_email,user_name,granted_by_email) seguem a mesma regra de visibilidade das ferramentas de diretório abaixo: aparecem para chamadores da equipe da transação, identidades de investidores exigem, além disso, um administrador ou gerente da organização, e, quando você não tem permissão, as chaves ficam ausentes em vez denull.identities_visibleinforma em qual caso você está; as concessões em si são sempre listadas.
dataroom_list_users
Nome no endpoint da área: list_dataroom_users
Lista os usuários que têm uma concessão de acesso ativa em uma sala de dados, com o user_id
que as ferramentas de permissão exigem, mais o endereço de e-mail e o nome de cada beneficiário. Esta
costuma ser a primeira chamada quando você precisa de um user_id.
- Escopo:
read, e uma função na equipe da transação da organização da sala de dados (o mesmo controle da página da equipe). - Entradas:
dataroom_id(obrigatório);limit(opcional, 1–200, padrão 50);offset(opcional, padrão 0). - Saída:
{ 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 }. - Identidades de investidores são omitidas, a menos que você seja administrador ou
gerente da organização;
investor_rows_visibleinforma qual conjunto você recebeu. - Lista apenas beneficiários explícitos. Proprietários e administradores da organização têm
acesso implícito sem uma linha de concessão e não aparecerão — resolva-os com
find_user_by_email.
dataroom_find_user_by_email
Nome no endpoint da área: find_user_by_email
Resolve um endereço de e-mail para o user_id que as ferramentas de permissão exigem,
junto com a função do usuário na organização e sua permissão atual nesta sala de dados.
- Escopo:
read, e uma função na equipe da transação da organização da sala de dados. Resolver um investidor exige, além disso, um administrador ou gerente da organização. - Entradas:
dataroom_id(obrigatório);email(obrigatório, comparado sem diferenciar maiúsculas de minúsculas). - Saída:
{ found: true, user: { user_id, email, name, org_role, dataroom_permission } }ou{ found: false }. Umdataroom_permissionigual anullsignifica que o usuário está na organização, mas ainda não tem acesso a esta sala — convide-o primeiro. - Esta não é uma consulta a um diretório global: só são resolvidos usuários da
própria organização da sala de dados ou que tenham acesso ativo a ela. Um endereço desconhecido, um
usuário fora do seu locatário e um usuário que você não tem permissão para ver retornam todos
um
{ found: false }idêntico, de modo que uma resposta negativa nunca revela se uma conta existe.
dataroom_set_file_permissions
Nome no endpoint da área: set_file_permissions
Concede ou atualiza a permissão de leitura/download de um usuário em um arquivo. Um token
read/write, ou um proprietário que não seja administrador ou gerente da organização, é rejeitado.
- Escopo:
admin. - Entradas:
dataroom_id(obrigatório);file_id(obrigatório);user_id(obrigatório);can_read(booleano obrigatório);can_download(booleano obrigatório);expires_at(timestamp ISO opcional, deve estar no futuro). - Saída:
{ success: true, effective: { can_read, can_download } }— a decisão posterior à concessão, que reflete as restrições do arquivo e a herança da pasta e pode, portanto, diferir do que você solicitou. - Esta ferramenta concede acesso; não pode removê-lo. Passar
can_read: falsegrava uma concessão ativa com leitura negada, que outras concessões (associação à organização, uma concessão na sala de dados, herança de pasta) ainda podem sobrepor. Para remover de fato o acesso de um usuário a um arquivo, userevoke_file_permission.
dataroom_revoke_file_permission
Nome no endpoint da área: revoke_file_permission
Remove a concessão de permissão direta de um usuário em um arquivo (revogação lógica: a linha é
preservada para a trilha de auditoria). Retorna revoked: false se o usuário não tinha
concessão direta no arquivo.
- Escopo:
admin. - Entradas:
dataroom_id(obrigatório);file_id(obrigatório);user_id(obrigatório). - Saída:
{ success: true, revoked }. - Afeta apenas a concessão direta. O acesso herdado de uma permissão de pasta não é
afetado e precisa ser revogado na pasta. Reversível concedendo novamente com
set_file_permissions.
dataroom_invite_user
Nome no endpoint da área: invite_user_to_dataroom
Concede a um usuário conhecido acesso no nível da sala de dados com um determinado nível de permissão — uma concessão de acesso direta (não um convite por e-mail). Idempotente (upsert).
- Escopo:
admin. - Entradas:
dataroom_id(obrigatório);user_id(obrigatório);permission(obrigatório — um deviewer,downloader,contributor,manager);expires_at(timestamp ISO opcional, deve estar no futuro). - Saída:
{ success: true, grant_id }.
dataroom_remove_user
Nome no endpoint da área: remove_user_from_dataroom
Revoga o acesso de um usuário no nível da sala de dados (revogação lógica: define revoked_at,
preservando a trilha de auditoria). Retorna revoked: false se o usuário não tinha concessão
ativa.
- Escopo:
admin. - Entradas:
dataroom_id(obrigatório);user_id(obrigatório). - Saída:
{ success: true, revoked }.
Ferramentas de administração da sala
Concessões de pasta, concessões em muitos arquivos de uma vez e a marca d'água de download
da sala. Cada uma executa as mesmas verificações e grava as mesmas linhas que a tela do Waafir
que ela espelha. As gravações exigem o escopo admin e um proprietário do token que seja
administrador da organização. Os destinatários são sempre um user_id (obtido de
find_user_by_email ou list_dataroom_users), nunca um endereço de e-mail.
dataroom_get_folder_permissions
Lista as concessões diretas em uma pasta e se ela é restrita (por si só ou por meio de uma pasta-mãe restrita).
- Escopo:
read, e o proprietário do token precisa fazer parte da equipe da transação. - Entradas:
dataroom_id(obrigatório);folder_id(obrigatório). - Saída:
{ folder_id, restricted, effectively_restricted, permissions: [{ user_id, can_read, can_download, expires_at, access_revoked, user_email?, user_name? }] }. As chaves de identidade ficam ausentes quando você não pode ver aquela pessoa. - Uma pasta que você não pode ver responde
NOT_FOUND, igual a uma que não existe.
dataroom_set_folder_permissions
Concede a usuários acesso a uma pasta, ou o nega com can_read: false, opcionalmente
em toda a árvore abaixo dela.
- Escopo:
admin. - Entradas:
dataroom_id,folder_id,grants(obrigatórios:[{ user_id, can_read, can_download, expires_at? }]);recursive(padrãofalse). - Saída:
{ success: true, recursive, granted, skipped: { count, items } }. - Todo beneficiário já precisa estar na sala. Um
expires_atno passado é recusado. Uma concessão que uma negação em uma pasta acima anularia é recusada (CONFLICT) antes que qualquer coisa seja gravada. Uma concessão recursiva ignora os filhos em que o beneficiário tem uma negação e os lista emskipped. Os beneficiários recebem a notificação "Access Granted" no aplicativo.
dataroom_revoke_folder_permission
Revoga a concessão direta de um usuário em uma pasta ou suspende a negação dele.
- Escopo:
admin. - Entradas:
dataroom_id,folder_id,user_id(todos obrigatórios). - Saída:
{ success: true, revoked }.revoked: falsesignifica que não havia concessão ativa. - Isso não se propaga em cascata: as concessões que uma concessão recursiva gravou nos descendentes da pasta permanecem.
dataroom_bulk_set_file_permissions
Concede aos mesmos usuários acesso a muitos arquivos de uma vez. No mode: "add" (o
padrão), ela apenas adiciona: um campo que você omite nunca retira acesso. No
mode: "replace", ela sobrescreve cada concessão exatamente como informada, podendo assim remover
o download, limpar uma expiração ou restabelecer um acesso revogado. A substituição é feita em duas etapas:
a primeira chamada retorna uma prévia e um confirm_token, e a repetição com o
token a aplica, desde que nenhuma concessão da seleção tenha mudado nesse intervalo.
- Escopo:
admin. - Entradas:
dataroom_id,file_ids(até 200),grants(todos obrigatórios);mode;confirm_token. - Saída:
{ success: true, mode, total_grants, left_revoked_user_ids }. - Um id de arquivo que não está na sala, ou que você não pode ver, faz toda a solicitação ser recusada com
NOT_FOUND. - Todo arquivo precisa estar na sala e visível para você, e todo beneficiário já precisa estar na sala. Se uma negação de pasta anular qualquer concessão, toda a solicitação é recusada antes que qualquer arquivo seja gravado.
- Se o acesso de um beneficiário foi revogado, um
addnão o restabelece, e o beneficiário é listado emleft_revoked_user_ids.
dataroom_bulk_revoke_file_permissions
Revoga as concessões diretas dos usuários informados em muitos arquivos de uma vez. Concessões de pasta e acesso à sala não são afetados.
- Escopo:
admin. - Entradas:
dataroom_id,file_ids(até 200),user_ids(todos obrigatórios). - Saída:
{ success: true, revoked_count }. - Um id de arquivo que não está na sala, ou que você não pode ver, faz toda a solicitação ser recusada com
NOT_FOUND.
dataroom_get_watermark_settings
Lê os modos de marca d'água de download da sala, para downloads de arquivo único e em lote:
two_layer (a identidade de quem baixa mais uma passada de IP e data por download) ou
static (somente a identidade). Somente leitura: altere-os nas configurações do Waafir.
- Escopo:
read, e o proprietário do token precisa ser administrador da organização na equipe da transação. - Entradas:
dataroom_id(obrigatório). - Saída:
{ dataroom_id, single, bulk, stored: { single, bulk } }. Umnullemstoredsignifica que a sala nunca o definiu, então o padrão se aplica.
dataroom_archive
Arquiva uma sala de dados, para que ela saia das listas de salas. Em duas etapas: a primeira chamada
não altera nada e retorna uma prévia (o nome da sala e quantos arquivos,
pastas, pessoas com acesso e links de compartilhamento ativos ela tem) e um
confirm_token. Repita a chamada com o token para arquivar.
- Escopo:
admin, e o proprietário do token precisa ser proprietário ou administrador da organização. - Entradas:
dataroom_id(obrigatório);confirm_token. - Saída:
{ success: true, dataroom_id, name, archived: true, restore_with: 'dataroom_restore' }. - Arquivar não revoga o acesso nem as concessões de ninguém, e nada é
excluído. A sala sai das listas, e as leituras no nível da sala (
get_dataroom,list_files,list_folders, busca, Q&A, perguntas à IA) respondemNOT_FOUNDaté que ela seja restaurada. Um link direto para um de seus arquivos ainda o abre.dataroom_restoretraz a sala de volta, então guarde odataroom_id. A última sala de dados ativa não pode ser arquivada (CONFLICT). Não existe ferramenta que exclua uma sala de dados.
dataroom_restore
Restaura uma sala de dados que sua organização arquivou. Ela volta às listas de salas, e tudo o que o arquivamento ocultou volta com ela: busca por IA, resumos periódicos, atualizações para investidores, Q&A e os complementos da sala. Pastas, arquivos e acessos permanecem como estavam, porque o arquivamento não alterou nenhum deles. Uma chamada, sem etapa de confirmação.
- Escopo:
admin, e o proprietário do token precisa ser proprietário ou administrador da organização. - Entradas:
dataroom_id(obrigatório): o id quedataroom_archiveretornou. - Saída:
{ success: true, dataroom_id, name, archived: false }. - Uma sala que não está arquivada é recusada (
CONFLICT, códigoNOT_ARCHIVED). Uma sala arquivada pelo suporte do Waafir, ou junto com sua organização, é recusada (CONFLICT, códigoSUPPORT_RESTORE_ONLY): somente o suporte pode restaurá-la. - Recusada enquanto a assinatura estiver inativa ou a equipe estiver acima do seu limite de licenças.
dataroom_rename
Renomeia uma sala de dados.
- Escopo:
write, e o proprietário do token precisa fazer parte da equipe da transação. - Entradas:
dataroom_id,name(ambos obrigatórios). O nome é aparado e deve ter de 1 a 100 caracteres. - Saída:
{ success: true, dataroom_id, name }. - A trilha de auditoria registra o nome antigo e o novo.
Ferramentas de equipe
A equipe da organização abrange toda a organização, portanto um token limitado a salas de dados específicas
é recusado (FORBIDDEN, código PAT_ROOM_SCOPED).
dataroom_team_list_members
Lista os membros ativos da organização. Convites pendentes não são incluídos.
- Escopo:
read, e o proprietário do token precisa fazer parte da equipe da transação. - Entradas: nenhuma.
- Saída:
{ members: [{ membership_id, user_id, email, name, role, last_active_at }] }.roleé um deowner,adminoumember.
As gravações abaixo precisam de um token com escopo admin cujo proprietário seja proprietário
ou administrador da organização. As quatro marcadas como de duas etapas retornam uma prévia e um
confirm_token na primeira chamada e só agem quando repetidas com ele.
dataroom_team_invite_member
Convida alguém por e-mail. Em duas etapas; a confirmação envia o e-mail de convite.
- Escopo:
admin, mais a permissão Enviar para pessoas fora da sua organização. - Entradas:
email,role(owner,adminoumember) (obrigatórios);confirm_token. - Saída:
{ membership_id, email, role, status: "pending" }. Nunca o link do convite. - Somente um proprietário pode convidar um proprietário. O limite de licenças e os limites diários de convites se aplicam.
dataroom_team_change_member_role
Altera a função de um membro ativo. Em duas etapas; a prévia mostra a função antiga e a nova.
- Escopo:
admin. - Entradas:
membership_id,role(obrigatórios);confirm_token. - Saída:
{ success: true, membership_id, old_role, role }. - Somente um proprietário pode alterar a função de um proprietário ou promover alguém a proprietário. Você não pode alterar a sua própria função, e o último proprietário não pode ser rebaixado.
dataroom_team_remove_member
Remove um membro ou revoga um convite pendente. Em duas etapas; a prévia mostra quantas das concessões de arquivo e de pasta e quantos links de compartilhamento do membro terminam.
- Escopo:
admin. - Entradas:
membership_id(obrigatório);confirm_token. - Saída:
{ success: true, membership_id, action, file_grants_ended?, folder_grants_ended?, share_links_deactivated? }. - A remoção encerra as concessões dele nesta organização e desativa os links de compartilhamento que ele criou; as negações permanecem. Somente um proprietário pode remover um proprietário.
dataroom_team_resend_invite
Envia novamente um convite pendente com um link novo; o link antigo deixa de funcionar. Em duas etapas; a confirmação envia o e-mail de convite.
- Escopo:
admin, mais a permissão Enviar para pessoas fora da sua organização. - Entradas:
membership_id(obrigatório);confirm_token. - Saída: a prévia (
membership_id,email,role) na primeira chamada;{ success: true, membership_id }após a confirmação. - Somente um convite pendente pode ser reenviado: qualquer outra associação é recusada na prévia, sem token. Os limites diários de convites são debitados quando você confirma.
Ferramentas de investidores e NDA
Ferramentas sobre a sua lista de investidores, o NDA da sua organização e os NDAs das suas firmas de investidores. Cada uma verifica a função atual do proprietário do token na sua organização a cada chamada, de modo que uma pessoa que tenha sido rebaixada desde então, ou um token limitado abaixo da função de que a ferramenta precisa, é recusado.
As ferramentas que leem a organização inteira precisam de um token que não esteja limitado a salas de dados específicas. A lista inclui dados de engajamento (quando alguém abriu a sala pela última vez, quantos e-mails de convite foram enviados, quando a pessoa aceitou) somente para um token criado com Ler análise de engajamento ativado. Ela nunca inclui links de dispensa de NDA nem ids de usuário.
Convidar um investidor, remover ou restaurar o acesso dele, alterar suas
permissões e anexar ou revogar o NDA de uma firma exigem, cada um, duas etapas. A
primeira chamada não altera nada: ela retorna uma prévia exata do que vai acontecer e
um confirm_token. Seu assistente mostra a prévia a você e, somente depois que você concordar,
repete a chamada com argumentos idênticos mais esse confirm_token. Um token
funciona uma vez e expira após alguns minutos. Se algo mostrado na prévia tiver
mudado nesse intervalo, a segunda chamada é recusada e seu assistente pergunta novamente.
dataroom_list_investors
Lista os investidores convidados para a sua organização ou para uma sala de dados.
- Escopo:
read. Função: proprietário ou administrador. - Entradas:
dataroom_id(opcional; obrigatório para um token limitado a salas de dados específicas);status(opcional:pending,accepted,revokedouaccess_requested). - Saída:
{ investors: [{ id, email, display_name, role, status, require_nda, nda, investor_org, can_view_monitoring, can_view_updates, expires_at, invited_at }] }. Oidé o id do convite que as outras ferramentas de investidores recebem. Com Ler análise de engajamento, cada linha também temengagement: { last_seen_at, send_count, last_sent_at, accepted_at }.
dataroom_get_nda
Lê o NDA da sua organização: o título, o texto e as cláusulas da versão atual,
e o histórico de versões. Retorna current: null quando a organização ainda não tem
NDA; lê-lo nunca cria um.
- Escopo:
read. Função: membro da equipe da transação. - Entradas: nenhuma.
- Saída:
{ current, versions, clauses, tally }.tally(contagens de assinados, dispensados e pendentes) énullpara um token limitado a salas de dados específicas.
dataroom_list_firm_ndas
Lista as firmas de investidores da sua organização e se cada uma tem um NDA de firma vigente.
- Escopo:
read. Função: membro da equipe da transação. Precisa de um token não limitado a salas de dados específicas. - Entradas: nenhuma.
- Saída:
{ firms: [{ id, name, has_live_nda }] }.
dataroom_get_firm_nda
Lê o NDA de uma firma com a sua organização e os envelopes de assinatura eletrônica concluídos que você poderia anexar como NDA dela.
- Escopo:
read. Função: membro da equipe da transação. Precisa de um token não limitado a salas de dados específicas. - Entradas:
investor_org_id(obrigatório). - Saída:
{ agreement, attachable_envelopes }.agreementénullquando a firma não tem nenhum.
dataroom_extend_investor_access
Estende o acesso de um convite aceito pelo prazo de expiração de link de convidado da sua organização (7 dias, a menos que você o tenha alterado) e mantém a sessão atual do investidor ativa por esse tempo. Somente para um convite para uma sala de dados.
- Escopo:
write. Função: membro da equipe da transação. Requer: Enviar para pessoas fora da sua organização. - Entradas:
invite_id(obrigatório). - Saída:
{ invite_id, expires_at, expiry_hours }. Um convite que não foi aceito é recusado com um conflito.
dataroom_invite_investor
Convida um investidor para uma sala de dados por e-mail, convida-o novamente com uma nova função ou
exigência de NDA, ou reenvia o convite dele. Ele recebe um e-mail com um link pessoal,
a menos que notify seja false. A prévia informa se isso cria, atualiza ou
mantém o convite, quais dos seus argumentos serão ignorados (um reenvio mantém a
função e o NDA armazenados), a mudança de status (um investidor removido é restaurado), qualquer
dispensa de NDA e se um e-mail será enviado. A prévia não consome nada do limite diário
de convites; o envio consome.
- Escopo:
admin. Função: proprietário ou administrador, na equipe da transação da sala de dados. Requer: Enviar para pessoas fora da sua organização. - Entradas:
email,dataroom_id(obrigatórios);role(vieweroudownloader);require_nda;resend;notify;confirm_token. - Saída: a prévia e o
confirm_tokenna primeira chamada; depois{ status: 'sent' | 'added', invite_id, link_expires_at }.
dataroom_revoke_investor_access
Remove o acesso de um investidor. A sessão atual dele e as concessões de arquivo e de pasta dele na sala de dados do convite terminam. Restabelecer mais tarde restaura o acesso à sala, não as concessões de arquivo.
- Escopo:
admin. Função: proprietário ou administrador. - Entradas:
invite_id(obrigatório);confirm_token. - Saída: a prévia e o
confirm_token; depois{ status: 'revoked', invite_id }.
dataroom_reinstate_investor_access
Restabelece um investidor removido ou aprova uma solicitação de acesso. Somente acesso à sala.
- Escopo:
admin. Função: proprietário ou administrador. Requer: Enviar para pessoas fora da sua organização. - Entradas:
invite_id(obrigatório);confirm_token. - Saída: a prévia e o
confirm_token; depois{ status: 'reinstated', invite_id }.
dataroom_set_investor_permissions
Altera a função, a exigência de NDA e o acesso a monitoramento e atualizações de um convite. A prévia lista cada alteração. Desativar o NDA registra uma dispensa em seu nome, com um motivo e um link opcionais.
- Escopo:
admin. Função: proprietário ou administrador. - Entradas:
invite_id(obrigatório); pelo menos um derole,require_nda,can_view_monitoring,can_view_updates;nda_waiver_reason;nda_waiver_url;confirm_token. - Saída: a prévia e o
confirm_token; depois{ status: 'updated', invite_id, changes }.
dataroom_attach_firm_nda
Registra um envelope de assinatura eletrônica concluído como o NDA executado de uma firma de investidores, com a data de execução e o prazo. Qualquer envelope que você possa ver pode ser anexado.
- Escopo:
admin. Função: proprietário ou administrador. Precisa de um token não limitado a salas de dados específicas. - Entradas:
investor_org_id,envelope_id,executed_at,term(obrigatórios);confirm_token. - Saída: a prévia e o
confirm_token; depois{ status: 'attached', agreement }.
dataroom_revoke_firm_nda
Revoga o NDA de uma firma de investidores. Um NDA iniciado no Waafir que ainda esteja aguardando assinatura também tem seu envelope anulado.
- Escopo:
admin. Função: proprietário ou administrador. Precisa de um token não limitado a salas de dados específicas. - Entradas:
investor_org_id(obrigatório);reason;confirm_token. - Saída: a prévia e o
confirm_token; depois{ status: 'revoked', investor_org_id, envelope_voided }.
Ferramentas de firmas de investidores
Ferramentas sobre as suas firmas de investidores: os grupos aos quais seus investidores pertencem, como na página Investidores. Cada uma precisa de uma função de proprietário ou administrador na sua organização, verificada a cada chamada, e de um token que não esteja limitado a salas de dados específicas. Uma firma desconhecida, uma firma de outra organização e uma firma que foi incorporada a outra recebem a mesma resposta de não encontrado.
Colocar alguém em uma firma e mesclar duas firmas exigem, cada um, duas etapas, como as ferramentas de investidores acima. Ambas podem tirar uma pessoa da firma atual dela. Se a firma em que ela entra tiver um NDA executado, ele passa a cobri-la a partir daí, e os convites pendentes dela que pedem um NDA deixam de pedi-lo. Quando a prévia lista um convite assim, o token também precisa de Enviar para pessoas fora da sua organização. Remover alguém de uma firma não está disponível aqui.
dataroom_list_investor_firms
Lista as firmas de investidores da sua organização com seu domínio, número de membros, a nota privada da equipe da transação e o status do NDA da firma.
- Escopo:
read. Função: proprietário ou administrador. - Entradas: nenhuma.
- Saída:
{ investor_firms: [{ id, name, canonical_domain, member_count, deal_team_note, firm_nda }] }.deal_team_noteé marcado como texto escrito por um colega.
dataroom_create_investor_firm
Cria uma firma de investidores. Com member_emails e canonical_domain, cada
pessoa listada nesse domínio que já tenha sido convidada para uma das suas salas de dados
e ainda não esteja em nenhuma firma torna-se membro. Ninguém é retirado de outra firma.
- Escopo:
admin. Função: proprietário ou administrador. - Entradas:
name(obrigatório);canonical_domain;member_emails(até 500, requercanonical_domain). - Saída:
{ status: 'created', investor_firm: { id, name }, added }.
dataroom_rename_investor_firm
Renomeia uma firma de investidores.
- Escopo:
admin. Função: proprietário ou administrador. - Entradas:
investor_org_id,name(obrigatórios). - Saída:
{ status: 'renamed' | 'unchanged', investor_org_id, name }.
dataroom_set_investor_firm_note
Define ou limpa a nota privada da equipe da transação sobre uma firma. Os investidores nunca a veem.
- Escopo:
admin. Função: proprietário ou administrador. - Entradas:
investor_org_id,note(obrigatórios; uma string vazia a limpa). - Saída:
{ status: 'set' | 'cleared' | 'unchanged', investor_org_id, cleared }.
dataroom_assign_investor_to_firm
Coloca um investidor, por e-mail, em uma firma, retirando-o da firma atual dele, se houver. A prévia indica a firma que ele deixa e os convites pendentes cuja etapa de NDA o NDA da firma passaria a atender. Alguém que já esteja na firma fica como está, sem etapa de confirmação.
- Escopo:
admin. Função: proprietário ou administrador. Requer: Enviar para pessoas fora da sua organização quando a prévia lista um convite. - Entradas:
investor_org_id,email(obrigatórios);confirm_token. - Saída: a prévia e o
confirm_token; depois{ status: 'assigned', investor_org_id, email, moved_from, coverage_started }.
dataroom_merge_investor_firms
Mescla uma firma em outra. Todos os membros da firma de origem passam para a firma de destino, e a firma de origem sai da sua lista de firmas. Você não pode desfazer uma mesclagem pelo seu assistente nem pelo aplicativo. A prévia lista as pessoas que serão movidas e os convites pendentes cuja etapa de NDA o NDA da firma de destino passaria a atender.
- Escopo:
admin. Função: proprietário ou administrador. Requer: Enviar para pessoas fora da sua organização quando a prévia lista um convite. - Entradas:
source_investor_org_id,target_investor_org_id(obrigatórios e diferentes);confirm_token. - Saída: a prévia e o
confirm_token; depois{ status: 'merged', source_investor_org_id, target_investor_org_id, moved_count, coverage_started_count }.
Ferramentas de engajamento
Ferramentas somente leitura sobre quem leu o quê, quando e por quanto tempo. Trata-se de dados
comportamentais sobre pessoas identificadas, portanto cada uma precisa de um token criado com Ler análise de engajamento
ativado e de uma função na equipe da transação. Cada uma conta apenas
documentos que o próprio proprietário do token pode ler. As ferramentas de sala aceitam o mesmo
filtro da página de engajamento: range (ou from e to), people,
firm_ids, folder_id e tz.
dataroom_get_activity_trail
O log de acesso da sua organização, do mais recente para o mais antigo. Precisa de um token não limitado a salas de dados específicas.
- Escopo:
read. Entradas:counterparty,since,cursor,limit.
dataroom_get_room_engagement
O placar, o mapa de calor e a linha do tempo de uma sala de dados, com seus consolidados da transação.
- Escopo:
read. Entradas:dataroom_id(obrigatório) e o filtro.
dataroom_get_engagement_scores
A pontuação de engajamento de cada investidor em uma sala de dados, em ordem de classificação.
- Escopo:
read. Entradas:dataroom_id(obrigatório) e o filtro.
dataroom_get_investor_engagement
As visitas e os documentos abertos por um investidor em uma sala de dados. A visualização é registrada no seu log de auditoria, como acontece no Waafir.
- Escopo:
read. Entradas:dataroom_id,email(obrigatórios) e o filtro.
dataroom_get_document_engagement
Leitura por documento, por contraparte, em toda a sua organização e, com
file_id, o tempo gasto por página nesse documento. Precisa de um token não limitado a salas de dados específicas.
- Escopo:
read. Entradas:counterparty,file_id,weeks,cursor,limit,page_range.
dataroom_get_firm_rollups
Atividade semanal por contraparte em toda a sua organização. Precisa de um token não limitado a salas de dados específicas.
- Escopo:
read. Entradas:counterparty,weeks,cursor,limit.
Ferramentas de Q&A
Duas ferramentas somente leitura sobre os tópicos de Q&A (perguntas e respostas) de investidores em uma sala de dados. Um token
da equipe da transação não pode publicar uma pergunta aqui; o agente do próprio investidor pergunta com
dataroom_ask_question (consulte Ferramentas do agente do investidor).
O que uma chamada retorna depende de quem é o proprietário do token:
- um membro da equipe da transação vê todos os tópicos da sala de dados, incluindo o endereço de e-mail de quem perguntou;
- um investidor vê apenas as perguntas que ele mesmo fez, e nenhum endereço de e-mail.
Os documentos anexados retornam apenas como id e nome — nunca o conteúdo, nunca um link de download — e o nome de um documento que o chamador não pode ver é ocultado. Use as ferramentas de documentos para obter o conteúdo; elas aplicam suas próprias verificações de acesso. As perguntas do Q&A da empresa, de toda a organização, que não estão vinculadas a uma sala de dados, nunca são retornadas por nenhuma das ferramentas.
dataroom_list_questions
Nome no endpoint da área: list_questions
Lista os tópicos de Q&A de uma sala de dados autorizada, do mais recente para o mais antigo, cada um com suas respostas.
- Escopo:
read. - Entradas:
dataroom_id(obrigatório);status(opcional —open,answeredouclosed);file_id(opcional — apenas perguntas feitas sobre esse documento);limit(opcional, 1–100, padrão 25);offset(opcional, padrão 0). - Saída:
{ questions, pagination }. Pagine comoffsetenquantopagination.has_morefortrue.
dataroom_get_question
Nome no endpoint da área: get_question
Obtém um tópico de Q&A pelo id, com todas as suas respostas.
- Escopo:
read. - Entradas:
dataroom_id(obrigatório);question_id(obrigatório). - Saída:
{ question }. - Uma pergunta em outra sala de dados ou em outra organização — ou, para um
investidor, uma pergunta feita por outra pessoa — retorna
NOT_FOUND. A ferramenta nunca confirma que tal id existe.
Cada pergunta traz { id, dataroom_id, title, body, question_type, status, asked_by, file_id, file_name, created_at, updated_at, responses }, mais
asker_email somente quando o chamador tem direito a ele — para um investidor, a
chave fica ausente do payload em vez de presente e nula. Cada entrada em
responses é { id, body, responded_by, is_ai_draft, created_at, updated_at, attachments }.
dataroom_answer_question (escrita)
Responde à pergunta de um investidor. Não há rascunho: o investidor vê a resposta imediatamente, e quem perguntou recebe um e-mail se as configurações dele permitirem. Nenhum dos dois pode ser desfeito.
- Escopo:
write. Membros da equipe da transação da sala de dados. - Permissão: o token precisa de Enviar para pessoas fora da sua organização.
- Entradas:
dataroom_id,question_id,body(todos obrigatórios);confirm_token. - Duas etapas. Sem
confirm_token, nada é publicado e você recebe uma prévia (a pergunta, quantas respostas ela tem, se quem perguntou receberá um e-mail) mais um token. Chame novamente com os mesmos argumentos e o token para publicar. Uma nova resposta ou um tópico fechado nesse intervalo faz a chamada falhar, e você gera a prévia de novo.
dataroom_close_question (escrita)
Fecha um tópico de Q&A. Quem perguntou, ou um administrador ou gerente da organização, pode fechá-lo.
- Escopo:
write. - Entradas:
dataroom_id,question_id(ambos obrigatórios). - Saída:
{ question_id, outcome, kb_draft, kb_draft_skip_reason }. - Quando a organização paga pela IA e a tem ativada, fechar um tópico que tem respostas
também enfileira um rascunho para a base de conhecimento. Caso contrário,
kb_draftéskippede o motivo explica por quê. Nada é enviado ao investidor.
dataroom_bulk_close_questions (escrita)
Fecha até 100 tópicos de uma sala de dados. Cada um é avaliado individualmente.
- Escopo:
write. - Entradas:
dataroom_id,question_ids(ambos obrigatórios). - Saída:
{ requested, closed, results }. Ooutcomede cada resultado éclosed,not_found,forbiddenoualready_closed.
dataroom_edit_question (escrita)
Edita o título e/ou o corpo de uma pergunta. Somente administradores e gerentes.
- Escopo:
write. - Entradas:
dataroom_id,question_id(ambos obrigatórios);title,body(pelo menos um). - Saída:
{ question_id, title, body }.
dataroom_edit_answer (escrita)
Edita o texto de uma resposta. Somente administradores e gerentes. O investidor vê a edição imediatamente, como no Waafir; nenhum novo e-mail é enviado.
- Escopo:
write. - Entradas:
dataroom_id,question_id,response_id,body(todos obrigatórios). - Saída:
{ response_id, question_id, body }.
dataroom_delete_question (escrita)
Exclui um tópico de Q&A. Os investidores deixam de vê-lo, assim como suas respostas. Somente administradores e gerentes.
- Escopo:
write. - Entradas:
dataroom_id,question_id(ambos obrigatórios);confirm_token. - Duas etapas. Sem
confirm_token, nada é excluído e você recebe uma prévia mais um token. Chame novamente com os mesmos argumentos e o token para excluir. Um token funciona uma vez e expira após alguns minutos.
dataroom_delete_answer (escrita)
Exclui uma resposta de um tópico. O investidor deixa de vê-la. Somente administradores e gerentes.
- Escopo:
write. - Entradas:
dataroom_id,question_id,response_id(todos obrigatórios);confirm_token. - Duas etapas, como em
dataroom_delete_question.
dataroom_publish_kb_article (escrita)
Publica um artigo da base de conhecimento, por exemplo um rascunho criado a partir de um tópico fechado. Os investidores que podem ver a sala de dados passam então a poder lê-lo. Somente administradores e gerentes.
- Escopo:
write. - Entradas:
dataroom_id,article_id(ambos obrigatórios);confirm_token. - Duas etapas, como em
dataroom_delete_question.
Ferramentas de atualizações para investidores
Estas espelham o editor de atualizações para investidores do Waafir, com as mesmas verificações de função. Todas precisam do complemento Materiais do Investidor na sala de dados. Nenhuma delas envia nada aos investidores: a publicação é feita no Waafir.
dataroom_list_updates
Lista as atualizações para investidores de uma sala de dados em todos os status, da alteração mais recente para a mais antiga.
- Escopo:
read. Membros da equipe da transação da sala de dados. - Entradas:
dataroom_id(obrigatório). - Saída:
{ updates }, cada uma{ id, title, period_label, status, version, published_at, updated_at }.
dataroom_create_update (escrita)
Cria uma atualização em rascunho a partir de portfólios e/ou arquivos (pelo menos um).
- Escopo:
write. Membros da equipe da transação da sala de dados. - Entradas:
dataroom_id,period_label(ambos obrigatórios);title,period_start,period_end,tone_notes,portfolio_ids,file_ids. - Saída:
{ update_id, status, portfolio_count, file_count }. Arquivos e portfólios que não estão na sua organização são deixados de fora e não são contados.
dataroom_get_update
Lê uma atualização tal como o editor a mostra.
- Escopo:
read. Proprietários e administradores. - Entradas:
dataroom_id,update_id(ambos obrigatórios). - Saída:
{ update_id, status, document, latest_generation }.documenté o rascunho gerado mais recente com as suas edições aplicadas, ou null antes da primeira geração.
dataroom_get_update_generation
O status de uma execução de geração.
- Escopo:
read. Proprietários e administradores. - Entradas:
dataroom_id,update_id,generation_id(todos obrigatórios). - Saída:
{ generation_id, status, error_code }. Uma execução com falha informa seu código, nunca a mensagem armazenada.
dataroom_generate_update (escrita)
Inicia uma geração por IA de uma atualização em rascunho ou em revisão.
- Escopo:
write, mais Ler conteúdo do documento no token: a execução lê os arquivos selecionados na íntegra, orientada pelas notas de tom da atualização. Proprietários e administradores. - Entradas:
dataroom_id,update_id(ambos obrigatórios). - Saída:
{ generation_id, queued }. Consultedataroom_get_update_generationperiodicamente. - Requer um plano pago e os recursos de IA ativados, e conta para o limite diário de IA. Compartilha o limite do editor de 5 gerações por minuto.
dataroom_edit_update_draft (escrita)
Salva as suas edições sobre o conteúdo gerado de um rascunho, como o editor faz.
- Escopo:
write. Proprietários e administradores. - Entradas:
dataroom_id,update_id,overrides(todos obrigatórios).overridesaceitanarrative_sections,chart_placementsecitations. - Saída:
{ update_id, status, document }. Somente um rascunho pode ser editado.
dataroom_submit_update_for_review (escrita)
Move uma atualização em rascunho para in_review.
- Escopo:
write. Administradores e gerentes. - Entradas:
dataroom_id,update_id(ambos obrigatórios). - Saída:
{ update_id, status }. - A atualização precisa ter conteúdo gerado e nenhuma geração em andamento.
dataroom_publish_update (escrita)
Publica uma atualização em revisão. Os investidores da sala de dados podem vê-la imediatamente e cada um recebe um e-mail, o que não pode ser desfeito.
- Escopo:
write. Administradores e gerentes. - Permissão: o token precisa de Enviar para pessoas fora da sua organização.
- Entradas:
dataroom_id,update_id(ambos obrigatórios);confirm_token. - Duas etapas. Sem
confirm_token, nada é publicado e você recebe uma prévia (a atualização e quantos investidores receberão e-mail) mais um token. Chame novamente com os mesmos argumentos e o token para publicar. Se a atualização ou a lista de investidores dela tiver mudado nesse intervalo, a chamada é recusada e você gera a prévia de novo.
dataroom_republish_update (escrita)
Copia uma atualização publicada para uma nova versão em rascunho, que você então edita, revisa e publica. A versão publicada permanece no ar até lá.
- Escopo:
write. Administradores e gerentes. - Entradas:
dataroom_id,update_id(ambos obrigatórios). - Saída:
{ update_id, status, version }do novo rascunho.
Ferramentas de Inteligência de Mercado
Somente leitura. Elas precisam do complemento Inteligência de Mercado (uma prévia funciona, com seus limites), de um token que não esteja limitado a salas de dados específicas e de um membro da equipe da transação como proprietário.
mi_get_subject
A empresa da sua organização na Inteligência de Mercado.
- Escopo:
read. - Entradas: nenhuma.
- Saída:
{ subject, access }.subjecté{ id, name }, ou null até que alguém tenha aberto a Inteligência de Mercado no Waafir.
mi_get_profile
O perfil de uma empresa: a versão confirmada e o rascunho em elaboração.
- Escopo:
read. - Entradas:
subject_id(obrigatório). - Saída:
{ subject, confirmed, draft, file_names }. Cada campo éstated(com ofile_ide apagede onde foi lido, ou uma página da web pública e sua citação),entered,not_applicableou null. - Citações de documentos da sala de dados não são retornadas. Leia o arquivo com as ferramentas de documentos se precisar delas.
mi_list_matches
Os investidores classificados para o perfil da empresa, do mais adequado para o menos adequado.
- Escopo:
read. - Entradas:
subject_id(obrigatório). - Saída:
{ profile_version, preliminary, similarity, live, country, caveat, total, matches }. Cada correspondência é{ entity_id, name, score, penalties, reasons, contacts_available, on_roster, addable }. - Uma prévia mostra os 3 primeiros. A classificação por similaridade só é usada quando o seu plano
paga pela IA, a IA está ativada e o limite diário de IA permite;
similarityinforma qual foi o caso. - Dados de contato nunca são retornados. Compartilha o limite da página do Waafir de 30 por minuto.
Ferramentas de IA
Estas ferramentas fazem o trabalho de IA do lado do Waafir e entregam ao seu cliente de IA o resultado: uma resposta com citações, um resumo, uma revisão, um plano de pastas proposto ou um rascunho. Seu cliente nunca precisa baixar os documentos para chegar lá. Elas precisam do complemento de IA, contam para o orçamento diário de IA da sua organização e ficam pausadas quando seus administradores pausam a IA. Cada uma é limitada, por pessoa, à mesma taxa do botão correspondente no aplicativo e registra o que retornou no log de atividades.
Uma resposta pode repetir o que um documento diz quando é o seu cliente que escreve a
pergunta, por isso dataroom_ask, dataroom_draft_answer e
dataroom_compare_files precisam de Ler conteúdo do documento no token, assim como
dataroom_get_file_text. Sem isso, elas não são listadas, e uma chamada é
recusada com GRANT_REQUIRED. As outras ferramentas de IA executam uma tarefa fixa sobre a
sala e funcionam sem isso. Todo resultado marca os campos que contêm saída de IA em
untrusted_content (consulte Texto não confiável nos resultados).
Somente documentos que o proprietário do token pode abrir são usados ou citados. As ferramentas funcionam em salas de dados da própria organização do token.
dataroom_ask
Faz uma pergunta sobre uma sala de dados e obtém uma resposta fundamentada.
- Escopo:
read, mais Ler conteúdo do documento no token. Qualquer membro da sala de dados. - Entradas:
dataroom_id(obrigatório);question(obrigatório). - Saída:
{ dataroom_id, answer, citations }. Até 10 citações, cada uma{ source_type, id, title, page? }. Nenhum texto de documento é retornado, e nenhuma conversa de chat é salva.
dataroom_summarise_file
Obtém o resumo de IA e os pontos-chave de um arquivo.
- Escopo:
read. Equipe da transação, com acesso de download ao arquivo. - Entradas:
dataroom_id(obrigatório);file_id(obrigatório). - Saída:
{ file_id, file_name, status: "ready", summary, key_points }, oustatus: "queued"quando o arquivo ainda não tem resumo. O resumo então começa em segundo plano, como acontece com o botão Summarise (Resumir); chame novamente mais tarde.
dataroom_list_facts
Lista os fatos verificados e os termos-chave extraídos dos documentos de uma sala de dados.
- Escopo:
read. Equipe da transação. - Entradas:
dataroom_id(obrigatório);file_id(opcional);types(opcional);limit(opcional, 1–200, padrão 50);cursor(opcional). - Saída:
{ dataroom_id, facts, has_more, next_cursor }. Cada fato é{ id, file_id, file_name, fact_type, value, page, confidence, created_at }. Enquantohas_morefortrue, passenext_cursorde volta comocursorpara a próxima página. - Sem Ler conteúdo do documento no token, o
valuede cada fato mantém no máximo 20 palavras (160 caracteres), contadas sobre o valor inteiro, e o fato trazvalue_truncated.
dataroom_compare_files
Compara dois arquivos de uma sala de dados e obtém as diferenças relevantes.
- Escopo:
read, mais Ler conteúdo do documento no token. Equipe da transação, com acesso de download a ambos os arquivos. - Entradas:
dataroom_id(obrigatório);file_id_a(obrigatório);file_id_b(obrigatório). - Saída:
{ dataroom_id, file_a, file_b, differences }. Cada entrada de arquivo é{ id, name, truncated }: um documento muito longo é comparado pela sua primeira parte, etruncatedindica isso. Nenhum texto de documento é retornado. - Um arquivo de um tipo sem texto a extrair é recusado com um
400, e um arquivo armazenado com mais de 50 MB, com um413(FILE_TOO_LARGE), antes que qualquer um deles seja buscado, quando o texto do arquivo ainda não foi extraído.
dataroom_review
Executa a revisão de prontidão por IA de uma sala de dados.
- Escopo:
read. Equipe da transação. - Entradas:
dataroom_id(obrigatório);force_refresh(opcional). - Saída:
{ dataroom_id, cached, readinessScore, presentDocs, missingDocs, flaggedForRedaction, flaggedForRename, flaggedOutOfDate, suggestions }. Uma revisão armazenada atual é retornada sem uma nova execução de IA, a menos queforce_refreshsejatrue.
dataroom_propose_organise (escrita)
Etapa 1 de 2: propõe uma estrutura de pastas para uma sala de dados. Nada é movido.
- Escopo:
write. Proprietário ou administrador. - Entradas:
dataroom_id(obrigatório). - Saída:
{ dataroom_id, suggestion_id, applied: false, proposed_folders, unchanged_file_ids, files, total_files, accounted_for }.
dataroom_apply_organise (escrita)
Etapa 2 de 2: aplica uma proposta pelo seu suggestion_id. Exatamente a proposta
armazenada é aplicada, uma única vez; ela não pode ser editada no caminho. Arquivos que o
proprietário do token não pode mover são ignorados e contados. Para desfazer, use o painel Organise (Organizar) no
aplicativo.
- Escopo:
write. Proprietário ou administrador. - Entradas:
dataroom_id(obrigatório);suggestion_id(obrigatório). - Saída:
{ dataroom_id, suggestion_id, folders_created, files_moved, files_skipped }.
dataroom_draft_answer
Redige uma resposta a uma pergunta de investidor com base nos documentos da sala de dados.
- Escopo:
read, mais Ler conteúdo do documento no token. Proprietário ou administrador. - Entradas:
question_id(obrigatório). - Saída:
{ question_id, draft, is_draft: true, sources }. O rascunho é retornado somente a você: nada é salvo, enviado ou publicado. Uma pessoa publica a resposta no aplicativo. Perguntas no nível da organização são redigidas no aplicativo.
Ferramentas de prontidão e base de conhecimento
Somente leitura. A prontidão retorna a pontuação e as contagens por trás dela, nunca o
texto da revisão; execute dataroom_review para isso.
dataroom_get_readiness_score
A pontuação de prontidão de uma sala de dados.
- Escopo:
read, e o proprietário do token precisa ser proprietário ou administrador da organização. - Entradas:
dataroom_id(obrigatório). - Saída:
{ dataroom_id, score, reviewed, questions_total, questions_answered, kb_articles, files_uploaded, present_categories, missing_categories }.scorevai de 0 a 100, ou énullquando não há revisão de IA que possa ser mostrada a você.
dataroom_get_readiness_rollup
A prontidão em todas as salas de dados da organização, como o Dashboard a mostra.
- Escopo:
read, e o proprietário do token precisa fazer parte da equipe da transação. Um token limitado a salas de dados específicas é recusado. - Entradas: nenhuma.
- Saída:
{ rooms: [{ id, name, investors, reading, updated, status, readinessPct, tone, reviewedAt, presentCount, missingCount, categories }] }. As contagens de documentos por categoria incluem apenas documentos que o proprietário do token pode ler.
dataroom_list_kb_articles
Lista os artigos da base de conhecimento de uma sala, os dela e os de toda a organização.
- Escopo:
read. - Entradas:
dataroom_id(obrigatório);category;include_drafts(somente equipe da transação). - Saída:
{ articles: [{ id, title, category, published }] }. - Quem foi admitido na sala apenas por meio de um documento compartilhado não vê nenhum artigo. Um token de investidor vê apenas artigos publicados.
dataroom_get_kb_article
Lê um artigo.
- Escopo:
read. - Entradas:
dataroom_id,article_id(obrigatórios). - Saída:
{ id, title, category, body, published, updated_at }. Um rascunho é tratado como não encontrado, a menos que o proprietário do token faça parte da equipe da transação.
Ferramentas do agente do investidor
Ferramentas para o agente do próprio investidor: elas funcionam somente com um token de acesso de investidor, e um token da equipe da transação não as lista nem as chama.
Um token de investidor também pode chamar estas ferramentas compartilhadas. Cada uma responde apenas com o que o investidor vê na sala de dados.
- Salas e arquivos:
dataroom_list,dataroom_get,dataroom_list_folders,dataroom_list_files,dataroom_get_file_metadataedataroom_search. - Snapshots:
dataroom_list_snapshotsedataroom_get_snapshot, para snapshots que o investidor visualiza. - Downloads:
dataroom_get_file_download_url. A cópia sempre recebe marca d'água com a identidade do investidor, assim como o download pelo navegador dele. - Q&A e artigos:
dataroom_list_questions,dataroom_get_question,dataroom_list_kb_articlesedataroom_get_kb_article. Estas retornam as perguntas do próprio investidor e os artigos publicados. - IA:
dataroom_ask,dataroom_compare_files,translate_text,translate_fileetranslate_file_status. As traduções de um investidor são privadas para ele.
Um token de investidor é recusado em dataroom_get_file_text: texto simples não pode levar
marca d'água, então o agente usa o download com marca d'água.
Quem paga pela IA. Cada chamada de IA custa unidades da franquia. A organização
da sala paga até uma franquia mensal por investidor por sala (meses em UTC).
A equipe da transação define a franquia por sala, e o padrão é 200 unidades. Ultrapassada
a franquia, paga uma organização da qual o investidor seja membro, se ela tiver uma
assinatura ativa e a IA ativada (primeiro as organizações das quais o investidor é proprietário,
depois a mais antiga). Sem nenhuma das duas, a chamada é recusada antes de qualquer trabalho do modelo com QUOTA_EXCEEDED (HTTP
402). A mensagem informa a data em que a franquia é renovada.
Limite de taxa. Os agentes de um investidor compartilham um limite de 60 chamadas por minuto, somando todos os tokens e conexões desse investidor. Acima dele, a chamada é recusada (HTTP 429) com o tempo de espera antes de tentar novamente.
Cada ferramenta verifica o que a sala de dados verifica para o investidor: acesso não expirado nem revogado, NDA aceito, a chave de agente por sala da equipe da transação ativada e, para um arquivo, o acesso de leitura do investidor a ele. Um arquivo que ele não pode ler é relatado como não encontrado, e seu nome nunca é retornado. A aceitação de um NDA continua sendo feita na sala de dados.
dataroom_ask_question (escrita)
Faz uma pergunta à equipe da transação em uma sala de dados. Somente o investidor e a equipe da transação a veem; a equipe da transação é notificada.
- Escopo:
write. - Entradas:
dataroom_id,title(pelo menos 5 caracteres) (obrigatórios);description,category,file_id(um arquivo que o investidor pode ler). - Saída:
{ question_id, dataroom_id, file_id, status }.
dataroom_list_file_comments
Os comentários que o investidor pode ver em um arquivo: os dele próprio, com as respostas.
- Escopo:
read. - Entradas:
dataroom_id,file_id(obrigatórios). - Saída:
{ comments: [{ id, content, page, resolved, created_at, author, replies }] }.
dataroom_add_file_comment (escrita)
Comenta em um arquivo que o investidor pode ler. Visível para o investidor e para a equipe da transação, nunca para outros investidores.
- Escopo:
write. - Entradas:
dataroom_id,file_id,content(obrigatórios);page. - Saída:
{ comment_id, file_id, created_at }.
dataroom_reply_file_comment (escrita)
Responde a um comentário que o investidor pode ver. Um comentário em outro arquivo é relatado como não encontrado.
- Escopo:
write. - Entradas:
dataroom_id,file_id,comment_id,content(obrigatórios). - Saída:
{ reply_id, comment_id, created_at }.
dataroom_get_my_nda_status
A situação do NDA do investidor em cada sala que o agente dele pode alcançar.
- Escopo:
read. - Entradas: nenhuma.
- Saída:
{ rooms: [{ dataroom_id, dataroom_name, basis, accepted, accepted_at, version, accept_step }] }.basiséorg_standard,firm_executed,firm_in_progress,waivedounot_required;accept_stepéclickthrough,heldounone.
dataroom_list_my_notifications
As notificações do investidor vindas da organização do token: convites, respostas às perguntas dele e alterações no acesso dele a pastas.
- Escopo:
read. - Entradas:
unread_only;limit(1–50, padrão 20);offset. - Saída:
{ notifications: [{ id, type, title, body, resource_type, resource_id, read, created_at }], unread_count, pagination }.
dataroom_mark_notifications_read (escrita)
Marca notificações como lidas: os ids listados, ou todas com all: true.
- Escopo:
write. - Entradas:
ids(1–100) ouall. - Saída:
{ marked }, quantas foram alteradas.
dataroom_list_published_updates
As atualizações para investidores publicadas para o investidor em uma sala.
- Escopo:
read. - Entradas:
dataroom_id(obrigatório). - Saída:
{ updates: [{ id, title, period_label, version, published_at, unread }] }. - Recusada quando a equipe da transação desativou as atualizações para o investidor e quando a sala não tem o complemento Materiais do Investidor.
dataroom_get_published_update
Lê uma atualização publicada.
- Escopo:
read. - Entradas:
dataroom_id,update_id(obrigatórios). - Saída:
{ update_id, title, period_label, version, published_at, document }.
Ferramentas de snapshot
Um snapshot é uma cópia congelada das pastas e versões de arquivos de uma sala, mantida para uma
trilha de auditoria. Nenhuma ferramenta retorna o conteúdo de arquivos ou um link de download; os downloads continuam no
aplicativo.
dataroom_get_snapshot e as ferramentas de visualizadores recusam um token limitado a salas de dados
específicas, assim como as rotas correspondentes no aplicativo.
dataroom_list_snapshots
- Escopo:
read. A equipe da transação vê todos os snapshots; qualquer outra pessoa vê apenas aqueles aos quais foi adicionada como visualizador. - Entradas:
dataroom_id(obrigatório). - Saída:
{ snapshots: [{ id, name, purpose, snapshot_at, file_count, folder_count, viewer_count? }] }.
dataroom_get_snapshot
- Escopo:
read, e acesso ao snapshot. - Entradas:
snapshot_id(obrigatório). - Saída:
{ snapshot, folders: [{ folder_id, parent_folder_id, name }], files: [{ file_id, folder_id, name, size_bytes, mime_type, can_download }], can_manage_viewers }. Arquivos e pastas que o proprietário do token não pode ver hoje são deixados de fora, e as contagens correspondem ao que é listado.
dataroom_create_snapshot
Congela a sala como ela está agora. Nada na sala é alterado.
- Escopo:
write, somente equipe da transação. - Entradas:
dataroom_id,name(obrigatórios);purpose,notes. - Saída:
{ snapshot: { id, name, purpose, snapshot_at, file_count, folder_count, viewer_count } }.
dataroom_list_snapshot_viewers
- Escopo:
read, somente equipe da transação. - Entradas:
snapshot_id(obrigatório). - Saída:
{ viewers: [{ viewer_id, email, granted_at, revoked_at, active }] }.
dataroom_grant_snapshot_viewer
Permite que alguém abra um snapshot pelo endereço de e-mail. Em duas etapas: a prévia indica o snapshot e o endereço. Nenhum e-mail é enviado: avise a pessoa você mesmo.
- Escopo:
write, somente equipe da transação, mais a permissão Enviar para pessoas fora da sua organização. - Entradas:
snapshot_id,email(obrigatórios);confirm_token. - Saída:
{ viewer_id, email, active }.
dataroom_revoke_snapshot_viewer
Em duas etapas.
- Escopo:
write, somente equipe da transação. - Entradas:
snapshot_id,viewer_id(obrigatórios);confirm_token. - Saída:
{ success: true, viewer_id }.
Ferramentas de links de compartilhamento
Um link de compartilhamento dá a quem o tiver acesso a uma sala ou a um documento, por isso criar um sempre exige duas etapas e um token com a permissão Enviar para pessoas fora da sua organização. Nenhuma ferramenta lista a URL de um link.
dataroom_list_share_links
- Escopo:
read, e o proprietário do token precisa ser proprietário ou administrador da organização. - Entradas:
dataroom_id(obrigatório);file_idpara os links ativos de um documento. - Saída:
{ links: [{ id, kind, file_id?, mode, active, expires_at, has_password, require_nda, domain_allow_list, created_at, admitted_count? }] }. - Links por investidor não são listados; consulte as ferramentas de investidores.
dataroom_create_share_link
Em duas etapas. A prévia informa o que é compartilhado, quem pode entrar, a regra de NDA, quando expira e como os downloads recebem marca d'água. A confirmação precisa repetir os mesmos argumentos; se a lista de investidores mudar nesse intervalo, confirme novamente.
- Escopo:
write, proprietário ou administrador da organização, mais a permissão Enviar para pessoas fora da sua organização. - Entradas:
dataroom_id,mode(openourestricted) (obrigatórios);file_id;expires_in_hours;domain_allow_list;require_nda(padrãotrue);confirm_token. - Saída:
{ id, url, mode, active, expires_at, require_nda, file_id }. - Um documento restrito não pode ser compartilhado por link. Não há opção de senha.
dataroom_revoke_share_link
Em duas etapas. Todos que usam o link perdem o acesso imediatamente.
- Escopo:
write, proprietário ou administrador da organização. - Entradas:
dataroom_id,link_id(obrigatórios);confirm_token. - Saída:
{ success: true, link_id, status: "revoked" }.