> ## Documentation Index > Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Ads > Estrutura da conta de anúncios do OpenAI Ads e métricas diárias de entrega e conversão por anúncio, no Data Catalog e no Memory. 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. | | | | - | - | | **Status** | Disponível | | **Conteúdo** | Registros | | **Autenticação** | API key | | **Permissões** | Sem permissão por item | | **Sincronização** | Incremental e full refresh, por recurso | | **Última revisão** | 07/10/2026 | ## 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. | Recurso | O que contém | Carga | Cursor | Destino | Permissão por item | | - | - | - | - | - | - | | `ad_account` | A conta de anúncios da chave, com `currency_code`, `timezone` e `status` | Full refresh | — | Catálogo e Memory | Não | | `campaigns` | Campanhas, com `objective`, `status`, orçamento, `targeting` e datas | Full refresh | — | Catálogo e Memory | Não | | `ad_groups` | Grupos de anúncios, com a campanha de origem e a configuração de lance | Full refresh | — | Catálogo e Memory | Não | | `ads` | Anúncios, com campanha, grupo, `review_status` e criativo | Full refresh | — | Catálogo e Memory | Não | | `ad_insights_daily` | Uma linha por anúncio e dia com entrega: `spend`, `impressions`, `clicks`, `ctr`, `cpc` e `cpm` | Incremental, fixo | `fetched_at` | Catálogo e Memory | Não | | `ad_conversions_daily` | Uma linha por anúncio e dia com conversão: `conversions`, `click_through_conversions`, `view_through_conversions` e vendas atribuídas | Incremental, fixo | `fetched_at` | Catálogo e Memory | Não | `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. > [!NOTE] > > 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. | Escopo ou permissão | Para quê | | - | - | | API key da conta de anúncios | Ler a conta, as campanhas, os grupos, os anúncios, os insights e as conversões. | **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 | Método e caminho | Usado para | Recurso | | - | - | - | | `GET /v1/ad_account` | Testar a chave e ler a conta, a moeda e o fuso | Todos | | `GET /v1/campaigns` | Listar campanhas | `campaigns`, `ad_groups`, `ads`, `ad_conversions_daily` | | `GET /v1/ad_groups?campaign_id=` | Listar os grupos de cada campanha | `ad_groups`, `ads`, `ad_conversions_daily` | | `GET /v1/ads?ad_group_id=` | Listar os anúncios de cada grupo | `ads`, `ad_conversions_daily` | | `GET /v1/ad_account/insights` | Métricas diárias de entrega por anúncio | `ad_insights_daily` | | `POST /v1/conversions/insights` | Conversões diárias por anúncio | `ad_conversions_daily` | 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](https://developers.openai.com/ads/api-overview) ## 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 | Mensagem ou sintoma | Causa | O que fazer | | - | - | - | | Informe a API key do OpenAI Ads. | O campo **API Key** está vazio. | Cole a chave criada em **Settings** no Ads Manager. | | A OpenAI recusou a API key. | A chave está incompleta, foi revogada ou não é do OpenAI Ads. | Confira se copiou a chave inteira. Se precisar, crie uma nova em **Settings**. | | Muitas requisições ao OpenAI Ads. | O limite de requisições da conta ou do IP foi atingido. | Aguarde alguns instantes e teste de novo. | | Não foi possível contatar a API do OpenAI Ads. | Falha de rede até `api.ads.openai.com`. | Verifique a conectividade de rede e tente novamente. | | Erro ao testar a conexão com o OpenAI Ads (HTTP …). | A API respondeu com outro erro. | Tente novamente. Se o erro persistir, contate o suporte do OpenAI Ads. | | Já existe um conector do tipo openai\_ads. | A instalação já tem uma conexão OpenAI Ads. | Edite a conexão existente ou remova-a antes de criar outra. | | A execução falha logo no início. | A chave deixou de funcionar depois da criação. | Troque a chave na edição do conector e rode de novo. | | `openai_ads_ad_performance_daily` não aparece ou vem sem nomes de campanha. | Algum dos seis recursos está desligado no Data Catalog. | Ligue os seis recursos e rode a sincronização. | | `ad_conversions_daily` vazia. | A conta não tem rastreio de conversão, ou ainda não houve conversão atribuída. | Configure a fonte e o evento de conversão no Ads Manager. | ## Próximos passos > **[Data Catalog](/data-catalog/overview)** > > Ligue os recursos do OpenAI Ads e acompanhe a carga de cada tabela. > **[Memory](/memory/overview)** > > Veja como contas, campanhas, grupos e anúncios entram no grafo. > **Desenvolvimento local** > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.