Skip to main content
O conector OpenAI Ads lê a estrutura de uma conta de anúncios do OpenAI Ads (conta, campanhas, grupos de anúncios e anúncios) e as métricas diárias de entrega e de conversão de cada anúncio.

​
Capacidades

  • Traz ao Data Catalog a hierarquia da conta: a conta de anúncios, as campanhas, os grupos de anúncios e os anúncios, com status, orçamento, lances e criativo.
  • Traz, por anúncio e por dia, o gasto, as impressões, os cliques, o CTR, o CPC e o CPM.
  • Traz, por anúncio e por dia, as conversões (total, por clique e por visualização) e as vendas atribuídas.
  • Junta entrega e conversões no modelo clean openai_ads_ad_performance_daily, com os nomes de campanha, grupo e anúncio e as métricas derivadas cpa e roas.
  • Guarda o histórico diário além dos 365 dias que o OpenAI Ads retém: os dias já lidos nunca são apagados por uma nova carga.
  • Alimenta o Memory com os nós AdAccount, Campaign, AdGroup e Ad, ligados na mesma hierarquia, e com o desempenho diário como linha do tempo de cada Ad. O nó Campaign é o mesmo rótulo das campanhas do Mailchimp, sem fusão entre os dois conectores. Os nós só entram no grafo depois que a ontologia unificada é aplicada.

​
Recursos disponíveis

Todo recurso nasce desligado no Data Catalog. Você escolhe quais carregar depois de conectar. ad_insights_daily e ad_conversions_daily são sempre incrementais. O Data Catalog mostra “Incremental” desabilitado para os dois, porque o OpenAI Ads guarda só os últimos 365 dias e uma carga completa apagaria o histórico mais antigo.
O modelo clean openai_ads_ad_performance_daily lê os seis recursos: os dois fatos e as quatro tabelas da hierarquia. Selecione os seis no Data Catalog para que ele seja construído com os nomes e a moeda preenchidos.

​
Como ler as métricas

  • date é o dia do calendário no fuso da conta (timezone de ad_account), o mesmo corte do Ads Manager. A data não é convertida para UTC.
  • Valores monetários estão na moeda da conta (currency_code), sem conversão. Os insights já vêm em unidade cheia. Orçamentos e lances, que a API envia em micros, saem na clean em unidade cheia (daily_budget, lifetime_budget, max_bid).
  • As conversões seguem a atribuição padrão da API: até 30 dias depois do clique e 1 dia depois da visualização. Por isso pode haver conversão num dia sem gasto. No modelo de desempenho, essa linha aparece com spend vazio.
  • cpa é spend dividido por conversions, e roas é a venda atribuída dividida por spend. Com divisor zero, o valor fica vazio.
  • Uma conta sem rastreio de conversão configurado deixa ad_conversions_daily vazia.

​
Permissões (ACL)

Esta fonte não define permissões por registro, então todo mundo que puder usar o conector vê todos os registros. Quem pode usar o conector é definido em Quem pode usar este conector: “Todos os usuários” ou “Apenas times específicos”. O Comportamento dos dados deste conector é sempre “Aberto”.

​
Como a fonte define acesso

A API do OpenAI Ads não expõe usuários, papéis nem membros da conta de anúncios. A chave enxerga a conta inteira.

​
Como a Strattum traduz o acesso

A Strattum não grava permissão por item. Todas as linhas ficam visíveis para quem pode usar o conector. O conector não oferece Exigir login na fonte como prova de identidade.

​
Quando a identidade não é encontrada

Não se aplica: nenhuma linha depende da identidade de quem consulta.

​
Quando a permissão é atualizada

Não há permissão da fonte para atualizar. O acesso depende só de Quem pode usar este conector.

​
Pré-requisitos

  • Uma conta de anúncios ativa no OpenAI Ads.
  • Acesso à página Settings do Ads Manager, onde a API key é criada. A documentação do OpenAI Ads não informa qual papel na conta é exigido para criar a chave.
  • Uma só conexão OpenAI Ads por instalação da Strattum, que cobre uma conta de anúncios.

​
Autenticação e escopos

A autenticação usa uma API key enviada no cabeçalho Authorization como Bearer. Cada chave vale para uma única conta de anúncios. A chave não tem escopos por recurso: ela lê tudo o que o conector usa.
1

Abra as configurações

No Ads Manager do OpenAI Ads, abra Settings.
2

Crie a chave

Crie uma API key para a conta de anúncios que você quer conectar.
3

Copie a chave

Copie o valor e guarde. Você o informa no Console.

​
Configuração no Console

1

Abra o assistente

Em Conectores, clique em + Nova Conexão e selecione OpenAI Ads.
2

Preencha a conexão

Nome do Conector (Opcional): como a conexão aparece na lista. O padrão é OpenAI Ads.API Key (Obrigatório): a chave criada no Ads Manager.
3

Teste a conexão

Clique em Testar Conexão. Você só avança depois de um teste com sucesso. A mensagem de sucesso mostra o nome da conta de anúncios encontrada.
4

Escolha a frequência

Em Sincronização (Obrigatório), escolha a frequência. A referência do conector é A cada 6h.
5

Defina o acesso

Em Permissionamento, defina Quem pode usar este conector. O Comportamento dos dados é sempre “Aberto”.
6

Revise e salve

Em Revisão, confira os dados e salve. Depois, no Data Catalog, ligue os recursos que você quer carregar. Para o modelo de desempenho diário, ligue os seis.

​
Como a sincronização funciona

A frequência vem do passo Sincronização. O padrão do tipo de conector é uma execução a cada 6 horas. Ordem. Cada execução testa a chave e depois lê os recursos selecionados um por um, na ordem da tabela de recursos. Recurso desligado no Data Catalog não é lido. Todas as chamadas saem uma por vez. Hierarquia em full refresh. ad_account, campaigns, ad_groups e ads são reescritos por inteiro a cada execução. O conector percorre campanhas, depois os grupos de cada campanha, depois os anúncios de cada grupo, e grava em cada linha o id do pai, que a API não devolve. Um item apagado no OpenAI Ads some da tabela na execução seguinte. Fatos em incremental. Cada execução relê, a partir do dia da última execução menos 30 dias, até hoje, e substitui as linhas lidas pela chave anúncio e dia. A releitura existe porque gasto e impressões continuam mudando depois do dia, e uma conversão pode ser atribuída a um clique de até 30 dias antes. O cursor é o instante da execução (fetched_at), igual em todas as linhas daquela execução. Primeira carga. Sem cursor, o conector lê os últimos 365 dias, contando o dia de hoje, que é o máximo que o OpenAI Ads guarda e aceita por consulta. Full Refresh do Console. A ação Full Refresh apaga o cursor dos fatos e dispara uma execução. Ela relê os 365 dias e mescla o resultado com a tabela: os dias da janela são corrigidos e os dias mais antigos continuam lá. A tabela nunca é truncada. Conversões. A API de conversões pede a lista de anúncios. Por isso, toda execução de ad_conversions_daily percorre campanhas, grupos e anúncios, mesmo que ads esteja desligado. Os anúncios vão em lotes, para que cada consulta devolva no máximo 2.000 linhas (anúncios vezes dias). Paginação. As listagens seguem o cursor da API enquanto ela indicar que há mais páginas, com 500 itens por página na hierarquia e 2.000 nos insights. Se a API indicar mais páginas sem devolver cursor, o recurso falha em vez de gravar uma leitura incompleta. Remoção. Na hierarquia, o full refresh reflete a remoção. Nos fatos, uma linha já gravada só é substituída por outra do mesmo anúncio e dia. Um anúncio apagado na fonte some de ads, mas os dias dele continuam em ad_insights_daily e ad_conversions_daily.

​
API da fonte

A consulta POST /v1/conversions/insights só lê dados. Rate limits. O OpenAI Ads limita a API a 600 requisições por minuto por endpoint e 1.200 por minuto no total, e a requisição precisa respeitar ao mesmo tempo o limite da conta de anúncios e o do endereço IP. A documentação não diz que resposta vem no estouro. O conector envia uma requisição por vez, com tempo limite de 60 segundos. Diante de um 429, espera o Retry-After quando ele vem (no mínimo 1 segundo), soma no máximo 900 segundos de espera por requisição e tenta de novo. Erros 5xx têm até 5 tentativas com recuo crescente. Conexão interrompida é repetida nas leituras GET, e não na consulta POST de conversões. Se o recurso ainda assim falhar, a execução tenta o recurso de novo até 3 vezes, depois de 30, 60 e 120 segundos. Referência oficial: OpenAI Ads, visão geral da API

​
Limitações conhecidas

  • Sem permissão por item: todo usuário que pode usar o conector vê todos os dados da conta. Para restringir, limite Quem pode usar este conector.
  • Uma conexão OpenAI Ads por instalação, e portanto uma conta de anúncios. O Console recusa uma segunda conexão do mesmo tipo.
  • Os valores de conversão e de vendas atribuídas foram conferidos só na forma, com uma conta sem evento de conversão. Confira os números contra o Ads Manager na primeira carga com conversões reais.
  • Uma correção na fonte só é capturada enquanto o dia estiver na janela de 30 dias antes da última execução. Para corrigir dias mais antigos, use Full Refresh, que relê os últimos 365 dias.
  • Dias com mais de 365 dias que ainda não foram lidos não podem ser recuperados: o OpenAI Ads não os devolve.
  • Só entram dias com entrega em ad_insights_daily e dias com conversão em ad_conversions_daily. Dias zerados não geram linha.
  • O conector não troca a janela de atribuição: vale o padrão da API.
  • Não há quebra por país, dispositivo ou hora, nem métricas por campanha ou grupo além da soma dos anúncios.
  • Ficam de fora o histórico de alterações da conta, públicos, leads, pixels e eventos de conversão.
  • Não há conversão de moeda.

​
Troubleshooting

​
Próximos passos

Data Catalog

Ligue os recursos do OpenAI Ads e acompanhe a carga de cada tabela.

Memory

Veja como contas, campanhas, grupos e anúncios entram no grafo.
O conector não lê variáveis do .env. A API key é informada no Console e fica no cofre de segredos da plataforma, sob o nome OPENAI_ADS_API_KEY. Para testar localmente, crie a conexão pelo Console da stack local.