Lucratividade: visão geral

O que esta análise respondeCopiar link da seção

A API de Lucratividade cruza o faturamento da sua loja com o investimento em mídia paga (Meta Ads e Google Ads) para mostrar se a aquisição e a retenção de clientes dão lucro. Todos os valores derivados de receita podem ser convertidos em margem de contribuição, de acordo com a margem configurada pela organização na plataforma V4MOS.AI.

Perguntas que você consegue responder:

• Quanto custa adquirir um cliente novo (CAC)? E quanto custa cada venda (CPV)?
• O valor que um cliente gera ao longo da vida (LTV) paga o custo de adquiri-lo (LTV/CAC)?
• Qual é o retorno do investimento em mídia (ROI) e em quantos meses ele se paga (payback)?
• Quantos clientes compram pela primeira vez e quantos voltam a comprar?
• Quanto da receita de cada safra de clientes volta nos meses seguintes?
• Quais produtos, canais, campanhas ou cupons de entrada trazem os clientes que mais recompram?
• Quanto o custo real das mercadorias (CMV) consome da receita?

Qual endpoint usarCopiar link da seção

Endpoints disponíveisCopiar link da seção

• getCards de resumo de lucratividade/v1/profitability/cardsRetorna os indicadores consolidados de lucratividade da organização no período: faturamento, investimento em mídia, pedidos, clientes,…
• getClientes novos vs. recorrentes ao longo do tempo/v1/profitability/new-vs-recurringRetorna uma série temporal com clientes novos (primeira compra no período do ponto) e recorrentes (já tinham comprado antes) que fizeram…
• getEvolução das métricas de lucratividade/v1/profitability/metrics-evolutionRetorna uma série mensal com CAC, LTV, CPV, LTV/CAC, receita, pedidos, investimento, clientes novos e o bloco de CMV real de cada mês.
• getEvolução diária do CMV/v1/profitability/cmv-evolutionRetorna uma série diária com receita, pedidos, ticket médio e o custo real das mercadorias vendidas (CMV) de cada dia, com os mesmos…
• getAnálise de safras de lucratividade/v1/profitability/cohortRetorna uma matriz de retenção por coorte: cada linha agrupa clientes pelo início da relação com a loja e cada coluna mostra quanto deles…

AutenticaçãoCopiar link da seção

Envie os headers x-client-id e x-client-secret em toda requisição, junto com o query parameter organizationId. Veja Autenticação.

Parâmetros comunsCopiar link da seção

Todos os endpoints usam a base URL https://data.v4mos.ai e aceitam os parâmetros abaixo.

O endpoint /cohort aceita ainda view, groupBy e breakBy (veja Coortes).

• Parâmetros desconhecidos na query resultam em 400.
• Valores fora da lista permitida em view, groupBy ou breakBy também resultam em 400.

ExemplosCopiar link da seção

# Indicadores consolidados de janeiro a março de 2025
curl "https://data.v4mos.ai/v1/profitability/cards?organizationId=SUA_ORG&startDate=2025-01-01&endDate=2025-03-31" \
  -H "x-client-id: SEU_CLIENT_ID" \
  -H "x-client-secret: SEU_CLIENT_SECRET"

# Evolução mensal das métricas em 2025
curl "https://data.v4mos.ai/v1/profitability/metrics-evolution?organizationId=SUA_ORG&startDate=2025-01-01&endDate=2025-12-31" \
  -H "x-client-id: SEU_CLIENT_ID" \
  -H "x-client-secret: SEU_CLIENT_SECRET"

# Retenção de receita por safra, com colunas trimestrais
curl "https://data.v4mos.ai/v1/profitability/cohort?organizationId=SUA_ORG&startDate=2024-01-01&endDate=2024-12-31&view=revenue&groupBy=quarter" \
  -H "x-client-id: SEU_CLIENT_ID" \
  -H "x-client-secret: SEU_CLIENT_SECRET"

MétricasCopiar link da seção

Valores monetários estão na moeda da loja, arredondados em 2 casas decimais. "× margem" significa multiplicar por marginPercent / 100 (veja Margem de contribuição).

Indicadores gerais (/cards, /metrics-evolution)Copiar link da seção

Indicadores por estratégia de campanha (/cards)Copiar link da seção

Dependem da classificação de campanhas feita na plataforma V4MOS.AI (aquisição, marca, monetização).

Custo das mercadorias (/cards, /metrics-evolution, /cmv-evolution)Copiar link da seção

Coortes (/cohort)Copiar link da seção

Regras importantesCopiar link da seção

Margem de contribuiçãoCopiar link da seção

A organização pode configurar na plataforma a margem de contribuição, isto é, o percentual da receita que sobra depois dos custos variáveis (produto, impostos, frete, meios de pagamento). Toda resposta que usa essa margem informa:

• marginPercent: o percentual aplicado (0–100).
• marginConfigured: true se a organização configurou uma margem; false se não configurou.
• marginCompleteness: complete, partial ou none. Indica se a margem foi montada item a item (gateway, imposto, frete e CMV) e se todos os itens estão resolvidos. none quando não há composição por item.
• marginItemStatus: status de cada item (synced = vem dos pedidos, configured = informado pelo usuário, pending = não configurado ou sem dados). null quando não há composição por item.

O percentual de retenção (pct) não muda com a margem, porque ela se cancela na divisão.

null não é 0Copiar link da seção

Muitos campos podem vir null. null significa "não foi possível calcular" (não há base, a divisão não está definida ou o dado não está disponível), enquanto 0 é um valor medido. Mostre um traço ou "N/D" para null e nunca o converta em 0.

Comparação com o período anteriorCopiar link da seção

Em /cards, quando startDate e endDate são enviados, a resposta inclui:

• previousPeriod: os mesmos indicadores calculados para o período imediatamente anterior, com o mesmo número de dias. Exemplo: para 01/03 a 31/03 (31 dias), o período anterior é 29/01 a 28/02.
• changes: a variação percentual de cada indicador: (atual − anterior) ÷ anterior × 100. Cada campo é null quando o valor anterior é 0 ou null.

Exceções: ltv e retentionLtv não usam o período anterior. Eles comparam a base de clientes adquirida até o fim do período selecionado com a base adquirida até o início dele. margin é a margem configurada, que não depende do período, então sua variação é sempre 0.

Sem startDate/endDate, previousPeriod e changes vêm null.

Granularidade das séries temporaisCopiar link da seção

Nas séries mensais, o campo month é o primeiro dia do mês (2025-03-01). Na série diária de /new-vs-recurring, o mesmo campo month traz o próprio dia.

CoortesCopiar link da seção

• view: logo (padrão) mede retenção por número de clientes; revenue mede por receita × margem.
• groupBy: month (padrão), quarter ou semester. Muda apenas o tamanho das colunas de período (M1, M2… viram T1, T2… ou S1, S2…). As linhas continuam sendo safras mensais. A coluna 0 é sempre o mês de entrada.
• breakBy: cohort (padrão, uma linha por safra mensal), product (uma linha por produto da primeira compra), origem (canal), campanha ou cupom. Nas quebras diferentes de cohort, cada cliente começa no seu próprio mês 0, independentemente do mês do calendário.

• Com breakBy=product, as linhas se sobrepõem: um cliente cujo primeiro pedido tem vários produtos entra em várias linhas. Não some as linhas (overlappingRows: true).
• Com breakBy=origem|campanha|cupom, cada cliente cai em exatamente uma linha, então as linhas podem ser somadas (overlappingRows: false). Clientes sem valor identificado entram na linha Sem origem, Sem campanha ou Sem cupom.
• A atribuição de clientes a campanhas e cupons depende das UTMs e cupons registrados nos pedidos. Exiba sempre o campo coverage junto dos números para indicar quanto da base foi atribuída.
• Com groupBy=quarter|semester e view=logo, as contagens somam clientes de cada mês. Um cliente ativo em vários meses do mesmo trimestre conta uma vez por mês, então o número é um teto de clientes distintos. As somas de receita são exatas.

CMV real e blendedContributionCopiar link da seção

Quando a plataforma de e-commerce informa o custo dos produtos, a API separa a receita em duas partes: com CMV real (revenueWithCmv) e sem CMV real (revenueWithoutCmv).

Se a margem foi configurada item a item e está completa (marginCompleteness = complete), cada parte desconta seus próprios custos (gateway, imposto, frete e CMV) em vez do percentual único.

contribution continua sendo sempre revenue × margem, mesmo quando há CMV real. Quando marginBasis vem null, os dados de custo não estavam disponíveis no momento da consulta, o que é diferente de no_basis. Em /cmv-evolution, essa situação é sinalizada por degraded: true com data: [].

Base de cálculo dos clientesCopiar link da seção

• newCustomers e recurringCustomers em /cards respeitam exatamente as datas pedidas.
• recurringCustomers (clientes que já tinham comprado antes do início do período) e recurringOrders (pedidos de quem já tinha comprado antes daquele pedido) medem coisas diferentes. Não divida um pelo outro.
• cac usa o investimento total em mídia. campaignCac usa só campanhas de aquisição, mas divide por todos os clientes novos. acquisitionCac restringe os dois lados às campanhas de aquisição. São três CACs diferentes, de propósito.
• As quatro fatias de investimento por estratégia (acquisitionInvestment + brandInvestment + monetizationInvestment + unclassifiedInvestment) somam o investimento das campanhas da organização, mas podem diferir ligeiramente de investment por diferença de atualização e porque ajustes de gasto zerados ou negativos entram nas fatias e não em investment.

ErrosCopiar link da seção