Como funciona por dentro

1. Cada nível é coletado, nenhum é derivado por soma

Conta, campanha, conjunto de anúncios e anúncio são buscados da plataforma em chamadas separadas. A alternativa — pedir o nível mais fundo e somar para cima — produziria número errado justamente nas métricas que o cliente mais questiona.

O motivo é o alcance: ele conta pessoas únicas, e a mesma pessoa alcançada por dois anúncios do mesmo conjunto conta uma vez no conjunto e duas na soma dos anúncios. Só a plataforma consegue deduplicar, porque só ela sabe quem é quem.

A estrutura — nomes, estados, orçamentos, criativos — é coletada em separado dos números. A API de insights só devolve linha para objeto que teve entrega; montando a árvore a partir dos números, um conjunto pausado ontem sumiria da tela. E é exatamente ele que se procura quando a veiculação para.

2. Todo valor é comparado com o anterior

Cada linha coletada tem um hash do próprio conteúdo. Na coleta seguinte, o hash novo é comparado com o gravado: igual, nada acontece; diferente, a alteração é registrada campo a campo, com o valor antes, o valor depois e a causa provável.

As causas são inferidas do padrão do que mudou — conversão tardia, mudança de janela de atribuição, reprocessamento da plataforma, correção de gasto. A inferência é registrada como inferência, não como fato: o sistema diz qual é a causa provável, não afirma saber a causa.

A resposta bruta da plataforma é guardada junto. Todo número exibido aponta para a chamada de API que o originou — é isso que transforma “acho que era esse valor” em evidência.

3. A agregação tem três classes, e a distinção é tudo

Aditiva — gasto, impressões, cliques, conversões e valor somam direto. São contagens de eventos; dois dias somados são os eventos dos dois dias.

Derivada — CTR, CPC, CPM, CPA, ROAS e frequência são recalculadas a partir dos aditivos já somados. Nunca somadas, nunca com média tirada: média de médias erra sempre que os dias têm volumes diferentes, ou seja, sempre.

Não-aditiva — alcance. A soma é devolvida como teto declarado, marcada com ≤ quando o período tem mais de um dia, e exata quando cobre um dia só.

4. Leitura e escrita são caminhos separados

A coleta grava os fatos e publica um evento na mesma transação; um serviço separado consome esses eventos e monta as tabelas que o painel lê. A separação existe para que uma coleta pesada não deixe o painel lento, e para que o painel continue respondendo mesmo se a coleta estiver falhando — com o aviso de que o dado está velho, que é a informação certa nesse caso.

5. O isolamento entre clientes é do banco, não da aplicação

Cada consulta roda sob uma política de linha que filtra pelo cliente da sessão. Se alguém escrever uma consulta nova e esquecer o filtro, o banco não devolve a linha do outro cliente — a proteção não depende de ninguém lembrar.

O cliente vem do endereço da URL e é confirmado contra o token de acesso a cada requisição. Não existe “cliente selecionado” guardado em cookie: é por esse mecanismo que se abre a tela errada sem perceber.

Há um conjunto de testes que tenta atravessar essa fronteira por vários caminhos e verifica que ela recusa. Ele é executado a cada mudança.

6. Escrever na plataforma exige intenção

Pausar, retomar e alterar orçamento passam por plano, revisão e confirmação explícita, com registro imutável de quem mandou o quê, quando, e qual foi a resposta da plataforma.

A escrita nasce desligada em todo ambiente. Ligá-la é uma ação deliberada e reversível, e nada acontece na plataforma de anúncios sem que alguém tenha clicado sabendo o que ia acontecer.