Visão geral

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

A API de Aquisição mostra quanto a organização investe para conquistar clientes novos e o retorno desse investimento. Ela junta o investimento em mídia (Meta Ads e Google Ads), os clientes atribuídos a cada canal e campanha e a receita gerada por eles, e entrega métricas prontas como CAC, LTV, ROI e payback. Todas as respostas usam o mesmo período, e os cards trazem a comparação com o período anterior.

Perguntas que você consegue responder:

• Quanto investimos no período e quantos clientes novos isso trouxe?
• Qual é o CAC e em quantos meses o investimento se paga (payback)?
• Qual canal e qual campanha têm o melhor custo e o melhor retorno?
• Como os clientes avançam pelas etapas do funil?
• Como está a mídia paga (impressões, cliques, leads, custo por lead) e qual público e região ela alcança?

Qual endpoint usarCopiar link da seção

Observações por endpointCopiar link da seção

• /summary e /channels: cada métrica vem como { value, changePct }, com a variação percentual contra o período anterior. O canal Orgânico não aparece em /channels, porque não tem investimento. A lista de canais não vem ordenada.
• /funnel: retorna só as etapas de funil que a organização configurou na plataforma V4MOS.AI. A contagem de cada etapa é volume de eventos (impressões, cliques, leads, pedidos), somado entre as ferramentas conectadas. Não é número de pessoas distintas. As etapas EXPOSURE e ATTENTION medem mídia (scale: "media") e as demais medem eventos do cliente (scale: "customer"). A passagem de um grupo para o outro é uma troca de unidade, não uma taxa de conversão. Sem etapas configuradas, a resposta é stages: [].
• /new-customers-over-time inclui o canal Orgânico. /unit-economics-over-time traz só canais pagos. Nas duas séries, dias sem dados não aparecem: preencha esses dias com zero no seu gráfico (clientes novos) ou deixe-os em branco (razões).
• /campaigns: árvore canal → campanha → conjunto de anúncios → anúncio, sempre com dois grupos: acquisition (campanhas marcadas como aquisição) e other (todas as demais). As métricas de mídia existem em todos os níveis. As métricas de negócio (clientes, CAC, LTV, ROI, payback, leads) só existem nos níveis de canal e campanha, porque a atribuição de clientes vai até a campanha.
• /paid-media: só Meta Ads e Google Ads. Os leads somam os leads do CRM atribuídos a um canal pago por UTM e os leads registrados pelas plataformas (Meta e Google) que o funil da organização conta na etapa de Interesse. A série daily tem um ponto por dia, sem lacunas, e os cards são a soma dela.
• /paid-media/audience: só Meta Ads. Os leads daqui são o evento lead do Meta e não batem com os de /paid-media, que também soma CRM e Google.

Endpoints disponíveisCopiar link da seção

• getCards de resumo de aquisição/v1/acquisition/summaryNúmeros consolidados de aquisição da organização no período: investimento, novos clientes, CAC, LTV, ROI e payback.
• getCards de aquisição por canal/v1/acquisition/channelsUm card por canal pago, como Meta Ads e Google Ads, com investimento, novos clientes, CAC, LTV, LTV/CAC, ROI e payback.
• getFunil de fluxo de ganho/v1/acquisition/funnelVolume de cada etapa do funil configurado pela organização, da exposição à retenção, com a proporção entre as etapas.
• getNovos clientes ao longo do tempo/v1/acquisition/new-customers-over-timeSérie diária de novos clientes, com uma aba por canal, incluindo o canal Orgânico.
• getUnit economics ao longo do tempo/v1/acquisition/unit-economics-over-timeSérie diária de CAC, LTV e custo por venda (CPV), com uma aba por canal pago.
• getTabela de campanhas/v1/acquisition/campaignsTabela hierárquica canal → campanha → conjunto de anúncios → anúncio, com métricas de mídia e de negócio, separada em dois grupos.
• getVisão geral da mídia paga/v1/acquisition/paid-mediaVisão geral da mídia paga (Meta Ads e Google Ads): investimento, impressões, alcance, cliques, leads e custo por lead, com série diária.
• getPúblico da mídia paga/v1/acquisition/paid-media/audiencePúblico e região da mídia do Meta Ads: investimento, leads e custo por lead por gênero e faixa etária, e alcance e custo por região.

MétricasCopiar link da seção

As razões são arredondadas em 2 casas decimais. O investimento não é arredondado.

Regras importantesCopiar link da seção

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

Quando uma razão não pode ser calculada (por exemplo, CAC sem nenhum cliente novo, ou CPC sem nenhum clique), o campo vem null. Um 0 é sempre um valor medido de verdade.

Campos que podem vir null: cac, ltv, avgLtv, acquisitionAvgLtv, ltvCacRatio, acquisitionLtvCacRatio, roi, acquisitionRoi, paybackMonths, cpv, cpm, ctr, cpc, cpl, leads, reach e costPerThousandReach. Já changePct vem null quando a comparação não é possível (valor anterior zero ou ausente), e em paybackMonths ele é sempre null. Para paybackMonths, 0 e null são resultados opostos: 0 significa que o investimento se pagou no próprio mês de aquisição; null significa que nenhum grupo de clientes atingiu o payback ou que o custo deles é desconhecido.

Exceção no funil: em /funnel, pctOfFirst e pctOfPrevious vêm 0 (e não null) quando a etapa de referência tem contagem zero.

O CAC considera só campanhas marcadas como aquisiçãoCopiar link da seção

Na plataforma V4MOS.AI, cada organização marca quais campanhas são de aquisição (conquistar clientes novos). As outras campanhas são de marca, de monetização ou ficam sem classificação. O CAC desta API usa só as campanhas marcadas como aquisição, nos dois lados da conta: cac = acquisitionInvestment ÷ acquisitionNewCustomers.

Por isso as respostas trazem dois conjuntos de números:

O campo hasAcquisitionClassification (em /summary e /channels) indica se a organização já marcou alguma campanha como aquisição, em qualquer data. Quando é false, cac, ltvCacRatio, paybackMonths e as métricas acquisition* vêm null e o grupo acquisition de /campaigns vem vazio. Isso não é falta de dados no período: falta marcar as campanhas de aquisição na plataforma. Os totais amplos continuam com valores reais.

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

A margem de contribuição configurada pela organização na plataforma (100% quando não configurada) é aplicada em roi, acquisitionRoi, paybackMonths e acquisitionAvgLtv (e portanto em acquisitionLtvCacRatio). Os campos ltv e avgLtv são brutos, sem margem. As respostas de /summary, /channels, /unit-economics-over-time e /campaigns informam o estado da margem em marginConfigured (se foi configurada), marginCompleteness (complete, partial ou none) e marginItemStatus (situação de cada custo: gateway, imposto, frete e custo da mercadoria).

Período e comparaçãoCopiar link da seção

• A janela de comparação é sempre o período de mesmo tamanho imediatamente anterior ao selecionado. Exemplo: uma seleção de 12 dias é comparada com os 12 dias que vêm logo antes dela.
• As séries temporais são sempre diárias, qualquer que seja o tamanho do período. Um período de 365 dias retorna cerca de 365 pontos por canal; agrupe em semanas ou meses no seu lado, se precisar.
• "Hoje" é o dia de calendário em UTC. Quando o período inclui hoje, esse último dia ainda está parcial, porque os dados do dia continuam chegando.

Flags de disponibilidade de dadosCopiar link da seção

Tabela de campanhas: limite de linhasCopiar link da seção

/campaigns retorna no máximo 5.000 linhas somando os dois grupos e todos os níveis, sem paginação. Se o limite for atingido, os níveis mais profundos são removidos primeiro (anúncios, depois conjuntos de anúncios). Canais e campanhas nunca são removidos. O objeto truncation informa o que aconteceu: truncated, returnedRows, totalRows e droppedLevels. Use-o para avisar "exibindo N de M linhas".

Use campaignId para identificar uma campanha. O id de cada linha é único na resposta e serve como chave, mas para canais e linhas sem identificador na plataforma ele é gerado pela API e não deve ser interpretado.

Parâmetros comunsCopiar link da seção

Regras de datas:

• Envie startDate e endDate juntos. Enviar só um deles retorna 400.
• Use só a data (2026-03-11). Data com hora (2026-03-11T00:00:00Z) ou data inexistente (2026-02-30) retorna 400.
• startDate deve ser menor ou igual a endDate, nenhuma das datas pode estar no futuro (UTC) e o intervalo pode ter no máximo 366 dias (365 dias entre as datas).
• Sem datas e sem period, a API usa os últimos 30 dias (30d).

ExemploCopiar link da seção

curl -X GET "https://data.v4mos.ai/v1/acquisition/summary?organizationId=organization_123&startDate=2026-03-01&endDate=2026-03-31" \
  -H "x-client-id: seu_client_id" \
  -H "x-client-secret: seu_client_secret"

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.