Clientes e carteiras

Cadastro, famílias, perfil de objetivos e restrições, e carteiras por cliente com posição a mercado.

Cadastro

Cliente é pessoa (person) ou entidade (entity), e nasce como prospect ou active. Famílias agrupam clientes que se olham juntos (o casal, a holding e a PF, o grupo familiar).

databolsa-advisor advisorCreateFamily meu-escritorio --name "Família Souza"
databolsa-advisor advisorCreateClient meu-escritorio \
  --name "Maria Souza" --kind person --email [email protected] \
  --family_id <familyId> --status active
databolsa-advisor advisorListClients meu-escritorio --json

advisorSetClientAssignment define o assessor responsável — é ele que decide o que cada pessoa enxerga quando a organização está em client_visibility: assigned.

Perfil: o contexto que a IA lê

advisorUpdateClientProfile guarda objetivos, restrições, perfil de risco, horizonte e notas. Este é o contexto que o chat do escritório, o conector MCP e os relatórios leem — é o que faz a resposta sair no enquadramento daquele cliente em vez de genérica.

databolsa-advisor advisorUpdateClientProfile meu-escritorio <clientId> \
  --risk_profile moderado --horizon "10 anos" \
  --objectives '[{"kind":"aposentadoria","description":"Renda de R$ 15k/mês","target_date":"2038-01-01"}]' \
  --restrictions '[{"kind":"setor","description":"Sem tabaco e armas"},{"kind":"concentracao","asset_class":"acoes","max_pct":40}]'

Restrições aceitam alvo por symbol, por asset_class e teto em max_pct. O perfil não versiona por conta própria: o histórico de quem mudou o quê está na trilha de auditoria.

Carteiras

Cada cliente tem quantas carteiras precisar, em dois tipos:

actual — o que o cliente tem de fato; entra no consolidado dele.
proposal — estudo, realocação, proposta comercial. Fica fora do consolidado, então dá para simular sem sujar a posição real.

databolsa-advisor advisorCreateClientPortfolio meu-escritorio <clientId> \
  --name "Consolidado" --kind actual
databolsa-advisor advisorGetClientPortfolio meu-escritorio <portfolioId> --json | jq .totals

Posição sai do ledger

Ativos e transações são a fonte; a posição é calculada — quantidade e preço médio do ledger, valor a mercado da cotação do dia. Não existe "corrigir a posição": corrige-se o lançamento.

databolsa-advisor advisorAddClientPortfolioAsset meu-escritorio <portfolioId> \
  --asset_type stock --symbol PETR4
databolsa-advisor advisorAddClientPortfolioTransaction meu-escritorio <portfolioId> <assetId> \
  --kind buy --trade_date 2026-07-10 --quantity 100 --price 38.10
databolsa-advisor advisorGetClientPortfolioLedger meu-escritorio <portfolioId>

Importar de planilha

advisorImportClientPortfolioFile aceita o xlsx de negociação da B3 e CSV — o mesmo importador do produto, idempotente: reimportar o mesmo arquivo não duplica lançamento.

databolsa-advisor advisorImportClientPortfolioFile meu-escritorio <portfolioId> \
  --file negociacao-2026.xlsx

Evolução

advisorGetClientPortfolioHistory devolve a série de uma carteira e advisorGetClientHistory a do cliente inteiro (todas as actual somadas), para gráfico de evolução e comparação com benchmark.

Dado pessoal do escritório

Nome, documento, e-mail e perfil do cliente são dados pessoais sob responsabilidade do escritório. O cliente não tem login e não vira usuário do DataBolsa. Ao usar CLI, SDK ou um agente, não copie esses campos para além do que a tarefa pede — e lembre que toda leitura escrita fica auditada.