Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

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 exigem write, e as ferramentas que concedem permissões exigem admin. Um token abaixo do escopo exigido não vê a ferramenta e é rejeitado com um erro FORBIDDEN se a chamar (consulte Como uma falha é informada). O escopo é cumulativo — write inclui read, admin inclui 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ódigoSignificadoO que fazer
INVALID_ARGUMENTUm argumento está ausente, malformado ou não é um id válidoCorrija os argumentos e tente novamente
FORBIDDENO 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 permiteSolicite acesso ou use um token com o escopo correto
NOT_FOUNDO 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 existeVerifique o id e se o token está restrito à sala de dados do item
CONFLICTCompreendido e permitido, mas a sala de dados não está em um estado em que isso possa ser feitoLeia a mensagem, resolva o bloqueio e tente novamente
TOO_LARGEA entrada excede um limite de tamanhoDivida a entrada
QUOTA_EXCEEDEDUma cota medida foi esgotada ou a assinatura da organização expirouAlguém precisa comprar ou fazer upgrade — tentar novamente não resolve
UPSTREAM_ERRORUm serviço subsequente falhou — o documento armazenado não pôde ser obtido, ou a extração de texto falhou neleTransitório. Tente novamente mais tarde antes de tratá-lo como fatal
UNAVAILABLEO 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 registroTransitório. Tente novamente mais tarde
INTERNALUma falha inesperadaNã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:

CampoSignificado
limito tamanho de página efetivamente aplicado
offseto offset efetivamente aplicado
countquantas linhas há nesta página
has_moretrue quando existem mais linhas além desta página
next_offseto offset a informar para a próxima página, ou null quando o resultado está completo
totalo 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: true também é paginado — em uma árvore grande, percorra as páginas com next_offset em 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ão desc).
  • 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. Use has_more / next_offset para 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 }.

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 com next_offset ou 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ódigo PAT_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 }. Informe id como dataroom_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_list antes 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 de CONFLICT indica 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_folder nã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 } }. Informe previous_parent_folder_id de volta como new_parent_folder_id para 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 retornaSignificadoFinalize 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 1register_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 delefinalise_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 de request_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_version como a ferramenta para as versões 2 em diante.
  • A chave de armazenamento é derivada no servidor, e o s3_key do cliente nunca é considerado confiável. Ele é opcional; se você o enviar, ele precisa ser igual à chave que request_file_upload retornou, 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 — o version_number que request_file_upload retornou).
  • 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_number precisa 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_id a restore_file_version para desfazer.
  • Um arquivo que ainda não concluiu seu primeiro upload é rejeitado — finalize a versão 1 com register_file primeiro. 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_metadata lista os ids de versão do arquivo).
  • Saída: { file_id, version_id, version_number, already_current, new_version_created: false }.
  • already_current: true significa 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_metadata já 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 }. O name retornado é 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 }. Informe previous_folder_id de volta como folder_id para 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_file nã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_FOUND em 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çãoerror.codeO que fazer
1O arquivo não existe ou não é seuNOT_FOUNDVerifique o id.
2O arquivo não está excluído — ele já está ativoCONFLICTNão há nada a restaurar.
3O upload do arquivo nunca foi concluídoCONFLICTNão há nada a restaurar: os bytes nunca chegaram, então não há documento a trazer de volta. Faça o upload novamente.
4A pasta que o contém ainda está excluídaCONFLICTUse restore_folder primeiro — isso também traz de volta os arquivos excluídos junto com ela.
5Um arquivo ativo passou a usar o nome naquela pastaCONFLICTRenomeie 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 com GRANT_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 UNAVAILABLE e 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 source informa 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 com GRANT_REQUIRED; dataroom_get_file_metadata e dataroom_summarise_file ainda 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 como NOT_FOUND em 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". pagination traz um total.
  • Um arquivo sem objeto armazenado — uma nota, cujo corpo é mantido inline — retorna NOT_FOUND com "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 um 413 (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_ERROR quando o documento armazenado não pode ser buscado ou a extração de texto falha nele, e UNAVAILABLE quando 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, depois user_id, depois source, depois source_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 de null. identities_visible informa 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_visible informa 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 }. Um dataroom_permission igual a null significa 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: false grava 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, use revoke_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 de viewer, 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ão false).
  • Saída: { success: true, recursive, granted, skipped: { count, items } }.
  • Todo beneficiário já precisa estar na sala. Um expires_at no 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 em skipped. 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: false significa 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 add não o restabelece, e o beneficiário é listado em left_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 } }. Um null em stored significa 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) respondem NOT_FOUND até que ela seja restaurada. Um link direto para um de seus arquivos ainda o abre. dataroom_restore traz a sala de volta, então guarde o dataroom_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 que dataroom_archive retornou.
  • Saída: { success: true, dataroom_id, name, archived: false }.
  • Uma sala que não está arquivada é recusada (CONFLICT, código NOT_ARCHIVED). Uma sala arquivada pelo suporte do Waafir, ou junto com sua organização, é recusada (CONFLICT, código SUPPORT_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 de owner, admin ou member.

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, admin ou member) (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, revoked ou access_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 }] }. O id é o id do convite que as outras ferramentas de investidores recebem. Com Ler análise de engajamento, cada linha também tem engagement: { 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) é null para 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 é null quando 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 (viewer ou downloader); require_nda; resend; notify; confirm_token.
  • Saída: a prévia e o confirm_token na 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 de role, 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, requer canonical_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, answered ou closed); 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 com offset enquanto pagination.has_more for true.

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 é skipped e 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 }. O outcome de cada resultado é closed, not_found, forbidden ou already_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 }. Consulte dataroom_get_update_generation periodicamente.
  • 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). overrides aceita narrative_sections, chart_placements e citations.
  • 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 o file_id e a page de onde foi lido, ou uma página da web pública e sua citação), entered, not_applicable ou 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; similarity informa 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 }, ou status: "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 }. Enquanto has_more for true, passe next_cursor de volta como cursor para a próxima página.
  • Sem Ler conteúdo do documento no token, o value de cada fato mantém no máximo 20 palavras (160 caracteres), contadas sobre o valor inteiro, e o fato traz value_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, e truncated indica 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 um 413 (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 que force_refresh seja true.

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 }. score vai de 0 a 100, ou é null quando 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_metadata e dataroom_search.
  • Snapshots: dataroom_list_snapshots e dataroom_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_articles e dataroom_get_kb_article. Estas retornam as perguntas do próprio investidor e os artigos publicados.
  • IA: dataroom_ask, dataroom_compare_files, translate_text, translate_file e translate_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, waived ou not_required; accept_step é clickthrough, held ou none.

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) ou all.
  • 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 }.

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.

  • Escopo: read, e o proprietário do token precisa ser proprietário ou administrador da organização.
  • Entradas: dataroom_id (obrigatório); file_id para 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.

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 (open ou restricted) (obrigatórios); file_id; expires_in_hours; domain_allow_list; require_nda (padrão true); 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.

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" }.