Lucro ON

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

Gera o Relatório Mensal em PDF (capa, sumário executivo, DRE, evolução, custos, lojas, produtos, ads, estoque, devoluções, conciliação, meta, diagnóstico e plano de ação) e devolve um link de download válido por 7 dias. Os números saem do mesmo dossiê de montar_relatorio_mensal, montado no servidor; `analise` recebe o texto do diagnóstico e do plano de ação.

gerar_relatorio_pdf

Lista os agentes especialistas da Lucro ON (financeiro, ads, relatório mensal em PDF…) com o que cada um faz e exemplos de pedido.

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) com o shop_id que as demais ferramentas usam para filtrar por loja ou marketplace.

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". Suporta busca por 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

Monta o DOSSIÊ do Relatório Mensal (Agente Relatório Mensal): KPIs do mês e do mês anterior (kpis, kpis_anterior), DRE, evolução de 6 meses e diária, custos em % da receita, lojas, produtos (ABC, mais lucrativos, vilões, falsos campeões), anúncios pagos (ROAS × mínimo), estoque do Full, devoluções, conciliação e meta, mais diagnosticos (alertas com número), saude (0–100), sugestoes (ações por impacto em R$) e nao_disponivel. Serve ao relatório/fechamento do mês; é deste dossiê que gerar_relatorio_pdf tira os números do PDF.

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

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 dos últimos 30 dias, 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

Devolve o MÉTODO de um agente especialista da Lucro ON (financeiro, ads, relatório mensal em PDF…): os passos da análise, as ferramentas usadas e o formato da entrega, para pedidos de relatório, fechamento, plano ou análise de uma área.

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