> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics de Vendas

> Descubra quais canais, campanhas e origens de tráfego geram mais vendas e receita. Tome decisões baseadas em dados para otimizar seus investimentos em marketing e aumentar o retorno sobre cada real gasto.

#### Escopo

```bash theme={null}
    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.

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

***

## Por que analisar canais de venda?

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

<CardGroup cols={2}>
  <Card title="Descobrir o que funciona" icon="magnifying-glass-dollar">
    Identifique quais canais (Google, Facebook, Instagram, orgânico etc.) trazem mais pedidos e receita líquida.
  </Card>

  <Card title="Otimizar investimentos" icon="sliders">
    Reduza gastos em canais com baixo retorno e aumente o budget nas origens que realmente convertem.
  </Card>

  <Card title="Comparar campanhas" icon="chart-column">
    Avalie o desempenho financeiro de campanhas específicas e descubra quais mensagens e criativos geram mais resultado.
  </Card>

  <Card title="Construir relatórios" icon="file-lines">
    Alimente dashboards e apresentações com dados consolidados de performance por origem de tráfego.
  </Card>
</CardGroup>

***

## Casos de uso

<AccordionGroup>
  <Accordion title="Avaliar retorno por canal" icon="arrow-right-arrow-left">
    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.
  </Accordion>

  <Accordion title="Medir performance de campanhas" icon="bullseye">
    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.
  </Accordion>

  <Accordion title="Analisar o impacto de mídia paga" icon="money-bill-trend-up">
    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.
  </Accordion>

  <Accordion title="Monitorar sazonalidades" icon="calendar-check">
    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.
  </Accordion>

  <Accordion title="Filtrar por produto ou oferta" icon="filter">
    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.
  </Accordion>
</AccordionGroup>

***

## Insights que podem ser obtidos

<AccordionGroup>
  <Accordion title="Canais mais lucrativos" icon="trophy">
    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.
  </Accordion>

  <Accordion title="Eficiência de descontos" icon="tags">
    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.
  </Accordion>

  <Accordion title="Custo de aquisição por origem" icon="piggy-bank">
    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.
  </Accordion>

  <Accordion title="Oportunidades escondidas" icon="lightbulb">
    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.
  </Accordion>
</AccordionGroup>

***

## 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

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

<AccordionGroup>
  <Accordion title="Filtros por Status" icon="flag">
    * `status` — Status do pedido (múltiplos valores separados por vírgula)

    <Tip>
      Para analisar apenas vendas concluídas, use `status=paid`.
    </Tip>

    **Exemplo:** `?status=paid` — Considera apenas pedidos pagos na agregação, ignorando pendentes, cancelados ou reembolsados.
  </Accordion>

  <Accordion title="Filtros por Relacionamentos" icon="link">
    * `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.
  </Accordion>

  <Accordion title="Filtros por Tipo" icon="tag">
    * `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).
  </Accordion>
</AccordionGroup>

***

## 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 |

<Info>
  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.
</Info>


## OpenAPI

````yaml GET /public_api/orders/analytics/
openapi: 3.0.3
info:
  title: Cakto API
  version: 1.0.0
  description: Documentação da API pública do Cakto.
servers:
  - url: https://api.cakto.com.br
    description: Cakto API
security: []
paths:
  /public_api/orders/analytics/:
    get:
      tags:
        - orders
      description: >-
        Public API for order sales analytics, inherits from
        OrderAnalyticsAPIView,

        customizes authentication and permission settings.
      operationId: orders_analytics
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderAnalyticsResponse'
              examples:
                Sucesso:
                  value:
                    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'
          description: >-
            Métricas financeiras agregadas por origem de tráfego, canal ou
            campanha.
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                ParâmetrosObrigatóriosAusentes:
                  value:
                    detail: start_date and end_date query parameters are required.
                  summary: Parâmetros obrigatórios ausentes
                GroupByInválido:
                  value:
                    detail: >-
                      Invalid group_by. Must be one of: utm_source, utm_medium,
                      utm_campaign.
                  summary: group_by inválido
          description: Parâmetros inválidos ou ausentes.
        '401':
          description: Request não autenticado devido à ausência ou invalidez do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                Token ausente ou inválido:
                  $ref: '#/components/examples/UnauthenticatedErrorExample'
      security:
        - OAuth Token: []
components:
  schemas:
    OrderAnalyticsResponse:
      type: object
      properties:
        group_by:
          type: string
          description: Dimensão utilizada para agrupar os resultados
        results:
          type: array
          items:
            $ref: '#/components/schemas/OrderAnalyticsResult'
          description: Lista de métricas agregadas por dimensão
        totals:
          $ref: '#/components/schemas/OrderAnalyticsTotals'
      required:
        - group_by
        - results
        - totals
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    OrderAnalyticsResult:
      type: object
      properties:
        utm_source:
          type: string
          description: Valor da dimensão de origem de tráfego
        utm_medium:
          type: string
          description: Valor da dimensão de mídia/canal
        utm_campaign:
          type: string
          description: Valor da dimensão de campanha
        order_count:
          type: integer
          description: Quantidade de pedidos
        gross_volume:
          type: string
          description: Valor bruto total dos pedidos
        net_value:
          type: string
          description: Valor líquido total dos pedidos
        total_discount:
          type: string
          description: Valor total de descontos aplicados
        total_fees:
          type: string
          description: Valor total de taxas e custos
      required:
        - gross_volume
        - net_value
        - order_count
        - total_discount
        - total_fees
    OrderAnalyticsTotals:
      type: object
      properties:
        order_count:
          type: integer
          description: Quantidade total de pedidos
        gross_volume:
          type: string
          description: Valor bruto total agregado
        net_value:
          type: string
          description: Valor líquido total agregado
        total_discount:
          type: string
          description: Valor total de descontos
        total_fees:
          type: string
          description: Valor total de taxas e custos
      required:
        - gross_volume
        - net_value
        - order_count
        - total_discount
        - total_fees
  examples:
    UnauthenticatedErrorExample:
      summary: Token ausente ou inválido
      description: Token ausente ou inválido
      value:
        detail: As credenciais de autenticação não foram fornecidas.
  securitySchemes:
    OAuth Token:
      type: http
      scheme: bearer
      in: header
      name: Authorization
      description: >-
        Token de autenticação do tipo `Bearer {access_token}`, onde
        `{access_token}` é o token obtido no fluxo de
        [autenticação](/authentication).

````