--- id: agencias/midia-paga-carteira industria: Agências de marketing uso: muito usado esforco: médio grao: Cliente x plataforma x conta x campanha x dia (anúncio quando a plataforma tiver) --- # Mídia paga de toda a carteira Investimento, cliques e resultados de todos os clientes e plataformas numa tabela só, com cada conta de anúncio presa ao cliente certo. ## Resumo executivo **Para quem:** Agências que gerenciam contas de anúncio de vários clientes em mais de uma plataforma. **O que resolve** - Uma tabela só com o investimento de todos os clientes, comparável entre Meta, Google, TikTok e LinkedIn. - Cada conta de anúncio pertence a um cliente declarado, e o número de um cliente nunca aparece no do outro. - O total por cliente e por dia bate com cada gerenciador, sem fator de um milhão, moeda misturada ou dia trocado. **Por que importa:** É a base de todo o resto: relatório do cliente, funil até a venda, alertas e o agente de IA leem desta tabela. Um erro de escala ou de mapeamento aqui aparece em todos os relatórios ao mesmo tempo, e um vazamento entre clientes é o tipo de erro que custa a conta. **Perguntas de negócio que responde** - Quanto cada cliente investiu neste mês, por plataforma? - Como foi a semana do cliente X no Meta e no Google? - Investimento de setembro contra agosto, cliente a cliente. - Qual o CPC e o CPM consolidados da carteira por plataforma? - Quais contas de anúncio estão gastando sem cliente definido? - Quais clientes têm mídia paga ativa hoje? **O que você precisa** - As contas de anúncio de cada cliente conectadas na Nekt (uma fonte por conta) - Um registro conta para cliente: plataforma, id da conta, cliente, moeda, fuso e status - O critério de cada cliente para contas compartilhadas e imposto sobre a verba **O que você recebe** - Uma tabela unificada por cliente, plataforma, campanha e dia, já em reais - Um registro versionado que diz de qual cliente é cada conta - Um alerta de contas sem cliente e de fontes paradas - Um agente de IA que responde sobre a carteira sem misturar clientes ## Detalhado ### O problema Cada cliente vira uma fonte por plataforma, e a agência acaba com dezenas de tabelas iguais por fora e diferentes por dentro. O Google manda custo em micros, o Meta manda tudo como texto, cada conta tem moeda e fuso próprios. E a conta de anúncio não é o cliente: um cliente tem várias contas, uma conta serve mais de uma marca, e o nome da conta raramente é o nome do cliente. ### Regras de negócio 1. **O cliente vem do registro, nunca do nome.** Mantenha um registro com uma linha por conta: plataforma, account_id (ou customer_id do Google), client_id, moeda, fuso, status e data de início e fim. A tabela unificada pega o cliente por plataforma + account_id. O prefixo da tabela e o nome da conta no gerenciador são da conta, não do cliente, e casar por nome não serve como prova. (Evite: Tirar o cliente do nome da tabela ou da conta.) 2. **Converta cada plataforma para reais antes de unir.** Google: metrics_cost_micros ÷ 1.000.000 (orçamento e lance em micros também). Meta: spend, impressions e clicks chegam como texto e viram número. LinkedIn: costInLocalCurrency é texto. TikTok: spend por stat_time_day. Converta em cada braço, antes do UNION, para que a coluna investimento tenha a mesma unidade em todas as linhas. (Evite: Unir as colunas de custo como vieram e converter no dashboard.) 3. **Nunca some moedas diferentes.** Leia a moeda da conta (currency na tabela de contas da plataforma) e leve a coluna moeda até o fim. Para consolidar a carteira, converta com uma cotação declarada e datada, ou deixe a conta de fora e diga que deixou. Conta em dólar somada com contas em real gera um total sem significado. (Evite: Somar investimento de todas as contas sem olhar a moeda.) 4. **A data da plataforma é rótulo de dia.** O Meta agrega date_start no fuso da conta, e o Google entrega date como o dia da conta, muitas vezes num timestamp à meia-noite. Use o dia como veio. Converter esse timestamp para outro fuso joga o investimento para o dia anterior. Guarde o fuso de cada conta no registro e só compare contas de fusos diferentes sabendo disso. (Evite: Converter a data da plataforma para o fuso de São Paulo.) 5. **Schema comum com colunas explícitas.** Defina um contrato de colunas (data, cliente, plataforma, conta, campanha, conjunto, anúncio, moeda, investimento, impressões, cliques, resultado) e liste as colunas em cada braço do UNION ALL, com tipo forçado. Ids viram texto: campaign_id é número numa plataforma e texto na outra, e o cruzamento com a tabela de campanhas do Google precisa do CAST. (Evite: SELECT * em cada braço do UNION ALL.) 6. **O realizado vem do relatório de desempenho.** Investimento, impressões e cliques saem dos relatórios diários (adsinsights, campaign_performance, campaign_analytics, daily_report). As tabelas de contas, campanhas e conjuntos só enriquecem nome, status e objetivo. A lista de contas não define quais contas existem, e configuração ausente não apaga gasto realizado. (Evite: Partir da lista de contas ou campanhas e trazer o gasto por LEFT JOIN.) 7. **Conta sem cliente aparece, não some.** Toda linha leva client_id. Quando a conta não casa no registro, a linha fica com status de mapeamento UNMAPPED_ACCOUNT e entra num alerta. Ela não vai para cliente nenhum e não é descartada em silêncio. A cobertura de mapeamento (investimento com cliente / investimento total) é um número que a agência acompanha. (Evite: INNER JOIN com o registro, que derruba contas novas sem avisar.) 8. **Conta compartilhada se filtra pela regra do registro.** Quando a conta é dividida com o time interno do cliente ou entre marcas, só entram as campanhas da agência ou da marca, por um termo no nome da campanha guardado no registro (nome em minúsculas, com _ virando espaço). Fonte de agência que atende vários clientes, como perfil de empresa no Google, precisa de filtro pelo id do local de cada cliente. (Evite: Somar a conta inteira para o cliente.) 9. **Uma fonte viva por conta.** Fonte retirada, congelada ou reconectada com outro prefixo convive com a nova. Marque no registro qual fonte está ativa e com qual vigência, e nunca some uma tabela congelada com a consolidada. Em fontes que reextraem o mesmo dia, fique com a versão mais recente de cada chave antes de somar. (Evite: Unir todas as tabelas que existem para a conta.) 10. **Performance Max entra no nível de campanha.** PMax não tem anúncio individual. Use o relatório de anúncio para Search, Display e Vídeo e o relatório de campanha só para as campanhas PMax. Nunca some os dois níveis da mesma campanha. (Evite: Somar o relatório de campanha com o de anúncio.) ### Como cada plataforma entrega o custo e o dia Converta no braço de cada plataforma, antes de unir. - **Meta Ads · adsinsights** → Custo em moeda da conta, como texto (`spend → número; date_start (texto, fuso da conta)`) - **Google Ads · campaign_performance** → Custo em micros (`metrics_cost_micros ÷ 1.000.000; date`) - **LinkedIn Ads · campaign_analytics** → Custo em moeda local, como texto (`costInLocalCurrency → número; date`) - **TikTok Ads · daily_report** → Custo em moeda da conta (`spend; stat_time_day`) - **GA4** → Data em texto AAAAMMDD (`date → data`) - **Tabela de contas de cada plataforma** → Moeda, fuso e status da conta (`currency, timezone_name`) ### Definições | Métrica | Definição | |---|---| | Investimento | soma do custo convertido para moeda (Google ÷ 1.000.000), por cliente, plataforma e dia da conta | | Impressões e cliques | soma dos relatórios diários de desempenho; no Meta, cliques no link vêm de link_click | | CTR | soma dos cliques / soma das impressões no período | | CPC | soma do investimento / soma dos cliques no período | | CPM | soma do investimento / soma das impressões × 1.000 no período | | CPA e ROAS | investimento / conversões e valor de conversão / investimento, com as somas do período | | Cobertura de mapeamento | investimento com client_id resolvido / investimento total, por dia | | Cliente com mídia ativa | cliente com investimento maior que zero nos últimos 7 dias em pelo menos uma conta ativa no registro | ### Armadilhas - **Fator de um milhão.** Padronizar a coluna de custo do Google e do Meta da mesma forma faz uma das duas mentir por um milhão. No total salta aos olhos; em CPA e ROAS os micros podem se cancelar e passar. Como evitar: Converta em cada braço e confira o total de um dia contra cada gerenciador. - **Gasto no dia errado.** A data do Google chega como timestamp à meia-noite. Converter esse valor para o fuso de São Paulo leva tudo para o dia anterior, e num monitor de frescor isso fez a fonte parecer atrasada. Como evitar: Trate a data da plataforma como dia, sem conversão de fuso. - **UNION que quebra sozinho.** O UNION ALL casa por posição. Bastou o conector de uma conta ganhar uma coluna para a tabela da carteira inteira parar. Como evitar: Liste as colunas em cada braço e mantenha o schema de saída idêntico. - **Dupla contagem com fonte antiga.** Fontes retiradas ficaram congeladas ao lado da consolidada, e quem somou as duas dobrou o investimento daqueles clientes. Como evitar: Registre a fonte ativa e a vigência de cada conta. - **Cruzamento por nome.** O nome do cliente diverge entre mídia, CRM, financeiro e planilha de controle, e o cruzamento por nome falhava na maioria das linhas. Contas com nome parecido são unidades distintas. Como evitar: Cruze por id de conta ou documento, com tabela de apelidos só como pista. - **Cliente que sai da carteira.** Apagar o dado do cliente que saiu sem tirar o braço dele quebrou a consulta da carteira. Deixar o braço faz o alerta acusar atraso para sempre. Como evitar: Marque o status no registro com data de fim e remova o braço sem mudar o schema de saída. Validado em dados reais: Na própria Nekt, a tabela de contas do Meta lista contas em três moedas (real, dólar e euro) e três fusos, mas só uma delas tem linhas de desempenho: a lista de contas não define o universo. No mesmo workspace, spend, impressions e clicks do Meta chegam como texto, o custo do Google vem em micros, costInLocalCurrency do LinkedIn vem como texto, e as datas do Google e do LinkedIn chegam como timestamp à meia-noite. ### Teste de aceitação - [ ] Para um cliente e um mês fechado, o investimento de cada plataforma bate com o gerenciador correspondente (diferença abaixo de 1%). - [ ] O investimento de um dia escolhido bate com o gerenciador no mesmo dia, em cada plataforma (prova de que o dia não foi deslocado). - [ ] A soma do investimento da tabela unificada é igual à soma das fontes ativas no registro, já convertidas, sem nenhuma fonte congelada. - [ ] Nenhuma linha fica sem client_id fora do status UNMAPPED_ACCOUNT, e a lista de contas não mapeadas é conferida a cada semana. - [ ] A chave plataforma, conta, campanha, dia (e anúncio, quando houver) não se repete. ### Context document ```text Mídia paga da carteira - O cliente de cada linha vem do registro conta para cliente (plataforma + account_id). Nunca deduza o cliente pelo nome da tabela, da conta ou da campanha. - Dados de outro cliente não são evidência para este cliente, mesmo com tabelas e métricas de nome parecido. - Investimento já está em moeda: Google foi dividido por 1.000.000; Meta e LinkedIn foram convertidos de texto para número. - Nunca some investimento de moedas diferentes. Se precisar consolidar, diga a cotação usada ou que a conta ficou de fora. - A data é o dia da conta na plataforma. Não converta fuso. - CTR, CPC, CPM, CPA e ROAS são recalculados das somas do período, nunca média de taxas diárias. - Contas com status UNMAPPED_ACCOUNT não pertencem a cliente nenhum: cite como pendência, não atribua. - Fontes congeladas ou retiradas não entram em totais. - Para resultado por objetivo no Meta, siga as regras do caso Resultado do Meta Ads por objetivo. Exceções por cliente: - : conta compartilhada com o time interno; só entram campanhas com no nome. - : conta opera em ; fica fora do total da carteira. - : custo do Meta reportado com imposto de % sobre a verba. ``` ### Variações - **Acesso por cliente:** O mesmo registro define quem da equipe ou do cliente vê cada conta no dashboard. - **Microsoft Ads e outras:** Novo braço com a mesma lista de colunas: a tabela da carteira não muda. - **Grupo com várias marcas:** O registro aponta conta para marca e marca para grupo, com a mesma regra de isolamento.