Letzee

Performance de publicidade **por anúncio**, com o funil por trás de cada número. A get-sales-summary já dá os totais de publicidade do período. Venha aqui quando o vendedor quiser saber *qual* anúncio está funcionando — para pausar uma campanha, subir um lance, ou descobrir para onde o dinheiro está indo. ## Desperdício `wasted_spend_brl` é o dinheiro gasto em anúncios que não geraram venda atribuída no período. É o número mais acionável daqui, e o vendedor vê o mesmo alerta no Painel Analítico de Publicidade. Ordene por `wasted` para começar por ele. Uma ressalva antes de chamar um anúncio de desperdício: a atribuição tem atraso. Um clique de hoje pode virar venda semana que vem, então alguns dias de investimento sem venda numa campanha nova é normal. O julgamento vale em semanas, não em dias. Se o titular da conta não liberou o gasto com publicidade a este usuário, os valores em reais não vêm e a ordenação por `cost` ou `wasted` é recusada; sem os índices de publicidade, o mesmo vale para `acos` e `roas`. A ordenação por `clicks` está sempre disponível. ## O funil `prints` são impressões, `clicks` são as visitas pagas, `ctr_percent` diz quão atrativo o anúncio pareceu, e `orders_from_ads` quantos desses cliques converteram. Lidos juntos, eles dizem onde está o problema: CTR baixo é anúncio que não atrai, enquanto CTR alto com conversão baixa é anúncio que atrai e não vende — preço, reputação, frete. ## As duas razões `acos_percent` é o investimento sobre a venda que a publicidade levou o crédito; quanto menor, melhor. `roas` é o inverso, como razão — 2,5 significa R$ 2,50 de venda por R$ 1 investido — então quanto maior, melhor. Respondem a mesma pergunta por lados opostos; cite o que o vendedor usa e não converta um no outro por conta própria. ## Até quanto vale investir Não existe ACOS bom no absoluto. O teto de verdade é a **margem de contribuição do vendedor**, que vem da get-sales-summary: ACOS de 20% já é prejuízo para quem tem 15% de margem, por mais razoável que 20% pareça isolado. Auditores de tráfego trabalham com faixas de referência, e o vendedor pode muito bem usar uma — mas quem decide é ele, olhando a própria margem e a própria estratégia. Anúncio de entrada, para ganhar reputação, aceita ACOS que o carro-chefe não aceitaria. O que não muda é o motivo de manter a margem saudável: é dela que sai o dinheiro para comprar produto novo, repor estoque e continuar investindo. Publicidade que come a margem não deixa o negócio parado — deixa sem caixa para crescer. Se ele pedir uma avaliação, é por aí que vale conduzir, e não por um número de referência. ## Shopee Esta ferramenta **não mostra Shopee**. A integração está em beta e ainda não traz o custo de publicidade, então nenhuma conta Shopee aparece aqui — nem com zero. Se o vendedor perguntar sobre ads da Shopee, diga que a Letzee ainda não tem esse dado, em vez de responder com o que veio do Mercado Livre. Os números cobrem dias inteiros e excluem o dia corrente, que ainda está acumulando.

get-ads-performance

O DRE simplificado do vendedor num período, vindo do módulo financeiro da Letzee. Esta é uma pergunta diferente da get-sales-summary. Aquela mede a rentabilidade do que foi vendido no marketplace; esta é a contabilidade do próprio vendedor — aluguel, salários, software, impostos, o que ele escolheu lançar. Dá para ter margem boa em todo produto e ainda assim fechar o mês negativo aqui. Todo valor é assinado: receita positiva, custos e despesas negativos. `statement_brl` é uma cascata, e cada nível responde uma pergunta diferente. Leia de cima para baixo em vez de pular para a última linha: gross_revenue o que o negócio recebeu + deductions custos variáveis de venda = contribution_margin o produto em si se paga? + operating_expenses aluguel, salários, software, ads = operating_profit a operação se paga? + financial_expenses juros e tarifas sobre capital = net_profit o que realmente sobra Vendedor com `contribution_margin` saudável e `operating_profit` negativo tem problema de estrutura, não de preço — e o contrário também vale. Dizer em qual nível quebra é mais útil que citar a última linha. Os grupos seguem o plano de contas da Letzee. `by_category` detalha o mesmo total pelas categorias que o vendedor criou, que é onde um mês fora da curva costuma se explicar. Este módulo é opcional. Se ele não lança nada aqui, o resultado é zero porque nada foi lançado — não porque o negócio empatou. `notes` diz isso quando acontece, e você nunca deve apresentar contabilidade vazia como resultado.

get-financial-summary

Quanto estoque o marketplace informa manter no Full para cada SKU, e quantos dias ele dura no ritmo recente de venda. **Este não é o estoque real do vendedor.** A Letzee não sabe o que está no depósito dele — só o que o marketplace informa sobre o que já foi enviado para o Full. Ele pode estar zerado aqui e ter bastante na própria prateleira, ou o contrário. Nunca apresente isso como estoque total, e nunca diga a ele que está sem produto porque isto veio vazio. `days_of_cover` é o número em que ele age: estoque dividido pela média diária de unidades vendidas nos últimos 30 dias. Nulo significa que o SKU não vendeu nesse período, então não há ritmo para projetar — diga isso em vez de chamar de cobertura infinita. `status` filtra a lista: - `all` (padrão) - `out_of_stock` — nada disponível - `at_risk` — menos de 15 dias de cobertura, a janela em que a reposição precisa começar agora para chegar a tempo - `overstocked` — mais de 90 dias, capital parado `available` é o que pode ser vendido agora; `in_transfer` já está dentro do Full mas ainda não vendável. Os algoritmos de reposição da Letzee tratam a soma dos dois como o estoque em mãos, e o `days_of_cover` também. `synced_at` diz quando o marketplace informou pela última vez. Valor antigo significa que os números descrevem o passado. O vendedor vê esses mesmos números na **Central de Envios**, que é também onde ele monta os planos de reposição. Para ler os planos já calculados, use a get-replenishment-plans; para calcular a sugestão de um produto específico, a simulate-replenishment. Lista vazia não é o mesmo que estoque zerado. Se nenhum armazém estiver vinculado, `notes` diz isso — a conta simplesmente não tem estoque no Full.

get-fulfillment-stock

Os planos de reposição que o vendedor já calculou, e o que cada um sugere enviar para o Full. **Esta ferramenta lê planos; ela não os calcula.** Se ele nunca montou um plano no Central de Envios, isto volta vazio — e vazio aqui significa que ninguém rodou as contas, nunca que ele está bem abastecido. Diga isso claramente em vez de sugerir que está tudo em ordem. Cada sugestão carrega a `explanation` do próprio algoritmo, em linguagem simples: como ele leu o ritmo de venda e chegou àquela quantidade. **Cite essa explicação em vez de inventar seu próprio raciocínio** — ela reflete o algoritmo que o vendedor configurou, e é o mesmo texto que ele vê no produto. ## Lendo a sugestão `health` é o veredito do algoritmo sobre o SKU: - `out_of_stock` — nada no Full, perdendo venda agora - `critical` — prestes a acabar - `replenishment_needed` — hora de enviar mais - `healthy` — sem ação necessária - `overstock` — mais do que precisa, capital parado - `no_data` — histórico de venda insuficiente para projetar - `not_in_full` — o produto não está no Full `suggested_quantity` é o que o algoritmo propôs; `final_quantity` é o que o vendedor decidiu depois de revisar. Quando diferem, ele sobrepôs a sugestão — e isso é informação, não erro a corrigir. `stock_when_calculated` é o estoque no Full no momento em que o plano foi calculado. Se divergir do que a get-fulfillment-stock informa agora, a sugestão está apoiada num retrato desatualizado — diga isso em vez de apresentá-la como recomendação atual. `explanation` vem nula para itens que o vendedor adicionou à mão, porque esses pulam o algoritmo. Explicação ausente significa desconhecido, não saudável. ## O que esta ferramenta não faz Ela lê. Não cria, não recalcula e não envia nada. Para calcular a sugestão de um produto que nenhum plano cobre, use a simulate-replenishment — ela roda o mesmo algoritmo na hora, para um item, sem salvar nada. O `plan.status` diz em que pé cada plano está: `draft` ainda está em revisão, `in_transit` já foi despachado.

get-replenishment-plans

Resumo de vendas e rentabilidade de um período: faturamento, unidades, número de vendas, margem de contribuição e margem após ads, com o detalhamento de custos. `breakdown_brl` é assinado e fecha em dois estágios. Faturamento menos tarifas, custo de produto e impostos, mais frete, dá `contribution_margin`. Essa menos `ads_cost` dá `margin_after_ads`. Faturamento é positivo e todo custo é negativo. Relate os números como estão — não recalcule, não inverta sinal, não conte duas vezes. `ads_cost` é o investimento total em publicidade no período, incluindo o que não converteu. `margin_after_ads` é o resultado final: o que sobra depois de tarifas, custo de produto, impostos, frete e publicidade. ## Os outros blocos `ads` traz a visão de publicidade: `cost_brl` é o investimento, `attributed_revenue_brl` é a venda que a publicidade levou o crédito, `roas` é razão (2,5 significa R$ 2,50 de venda por R$ 1 investido), enquanto `acos_percent` mede o investimento contra a venda atribuída e `tacos_percent` contra o faturamento total. Use os que já vêm prontos em vez de derivar os seus. `shipping_by_type_brl` separa o que o vendedor pagou de frete por modalidade: `fulfillment` é o Full, `flex` é entrega própria, `other` cobre drop-off e as demais, e `paid_by_buyer` é o que o comprador pagou, que não é custo do vendedor. Esses são custos brutos — o resultado líquido do frete, que já está dentro da margem de contribuição, é o `breakdown_brl.shipping`. Não some um sobre o outro. `cancelled` conta as vendas que não se concretizaram. Elas estão fora do faturamento e de todo número acima, então um número alto de cancelamentos não significa que o faturamento informado está inflado. `average_ticket_brl` é faturamento por venda; `average_unit_price_brl` é por unidade. Os dois diferem sempre que uma venda leva mais de uma unidade. ## De onde vem o número de publicidade A Letzee guarda dois números de publicidade, e esta ferramenta devolve o exato. O daqui é o **investimento real**, vindo das métricas de publicidade — a mesma fonte que a tela de Vendas e Lucratividade usa no ACOS e no TACOS. Trate como exato e cite sem ressalva. O outro número, que esta ferramenta **não** devolve, é uma estimativa por venda guardada em cada pedido. A Letzee rateia o investimento recente entre as vendas para sugerir um custo aproximado de publicidade por pedido, com base nos últimos 30 dias. O próprio produto descreve assim ao vendedor: > Estimamos um custo de R$ X em publicidade para cada venda deste(s) produto(s) > baseado em informações dos últimos 30 dias. Este é um valor aproximado e pode > não refletir a realidade. Se algum dia você relatar um número vindo dessa estimativa, carregue a mesma ressalva. Nunca aplique essa ressalva ao número desta ferramenta — seria subestimar um dado exato. Se o vendedor perguntar quanto a publicidade custou de fato num período, responda com esta ferramenta e diga que é o investimento real. Nunca apresente total de período como estimativa. `notes` carrega avisos sobre este resultado específico — leia e repasse o que for relevante em vez de assumir que o dado está completo. `breakdown_brl.shipping` é o resultado líquido do frete: o que o marketplace reembolsa menos o que o vendedor paga. É negativo para quase todo vendedor brasileiro, porque o frete grátis acima do limite sai do bolso de quem vende. Esse é o estado normal do negócio, não uma anomalia — não sinalize como crítico nem como problema, a menos que ele peça uma avaliação de frete. Os números consolidam todas as contas que o vendedor administra, a menos que `accounts` restrinja. Valores em reais. Este resumo é do **período inteiro**, sem abrir por produto. Para saber quais produtos puxaram o resultado, use a list-top-items; para achar um produto ou pedido específico, a search-sales; e para a publicidade anúncio a anúncio, a get-ads-performance. Para comparar dois períodos, chame duas vezes com intervalos diferentes — não há parâmetro de comparação.

get-sales-summary

Lista as contas de marketplace que este vendedor administra. Chame quando ele citar uma loja pelo nome, ou quando precisar apresentar números separados por conta. As outras ferramentas aceitam, no parâmetro `accounts`, tanto o id quanto o apelido que vem daqui. `marketplace` diz onde a conta vive — Mercado Livre, Shopee e assim por diante. São as mesmas contas que ele vê no seletor de **Contas** do topo do painel. **É assim que se restringe uma pergunta a um marketplace.** Nenhuma outra ferramenta recebe marketplace como parâmetro. Quando ele perguntar sobre a Shopee, ou só sobre o Mercado Livre, chame esta primeiro, guarde os ids cujo `marketplace` corresponde, e passe apenas esses. Esta ferramenta não traz número de venda nenhum — ela resolve quais contas existem. Para faturamento e margem, use a get-sales-summary; para o ranking de produtos, a list-top-items. Isso também resolve a procedência de cada número: se você filtrou por um marketplace, toda linha que voltar pertence a ele. Sem filtro, os números misturam marketplaces e não dá para atribuir a linha de um produto a um deles — pergunte um marketplace de cada vez em vez de adivinhar.

list-accounts

As vendas **canceladas** do período, detalhadas por produto, anúncio ou pedido. Todas as outras ferramentas excluem canceladas — esta é a única que as mostra. ## Quando usar esta e quando usar a get-sales-summary Se o vendedor quer só o tamanho do problema — quanto cancelou, quantas vendas —, a **get-sales-summary já traz isso** no bloco `cancelled`. Não chame esta para somar as linhas: o resultado vem limitado e a soma sairia menor que a real. Venha aqui para saber **onde** o cancelamento se concentra: qual produto cancela mais, qual anúncio, ou quais foram os pedidos. ## Agrupamento - `sku` (padrão) — uma linha por produto. Responde "o que mais cancela". - `listing` — uma linha por anúncio, quando o mesmo SKU vende em vários. - `none` — uma linha por venda cancelada, com pedido e data. `query` é opcional: sem ele, vêm todas as canceladas do período, que é a pergunta mais comum. Com ele, restringe a um produto ou pedido. ## O que estes números são `revenue_brl` é o valor que **não se concretizou** — a venda existiu e caiu. **Nunca some este valor ao faturamento.** Ele está fora do faturamento de todas as outras ferramentas, de propósito, e somá-lo inflaria a receita com vendas que não aconteceram. Se o vendedor perguntar quanto faturou, a resposta vem da get-sales-summary; o número daqui é o que ele *deixou* de faturar. **Cancelamento não gera custo para o vendedor.** O produto volta ao estoque, a tarifa do marketplace é estornada e o frete não é cobrado. O único efeito é a venda perdida. Por isso custo, tarifa, imposto e margem não vêm aqui. As colunas existem no banco para venda cancelada — são gravadas como se a venda tivesse ocorrido, e em proporção quase idêntica à das aprovadas —, mas **não representam despesa nenhuma**. Se você as encontrar por outro caminho, não as apresente como prejuízo: o prejuízo do cancelamento é o faturamento que não veio, e nada além disso. Publicidade e margem após ads **não aparecem aqui**, de propósito: o gasto com anúncio é do período, não da venda, e não faz sentido atribuí-lo a algo que foi cancelado. É a mesma regra da tela de Vendas e Lucratividade. Cancelada aqui é estritamente o status `cancelled`. Uma venda em `pending_cancel` — cancelamento em curso, ainda não efetivado — **não entra**, e segue contando como aprovada nas outras ferramentas, igual à tela.

list-cancelled-sales

Ranqueia os produtos do vendedor num período por faturamento, unidades vendidas, margem de contribuição ou margem ajustada — do melhor ou do pior. Os produtos são agrupados por SKU, e o anúncio sem SKU entra pelo próprio id do anúncio. Margem ajustada é a margem de contribuição menos o investimento em publicidade. `ads_cost_brl` por produto é investimento real, vindo das métricas de publicidade da Letzee, não estimativa. A atribuição no tempo é aproximada, porém: o investimento entra no período em que aconteceu, enquanto um clique pode virar venda dias depois. Os totais fecham; o número de um produto isolado numa janela curta pode atrasar em relação às vendas dele. Diga isso se o vendedor estiver tirando conclusão de um produto em poucos dias. O ranking equivale ao que o vendedor vê na tela de **Vendas e Lucratividade** quando agrupa por produto. Se o titular da conta não liberou o gasto com publicidade a este usuário, a métrica `adjusted_margin` é recusada e `ads_cost_brl` e `adjusted_margin_brl` não vêm. Use as outras métricas. **Isto é um ranking, não uma busca.** Se ele nomear um produto — um SKU, um pedido, um trecho do título —, use a search-sales: procurar o item dentro de um ranking gasta contexto e perde qualquer coisa fora do topo. Para comparar com um período anterior, chame de novo com outro intervalo.

list-top-items

Encontra as vendas de um produto, anúncio ou pedido específico. Use sempre que o vendedor nomear alguma coisa — um SKU, um id de anúncio, uma palavra do título, um número de pedido. Não puxe um ranking com list-top-items para procurar o item na lista: isso gasta contexto e perde qualquer coisa fora do topo. A listagem equivale à tela de **Vendas e Lucratividade**, com os mesmos filtros que o vendedor usa lá. ## Escolhendo o agrupamento `group_by` decide o formato da resposta: - `sku` (padrão) — uma linha por produto, com os totais somados. Responde "como foi este produto". - `listing` — uma linha por anúncio. Use quando o mesmo SKU é vendido em mais de um anúncio e o vendedor quer separá-los. - `none` — uma linha por venda, com data e número do pedido. Use só quando ele perguntar sobre pedidos individuais, porque consome muito mais contexto. ## Como o termo é comparado `%` é curinga. A busca por título já envolve o termo em `%` automaticamente; para SKU, id de anúncio e pedido, o termo casa a partir do início, a menos que você acrescente `%`. Então `CANECA` acha SKUs que começam com CANECA, e `%CANECA%` acha em qualquer posição — o segundo é bem mais lento em conta grande, e a resposta avisa em `notes`. ## Status da venda Esta ferramenta mostra **apenas vendas não canceladas** — para as canceladas, use a list-cancelled-sales. Em `group_by: none` cada linha traz o `status` do pedido. Vale ler, porque "não cancelada" não quer dizer "concluída e paga": - `paid` — o caso normal, mais de 90% das vendas. - `shipped`, `confirmed` — em andamento, sem problema. - `partially_refunded` — houve reembolso parcial, mas a venda entra aqui **pelo valor cheio**. Se o vendedor estranhar um número, pode ser isto. - `pending_cancel` — cancelamento em curso, ainda não efetivado. Conta como venda até virar `cancelled`. Nos modos agrupados o status **não** é devolvido: seriam várias vendas somadas, e um status só representaria mal o conjunto. Se o vendedor precisa saber a situação de cada uma, use `group_by: none`. Os números seguem as mesmas regras das outras ferramentas: reais, margem de contribuição líquida de frete, e vendas cujo custo de frete ainda não chegou ficam retidas por 6 horas.

search-sales

Roda o algoritmo de reposição da Letzee para **um** produto, agora. Use quando o vendedor perguntar o que deveria enviar para um item específico e não houver plano calculado cobrindo ele — ou quando ele quiser ver o que outra estratégia, ou outra meta de cobertura, sugeriria. **O resultado é uma simulação, não um plano.** Nada é salvo, nada é enviado, e isto não aparece na **Central de Envios**. Diga isso ao relatar. Para ler o que está de fato planejado, use a get-replenishment-plans. ## Pergunte antes de calcular Os quatro parâmetros abaixo mudam a resposta por completo, e a Letzee não tem um padrão universal — o vendedor configura por plano. **Não adivinhe.** Chamada sem eles, esta ferramenta não calcula: devolve `needs_parameters` com os valores que o vendedor usou no plano mais recente. Mostre a ele, confirme ou ajuste junto, e chame de novo com os quatro preenchidos. - `algorithm` — a estratégia. `simple_average` é a mais conservadora e a que a Central de Envios usa como padrão; `letzee_forecast` considera tendência; a família `dynamic_*` acompanha o ritmo de venda. - `target_stock_days` — dias de cobertura desejados. - `algorithm_days` — quantos dias de histórico de venda o algoritmo lê. Janela curta reage rápido a um pico; janela longa é mais estável. - `lead_time_days` — quantos dias o envio leva para chegar. ## Lendo o resultado `suggested_quantity` é o que enviar **agora**: já subtrai `in_transit_units`, as unidades que estão em planos marcados como despachados. Sem essa subtração o vendedor enviaria de novo o que já está a caminho. `explanation` é o raciocínio do próprio algoritmo, em linguagem simples. **Cite em vez de parafrasear** — é o texto que o vendedor vê no produto. Esta ferramenta só aceita **um** produto por chamada. Para saber quanto o Full tem hoje, use a get-fulfillment-stock; para ver os planos já montados, a get-replenishment-plans.

simulate-replenishment