Advisor API

Envie uma chave de membro criada dentro da organização — é a chave que carrega o vínculo, não o header. Recursos fora do escopo respondem 404. Veja a visão da extensão.

O contrato é o protocolo

O contrato tem sete operações, e nada mais. Não há rota por recurso: toda leitura do escritório é uma Function e toda escrita é uma Action, chamadas por id. O catálogo diz o que existe, o spec traz os schemas, e a execução recebe o sujeito e o input:

GET  /v1/advisor/functions
GET  /v1/advisor/functions/{functionId}
POST /v1/advisor/functions/{functionId}/execute

GET  /v1/advisor/actions
GET  /v1/advisor/actions/{actionId}
POST /v1/advisor/actions/{actionId}/preview
POST /v1/advisor/actions/{actionId}/execute

Ler: Functions

As leituras são advisor.me.get, advisor.organization.get, advisor.license.get, advisor.members.list, advisor.invitations.list, advisor.overview.get, advisor.audit.list, advisor.families.list, advisor.clients.list, advisor.client.get, advisor.client.history, advisor.client_portfolios.list, advisor.client_portfolio.get, advisor.client_portfolio.history e advisor.client_portfolio.ledger.

A organização viaja no input. O sujeito é o recurso endereçado: o cliente (advisor.client) em advisor.client.get, advisor.client.history e advisor.client_portfolios.list, e a carteira (advisor.client_portfolio) em advisor.client_portfolio.get, .history e .ledger. As demais leituras não têm sujeito.

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

Recusas trazem details.code: subject_required, subject_not_found, temporal_cut_unsupported, invalid_input, scope_missing. Recurso de outra organização responde 404, nunca 403.

Escrever: Actions

As escritas são advisor.invitation.accept, advisor.organization.update, advisor.seat.assign, advisor.member.update, advisor.invitation.create, advisor.invitation.revoke, advisor.family.create, advisor.client.create, advisor.client.update, advisor.client.delete, advisor.client_assignment.set, advisor.client_profile.update, advisor.client_portfolio.create, advisor.client_portfolio.delete, advisor.client_portfolio.import, advisor.client_portfolio_asset.add, advisor.client_portfolio_asset.remove, advisor.client_portfolio_transaction.add e advisor.client_portfolio_transaction.delete.

O spec de cada Action declara efeitos, confirmação, idempotência e o evento de auditoria. preview mostra o efeito sem gravar; a execução exige confirmed: true onde o spec pede.

curl -X POST https://api.databolsa.com/v1/advisor/actions/advisor.client.create/execute \
  -H "authorization: Bearer $DATABOLSA_ADVISOR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input":{"org":"org_abc123","name":"Ana Souza"},"confirmed":true}'

Perfis do MCP

O contrato declara dois perfis, e os dois trazem as mesmas sete tools — o catálogo, o spec, a prévia e a execução de Functions e Actions, que alcançam tudo o que o escritório faz. O que cada leitura e cada escrita significa está no catálogo, buscado sob demanda, e não na descrição de uma tool por recurso.