Unidades e tipos

Esta página reúne o que o formato JSON sozinho não diz. Quem não conhece estas regras produz um relatório errado que parece certo.

Dinheiro está em micros

Todo campo terminado em _micros é um inteiro em que 1.000.000 vale uma unidade da moeda.

Valor na API	Valor na moeda
`1500000`	1,50
`129900000`	129,90
`1500000000`	1.500,00

Regras:

Divida por 1.000.000 com aritmética inteira. O valor 129,90 não tem representação exata em ponto flutuante, e a diferença aparece somada milhares de vezes no fim do mês.
Micros não são centavos. Dividir por 100 infla o valor dez mil vezes.
Para exibir em reais com dois decimais, arredonde de micros para centavos com inteiros: (micros + 5000) / 10000. Depois separe reais e centavos.
Os valores cabem em inteiros de 64 bits. Em JavaScript, Number é exato até cerca de 9 quatrilhões (2^53); acima disso use BigInt.

Exemplos de conversão estão nas receitas.

Conversões também estão em micros

conversions_micros: 75000000 são 75 conversões, não 75 milhões. A plataforma de anúncio reporta conversão fracionária por causa de atribuição parcial, e por isso o campo não é um inteiro simples. Divida por 1.000.000 para obter o número de conversões.

O campo conversion_value_micros é o valor das conversões reportado pela plataforma, em micros da moeda da conta.

Métrica derivada não vem pronta e não se soma

CPA, CPC, CTR, CPM e ROAS não aparecem nas respostas de totais, de propósito. Elas são razões, e somar ou tirar a média de razões dá o número errado.

Calcule sempre a partir dos totais somados:

Métrica	Cálculo
CPA	`soma(spend_micros) / (soma(conversions_micros) / 1.000.000)`
CPC	`soma(spend_micros) / soma(clicks)`
CTR	`soma(clicks) / soma(impressions)`
CPM	`soma(spend_micros) / soma(impressions) * 1000`
ROAS	`soma(conversion_value_micros) / soma(spend_micros)`

Exemplo: duas campanhas, uma com gasto de 100 e 10 conversões (CPA 10) e outra com gasto de 900 e 30 conversões (CPA 30). A média dos CPAs é 20. O CPA do conjunto é 1000 / 40 = 25. A diferença cresce quanto mais desiguais forem as campanhas.

Com gasto zero, não divida: trate como “sem dado”, não como infinito.

Moeda

Cada linha tem currency, o código ISO-4217 da moeda da conta de anúncio. Contas de moedas diferentes não podem ser somadas sem conversão: o total sairia numericamente certo e sem sentido. Agrupe por currency antes de somar.

O campo display_currency da troca de token é a moeda de exibição do cliente e não converte os valores da API.

Datas e fuso

Parâmetros de data usam o formato AAAA-MM-DD. A data deve existir no calendário (2026-02-31 é recusada, não corrigida).
Cada ponto da série diária (date) é o dia no fuso da conta de anúncio, não em UTC. O fuso de cada conta está no campo timezone de /accounts.
Por isso o total de um mês pode divergir da soma de trinta dias vindos de contas em fusos diferentes. Compare janelas inteiras, e não dias soltos entre contas de fusos distintos.
Carimbos de data e hora (expires_at, last_observed_at, observed_at, generated_at) são ISO 8601 em UTC.

A trilha de quando cada número foi observado

O número de ontem pode mudar amanhã. As plataformas revisam dados já reportados por vários dias: atribuição que se completa, tráfego inválido removido, conversão que chega atrasada.

A API expõe a trilha para você não divergir em silêncio:

Em cada linha de totais, revisions informa quantas alterações retroativas afetam aquele recorte. Maior que zero significa que a plataforma mudou números que já havia reportado.
A rota audit/revisions lista as alterações (data, campanha, campo, valor anterior, valor atual, quando foi observada e a defasagem em dias). Exige o papel analyst.
Na rota summary, o bloco caveats informa a janela de revisão (restatement_window_days, hoje 28 dias) e quando a resposta foi gerada (generated_at).
Em /accounts, last_observed_at diz quando a coleta falou com a conta pela última vez.

Se você guarda histórico, releia os últimos dias a cada execução (pelo menos a janela de revisão) e substitua o que mudou. Reconcilie por audit/revisions quando precisar explicar uma diferença.

Conta parada ou campanha morta

Uma conta que parou de coletar produz o mesmo desenho de uma campanha que parou de entregar: a série cai a zero. As duas hipóteses pedem ações opostas.

Antes de concluir que algo caiu, leia /accounts:

last_date é o último dia com dado.
last_observed_at é quando a coleta conferiu a conta pela última vez.
Uma conta conferida há dez minutos pode ter dados só até anteontem. Isso é normal e indica que a coleta funciona e a conta não entregou.
Uma conta com last_observed_at antigo indica problema de coleta ou de conexão, não de campanha. Veja também /conexoes, que mostra o estado das credenciais de cada rede (active, expired, revoked, error).

Identificadores

Use campaign_id e account_id como chaves. Nomes de campanha mudam, e casar por nome já produziu atribuição errada quando dois clientes usaram o mesmo nome.