Lucro ON

CUSTO POR SKU, como está cadastrado HOJE na tela de Produtos: uma linha por SKU com o produto, a pasta, o custo, de onde vem o custo (proprio | modelo = custo da pasta | erp | excecao_do_sku | soma_dos_componentes), o tipo (produto | kit | sem_produto = SKU de anúncio sem produto | nao_encontrado = a conta não tem esse SKU) e em quantos anúncios o SKU está. Kit traz a composição e alerta de kit suspeito. Use para CRUZAR UMA PLANILHA DE CUSTO com o cadastro ("os custos foram preenchidos certo?"): mande os SKUs da planilha em `skus` (até 200 por chamada — divida em lotes) e compare o custo de cada um; ou liste tudo por página, ou filtre sem_custo / sem_produto / kit. Só para contas no modo Produtos. Os dados podem ter até 10 minutos.

get_custos_por_sku

DRE completo do período: receita bruta → impostos → CMV → taxas/comissões/frete/ads → margem de contribuição → perda com devoluções → despesas → LUCRO LÍQUIDO. Use para "onde estou perdendo dinheiro", "monta meu DRE", análise de resultado.

get_dre

Evolução do resultado MÊS A MÊS (receita, despesas variáveis, custo fixo, lucro líquido). Use para "minha margem está caindo?", comparar meses, ver tendência.

get_dre_mensal

Gasto e retorno das campanhas de anúncios (Shopee e Mercado Livre) no período. Use para "meu ads dá retorno?", "quanto gastei de ads", ROAS.

get_performance_ads

Raio-X de pedido(s): itens, taxas, frete, custo do produto, ads e o lucro final. Use quando o vendedor citar um código de pedido ou perguntar "por que esse pedido deu prejuízo". Para vários pedidos passe `order_sns` (até 20) numa chamada só.

get_detalhe_pedido

Estoque do FULL no Mercado Livre (CD) e na Shopee (armazém): quanto tem de cada produto lá dentro, quanto vendeu em 7/30 dias, DIAS DE COBERTURA (quando vai acabar), quanto ENVIAR para cobrir 30 dias e capital parado. Use para "o que está esgotando no Full", "o que preciso enviar", "o que está encalhado", "o que mais vende no Full".

get_estoque_full

ESTOQUE PRÓPRIO (depósito do vendedor, fora do Full) por ANÚNCIO × venda dos últimos 30 dias: venda por dia, cobertura em dias, custo unitário e as listas RUPTURA (estoque 0 e vendeu em 30 dias — venda perdida), COBERTURA BAIXA (menos de 7 dias) e PARADOS (estoque e nenhuma venda em 30 dias, com o capital parado = estoque × custo quando há custo). `resumo` traz as contagens e o capital parado total. O estoque é o do anúncio sincronizado do marketplace (a variação está em get_anuncio); o Full está em get_estoque_full. Use para "o que vai acabar", "o que está parado".

get_estoque_proprio

Série diária de faturamento/lucro no período + ranking dos produtos que mais venderam. Use para tendência ("estou crescendo?", "qual dia vendi mais") e para top produtos.

get_evolucao_diaria

Painel financeiro do período: receita, margens, health score e projeção de fechamento. Use para "como fecho o mês", "qual minha saúde financeira".

get_faturamento

Fechamento por DATA DE ENVIO (despacho), não por data do pedido: "quantos pedidos enviei em agosto", "o que despachei entre X e Y". Conta TODO pedido despachado no período, mesmo que depois tenha sido cancelado ou devolvido (a transportadora cobra) — o status final vem em `por_status`. Traz total (com próprio × Full), por_dia, por_loja, por_plataforma (Amazon marcada `aproximado`), `pendentes` (pedidos já enviados que ainda não têm a data gravada; a reconciliação noturna preenche) e `fechado` (true quando não há pendentes — o mês está batido). `observacoes` traz as ressalvas do período. Use para conferência com transportadora/expedição e fechamento mensal por envio.

get_fechamento_por_envio

FICHA COMPLETA do anúncio no MESMO formato para Shopee, Mercado Livre, TikTok e Shein: título, descrição, marca, categoria, ficha técnica (atributos), variações, imagens, vídeo, peso e dimensões, preço, estoque, vendidos e link. Traz `saude` (0-100) APENAS no Mercado Livre — nas outras plataformas vem null, porque a plataforma não fornece. Traz também `lacunas`, a lista do que falta preencher no anúncio. Use para "como está meu anúncio X", "o que falta nesse anúncio", "compare a ficha técnica dos meus produtos", "quais anúncios estão sem descrição".

get_anuncio

FLUXO DE CAIXA das próximas semanas (GET /api/analise/fluxo-caixa): por semana (até 8, a 1ª começa hoje) o que as plataformas vão pagar (a mesma agenda da Conciliação: Mercado Livre e Shein pela data informada, TikTok pelos entregues, Shopee estimado), as outras entradas e as contas a pagar em aberto pelo vencimento, o saldo da semana e — com `saldo_inicial` (saldo em conta hoje, que o vendedor informa) — o saldo acumulado. Traz também contas vencidas, a receber atrasado, a receber sem data, TikTok aguardando entrega, a plataforma que falhou e as 5 maiores saídas de cada semana. Use para "vou ter dinheiro para pagar as contas?", "como fica meu caixa no mês?". Amazon não entra. Exige as páginas Conciliação e Financeiro: sub-usuário sem elas recebe "sem permissão" — isso não significa que não haja dados.

get_fluxo_caixa

PASSO 2 de 2 de QUALQUER relatório em PDF (depois de montar_relatorio): gera o PDF do tipo pedido e devolve o link de download (válido por 7 dias) — o relatório oficial da Lucro ON é ESTE PDF; entregue o link em vez de escrever um relatório no chat. Os números saem do mesmo dossiê de montar_relatorio, montado no servidor; `analise` recebe só o texto (resumo, destaques, um texto por seção e o plano de ação).

gerar_relatorio

PASSO 2 de 2 do relatório MENSAL (depois de montar_relatorio_mensal; atalho de gerar_relatorio com tipo relatorio_mensal): gera o Relatório Mensal em PDF e devolve o link (7 dias) — entregue o link em vez de escrever um relatório no chat. Os números saem do dossiê do servidor; `analise` recebe só o texto.

gerar_relatorio_pdf

Lista os agentes especialistas da Lucro ON com o que cada um faz e exemplos de pedido. Para acionar um, use usar_agente.

listar_agentes

Devoluções e reembolsos com status, valor e PRAZO de resposta. Use para "quais devoluções estão com prazo estourando", "quanto perdi com devolução".

listar_devolucoes

Lista as lojas conectadas do vendedor: nome, marketplace, status e o `id` da loja — é o `id` que vai em shop_ids nas demais ferramentas (para filtrar por loja ou por marketplace, passe os ids das lojas dele). `numero_no_marketplace` é só informativo.

listar_lojas

Lista pedidos do período (pela DATA DO PEDIDO) com o lucro de CADA venda e a data de envio (`shippedAt`, despacho real; null = ainda não despachado). Com apenas_prejuizo=true traz só os que deram prejuízo — use para "quais vendas deram prejuízo essa semana". Pedidos de um produto/anúncio/SKU: use `produto` (rápido). `busca` é só para código do pedido. A data de envio já vem em cada linha. A lista por DATA DE ENVIO é a de listar_pedidos_enviados.

listar_pedidos

Lista PEDIDO A PEDIDO o que foi DESPACHADO no período (pela data de envio real, `enviado_em`), com order_sn, loja, plataforma, status atual, data do pedido (`criado_em`), valor, repasse, Full, transportadora e rastreio — até 500 por página, ordenado por data de envio. Use para planilha/conferência com transportadora e fechamento por envio pedido a pedido ("liste os pedidos que enviei em setembro"). Para só os totais use get_fechamento_por_envio. Pedidos já enviados que ainda não têm data gravada não aparecem — veja `pendentes` no get_fechamento_por_envio.

listar_pedidos_enviados

Catálogo de anúncios/produtos com preço, custo e estoque. Use para "quais produtos tenho", "qual o custo desse anúncio", ou combinado com get_evolucao_diaria para achar os mais lucrativos.

listar_produtos

Ranking de produtos por LUCRO REAL do período (o lucro de cada pedido, já com taxas, frete, ads e imposto, dividido entre os produtos pela receita de cada um), com curva ABC por receita e por lucro, FALSOS CAMPEÕES (vendem muito e lucram pouco), JOIAS (lucram muito sem estar no topo de vendas), produtos NO PREJUÍZO e SEM CUSTO cadastrado, e, com comparar_com_anterior=true, o período anterior de mesmo tamanho (`anterior` em cada produto; sem ele `anterior` vem null). Use para "quais produtos me dão lucro de verdade", "o que está no prejuízo", "curva ABC", "onde focar". `totais.pct_receita_sem_custo` alto indica lucro superestimado (vendas de produtos sem custo cadastrado). O dia de hoje pode ainda não estar completo. Em contas muito grandes a PRIMEIRA consulta de um período pode levar até ~1 minuto (depois fica em cache); comparar_com_anterior dobra esse tempo. Período máximo: 93 dias. O erro "ainda está sendo calculado" significa que o cálculo continua no servidor e fica pronto em cerca de 1 minuto.

get_produtos_lucro

PASSO 1 de 2 de QUALQUER relatório em PDF: montar_relatorio { tipo } → escreva a análise com base só nesses números → gerar_relatorio com o MESMO tipo, período e lojas → entregue o link. Use sempre que o vendedor pedir um relatório, um PDF ou um documento para a equipe — não escreva um relatório próprio no chat. Devolve o dossiê com os números do servidor, as seções (com o texto padrão de cada uma), o diagnóstico e chaves_de_secao_para_analise. Os relatórios marcados [retrato] mostram a situação de agora e ignoram o período informado. Tipos: - relatorio_mensal: Relatório Mensal (agente relatorio_mensal) — fechamento do mês inteiro: DRE, evolução, custos, lojas, produtos, ads, estoque, devoluções, conciliação, meta e plano de ação - relatorio_semanal: Relatório Semanal (agente relatorio_mensal) — a semana fechada (7 dias até ontem) contra a anterior: vendas, lojas, produtos, ads, ritmo da meta e expedição - diagnostico_conta: Diagnóstico da Conta (agente auditoria_conta) — checklist da configuração (lojas, sincronização, imposto, meta, anúncios, custo dos produtos, despesas fixas) com onde resolver cada pendência — ideal para cliente novo - ads: Relatório de Anúncios Pagos (agente ads) — campanhas de Shopee, Mercado Livre e TikTok contra o ROAS mínimo da margem: onde cortar (com impacto em R$) e onde escalar - estoque: Relatório de Estoque (agente estoque) — ruptura, cobertura em dias e capital parado do estoque próprio e do Full, com quanto enviar ao Full [retrato de agora: IGNORA o período pedido] - financeiro: Relatório Financeiro (agente financeiro) — DRE do período contra o anterior, para onde vai o dinheiro, produtos no prejuízo e falsos campeões - promocoes: Relatório de Promoções (agente promocoes) — promoções do Mercado Livre: as ativas no prejuízo (sair) e as disponíveis com margem de pelo menos 5% (entrar) [retrato de agora: IGNORA o período pedido] - logistica: Relatório de Logística e Pós-venda (agente logistica) — devoluções (taxa, perda real e motivos), falhas de entrega e a fila de expedição com prazos vencidos - clientes: Relatório de Clientes e Recompra (agente clientes) — base de clientes agregada (sem dado pessoal): recorrentes, compra em 2+ dias, tickets, intervalo entre compras e estados - anuncios: Relatório de Otimização de Anúncios (agente anuncios) — os anúncios que mais vendem e o que falta na ficha de cada um (descrição, imagens, vídeo, ficha técnica, saúde), por prioridade [retrato de agora: IGNORA o período pedido] - afiliados: Relatório do Canal de Afiliados (agente afiliados) — quanto do faturamento vem de afiliados e quanto custa a comissão, por plataforma - bi_previsao: Relatório de BI e Previsão (agente bi_previsao) — curva ABC por receita, produtos subindo ou caindo (7 dias contra os 7 anteriores) e projeção do mês - diretor_comercial: Relatório Comercial (agente diretor_comercial) — meta × realizado, mínimo diário para bater, ritmo, lojas e as alavancas de venda (joias e produtos classe A) - catalogo: Relatório de Catálogo do Mercado Livre (agente catalogo) — disputa das páginas de catálogo do Mercado Livre: ganhando, perdendo, vendas em jogo e onde dá para ganhar com lucro [retrato de agora: IGNORA o período pedido] - diretor_criativo: Plano de Imagens dos Anúncios (agente diretor_criativo) — anúncios que mais vendem com poucas imagens ou sem vídeo e o plano da sequência de imagens (a IA escreve os prompts) [retrato de agora: IGNORA o período pedido] - comite: Briefing do Comitê Executivo (agente comite) — o mês até agora em um quadro por área (vendas, meta, operação, ads, produtos, alertas) e o plano priorizado por impacto em R$ - fluxo_caixa: Relatório de Fluxo de Caixa (agente fluxo_caixa) — as próximas 8 semanas: o que as plataformas vão pagar, o que vence em contas a pagar, o saldo de cada semana e as semanas que apertam [retrato de agora: IGNORA o período pedido] - calendario: Relatório de Calendário Comercial (agente calendario) — as datas comerciais dos próximos 120 dias por marketplace, com quando preparar, a receita do ano anterior, o efeito da data e a meta sugerida [retrato de agora: IGNORA o período pedido] - reputacao: Relatório de Reputação (agente reputacao) — termômetro do Mercado Livre e saúde da conta da Shopee por loja: métricas fora da meta, pontos de penalidade e o que piorou em 30 dias [retrato de agora: IGNORA o período pedido] - concorrencia: Relatório de Concorrência e Preço (agente concorrencia) — seu preço × o menor preço dos outros vendedores do mesmo produto no Mercado Livre: onde está caro, onde está barato e o que não tem comparação [retrato de agora: IGNORA o período pedido] - tendencias: Relatório de Tendências e Oportunidades (agente tendencias) — buscas em alta e mais vendidos das suas categorias no Mercado Livre, com as oportunidades que você ainda não cobre com anúncio [retrato de agora: IGNORA o período pedido]

montar_relatorio

PASSO 1 de 2 do relatório MENSAL (atalho de montar_relatorio com tipo relatorio_mensal): use quando o vendedor pedir o relatório do mês/fechamento — depois chame gerar_relatorio_pdf e entregue o link; não escreva um relatório próprio no chat. Monta o DOSSIÊ do Relatório Mensal: KPIs do mês e do anterior, DRE, evolução, custos, lojas, produtos, anúncios pagos, estoque, devoluções, conciliação e meta, com diagnóstico e chaves_de_secao_para_analise.

montar_relatorio_mensal

FILA DE EXPEDIÇÃO: pedidos pagos dos últimos 15 dias que ainda não saíram (status "Aguardando Envio" e sem data de despacho). Traz o total por idade desde a compra (ate_24h, de_24_a_48h, acima_48h), o PRAZO de despacho quando o marketplace informa (`prazo`: vencido, vence_hoje, vence_amanha, no_prazo, sem_prazo — Shopee e Shein informam; Mercado Livre e TikTok vêm sem_prazo), a quebra por plataforma e os 50 mais antigos (order_sn, loja, plataforma, criado_em, horas, prazo, situacao_prazo). Pedidos Full NÃO entram (o marketplace despacha): só a contagem em `full_fora_da_fila`. Use para "o que tenho para despachar", "tem pedido atrasado?". No Mercado Livre, "Aguardando Envio" com mais de 48 h pode ser status desatualizado (o envio já saiu e ainda não foi relido): confirme no painel do ML antes de tratar como atraso. Atualiza a cada 5 minutos.

get_pedidos_a_despachar

Promoções do Mercado Livre (ativas e disponíveis para aderir) com o LUCRO de cada uma já calculado: preço promocional, desconto seu vs. do ML, estorno de tarifa, comissão, frete e margem final. Use para "quais promoções estão ativas", "vale a pena entrar nessa promoção", "tem promoção me dando prejuízo". Em contas com muitas lojas a consulta é pesada; filtrar por shop_ids de uma loja reduz o tempo.

listar_promocoes_ml

Quanto foi descontado por TIPO no período: comissão + taxas do marketplace, frete do vendedor, frete reverso, afiliados, ads, imposto e custo do produto — com o quanto cada um representa do faturamento. Para uma plataforma específica ("quanto a Shopee me cobrou"), passe shop_ids das lojas dela (use listar_lojas antes).

get_quebra_de_taxas

REPUTAÇÃO E SAÚDE DA CONTA por loja (GET /api/analise/reputacao), coletada 1×/dia: Mercado Livre — nível/cor do termômetro, medalha MercadoLíder, reclamações, cancelamentos pelo vendedor e atraso no envio em % (com a cor de cada uma pelos limites do ML e a taxa REAL quando a loja está protegida), vendas no período avaliado; Shopee — nota geral (Poor…Excellent), cada métrica com o valor atual, a meta e se está fora dela, pontos de penalidade do trimestre e punições em curso. Traz a tendência de cada métrica contra a leitura de 30 dias ou mais (`comparado_com`; vazia com `tendencia_nota` enquanto não há 30 dias de histórico) e se o nível mudou. `lojas` só tem loja com leitura real; `sem_dado` traz, com o motivo, loja ainda não coletada, Shopee indisponível (permissão/IP) e TikTok, Shein e Amazon (a API não informa). Use para "como está minha reputação?", "corro risco de perder a medalha?", "quantos pontos de penalidade tenho?".

get_reputacao

Conciliação financeira por marketplace (Shopee, Mercado Livre, TikTok, Shein): quanto o vendedor RECEBEU no período, quanto ainda tem A RECEBER, retirado, estornado, saldo da carteira, valor em devolução e a previsão de recebimento quando a plataforma informa. Use para "quanto já caiu na minha conta", "quanto tenho a receber", "o dinheiro está batendo com as vendas?". Nem toda plataforma devolve todos os campos (os ausentes vêm null; `indisponivel` lista o que a plataforma não fornece). O "a receber" é saldo atual, não depende do período — leia `observacao`. A divergência pedido a pedido fica na tela Conciliação do Lucro ON.

get_conciliacao_resumo

Resumo de DEVOLUÇÕES do período, de todos os marketplaces: quantidades (no período, em aberto, em trânsito, para conferir), taxa de devolução sobre os pedidos do mesmo período, PERDA real (devoluções concluídas: frete reverso, frete flex, ads, produto não recuperado), reembolso pago/a reembolsar, motivos mais frequentes (top 10), motivos da perda (top 10), produtos que mais deram perda (top 10) e as FALHAS DE ENTREGA (pedido cancelado porque a entrega falhou: perda, desfecho do pacote, compensação) em `falhas_de_entrega`. Use para "quanto perco com devolução", "por que me devolvem", "meu pacote voltou?". Para a lista pedido a pedido e prazos, use listar_devolucoes. Em mais de uma loja a taxa é aproximada. No máximo 15 lojas por consulta: as demais voltam em `lojas_sem_resposta` — consulte-as em outra chamada.

get_resumo_devolucoes

Canal de AFILIADOS por plataforma no período (padrão: últimos 30 dias): pedidos com afiliado, receita deles, comissão total paga, % dos pedidos e % da receita vindos de afiliado, comissão média por pedido e comissão em % da receita afiliada. Use para "quanto pago de afiliado", "o canal de afiliados compensa?". É o que o marketplace descontou do repasse (Shopee/TikTok; no ML quando o pedido veio de afiliado). Não traz ranking de afiliados nem de produtos pelo canal.

get_resumo_afiliados

KPIs do período: faturamento, nº de pedidos, unidades, LUCRO LÍQUIDO e margem %. É a ferramenta padrão para "como foi meu mês", "quanto lucrei", "qual minha margem".

get_resumo_lucro

TENDÊNCIAS E MAIS VENDIDOS do Mercado Livre (GET /api/analise/tendencias), coletados toda segunda: para as categorias em que o vendedor mais fatura em 30 dias (e o Mercado Livre inteiro em `site`), as 50 buscas em alta do ML com o grupo — crescimento (posições 1–10, as que mais cresceram), desejadas (11–30) e populares (31–50) —, se o vendedor já tem anúncio ativo que cobre cada busca (`tem_anuncio`), as `oportunidades` (buscas em alta sem anúncio dele) e os até 20 mais vendidos da categoria. Mais vendido do tipo PRODUCT traz título e preço; ITEM e USER_PRODUCT vêm com `titulo` e `preco` null (o ML não informa o detalhe — sem dado, nunca 0). Categoria com `semana` null ainda não foi coletada; `aviso` explica quando nada foi coletado ainda. O ML informa só a posição, não o volume de buscas. Só Mercado Livre. Use para "o que está em alta na minha categoria?", "que produto novo eu deveria vender?". Devolve `{ site, categorias, aviso? }`.

get_tendencias_ml

USE ANTES DE RESPONDER sempre que o pedido do vendedor for de uma das áreas abaixo: devolve o MÉTODO do agente especialista (passos, ferramentas e formato da entrega, com cabeçalho e rodapé de identidade) — siga-o. Não responda essas perguntas só com as ferramentas de dados. Agentes (id: área, exemplo de pedido): - relatorio_mensal: Relatório Mensal (ex.: "Faça meu relatório mensal de setembro em PDF.") - comite: Comitê (ex.: "Faça o briefing de hoje: o que eu preciso resolver primeiro?") - financeiro: Financeiro (ex.: "Quais produtos estão me dando prejuízo este mês?") - ads: Ads (ex.: "Meus anúncios pagos estão dando retorno? Quais campanhas escalo e quais corto?") - bi_previsao: BI e Previsão (ex.: "Monte a curva ABC dos meus produtos por receita e por lucro.") - diretor_comercial: Diretor Comercial (ex.: "Estou batendo a meta do mês? Se não, quanto preciso vender por dia e de onde vem?") - estoque: Estoque e Full (ex.: "O que vai acabar nos próximos 15 dias? Monte a lista de compras.") - promocoes: Promoções (ex.: "Tem alguma promoção minha dando prejuízo no Mercado Livre?") - catalogo: Catálogo (ex.: "Quais produtos de catálogo eu perdi e dá para recuperar com lucro?") - logistica: Logística e Pós-venda (ex.: "Tem pedido para atrasar hoje? Monte a fila de expedição.") - anuncios: Anúncios (ex.: "Audite meus 15 anúncios mais vendidos e diga o que melhorar em cada um.") - afiliados: Afiliados (ex.: "Meu canal de afiliados dá retorno? Quanto vendi e quanto paguei de comissão?") - clientes: Clientes e Recompra (ex.: "Qual é a minha taxa de recompra e como eu aumento?") - auditoria_conta: Auditoria da Conta (ex.: "Minha conta está bem configurada? O que falta para os números ficarem certos?") - diretor_criativo: Diretor Criativo (ex.: "Monte o plano de fotos do meu anúncio mais vendido.") - calendario: Calendário Comercial (ex.: "Quais datas comerciais vêm aí e o que eu preciso preparar?") - fluxo_caixa: Fluxo de Caixa (ex.: "Vou ter dinheiro para pagar as contas nas próximas semanas?") - reputacao: Reputação (ex.: "Como está a reputação das minhas lojas?") - concorrencia: Concorrência e Preço (ex.: "Estou mais caro que a concorrência nos meus produtos que mais vendem?") - tendencias: Tendências e Oportunidades (ex.: "O que está em alta nas minhas categorias no Mercado Livre?")

usar_agente

Vendas DIÁRIAS (unidades e receita, com zero nos dias sem venda) de até 20 anúncios, nos últimos N dias (padrão 60, máx. 120). Use para tendência ("esse produto está subindo ou morrendo?"), sazonalidade e previsão de venda/estoque. Os item_ids vêm de get_produtos_lucro ou get_evolucao_diaria.

get_vendas_por_produto