Skip to main content

Escopo

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

Autenticação e escopo

As rotas usam o mesmo token das outras rotas da API (Autenticação), com o escopo analytics e o read.
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.

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:
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:
  • 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 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

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.