Advisor

Clientes, carteiras por cliente, permissões e auditoria dentro do workspace da organização.

O Advisor é a extensão organizacional do DataBolsa para escritórios de assessoria, consultorias e wealth managers. Ele acrescenta clientes, perfis, carteiras por cliente, papéis de equipe e uma trilha de auditoria ao mesmo workspace em que o profissional pesquisa o mercado e produz análises.

Não existe um painel ou chat separado. O trabalho acontece no Notebook, na rota /x/databolsa.advisor; o antigo host advisor.databolsa.com apenas redireciona para essa página.

Clientes e carteiras

A página da extensão começa pela lista de clientes. O cabeçalho já apresenta o patrimônio sob gestão e os recortes por status e responsável, sem um dashboard paralelo. Abrir um cliente mostra perfil, objetivos, restrições, atividade e carteiras reais ou de proposta.

Posições são derivadas do ledger de transações. Uma carteira de proposta pode ficar fora do AUM para estudar cenários sem alterar o consolidado real.

Organização e permissões

O Advisor só pode ser instalado em workspaces de organização. Equipe, papéis, convites e chaves pessoais são administrados na área Conta do Notebook.

O acesso é recortado pelo papel e pela relação com o cliente. Recursos fora do escopo respondem 404, sem revelar se existem. Toda escrita é auditada na mesma transação da mudança; licença vencida preserva leitura e bloqueia escrita com 402 license_required.

Chaves antigas de organização (db_org_...) não são aceitas. Integrações usam a chave pessoal db_live_... do membro e o workspace da organização.

Functions e Actions

O contrato do escritório é chamado por id, e só por id: são sete operações, não uma rota por recurso. As Functions são as leituras (advisor.clients.list, advisor.client.get, advisor.client_portfolio.get, advisor.client_portfolio.ledger, advisor.overview.get, advisor.audit.list…) e as Actions são as escritas (advisor.client.create, advisor.client_portfolio_transaction.add…). Cada superfície tem catálogo, spec com schemas e execução em /v1/advisor/functions e /v1/advisor/actions.

curl -X POST https://api.databolsa.com/v1/advisor/functions/advisor.client.get/execute \
  -H "authorization: Bearer $DATABOLSA_ADVISOR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"subject":{"entity_id":"cli_abc123"},"input":{"org":"org_abc123"}}'

A organização vai no input; o sujeito é o cliente ou a carteira do cliente, resolvido pelo chokepoint do data plane — recurso fora do escopo responde 404. Uma sessão MCP abre com as mesmas sete tools: catálogo, spec, prévia e execução das duas superfícies. O que cada leitura e cada escrita significa vem do catálogo, buscado sob demanda.

No SDK, o id escolhe o input aceito e o tipo do result:

import { DataBolsaAdvisor } from "@databolsa/advisor-sdk";

const advisor = new DataBolsaAdvisor({ apiKey: process.env.DATABOLSA_ADVISOR_API_KEY });

const clientes = await advisor.executeFunction("advisor.clients.list", {
  input: { org: "org_abc123", status: "active" },
});
clientes.result.data[0].name; // string, sem cast

const novo = await advisor.executeAction("advisor.client.create", {
  input: { org: "org_abc123", name: "Ana Souza" },
  confirmed: true,
});
novo.result.id; // string

Id publicado depois da versão instalada do SDK vai em executeFunctionAny ou executeActionAny, que devolvem result sem tipo.

No agente

O conector MCP é o mesmo do DataBolsa. As capacidades do Advisor aparecem quando a extensão está instalada, os scopes foram autorizados e o contexto do turno permite a operação. Escritas sobre clientes ou carteiras exigem alvo explícito e confirmação.

Conecte Claude, Codex, ChatGPT ou outro agente →

API e clientes

O data plane e o contrato permanecem separados para preservar as regras do domínio:

Referência da API
OpenAPI
@databolsa/advisor-sdk
@databolsa/advisor-cli
@databolsa/advisor-mcp para uso local

SDK

import { DataBolsaAdvisor } from "@databolsa/advisor-sdk";

// A organização vem da CHAVE, criada dentro dela.
const advisor = new DataBolsaAdvisor({
  apiKey: process.env.DATABOLSA_ADVISOR_API_KEY,
});

const { result } = await advisor.executeFunction("advisor.clients.list", {
  input: { org: "org_abc123", status: "active" },
});
result.data[0].status; // "prospect" | "active" | ... — o tipo veio do id

await advisor.executeAction("advisor.client.create", {
  input: { org: "org_abc123", name: "Ana Souza" },
  confirmed: true,
});

CLI

export DATABOLSA_ADVISOR_API_KEY=db_live_SUACHAVE
npx -y @databolsa/advisor-cli --list
npx -y @databolsa/advisor-cli advisorListFunctions --json
npx -y @databolsa/advisor-cli advisorGetFunction advisor.clients.list --json

O identificador da organização vai no input de cada Function ou Action; a credencial já carrega o workspace, então a mesma chave não age noutro escritório.

O Advisor não executa ordens nem substitui o julgamento ou a responsabilidade do profissional habilitado.