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

# Campanhas de todos os produtos

> Vendas por plataforma, campanha, conjunto e anúncio, com o gasto do Meta Ads quando conectado.

#### Escopo

```bash theme={null}
    read analytics
```

Com `metaAds.connected: true`, as campanhas do Meta ganham o bloco `ads` (gasto, impressões, cliques, ROAS, CPA, lucro) e o `financial` ganha gasto, lucro, ROI e margem. Sem a conexão, a resposta é a mesma, sem esses campos. Veja [como a campanha casa com o Meta](https://docs.cakto.com.br/api-reference/analytics/overview.md#campanhas-e-meta-ads).


## OpenAPI

````yaml GET /public_api/analytics/campaigns/
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/analytics/campaigns/:
    get:
      tags:
        - analytics
      summary: Campanhas de todos os produtos
      description: >-
        Vendas por plataforma, campanha, conjunto e anúncio de todos os
        produtos, lidas das UTMs, com o resumo financeiro da conta
        (`financial`). Com o Meta Ads conectado (`metaAds.connected`), cada
        campanha, conjunto e anúncio do Meta ganha o bloco `ads` (gasto,
        impressões, cliques, ROAS, CPA e lucro), e o resumo ganha gasto, lucro,
        ROI e margem. Sem a conexão, a resposta é a mesma, sem esses campos.
      operationId: analytics_campaigns
      parameters:
        - in: query
          name: startDate
          schema:
            type: string
            format: date
          description: >-
            Primeiro dia do período (`AAAA-MM-DD`, horário de Brasília). Sem
            ele, o período termina em `endDate` e tem 30 dias.
        - in: query
          name: endDate
          schema:
            type: string
            format: date
          description: >-
            Último dia do período, incluído (`AAAA-MM-DD`). Sem ele, hoje. O
            período vai até 12 meses (366 dias).
        - in: query
          name: platform
          schema:
            type: string
            enum:
              - meta
              - google
              - tiktok
              - kwai
              - whatsapp
              - email
              - organico
              - outras
              - sem_utm
          description: >-
            Só as vendas de uma plataforma, pela `utm_source` (ou pelo id de
            clique do anúncio). `whatsapp`, `email` e `organico` são origens
            marcadas à mão; `outras`, o resto que não é rede de anúncio;
            `sem_utm`, venda sem origem.
        - in: query
          name: adAccount
          schema:
            type: string
          description: >-
            Só o gasto de uma conta de anúncio do Meta (`act_...`, de
            `metaAds.adAccounts`). Conta que não é da sua conexão é ignorada.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsCampaigns'
              examples:
                Com o Meta conectado:
                  $ref: '#/components/examples/AnalyticsCampaignsWithMetaExample'
                Sem o Meta conectado:
                  $ref: '#/components/examples/AnalyticsCampaignsWithoutMetaExample'
          description: ''
        '400':
          description: Período ou plataforma inválidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsError'
              examples:
                Data inválida:
                  value:
                    detail: Datas inválidas. Use YYYY-MM-DD.
                Período invertido:
                  value:
                    detail: startDate maior que endDate.
                Acima de 12 meses:
                  value:
                    detail: Intervalo máximo de 366 dias.
                Plataforma inválida:
                  value:
                    detail: Plataforma inválida.
        '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'
        '403':
          description: >-
            O token não tem o escopo `analytics`, ou o Cakto Analytics não está
            liberado para a conta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsError'
              examples:
                Analytics não liberado:
                  value:
                    detail: Cakto Analytics não liberado para esta conta.
        '429':
          description: >-
            Passou do limite de 60 consultas por minuto. Espere os segundos do
            cabeçalho `Retry-After`.
        '503':
          description: A consulta passou do tempo. Tente de novo ou peça um período menor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsError'
              examples:
                Demorou demais:
                  value:
                    detail: >-
                      A visão geral demorou demais. Tente de novo ou um período
                      menor.
      security:
        - OAuth Token: []
components:
  schemas:
    AnalyticsCampaigns:
      type: object
      properties:
        period:
          type: object
          properties:
            startDate:
              type: string
              format: date
            endDate:
              type: string
              format: date
        platform:
          type: string
          nullable: true
        hasVisits:
          type: boolean
          description: '`false` com filtro de plataforma: aí as campanhas saem sem `visits`.'
        summary:
          type: object
          properties:
            visits:
              type: integer
            orders:
              type: integer
            paid:
              type: integer
            amount:
              type: number
            paidWithUtm:
              type: integer
            amountWithUtm:
              type: number
            campaignCount:
              type: integer
            adsSpend:
              type: number
              description: Só com o Meta conectado e gasto no período.
            adsRoas:
              type: number
              nullable: true
              description: Só com o Meta conectado e gasto no período.
        platforms:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                enum:
                  - meta
                  - google
                  - tiktok
                  - kwai
                  - whatsapp
                  - email
                  - organico
                  - outras
                  - sem_utm
              orders:
                type: integer
              paid:
                type: integer
              amount:
                type: number
              visits:
                type: integer
        campaigns:
          type: array
          description: Até 20 campanhas, e o resto em `outros`.
          items:
            $ref: '#/components/schemas/AnalyticsCampaignNode'
        placements:
          type: array
          description: Posicionamentos (`utm_term`), os 10 que mais venderam.
          items:
            type: object
            properties:
              value:
                type: string
              orders:
                type: integer
              paid:
                type: integer
              amount:
                type: number
        financial:
          $ref: '#/components/schemas/AnalyticsFinancial'
        metaAds:
          $ref: '#/components/schemas/AnalyticsMetaAds'
    AnalyticsError:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string
          description: >-
            `PRO_REQUIRED` quando a rota é do Cakto Analytics Pro e a conta não
            o tem.
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    AnalyticsCampaignNode:
      type: object
      description: >-
        Uma campanha, conjunto ou anúncio. A árvore vem de `utm_campaign` →
        `utm_medium` → `utm_content`, no formato `nome|id` que o gerenciador de
        anúncios grava.
      properties:
        key:
          type: string
        name:
          type: string
        id:
          type: string
          nullable: true
          description: Id da campanha, conjunto ou anúncio na rede, quando a UTM o traz.
        sources:
          type: array
          items:
            type: string
        platform:
          type: string
          nullable: true
          description: >-
            Plataforma que mais trouxe pedidos para este nó (a mesma lista do
            filtro `platform`). Nula em campanha só com acesso e no agrupado
            `outros`.
        visits:
          type: integer
          description: Acessos ao checkout. Só nas campanhas e sem filtro de plataforma.
        orders:
          type: integer
        paid:
          type: integer
        amount:
          type: number
        pixPending:
          type: integer
        refunded:
          type: integer
        ads:
          $ref: '#/components/schemas/AnalyticsAdsMetrics'
        children:
          type: array
          description: >-
            Conjuntos da campanha, ou anúncios do conjunto. Até 10 por nível, e
            o resto em `outros`.
          items:
            type: object
            additionalProperties: true
    AnalyticsFinancial:
      type: object
      nullable: true
      description: >-
        O resumo financeiro do período. Com o Meta conectado entram o gasto e o
        que depende dele; sem a conexão, esses campos vêm `null`. `null` inteiro
        quando o cálculo passa do tempo.
      properties:
        netAmount:
          type: number
          description: O que você recebeu nas vendas aprovadas, já sem as taxas.
        grossAmount:
          type: number
        adsSpend:
          type: number
          nullable: true
        roas:
          type: number
          nullable: true
          description: Líquido sobre o gasto.
        profit:
          type: number
          nullable: true
          description: Líquido menos o gasto e o imposto.
        roi:
          type: number
          nullable: true
        margin:
          type: number
          nullable: true
        pendingAmount:
          type: number
          description: Pix gerado e ainda não pago.
        refundAmount:
          type: number
        refundRate:
          type: number
          nullable: true
        chargebackRate:
          type: number
          nullable: true
        arpu:
          type: number
          nullable: true
          description: Líquido por venda.
        taxRate:
          type: number
          description: A alíquota de imposto configurada no painel do Analytics.
        taxAmount:
          type: number
        paidCount:
          type: integer
        paymentMethods:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              count:
                type: integer
              amount:
                type: number
              share:
                type: number
                nullable: true
    AnalyticsMetaAds:
      type: object
      description: >-
        Indicador da conexão com o Meta Ads. Vem em toda resposta de Analytics,
        com ou sem conexão.
      properties:
        connected:
          type: boolean
          description: >-
            `true` quando a conta tem o Meta Ads conectado e o custo dos
            anúncios entra nas campanhas. Com `false`, os números de venda vêm
            inteiros e só o custo fica de fora.
        status:
          type: string
          nullable: true
          enum:
            - active
            - expired
            - null
          description: >-
            `active`: a leitura do gasto está em dia. `expired`: o Meta recusou
            o token (venceu, senha trocada, permissão removida) e é preciso
            reconectar no painel; o gasto já lido continua valendo até
            `lastSyncedAt`. `null` sem conexão.
        adAccounts:
          type: array
          description: Contas de anúncio lidas da conexão.
          items:
            $ref: '#/components/schemas/AnalyticsMetaAdAccount'
        adAccount:
          type: string
          nullable: true
          description: >-
            A conta de anúncio filtrada em `adAccount`, quando ela é da conexão.
            `null` = todas.
        lastSyncedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Última leitura do gasto no Meta. O gasto dos três últimos dias é
            relido de hora em hora, porque o Meta ainda o ajusta.
      required:
        - connected
        - status
        - adAccounts
        - adAccount
        - lastSyncedAt
    AnalyticsAdsMetrics:
      type: object
      description: >-
        Métricas do Meta Ads da campanha, conjunto ou anúncio. Só existe com o
        Meta conectado e quando a UTM traz o id do Meta.
      properties:
        spend:
          type: number
          description: >-
            Gasto no período, em reais (ou na moeda da conta de anúncio, quando
            não há cotação).
        currency:
          type: string
        originalSpend:
          type: number
          description: Gasto na moeda da conta de anúncio, quando ela não é em reais.
        originalCurrency:
          type: string
        impressions:
          type: integer
        clicks:
          type: integer
        roas:
          type: number
          nullable: true
          description: Faturamento sobre o gasto.
        cpa:
          type: number
          nullable: true
          description: Gasto por venda aprovada.
        profit:
          type: number
          nullable: true
          description: Faturamento menos o gasto.
    AnalyticsMetaAdAccount:
      type: object
      properties:
        id:
          type: string
          description: Id da conta de anúncio no Meta (`act_...`).
        name:
          type: string
        currency:
          type: string
          description: Moeda da conta de anúncio (ISO 4217).
  examples:
    AnalyticsCampaignsWithMetaExample:
      summary: Com o Meta conectado
      value:
        period:
          startDate: '2026-11-01'
          endDate: '2026-11-30'
        platform: null
        hasVisits: true
        summary:
          visits: 1840
          orders: 120
          paid: 92
          amount: 18308
          paidWithUtm: 80
          amountWithUtm: 15920
          campaignCount: 1
          adsSpend: 5200
          adsRoas: 3.06
        platforms:
          - value: meta
            orders: 104
            paid: 80
            amount: 15920
            visits: 1500
        campaigns:
          - key: id:120210000000001
            name: Black Friday
            id: '120210000000001'
            sources:
              - fb
              - ig
            platform: meta
            visits: 1500
            orders: 104
            paid: 80
            amount: 15920
            pixPending: 6
            refunded: 2
            ads:
              spend: 5200
              currency: BRL
              impressions: 410000
              clicks: 8900
              roas: 3.06
              cpa: 65
              profit: 10720
            children: []
        placements:
          - value: facebook_feed
            orders: 70
            paid: 55
            amount: 10945
        financial:
          netAmount: 16012.4
          grossAmount: 18308
          adsSpend: 5200
          roas: 3.08
          profit: 9852.38
          roi: 189.47
          margin: 61.53
          pendingAmount: 1194
          refundAmount: 597
          refundRate: 3.16
          chargebackRate: 0
          arpu: 174.05
          taxRate: 6
          taxAmount: 960.02
          paidCount: 92
          paymentMethods:
            - value: pix
              count: 60
              amount: 11940
              share: 65.22
            - value: credit_card
              count: 32
              amount: 6368
              share: 34.78
        metaAds:
          connected: true
          status: active
          adAccounts:
            - id: act_123456789
              name: Conta principal
              currency: BRL
          adAccount: null
          lastSyncedAt: '2026-11-30T21:00:04.112Z'
    AnalyticsCampaignsWithoutMetaExample:
      summary: Sem o Meta conectado
      value:
        period:
          startDate: '2026-11-01'
          endDate: '2026-11-30'
        platform: null
        hasVisits: true
        summary:
          visits: 1840
          orders: 120
          paid: 92
          amount: 18308
          paidWithUtm: 80
          amountWithUtm: 15920
          campaignCount: 1
        platforms:
          - value: meta
            orders: 104
            paid: 80
            amount: 15920
            visits: 1500
        campaigns:
          - key: id:120210000000001
            name: Black Friday
            id: '120210000000001'
            sources:
              - fb
              - ig
            platform: meta
            visits: 1500
            orders: 104
            paid: 80
            amount: 15920
            pixPending: 6
            refunded: 2
            children: []
        placements: []
        financial:
          netAmount: 16012.4
          grossAmount: 18308
          adsSpend: null
          roas: null
          profit: null
          roi: null
          margin: null
          pendingAmount: 1194
          refundAmount: 597
          refundRate: 3.16
          chargebackRate: 0
          arpu: 174.05
          taxRate: 0
          taxAmount: 0
          paidCount: 92
          paymentMethods: []
        metaAds:
          connected: false
          status: null
          adAccounts: []
          adAccount: null
          lastSyncedAt: null
    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).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.