Visão geral

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

A API de Forecast projeta a receita da organização nos próximos 12 meses. Ela parte do que aconteceu nos últimos 30 dias (volume e taxas de conversão do funil, recompra, investimento em mídia, receita e ticket médio) e devolve uma projeção: o funil atual com os ajustes que você simular. Sem ajustes, a projeção é o funil como está.

Perguntas que você consegue responder:

• Quanto faturamos por mês hoje e quanto faturamos nos últimos 12 meses?
• Se investirmos 20% a mais e melhorarmos a taxa de carrinho em 10%, quanto faturamos em 12 meses?
• Quanto a recompra pesa na receita e quanto ela soma se crescer 15%?
• Quanto muda a receita se o ticket médio subir 5%?
• Em quanto tempo uma mudança aparece na receita, se ela leva 4 meses para amadurecer?

Qual endpoint usarCopiar link da seção

Endpoints disponíveisCopiar link da seção

• getBase do forecast/v1/forecast/baselineA base mensal de onde o forecast parte, montada com as mesmas leituras dos dashboards: o funil de aquisição, o investimento em mídia e os…
• postSimular o forecast/v1/forecast/simulateProjeta os 12 meses a partir de baseline.windowStart sobre a mesma base (em cache) que GET /v1/forecast/baseline devolve: o funil atual…

Como a projeção é calculadaCopiar link da seção

A receita mensal soma duas partes, aquisição e recompra:

1. Volume da primeira etapa × fator de tráfego. O investimento acompanha o tráfego com custo por unidade constante, então escala de forma linear.
2. Esse volume × a taxa de conversão de cada etapa seguinte = pedidos da cadeia. Deles, só a parcela que não é recompra conta como pedidos de aquisição.
3. Pedidos de recompra = os pedidos de recompra dos últimos 30 dias (etapa RETENTION) × (1 + a % de retenção).
4. (Aquisição + recompra) × ticket médio = receita modelada.
5. Receita modelada × fator de medição = receita projetada.

O funil conta eventos somados entre ferramentas, não pedidos distintos, então funil × ticket raramente bate com o faturamento. O fator de medição (calibrationFactor) é a receita real ÷ a receita modelada (aquisição + recompra): ele faz as alavancas atuais reproduzirem a receita real dos últimos 30 dias. Sem receita real, o fator é null e o modelo roda sem ajuste.

Retenção (recompra)Copiar link da seção

A etapa RETENTION conta os pedidos de recompra da janela: pedidos de um cliente que já tinha comprado antes nos mesmos 30 dias (Shopify, Tray e VTEX; em planilhas, clientes com pedido repetido). Esses pedidos já estão dentro dos pedidos de DECISION, então a projeção não os conta duas vezes: a cadeia escala só a parcela de aquisição (pedidos de DECISION menos os de recompra) e a recompra é somada à parte, movida só pela % de retenção. A taxa da etapa (rate) é a parcela dos pedidos que são recompra (RETENTION ÷ DECISION), o mesmo % da etapa anterior que o funil mostra. RETENTION só aparece quando está habilitada no funil e a cadeia termina em DECISION; é sempre o último item de stages.

Funil de e-commerceCopiar link da seção

Para lojas online no padrão de e-commerce da V4MOS (modelo de negócio vendas_online, Google Analytics 4 e uma plataforma de e-commerce conectados, com as etapas Atenção, Interesse, Qualificação e Decisão configuradas), a cadeia segue a fórmula da loja:

Receita = Sessões × Taxa de carrinho × Taxa de checkout × Taxa de compra × Ticket médio

EXPOSURE (impressões) e COMMITMENT (checkout concluído) não entram nessa cadeia. A resposta informa qual fórmula foi usada em funnelKind (ecommerce ou generic). As demais organizações usam a cadeia genérica: todas as etapas configuradas até a última do lado do cliente e, depois, RETENTION, com role: null.

Pisos do setorCopiar link da seção

Cada etapa traz em floor o benchmark de mercado da sua conversão para o modelo de negócio da organização (businessModel: online_sales, inside_sales ou pos), a mesma referência que o diagnóstico de gargalo usa. É só uma referência para mostrar ao lado da etapa: a projeção nunca sobe uma conversão até o piso por conta própria. RETENTION não tem piso. O piso de uma etapa é o benchmark da transição que entra nela (Atenção, Interesse, Qualificação, Compromisso, Decisão). Quando a cadeia pula uma etapa, o piso multiplica os benchmarks que ela atravessa: no e-commerce, a taxa de compra (pedidos ÷ checkouts iniciados) tem piso Compromisso × Decisão. Sem modelo de negócio conhecido, businessModel e todo floor vêm null. O modelo vem do cadastro da organização quando a chamada traz o token do usuário; com x-client-id/x-client-secret, vem da configuração do funil da organização.

Ajustes do simuladorCopiar link da seção

Todo ajuste é uma variação % sobre o valor atual, que sai do atual no mês 1 e chega ao alvo no mês rampMonths + 1 em linha reta, e depois se mantém (rampMonths 0 aplica o alvo já no mês 1).

Toda variação % fica limitada ao intervalo de -50 a 200. Uma variação % numa etapa sem taxa mensurável (rate null ou 0) não tem efeito.

RespostaCopiar link da seção

result.projection traz os 12 meses (months) e os totais (totals): receita, receita de recompra (repurchaseRevenue), investimento, pedidos, pedidos de recompra (repurchaseOrders) e ROAS. result.baselineMonthlyRevenue é a receita mensal com as alavancas atuais (a receita real quando há calibração), o lado "atual" do faturamento.

Regras importantesCopiar link da seção

Status da baseCopiar link da seção

POST /v1/forecast/simulate devolve result: null sempre que data.status não for ready.

PeríodosCopiar link da seção

• A base usa os últimos 30 dias corridos até hoje, no horário de Brasília (America/Sao_Paulo).
• O faturamento de 12 meses (trailingRevenue) usa os últimos 365 dias. Quando essa leitura não está disponível, ele é os últimos 30 dias × 365/30, com annualized: true.
• O mês 1 da projeção é o mês atual (windowStart).
• As contagens são volume de eventos somado entre ferramentas, não pessoas distintas.

null significa "não definido", nunca zeroCopiar link da seção

monthlyRevenue, trailingRevenue, rate, sourceLabel, calibrationFactor e roas podem ser null. Mostre um traço no lugar do número.

ParâmetrosCopiar link da seção

Campos desconhecidos retornam 400.

ExemploCopiar link da seção

curl -X POST "https://data.v4mos.ai/v1/forecast/simulate" \
  -H "x-client-id: seu_client_id" \
  -H "x-client-secret: seu_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "organization_123",
    "inputs": {
      "investmentPct": 20,
      "ticketPct": 0,
      "stagePct": { "INTEREST": 10, "RETENTION": 15 },
      "rampMonths": 4
    }
  }'

AutenticaçãoCopiar link da seção

Todos os endpoints usam a URL base https://data.v4mos.ai e exigem os headers x-client-id e x-client-secret. Veja Autenticação.