Posição, custódia, captação e comissão da corretora
Deduplicação, dia íntegro, assessor vigente na data
AUC, captação líquida e receita por assessor
Painel, lista diária do assessor e agente de IA
O que resolve
- O patrimônio e a captação de cada assessor batem com o relatório da corretora, sem dia parcial nem linha duplicada.
- Captação e receita ficam com o assessor que atendia a conta na data, mesmo depois de troca de carteira.
- O assessor recebe todo dia a lista do que fazer: vencimentos, saldo negativo, cadastros novos.
Perguntas de negócio que responde
Faça estas perguntas ao seu agente quando o caso estiver pronto.
O que você precisa
- O conector da corretora (BTG Parceiros ou XP) ou os arquivos de relatório conectados na Nekt
- A base de clientes com assessor, origem e o histórico de trocas de carteira
- As planilhas de comissão das fontes que não vêm pela API
O que você recebe
- Tabelas de custódia, captação e receita por conta e dia, com o assessor da data
- Painel por assessor e escritório com AUC, captação líquida e receita
- Listas diárias por assessor no WhatsApp ou no e-mail
- Um agente de IA que responde sobre carteira e captação com as regras certas
Onde ativar
AUC, captação líquida e receita por assessor e escritório, com o dia de referência e a fonte de cada número à vista.
No WhatsApp ou no e-mail: títulos vencendo em 2 dias, saldo negativo, saldo parado, cadastros dos últimos 7 dias e clientes sem Open Finance.
Responde carteira, captação e receita por assessor com a regra de vigência e o dia íntegro já aplicados.
Os conectores trazem os dados prontos. O trabalho está na deduplicação, na blindagem contra relatório parcial e no histórico de assessor. O detalhado traz as regras de negócio, as armadilhas e o teste de aceitação. Ou mande tudo direto para o seu agente com o MCP da Nekt.
Cada corretora entrega a carteira em pedaços: posição por mercado, custódia por produto, movimentos de captação, comissão por categoria, positivador mensal. Os cadastros de conta e assessor são versionados e as chaves mudam a cada versão, o relatório do dia às vezes chega com poucas linhas e o saldo em conta é sobrescrito a cada carga. Quem soma direto atribui captação antiga ao assessor de hoje, mostra patrimônio despencando num dia parcial e perde o histórico do saldo.
Como costuma ser feito, e a regra
Cada linha é um erro que já aconteceu na prática.
Captação, custódia e receita ficam com o assessor que atendia a conta na data do movimento ou da posição. Cruze com o histórico da base de clientes onde início da vigência <= data do fato e (fim da vigência nulo ou > data do fato). O assessor de hoje só vale para a foto de hoje.
Nos cadastros versionados da XP (conta, assessor, escritório, produto), dimAccountCode, dimAdvisorCode e dimOfficeChannelCode mudam a cada versão. O fato de custódia já aponta para a versão vigente na data da posição: junte por essa chave e nunca filtre por 'vigente hoje'. Para identidade ao longo do tempo, use accountCode, advisorCode e officeCode.
Custódia: uma linha por conta, dia e produto, a de maior lastupdate. Captação: uma por conta, dia, código do movimento, valor e quantidade. Posição por parceiro: uma por conta e dia. Positivador: primeiro some as linhas complementares que dividem o mesmo lastupdate (métricas de fluxo), depois deduplique os reprocessamentos e tire fins de semana.
O relatório mais recente pode trazer o dia corrente pela metade. Dentro do último relatório, escolha a data de referência mais recente cujo volume de linhas seja pelo menos 50% do maior volume daquele relatório. O dia parcial é descartado e o último dia bom se mantém.
Fim de semana e feriado sem posição são esperados. Um dia de pregão sem nenhuma linha de custódia para nenhuma conta é falha da fonte: sinalize, não preencha com zero e não deixe o painel mostrar patrimônio zerado.
Saldo em conta de investimento e em conta digital vem em carga completa sem partição de data: cada carga apaga a anterior. A cada execução, acrescente o snapshot numa tabela de histórico carimbado com a data de processamento. A data de referência é a data da execução em America/Sao_Paulo menos um dia quando a extração roda logo depois da meia-noite.
Quando a fonte muda (base antiga até uma data, API a partir dela), una as duas com uma coluna fonte e uma data de corte que não se sobrepõe. Converta data e número do legado ('dd/mm/aaaa', '1.234,56') antes da união. Campos que só existem numa fonte ficam nulos na outra.
Receita do dia por conta = primeiro valor preenchido entre receita líquida, receita e comissão, ou zero. Comissões que chegam em arquivos separados (por produto, câmbio, crédito, mercado internacional) são projetadas num schema comum: cliente, assessor, receita bruta, receita líquida, comissão, produto e moeda de origem. Receita em dólar vira real pela PTAX de fechamento. Competência vem do nome do arquivo (AAAAMM_fonte) quando não há coluna.
Quando os assessores conferem e corrigem a comissão de anos fechados, a planilha corrigida substitui o relatório original daquele período. O relatório da corretora vale a partir do corte. Grave com chave de hash para que reprocessar não duplique.
Compare e agrupe o assessor em maiúsculas, sem acento e sem espaço nas pontas. Valores nulos, vazios e '-' são conta sem assessor e aparecem como tal no painel, nunca somem.
De onde vem cada número
Fontes típicas de BTG e XP. Cada uma deduplicada pela sua chave.
Definições
Armadilhas que já aconteceram
A corretora mandou o dia corrente com poucas linhas, contra milhares num dia normal. O MAX da data puxou esse dia e o painel mostrou a carteira de renda fixa quase zerada.
Use a data mais recente com volume de pelo menos 50% do maior volume.
A tabela de relação entre conta e assessor cobria só um escritório, e cerca de um terço da custódia ficou sem assessor no cruzamento.
Leve o assessor pelo cadastro de assessor da data da posição e use a relação só como conferência.
Algumas contas e assessores não tinham nenhuma versão marcada como vigente no cadastro da corretora, mesmo com data de validade cobrindo hoje. Um filtro de vigente hoje fez essas contas sumirem.
Junte pela chave da data e, sem versão vigente, use a de maior início de validade com flag.
A partir de uma certa data de relatório, a data de nascimento passou a vir com dia e mês invertidos quando o dia era até 12, e a lista de aniversariantes saiu errada.
Corrija pela data do relatório e valide com uma amostra conhecida.
Uma fração pequena das posições vinha negativa e outra parte zerada. Filtrar tudo como erro tirou posições a descoberto e histórico legítimo.
Mantenha e marque; só exclua com regra de negócio escrita.
A lista diária era gerada numa tabela por assessor, com o nome fixo no código. Assessor novo ficava sem lista até alguém editar o notebook.
Uma tabela única particionada por assessor, com o destinatário vindo da base.
Teste de aceitação
O caso está pronto quando todos os itens passam.
- A custódia tratada tem o mesmo número de linhas distintas por conta, dia e produto que a fonte: os joins não perdem nem duplicam linhas.
- Para um dia íntegro, o AUC total por conta bate com o relatório da corretora (diferença abaixo de 0,5%).
- Toda linha de captação tem o assessor da data ou aparece como conta sem assessor; nenhuma usa o assessor atual para data passada.
- Todo dia útil sem custódia aparece sinalizado como falha de carga, e nenhum dia parcial vira a foto mais recente.
- A receita do mês por assessor é igual à soma das fontes de comissão daquela competência, já convertidas para real.
Pacote para o agente
Cole no Claude, ChatGPT ou outro cliente com o MCP da Nekt conectado.
Patrimônio, captação e receita por assessor - Corretora: <BTG/XP>. Custódia em <tabela>, captação em <tabela>, comissão em <tabela>, positivador em <tabela>. - Deduplicação: custódia por conta, dia e produto (maior lastupdate); captação por conta, dia, movimento, valor e quantidade; posição por conta e dia. - Foto do dia: dentro do último relatório, a data mais recente com volume >= 50% do maior volume. Dia útil sem dado é falha de carga, nunca patrimônio zero. - Assessor: o vigente na data do fato, pelo histórico de clientes (início <= data e fim nulo ou > data). Nunca o assessor de hoje para data passada. - Cadastros da XP são versionados: junte pela chave substituta da data; identidade por accountCode, advisorCode e officeCode. - Receita do dia = receita líquida, senão receita, senão comissão, senão zero. Dólar convertido pela PTAX de fechamento. - Até <data de corte>, a comissão vem da planilha corrigida pelos assessores; depois, do relatório. - Saldo em conta vem de snapshots acumulados por data de processamento, no fuso America/Sao_Paulo. - Assessor em maiúsculas e sem acento. Nulo, vazio ou '-' = sem assessor. - Nunca mostre CPF completo nem dados de contato fora da lista do próprio assessor. Exceções por cliente: - <cliente>: legado até <data> na base <tabela>, API a partir de <data>; coluna fonte indica a origem. - <cliente>: a mesa <mesa> tem lista fixa de contas em <tabela>. - <cliente>: data de nascimento com dia e mês trocados a partir de <data>; corrija quando o dia for até 12.
Construa no meu workspace Nekt o caso "Patrimônio e captação por assessor" seguindo as regras em https://academy.nekt.com/industrias/financeiros/patrimonio-captacao-assessor.md. 1) Encontre as tabelas de origem e confirme as colunas usadas pelas regras. 2) Crie uma transformação no grão indicado aplicando todas as regras. 3) Rode o teste de aceitação e me mostre o resultado de cada item. 4) Crie o context document do caso no workspace, com as exceções dos meus clientes em aberto para eu preencher.
Variações
Corretoras de seguros: percentual de repasse por ramo sobre a comissão de cada apólice, por franqueado, cruzando a produção por CNPJ e apólice.
Investimentos cadastrados à mão e via Open Finance, deduplicados pelos ids externos e conferidos contra o saldo agregado da instituição.
Recorte da custódia do último dia por classe (fundos imobiliários, renda fixa, renda variável, previdência), com produto, conta e assessor.