Voltar para o blog

Conector OpenAI Ads: sincronize campanhas, insights e conversões dos anúncios no ChatGPT para o seu data warehouse

Conector Erathos sincroniza campanhas, insights e conversões do OpenAI Ads (anúncios no ChatGPT) para BigQuery, Redshift e outros data warehouses.

Conector OpenAI Ads

Conector gerenciado para sincronizar ad accounts, campaigns, ad groups, ads, insights de performance, conversões, públicos customizados, feeds de produto e limites de gasto do OpenAI Ads para BigQuery, Redshift, Databricks, ClickHouse, PostgreSQL, Azure SQL Server, S3 Iceberg, Supabase, Snowflake e Azure Synapse. Crie sua conta e teste agora.

Todo time de dados que dá suporte a uma operação de mídia de performance chega no mesmo impasse mais cedo ou mais tarde: os dados de campanha vivem no OpenAI Ads, o restante do stack analítico vive no warehouse, e juntar os dois vira um projeto de engenharia que ninguém planejou. O que começa como um script Python rodando no cron de um EC2 se transforma, três meses depois, em um pipeline que ninguém entende, que falha em silêncio e que nenhum engenheiro quer herdar.

A Erathos lança o conector gerenciado para o OpenAI Ads. Vinte e cinco endpoints disponíveis, dez destinos suportados, zero código de pipeline para escrever ou manter.

O problema com pipelines de OpenAI Ads feitos na mão

A API do OpenAI Ads é autenticada por um bearer token emitido no Ads Manager, com escopo de uma única conta de anúncios. O padrão é simples o suficiente para convencer qualquer engenheiro a construir uma integração própria numa tarde. O custo real aparece depois, e ele é previsível.

Métricas em quatro níveis com números que mudam sozinhos. As métricas de entrega (impressões, cliques, spend, conversões) precisam ser puxadas separadamente no nível de conta, de campanha, de grupo de anúncios e de anúncio, cada uma com janela de data e paginação próprias. E a métrica atribuída muda com o tempo: conversões seguem chegando depois do clique e as janelas de atribuição amadurecem ao longo dos dias, então o número de ontem não é o mesmo da semana passada. Um pipeline incremental que nunca reprocessa o que já passou congela o histórico numa versão desatualizada, e o ROAS começa a divergir do painel sem nenhum erro logado. Em contas múltiplas, cada uma tem a sua moeda: somar spend de contas em moedas diferentes sem converter é o tipo de erro que só aparece no relatório consolidado.

Rate limit silencioso. Em uma extração incremental normal, para volumes de médio porte, você fica abaixo do limite. Quando você faz um backfill histórico ou puxa insights de uma conta inteira em paralelo, a API começa a devolver 429. Se o seu retry não está implementado com backoff exponencial, você perde janelas inteiras de dado e não sabe.

Schema evolution sem aviso. Campos novos aparecem, campos existentes ficam nullable, estruturas aninhadas mudam. O seu modelo dbt que rodava limpo começa a falhar em produção, ou pior: continua rodando, mas calculando receita sobre um campo que sumiu. A inconsistência vai parar no dashboard do time de mídia antes de chegar no seu monitor.

Observabilidade que não existe. Um 200 OK na chamada HTTP não significa que os dados chegaram corretos. Sem contagem de registros por endpoint por execução, sem comparação com a janela anterior e sem alerta de queda de volume, você está voando cego. O pipeline que rodou com sucesso pode ter trazido zero insights novos porque o cursor ficou preso.

O pior cenário não é o pipeline que quebra e manda alerta. É o pipeline que executa com sucesso e entrega dado errado, e o ROAS que sobe pro dashboard do time de mídia já está calculado sobre uma base podre.

O que é possível fazer quando os dados do OpenAI Ads chegam no warehouse

Antes de detalhar o conector, vale documentar o que se ganha de fato quando esses dados saem do SaaS e entram modelados ao lado do restante do seu stack.

Performance consolidada entre canais de mídia

Com campaign_insights, ad_group_insights, ad_insights e ad_account_insights no warehouse, você tem impressões, cliques, spend e conversões no dado bruto, registro por registro, em vez dos agregados pré-calculados dos relatórios nativos. Cruzando com os pipelines de Google Ads, Meta Ads, TikTok Ads e LinkedIn Ads que rodam na mesma plataforma, você monta uma visão única de ROAS, CPL e custo por conversão entre todos os canais, com uma única regra de moeda e uma única definição de conversão. Esse relatório consolidado não existe em nenhum painel individual; ele só existe quando todas as mídias vivem no mesmo banco.

Diagnóstico de entrega pela hierarquia de campanha

As tabelas campaigns, ad_groups e ads trazem objetivo, status, daily_budget, lifetime_budget e bid_strategy, e cada nível tem a sua tabela de insights correspondente. Com a hierarquia completa no warehouse, unida pelas chaves campaign_id e ad_group_id, você localiza exatamente onde a performance degrada: campanha saudável com um ad group queimando orçamento, ou um anúncio específico com CTR em queda arrastando o grupo inteiro. Nos painéis nativos, esse diagnóstico vira navegação manual nível por nível, sem histórico comparável.

Receita atribuída cruzada com CRM e financeiro

O endpoint conversions_insights traz conversões e valor de conversão agregados por evento, e conversions_events traz o evento bruto com horário, valor, moeda e URL de origem. Com isso no warehouse, você cruza conversões dos anúncios no ChatGPT com deals do seu CRM (HubSpot, Pipedrive) e com o sistema financeiro, e responde perguntas que nenhum dos sistemas responde sozinho: qual evento de conversão gera maior valor médio por pedido? Quantas conversões reportadas pelo pixel o financeiro reconhece como receita faturada? Onde está a divergência entre atribuição de mídia e faturamento?

Auditoria de catálogo e feeds de produto

Os endpoints feeds, feed_uploads e feed_products_query trazem o catálogo veiculado nos anúncios: título, preço, moeda, disponibilidade e marca, além do histórico de uploads com status e itens processados. Cruzando com a base de produtos do seu ecommerce ou ERP, você detecta produto esgotado ainda sendo anunciado, divergência de preço entre catálogo e site, e correlaciona quedas de entrega com uploads de feed problemáticos. Esse cruzamento exige que o catálogo veiculado e o catálogo real vivam no mesmo warehouse.

Pacing de orçamento e limites de gasto

O endpoint spend_limit_windows traz as janelas de limite de gasto da conta e, junto com os budgets de campanha e ad group, permite modelar pacing: quanto deveria ter sido gasto em cada janela versus quanto foi, por conta e por campanha. Para quem opera várias contas com moedas diferentes, a visão consolidada de pacing e consumo de limite é um modelo de warehouse, não um relatório nativo.

Trilha de auditoria das operações em massa

Os endpoints bulk_mutation_job e bulk_mutation_job_operations registram cada job de criação e edição em massa, com status, contagem de operações e mensagem de erro por operação. Materializadas no warehouse, essas tabelas viram um changelog da conta: o que mudou, quando mudou e qual operação falhou, exatamente o histórico que hoje mora em planilha ou na memória de quem operou a mídia.

O que está disponível no conector

O conector do OpenAI Ads entrega vinte e cinco endpoints prontos para serem materializados no seu warehouse de destino. Os cinco endpoints de insights suportam sincronização incremental com cursor em updated_at; os demais rodam em full refresh a cada execução. As entidades vêm com as chaves de relacionamento preservadas: campaigns se liga a ad_groups, que se liga a ads, e cada nível tem a sua tabela de insights correspondente.

Endpoint

O que contém

ad_account

A conta de anúncios conectada: nome, status, moeda, país, fuso horário e business_id

ad_accounts

Lista de contas de anúncios acessíveis pelo token

ad_account_insights

Métricas agregadas no nível de conta: impressões, cliques, spend, conversões e moeda, com cursor em updated_at

campaigns

Campanhas: objetivo, status, daily_budget, lifetime_budget e janela de veiculação

campaign_insights

Métricas de entrega por campanha: impressões, cliques, spend e conversões, com cursor em updated_at

ad_groups

Grupos de anúncios: orçamento diário, bid_strategy e janela de veiculação

ad_group_insights

Métricas de entrega por grupo de anúncios, com cursor em updated_at

ads

Anúncios: nome, formato, status e ad group de origem

ad_insights

Métricas de entrega por anúncio individual, com cursor em updated_at

conversions_pixels

Pixels de medição configurados para rastrear conversões

conversions_events

Eventos de conversão brutos: nome do evento, horário, URL de origem, valor e moeda

conversions_event_settings

Configuração dos eventos de conversão: nome, status, valor padrão e moeda

conversions_insights

Conversões e valor de conversão agregados por evento, com cursor em updated_at

custom_audiences

Públicos customizados: nome, tipo, descrição, tamanho aproximado e status

custom_audience_operations

Operações de carga e atualização dos públicos customizados

feeds

Catálogos de produto (feeds): tipo, status e número de itens

feed_products_query

Produtos do catálogo: título, preço, moeda, disponibilidade e marca

feed_sftp_access

Credenciais de acesso SFTP do feed

feed_uploads

Histórico de uploads do feed: status, itens processados e duração

bulk_mutation_job

Jobs de criação e edição em massa de campanhas, grupos e anúncios

bulk_mutation_job_operations

Operações de cada job em massa, com status e mensagem de erro por operação

geo_lookup_search

Códigos geográficos disponíveis para segmentação por país e região

lead_sync_subscriptions

Assinaturas de sincronização de leads da conta de anúncios

partner_data_upload

Uploads de dados de parceiro: arquivo, número de registros e status

spend_limit_windows

Janelas de limite de gasto configuradas na conta de anúncios

Os destinos suportados são Azure SQL Server, BigQuery, ClickHouse, Databricks, PostgreSQL, Redshift, S3 Iceberg, Supabase, Snowflake e Azure Synapse.

Como autenticar

A autenticação do conector requer um único campo:

  • Token: a API key do OpenAI Ads, um bearer token com escopo de uma única conta de anúncios, usado para autenticar todas as requisições do conector à API

Para gerar o token, faça login na conta de anúncios que você quer sincronizar e navegue em Settings > Integrations > API Keys, onde você cria uma nova API key. Cada chave é emitida a partir de uma única conta de anúncios: gere a chave a partir da conta cujos dados você quer trazer para a Erathos. Copie a chave gerada, guarde-a com segurança, cole no campo Token da plataforma e clique em Save and close para concluir a configuração.

O esquema de autenticação também está descrito na referência oficial da API, em https://developers.openai.com/ads/api-reference/authentication, onde é possível verificar os escopos e as permissões da sua chave. O processo completo de configuração do conector está documentado em https://docs.erathos.com/connectors/apis/openai-ads.

Por que terceirizar a ingestão para a Erathos

A premissa do conector é direta: a engenharia de manutenção da ingestão não deveria ser responsabilidade do seu time de dados. Paginação, rate limit, retry com backoff, schema evolution, alerta de falha, alerta de queda de volume, backfill. Tudo isso é responsabilidade de quem opera a plataforma de ingestão.

Com o conector configurado, a plataforma entrega:

Visibilidade ponta a ponta de cada execução

Tempo de extração por endpoint, contagem de registros por janela, quais janelas foram processadas, onde houve retentativa. Quando uma métrica de ROAS muda no dashboard e o time de mídia abre um chamado para o time de dados, você tem a trilha completa para encontrar a causa raiz.

Alertas configurados de fábrica

Falha de execução, queda de volume por endpoint e atraso de janela são detectados e roteados pelas integrações de alerta que o time já usa. Você não escreve esse código.

Reprocessamento como operação suportada

Quando você precisa reprocessar uma janela, porque mudou a lógica do modelo dbt ou porque as métricas de atribuição foram reestatadas pela fonte, isso é uma operação de plataforma, não uma sequência de DELETE + INSERT improvisada no warehouse.

Paginação correta, gestão de rate limit, evolução de schema e backfill são responsabilidade da plataforma. O time de dados foca no modelo, não no encanamento.

Pipelines disponíveis

O conector do OpenAI Ads está disponível com os seguintes destinos:

Comece agora

Crie sua conta na Erathos e conecte o OpenAI Ads ao seu warehouse em minutos. Com o token de API emitido no Ads Manager, os primeiros dados chegam ao destino sem nenhum código de pipeline para escrever, manter ou monitorar.

Dados de anúncios gerados todo dia não deveriam ficar trancados em um SaaS, desconectados do restante do seu modelo analítico. Ou pior: em um pipeline caseiro que vai custar atenção do time todo mês para sempre.

Veja a documentação completa do conector em https://docs.erathos.com/connectors/apis/openai-ads.