Escopo
Rotas
Autenticação e escopo
As rotas usam o mesmo token das outras rotas da API (Autenticação), com o escopoanalytics 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 emstartDate e endDate, no formato AAAA-MM-DD.
- Os dias são os de Brasília, e o
endDateentra no período. - Sem
endDate, o período termina hoje. SemstartDate, 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.previousStartDateaperiod.previousEndDate, empreviousTotals).
Com e sem o Meta Ads conectado
Toda resposta200 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.originalSpendeads.originalCurrencyguardam o valor original). Sem cotação, o gasto vem na moeda da conta, e ROAS, CPA e lucro vêmnull. - Para ver uma conta de anúncio só, passe
adAccountcom um id demetaAds.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.offersecomplement. - 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.pageViewsfica zero sem o script na sua página de vendas, e os dias antes detrackingSincenã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), eoutrossoma 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çalhoRetry-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.