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

# Visão geral

> Os números do Cakto Analytics Pro pela API: a conta inteira, cada produto, as campanhas e o custo do Meta Ads.

#### Escopo

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

O **Cakto Analytics Pro** mostra no painel quanto cada produto vende, de onde vêm os acessos e as
vendas, onde o comprador desiste e quanto cada campanha rende. Estas rotas entregam os mesmos números
pela API, com as mesmas regras da tela, para levar ao seu BI, planilha ou painel próprio.

Todas as rotas são **só leitura**. Funcionam para qualquer conta, **com ou sem o Meta Ads conectado**:
sem a conexão, você recebe tudo o que a Cakto mede sozinha; com ela, entram também o gasto e o
retorno dos anúncios.

## Rotas

| Para | Use |
| - | - |
| Os números da conta inteira, dia a dia e por produto | [Todos os produtos](https://docs.cakto.com.br/api-reference/analytics/overview-all.md) |
| O painel completo de um produto: funil, origens, pagamento, ofertas | [Analytics de um produto](https://docs.cakto.com.br/api-reference/analytics/product.md) |
| Vendas por campanha, conjunto e anúncio da conta, com o custo do Meta | [Campanhas de todos os produtos](https://docs.cakto.com.br/api-reference/analytics/campaigns.md) |
| O mesmo, de um produto só | [Campanhas de um produto](https://docs.cakto.com.br/api-reference/analytics/product-campaigns.md) |
| Saber se o Meta Ads está conectado | [Conexão com o Meta Ads](https://docs.cakto.com.br/api-reference/analytics/meta-ads.md) |

## Autenticação e escopo

As rotas usam o mesmo token das outras rotas da API ([Autenticação](https://docs.cakto.com.br/authentication.md)), com o escopo
**`analytics`** e o `read`.

> [!NOTE]
>
> **O escopo `analytics` precisa ser marcado.** Nenhuma chave emitida antes dele o tem, nem o ganha
> por `orders` ou `products`. Para ler o Analytics com uma chave existente, emita uma chave nova com
> o escopo.

```bash theme={null}
curl -G "https://api.cakto.com.br/public_api/analytics/" \
  -H "Authorization: Bearer $TOKEN" \
  -d startDate=2026-11-01 \
  -d endDate=2026-11-30
```

## Período

Toda rota de números recebe o período em `startDate` e `endDate`, no formato `AAAA-MM-DD`.

* Os dias são os de **Brasília**, e o `endDate` entra no período.
* Sem `endDate`, o período termina **hoje**. Sem `startDate`, ele tem **30 dias**.
* O período vai até **12 meses** (366 dias). Acima disso, a resposta é `400`.
* As rotas de números comparam com o **período anterior de mesmo tamanho**, logo antes do
  `startDate` (`period.previousStartDate` a `period.previousEndDate`, em `previousTotals`).

## Com e sem o Meta Ads conectado

Toda resposta `200` traz o bloco `metaAds`. É ele que diz se os números de anúncio estão na resposta:

```json theme={null}
"metaAds": {
  "connected": true,
  "status": "active",
  "adAccounts": [{ "id": "act_123456789", "name": "Conta principal", "currency": "BRL" }],
  "adAccount": null,
  "lastSyncedAt": "2026-11-14T12:41:07.512Z"
}
```

| | Sem o Meta conectado (`connected: false`) | Com o Meta conectado (`connected: true`) |
| - | - | - |
| Vendas, faturamento, reembolso, chargeback | ✅ | ✅ |
| Acessos, funil e conversão | ✅ | ✅ |
| Origem (UTM), afiliado, país, aparelho, pagamento | ✅ | ✅ |
| Campanha, conjunto e anúncio pelas UTMs | ✅ | ✅ |
| Líquido recebido, imposto, taxa de reembolso (`financial`) | ✅ | ✅ |
| Gasto, impressões e cliques por campanha, conjunto e anúncio (`ads`) | — | ✅ |
| ROAS, CPA e lucro por campanha, conjunto e anúncio | — | ✅ |
| Gasto, ROAS, lucro, ROI e margem da conta ou do produto (`financial`) | `null` | ✅ |

Sem a conexão, **nada vira erro**: os campos de anúncio simplesmente não vêm (`ads`,
`summary.adsSpend`) ou vêm `null` (`financial.adsSpend`, `roas`, `profit`, `roi`, `margin`).

* **`status: "expired"`**: o Meta recusou o acesso (token vencido, senha trocada, permissão
  removida). O gasto já lido continua nas respostas até `lastSyncedAt`; para voltar a atualizar, é
  preciso reconectar no painel.
* **`lastSyncedAt`**: a Cakto relê o gasto dos três últimos dias de hora em hora, porque o Meta ainda
  ajusta o gasto recente. Números de hoje e de ontem podem mudar.
* **Conectar, reconectar e desconectar** ficam no painel da Cakto, em **Analytics**, no botão
  **Conectar Meta Ads**. A conexão pede só leitura dos anúncios: a Cakto nunca altera campanhas.

## Campanhas e Meta Ads

As campanhas saem das **UTMs da venda**: `utm_campaign` é a campanha, `utm_medium` o conjunto,
`utm_content` o anúncio e `utm_term` o posicionamento. É a convenção que o gerenciador de anúncios
grava quando a UTM usa os parâmetros dinâmicos do Meta:

```text theme={null}
utm_source=FB&utm_campaign={{campaign.name}}|{{campaign.id}}&utm_medium={{adset.name}}|{{adset.id}}&utm_content={{ad.name}}|{{ad.id}}&utm_term={{placement}}
```

* O gasto entra **pelo id**: só a campanha, o conjunto ou o anúncio com o id do Meta na UTM ganha o
  bloco `ads`. Sem o id, a linha aparece com as vendas, mas sem o custo.
* Gasto de conta de anúncio em outra moeda é convertido para real pela cotação do dia
  (`ads.originalSpend` e `ads.originalCurrency` guardam o valor original). Sem cotação, o gasto vem
  na moeda da conta, e ROAS, CPA e lucro vêm `null`.
* Para ver uma conta de anúncio só, passe `adAccount` com um id de `metaAds.adAccounts`.
* A árvore traz até 20 campanhas, 10 conjuntos por campanha e 10 anúncios por conjunto. O resto é
  somado numa linha `outros`.

## Como os números são contados

* **Venda** é pedido aprovado da **oferta principal**, no dia em que o pedido foi criado. Order bump,
  upsell e downsell aparecem no produto onde o comprador entrou e, na rota do produto, em
  `breakdowns.offers` e `complement`.
* **Faturamento** (`grossAmount`, `amount`) é em **reais**. Venda em outra moeda conta no número de
  vendas, mas não no faturamento.
* **Líquido** (`financial.netAmount`) é o que você recebeu nas vendas aprovadas, já sem as taxas,
  somando o que entrou junto (bump, upsell).
* **Acesso** (`checkoutViews`, `pageViews`) é contado pela coleta do Analytics. `pageViews` fica zero
  sem o script na sua página de vendas, e os dias antes de `trackingSince` não têm acesso nem funil.
* **Percentuais** (`conversionRate`, `refundRate`, `roi`, `margin`) vêm de 0 a 100, com duas casas.
  **ROAS** vem em vezes (`3.06` = R\$ 3,06 por real gasto).
* `(sem origem)` é a venda sem aquele dado (sem UTM, por exemplo), e `outros` soma o que passou do
  limite da lista.

## Limites

* **60 consultas por minuto** por conta, somando as rotas de Analytics. Acima disso, `429`, com o
  tempo de espera no cabeçalho `Retry-After`.
* As respostas ficam **5 minutos** em cache: repetir a mesma consulta nesse intervalo devolve o mesmo
  resultado.
* A lista de produtos de [Todos os produtos](https://docs.cakto.com.br/api-reference/analytics/overview-all.md) traz os **200**
  que mais faturaram. O total da conta soma todos.
* Contas muito grandes em períodos longos podem passar do tempo (`503`). Tente de novo ou peça um
  período menor.

## Erros

| Status | Quando |
| - | - |
| `400` | Data inválida, `startDate` depois de `endDate`, período acima de 12 meses ou `platform` inválida |
| `401` | Token ausente, inválido ou vencido |
| `403` | O token não tem o escopo `analytics`, ou o Cakto Analytics não está liberado para a conta |
| `404` | O produto não existe ou não é da sua conta |
| `405` | Método diferente de `GET`: as rotas de Analytics são só leitura |
| `429` | Passou de 60 consultas por minuto |
| `503` | A consulta passou do tempo |

O corpo do erro é `{"detail": "..."}`. Quando a rota é do Analytics Pro e a conta não o tem, vem
também `"code": "PRO_REQUIRED"`.

## O que fica no painel

Conectar e desconectar o Meta Ads, escolher a alíquota de imposto usada no lucro
(`financial.taxRate`) e instalar o script de coleta na página de vendas.


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