Analytics de Vendas

curl --request GET \
  --url https://api.cakto.com.br/public_api/orders/analytics/ \
  --header 'Authorization: Bearer <token>'

{
  "group_by": "utm_source",
  "results": [
    {
      "utm_source": "google",
      "order_count": 42,
      "gross_volume": "12500.00",
      "net_value": "10625.00",
      "total_discount": "625.00",
      "total_fees": "500.00"
    },
    {
      "utm_source": "facebook",
      "order_count": 18,
      "gross_volume": "5400.00",
      "net_value": "4590.00",
      "total_discount": "0",
      "total_fees": "270.00"
    },
    {
      "utm_source": "(unclassified)",
      "order_count": 10,
      "gross_volume": "3000.00",
      "net_value": "2550.00",
      "total_discount": "0",
      "total_fees": "120.00"
    }
  ],
  "totals": {
    "order_count": 70,
    "gross_volume": "20900.00",
    "net_value": "17765.00",
    "total_discount": "625.00",
    "total_fees": "890.00"
  }
}

GET

public_api

orders

analytics

Analytics de Vendas

curl --request GET \
  --url https://api.cakto.com.br/public_api/orders/analytics/ \
  --header 'Authorization: Bearer <token>'

{
  "group_by": "utm_source",
  "results": [
    {
      "utm_source": "google",
      "order_count": 42,
      "gross_volume": "12500.00",
      "net_value": "10625.00",
      "total_discount": "625.00",
      "total_fees": "500.00"
    },
    {
      "utm_source": "facebook",
      "order_count": 18,
      "gross_volume": "5400.00",
      "net_value": "4590.00",
      "total_discount": "0",
      "total_fees": "270.00"
    },
    {
      "utm_source": "(unclassified)",
      "order_count": 10,
      "gross_volume": "3000.00",
      "net_value": "2550.00",
      "total_discount": "0",
      "total_fees": "120.00"
    }
  ],
  "totals": {
    "order_count": 70,
    "gross_volume": "20900.00",
    "net_value": "17765.00",
    "total_discount": "625.00",
    "total_fees": "890.00"
  }
}

Escopo

    read orders

O que é este endpoint?

Este endpoint mostra o desempenho das suas vendas agrupado por canal de aquisição, campanha ou origem de tráfego. Em vez de olhar pedido por pedido, você recebe métricas financeiras agregadas que revelam onde seu dinheiro de marketing está rendendo mais.

Valores financeiros são retornados como strings para preservar a precisão decimal. Pedidos sem UTM preenchido aparecem agrupados como "(unclassified)".

Por que analisar canais de venda?

Essa visão permite direcionar investimentos, cortar desperdícios e escalar o que funciona.

Descobrir o que funciona

Identifique quais canais (Google, Facebook, Instagram, orgânico etc.) trazem mais pedidos e receita líquida.

Otimizar investimentos

Reduza gastos em canais com baixo retorno e aumente o budget nas origens que realmente convertem.

Comparar campanhas

Avalie o desempenho financeiro de campanhas específicas e descubra quais mensagens e criativos geram mais resultado.

Construir relatórios

Alimente dashboards e apresentações com dados consolidados de performance por origem de tráfego.

Casos de uso

Avaliar retorno por canal

Descubra se o tráfego pago do Facebook está gerando mais receita líquida do que o tráfego orgânico do Google. Use o parâmetro group_by=utm_source para comparar canais lado a lado.

Medir performance de campanhas

Lançou três campanhas diferentes este mês? Use group_by=utm_campaign para ver qual delas trouxe mais pedidos, maior ticket médio e melhor margem líquida.

Analisar o impacto de mídia paga

Meça o resultado real dos seus anúncios. Filtre por período (start_date e end_date) e compare semanas com e sem investimento em tráfego pago para calcular o ROI.

Monitorar sazonalidades

Acompanhe semanal ou mensalmente como cada canal performa. Identifique picos de vendas em datas específicas (Black Friday, lançamentos etc.) e replique estratégias vencedoras.

Filtrar por produto ou oferta

Quer saber se o curso novo está vendendo mais pelo Instagram ou pelo YouTube? Filtre por product ou offer e agrupe por utm_source para descobrir.

Insights que podem ser obtidos

Canais mais lucrativos

O volume de pedidos não conta toda a história. Um canal com menos vendas pode ter ticket médio maior e menos taxas, resultando em maior receita líquida. Analise gross_volume, net_value e total_fees juntos.

Eficiência de descontos

O campo total_discount mostra quanto você está abrindo mão em cada canal. Se um canal depende muito de cupons para vender, a receita líquida pode ser menor do que parece.

Custo de aquisição por origem

Combine net_value e order_count com seus gastos em anúncios para calcular o CAC (Custo de Aquisição de Cliente) de cada canal. Isso revela onde cada real investido rende mais.

Oportunidades escondidas

Canais classificados como "(unclassified)" indicam vendas sem UTM. Isso pode ser tráfego direto, indicação ou campanhas mal configuradas. Corrigir o rastreamento pode revelar de onde vem sua melhor conversão.

Dimensão de análise

Use o parâmetro group_by para segmentar e comparar resultados. Escolha a dimensão que faz mais sentido para a sua pergunta de negócio:

Dimensão	O que permite analisar	Quando usar
`utm_source`	Compare vendas entre Google, Facebook, Instagram, orgânico etc.	Para entender qual plataforma traz mais resultado.
`utm_medium`	Analise performance por tipo de mídia (cpc, email, social, organic etc).	Para entender qual formato de tráfego funciona melhor.
`utm_campaign`	Descubra quais campanhas nomeadas geram mais receita.	Para comparar campanhas específicas uma a uma.

Exemplo: ?start_date=01-01-2025&end_date=31-12-2025&group_by=utm_medium Retorna a performance financeira agrupada por tipo de mídia (cpc, email, social etc) durante todo o ano de 2025.

Filtros adicionais

Filtros podem ser combinados com a dimensão de análise para refinar os resultados. Quanto mais específico, mais acionável é o insight.

Filtros por Status

status — Status do pedido (múltiplos valores separados por vírgula)

Para analisar apenas vendas concluídas, use status=paid.

Exemplo: ?status=paid — Considera apenas pedidos pagos na agregação, ignorando pendentes, cancelados ou reembolsados.

Filtros por Relacionamentos

product — Id ou nome do produto
products — Id dos produtos (múltiplos valores suportados)
offer — Id da oferta
paymentMethod — Método de pagamento

Exemplo: ?product=123&status=paid — Vendas pagas de um produto específico, útil para entender a performance de um lançamento.

Filtros por Tipo

offer_type — Tipo da oferta (main, upsell, downsell, orderbump)
type — Tipo do produto (unique, subscription)
installments — Número de parcelas

Exemplo: ?offer_type=upsell&group_by=utm_source — Descubra qual canal traz mais vendas adicionais (upsell).

Como interpretar a resposta

A resposta contém três elementos principais:

Campo	O que representa
`group_by`	A dimensão que você escolheu para agrupar (ex: `utm_source`)
`results`	Lista com as métricas de cada valor encontrado (ex: google, facebook, unclassified)
`totals`	Soma de todas as linhas, representando o total do período filtrado

Métricas de cada linha

Métrica	Descrição	Como usar
`order_count`	Quantidade de pedidos	Volume de vendas por canal
`gross_volume`	Valor bruto total	Receita antes de descontos e taxas
`net_value`	Valor líquido total	O que realmente entra no caixa
`total_discount`	Descontos aplicados	Quanto você abriu mão para vender
`total_fees`	Taxas e custos	Quanto foi gasto em taxas de pagamento

A diferença entre gross_volume e net_value mostra o impacto real dos descontos e taxas. Um canal com alto gross_volume mas baixo net_value pode estar mascarando uma margem fraca.

Authorizations

Authorization

string

header

required

Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.

Query Parameters

start_date

string

required

Data inicial do período (formato DD-MM-YYYY).

end_date

string

required

Data final do período (formato DD-MM-YYYY).

group_by

enum<string>

default:utm_source

Dimensão de análise. Valores possíveis são utm_source, utm_medium, utm_campaign. Padrão é utm_source.

Available options:

utm_source,

utm_medium,

utm_campaign

status

string

Filtra por status do pedido (múltiplos valores separados por vírgula).

product

string

Filtra por Id ou nome do produto.

offer

string

Filtra por Id da oferta.

paymentMethod

string

Filtra por método de pagamento.

offer_type

string

Filtra por tipo da oferta (main, upsell, downsell, orderbump).

type

string

Filtra por tipo do produto (unique, subscription).

Response

Métricas financeiras agregadas por origem de tráfego, canal ou campanha.

group_by

string

required

Dimensão utilizada para agrupar os resultados

results

object[]

required

Lista de métricas agregadas por dimensão

Show child attributes

totals

object

required

Show child attributes

Reenviar Acesso Listar Webhooks

​Escopo

​O que é este endpoint?

​Por que analisar canais de venda?

Descobrir o que funciona

Otimizar investimentos

Comparar campanhas

Construir relatórios

​Casos de uso

​Insights que podem ser obtidos

​Dimensão de análise

​Filtros adicionais

​Como interpretar a resposta

​Métricas de cada linha

Authorizations

Query Parameters

Response

Escopo

O que é este endpoint?

Por que analisar canais de venda?

Casos de uso

Insights que podem ser obtidos

Dimensão de análise

Filtros adicionais

Como interpretar a resposta

Métricas de cada linha