# Como funciona a API de Conversões da OpenAI Ads

A **API de Conversões da OpenAI Ads** envia para a OpenAI, direto do sistema, o que acontece com os leads e os negócios da imobiliária. Com isso, você acompanha no Gerenciador de Anúncios da OpenAI quais campanhas trouxeram contatos e quais desses contatos avançaram no funil, foram ganhos ou foram perdidos. Como o envio parte do sistema, ele não depende do navegador do visitante.

Você configura a integração uma vez. Depois disso, o sistema envia os eventos sozinho: quando um lead é cadastrado e quando um negócio muda de etapa, é ganho, é perdido ou é excluído. Cada envio fica registrado no histórico do lead ou do negócio.

Para configurar a integração, você precisa da permissão **Configurações > Integrações > Integrações > Editar** (ou de **Administrar Configurações**). Para escolher o evento de cada etapa do funil, você precisa da permissão **Negócios > Etapas para Negócios > Editar**.

---

#### **Navegação no módulo**

[![Tela Editando Integrações com Aplicativos de Terceiros com o cartão API de Conversões da OpenAI Ads destacado ao lado do cartão API de Conversões do Meta](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-1.png)](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-1.png)

**Rotina:** Configurações > Integrações > Integrações > cartão **API de Conversões da OpenAI Ads**

A tela abre com o título **Editando Integrações com Aplicativos de Terceiros**. Localize o cartão **API de Conversões da OpenAI Ads**, que fica logo depois do cartão **API de Conversões do Meta**.

---

#### **Antes de começar**

Você vai precisar de duas informações da conta de anúncios da imobiliária na OpenAI.

<table id="bkmrk-informa%C3%A7%C3%A3oonde-encon" style="width: 100%; table-layout: fixed; hyphens: manual;"><colgroup><col style="width: 150px;"></col><col></col></colgroup><tbody><tr><th>Informação

</th><th>Onde encontrar

</th></tr><tr><td>**Pixel ID**

</td><td>Na aba **Conversões** do Gerenciador de Anúncios da OpenAI.

</td></tr><tr><td>**Chave de API**

</td><td>É a chave fornecida pela OpenAI para o envio de conversões. A janela de configuração traz o link **Documentação**, que leva às instruções da própria OpenAI.

</td></tr></tbody></table>

<p class="callout info">Se tiver dúvida sobre onde gerar a Chave de API na sua conta da OpenAI, consulte o suporte.</p>

---

#### **Ativar a integração**

No rodapé do cartão, ligue a chave **Ativo**. A alteração é gravada na mesma hora.

O botão **Configurar** só fica disponível com a chave **Ativo** ligada.

O ícone no canto do cartão mostra a situação da integração:

<table id="bkmrk-%C3%8Dconeo-que-significa" style="width: 100%; table-layout: fixed; hyphens: manual;"><colgroup><col style="width: 169px;"></col><col></col></colgroup><tbody><tr><th>Ícone

</th><th>O que significa

</th></tr><tr><td>**Visto verde**

</td><td>"Integração está ativa". A chave Ativo está ligada e o Pixel ID e a Chave de API estão preenchidos.

</td></tr><tr><td>**Alerta laranja**

</td><td>A chave Ativo está ligada, mas faltam credenciais. A mensagem diz "Configure o Pixel ID e a Chave de API para ativar o envio de eventos."

</td></tr><tr><td>**X vermelho**

</td><td>"A integração está desativada".

</td></tr></tbody></table>

<p class="callout warning">Com a chave **Ativo** desligada, nenhum evento é enviado à OpenAI Ads, nem de lead, nem de funil. Isso vale mesmo que as outras opções da configuração continuem ligadas.</p>

---

#### **Informar as credenciais**

[![Janela API de Conversões da OpenAI Ads no painel Configurações, com o aviso sobre o Pixel do site e os campos Pixel ID e Chave de API preenchidos](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-2.png)](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-2.png)

Clique em **Configurar**. A janela **API de Conversões da OpenAI Ads** abre no painel **Configurações**. Preencha os campos:

<table id="bkmrk-campodescri%C3%A7%C3%A3oobriga" style="width: 100%; table-layout: fixed; hyphens: manual;"><colgroup><col style="width: 150px;"></col><col></col><col style="width: 145px;"></col></colgroup><tbody><tr><th>Campo

</th><th>Descrição

</th><th>Obrigatório

</th></tr><tr><td>Pixel ID

</td><td>Identificador do Pixel da OpenAI que vai receber os eventos. Fica na aba Conversões do Gerenciador de Anúncios.

</td><td>Sim

</td></tr><tr><td>Chave de API

</td><td>Chave que autoriza o envio dos eventos. O campo esconde o conteúdo digitado. O botão ao lado, **Copiar a chave de API**, copia a chave.

</td><td>Sim

</td></tr></tbody></table>

Clique em **Gravar** para gravar e fechar a janela, ou em **Gravar e Continuar** para gravar e seguir na configuração.

Sem os dois campos preenchidos, a integração não envia nada e o cartão continua com o alerta laranja.

<p class="callout warning">A Chave de API é uma credencial de segurança. Trate-a como uma senha e não a compartilhe. Só quem tem permissão para gravar esta configuração consegue ver a chave.</p>

---

#### **Enviar o evento de lead criado**

No painel **Lead Criado**, ligue a chave **Enviar evento de lead criado ao cadastrar lead no sistema** e grave.

Com ela ligada, cada lead novo cadastrado no sistema, inclusive o cadastrado à mão em Pessoas &gt; Leads, gera o evento **Lead criado** para a OpenAI. O envio acontece uma única vez, no cadastro. Editar o lead depois não gera um novo envio.

<p class="callout info">Leads trazidos por importação de arquivo não são enviados à OpenAI.</p>

---

#### **Enviar eventos do funil de negócios**

[![Painel Funil de Negócio com Enviar eventos de funil ligado e a lista do campo Evento ao Ganhar aberta](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-3.png)](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-3.png)

Além do lead, a integração pode contar à OpenAI o que acontece durante a negociação. Assim a OpenAI consegue otimizar as campanhas pela qualidade das oportunidades, e não só pelo volume de cadastros.

No painel **Funil de Negócio**, ligue a chave **Enviar eventos de funil (troca de etapa, ganho, perda e exclusão)**. Logo abaixo aparecem três campos:

<table id="bkmrk-campodescri%C3%A7%C3%A3oobriga-1" style="width: 100%; table-layout: fixed; hyphens: manual;"><colgroup><col style="width: 196px;"></col><col></col><col style="width: 145px;"></col></colgroup><tbody><tr><th>Campo

</th><th>Descrição

</th><th>Obrigatório

</th></tr><tr><td>Evento ao Ganhar

</td><td>Evento enviado quando o negócio é marcado como ganho. Em branco, é enviado o evento **Venda ou locação concluída**. O evento de ganho leva junto o valor do negócio (campo **Valor**), quando ele está preenchido.

</td><td>Não

</td></tr><tr><td>Evento ao Perder

</td><td>Evento enviado quando o negócio é marcado como perdido. Em branco, é enviado um evento personalizado de negócio perdido.

</td><td>Não

</td></tr><tr><td>Evento ao Excluir

</td><td>Evento enviado quando o negócio é excluído. Em branco, é enviado um evento personalizado de negócio excluído.

</td><td>Não

</td></tr></tbody></table>

Os três campos são listas, porque a OpenAI só aceita estes eventos:

- Lead criado
- Visita ou reunião agendada
- Cadastro concluído
- Imóvel visualizado
- Imóvel adicionado à seleção
- Negociação iniciada
- Venda ou locação concluída
- Página visualizada
- Assinatura iniciada
- Período de teste iniciado
- Evento personalizado (leva o nome da etapa)

A troca de etapa usa o evento escolhido no cadastro de cada etapa, como mostra a próxima seção.

---

#### **Escolher o evento em cada etapa do funil**

[![Janela Etapa de Negócio com a lista do campo Evento (OpenAI Ads Conversions API) aberta, abaixo do campo Nome do Evento (Meta Conversions API)](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-4.png)](https://ajuda.apresenta.me/uploads/images/gallery/2026-10/openai-ads-4.png)

**Rotina:** Configurações &gt; Negócios &gt; aba **Funis**

Na aba **Funis**, localize o funil e clique no lápis da etapa desejada (**Editar esta Etapa do Funil**). A janela **Etapa de Negócio** abre.

No campo **Evento (OpenAI Ads Conversions API)**, escolha o evento que deve ser enviado à OpenAI quando um negócio entrar nessa etapa. Depois clique em **Gravar**.

Se você deixar o campo em branco, a etapa não fica de fora: o sistema envia um evento personalizado com o título da etapa. Assim as etapas continuam diferentes umas das outras no Gerenciador de Anúncios.

<p class="callout info">Só o evento personalizado leva junto os dados da etapa, como o título da etapa, a etapa anterior e o funil. Ao escolher qualquer outro evento da lista, a OpenAI recebe apenas o evento.</p>

Repita nas outras etapas que quiser acompanhar. O mesmo campo aparece ao criar uma etapa nova, pelo botão **Adicionar uma nova Etapa de Negócio**.

<p class="callout warning">O campo aparece em todas as etapas, mesmo com a integração desligada. Ele só tem efeito com a chave **Ativo** do cartão ligada e com a opção **Enviar eventos de funil** ativada.</p>

---

#### **Utilizar o modo de teste**

No painel **Modo de Teste**, a chave **Enviar eventos como teste** serve para validar a integração antes de usar os eventos de verdade.

Enquanto ela estiver ligada, a OpenAI confere cada evento, mas não o grava. No histórico do lead e do negócio, os registros de envio aparecem com a marca **\[TESTE\]**, para não serem confundidos com eventos reais.

<p class="callout warning">Com o modo de teste ligado, nenhuma conversão fica registrada na OpenAI. Depois de validar, desligue a chave e clique em **Gravar**.</p>

---

#### **Conferir se a integração funcionou**

1. Com o Pixel ID e a Chave de API preenchidos, ligue **Enviar eventos como teste** e clique em **Gravar**.
2. Cadastre um lead de teste em Pessoas &gt; Leads, com e-mail ou telefone.
3. Abra o lead e clique no botão de histórico (**Abrir janela de históricos**).
4. Confira se aparece a mensagem "\[TESTE\] Lead enviado para a API de Conversões da OpenAI Ads.". Se aparecer uma mensagem de erro, veja a seção **Quando o envio não acontece**.
5. Para testar o funil, vá em Negócios &gt; Negócios em Painel, mova para outra etapa um negócio que tenha lead vinculado e confira o histórico do negócio.
6. Depois de validar, desligue **Enviar eventos como teste** e grave.

---

#### **O que aparece no lead e no negócio**

A integração não muda nenhum campo do lead nem do negócio. O resultado de cada envio aparece no histórico:

<table id="bkmrk-ondemensagemquando-a" style="width: 100%; table-layout: fixed; hyphens: manual;"><colgroup><col style="width: 300px;"></col><col style="width: 300px;"></col><col></col></colgroup><tbody><tr><th>Onde

</th><th>Mensagem

</th><th>Quando aparece

</th></tr><tr><td>Histórico do lead

</td><td>"Lead enviado para a API de Conversões da OpenAI Ads."

</td><td>O evento de lead criado foi enviado.

</td></tr><tr><td>Histórico do negócio

</td><td>"Negócio enviado para a API de Conversões da OpenAI Ads (evento...)."

</td><td>Um evento de troca de etapa, ganho, perda ou exclusão foi enviado. Entre parênteses aparece o nome do evento, do jeito que a OpenAI o recebe.

</td></tr><tr><td>Histórico do lead ou do negócio

</td><td>"Erro ao enviar para a API de Conversões da OpenAI Ads:" seguido do motivo

</td><td>O envio não aconteceu ou foi recusado pela OpenAI.

</td></tr></tbody></table>

Com o modo de teste ligado, essas mensagens começam com **\[TESTE\]**.

Logo abaixo de cada mensagem, o histórico guarda os dados que foram enviados à OpenAI. Esse complemento fica disponível por 3 meses. A mensagem de envio continua no histórico depois disso.

No cadastro do lead, o campo **Código da Campanha** mostra o código do anúncio quando o lead veio de uma campanha paga, inclusive dos anúncios do ChatGPT (OpenAI).

---

#### **Quando o envio não acontece**

- **Chave Ativo desligada:** nada é enviado, nem de lead, nem de funil.
- **Pixel ID ou Chave de API em branco:** nada é enviado.
- **Chave do lead ou do funil desligada:** com **Enviar evento de lead criado ao cadastrar lead no sistema** desligada, os leads não são enviados. Com **Enviar eventos de funil** desligada, os negócios não são enviados.
- **Lead importado:** leads trazidos por importação de arquivo não são enviados.
- **Lead sem e-mail e sem telefone:** a OpenAI não teria como reconhecer a pessoa. O evento não é enviado e o histórico mostra o motivo "evento omitido (sem identificador de contato)". A exceção é quando o site envia junto a identificação do navegador do visitante.
- **Data do Contato antiga:** lead com **Data do Contato** de mais de 7 dias atrás não é enviado, e o histórico registra que o evento foi ignorado.
- **Data do Contato no futuro:** lead com **Data do Contato** mais de 10 minutos à frente do horário atual não é enviado. O histórico mostra "evento ignorado (data do evento mais de 10 minutos no futuro)".
- **Negócio sem lead vinculado:** nada é enviado e nada aparece no histórico do negócio. Os dados de contato usados nos eventos do negócio vêm do lead mais recente vinculado a ele.
- **Negócio recém-cadastrado:** a entrada do negócio na primeira etapa, no momento do cadastro, não gera evento. O envio acontece nas trocas de etapa seguintes.

---

#### **Deduplicação com o Pixel do site**

Se o site da imobiliária também usa o Pixel da OpenAI, o mesmo lead pode aparecer duas vezes nos relatórios do Gerenciador de Anúncios: uma vez registrado pelo site e outra pelo sistema. Segundo o aviso da própria tela, isso não afeta o funcionamento das campanhas.

Para evitar a contagem dupla, o Pixel do site precisa reaproveitar o identificador que o sistema publica depois do envio do formulário. O painel **Deduplicação com o Pixel do Site**, na janela da integração, traz as instruções técnicas. Repasse-as a quem cuida das tags do seu site.

O mesmo painel orienta a enviar junto do lead o código de clique do anúncio e a referência de navegador do Pixel. São essas informações que permitem à OpenAI atribuir a conversão à campanha certa.

<p class="callout info">Para saber se o seu site já faz essa configuração, consulte o suporte.</p>

---

#### **Diferenças em relação à integração com o Meta**

As duas integrações funcionam lado a lado, cada uma com a própria configuração. Ligar uma não liga a outra, e a mesma etapa do funil pode ter um evento diferente para cada uma.

<table id="bkmrk-pontoapi-de-convers%C3%B5" style="width: 100%; table-layout: fixed; hyphens: manual;"><colgroup><col style="width: 300px;"></col><col style="width: 300px;"></col><col></col></colgroup><tbody><tr><th>Ponto

</th><th>API de Conversões do Meta

</th><th>API de Conversões da OpenAI Ads

</th></tr><tr><td>Credenciais

</td><td>Pixel ID e Access Token

</td><td>Pixel ID e Chave de API

</td></tr><tr><td>Evento de lead

</td><td>Lead

</td><td>Lead criado

</td></tr><tr><td>Eventos de ganho, perda, exclusão e etapa

</td><td>Nome digitado livremente

</td><td>Escolhido em uma lista, porque a OpenAI recusa nomes fora dela

</td></tr><tr><td>Campo na etapa do funil

</td><td>Nome do Evento (Meta Conversions API)

</td><td>Evento (OpenAI Ads Conversions API)

</td></tr><tr><td>Modo de teste

</td><td>Usa o Test Event Code gerado no Meta

</td><td>Não tem código: a OpenAI só confere o evento, sem gravar

</td></tr></tbody></table>

---

#### **Perguntas frequentes**

➜ **Liguei a integração e nada aparece no histórico do lead. O que devo verificar?** Confira se a chave **Ativo** do cartão está ligada, se o Pixel ID e a Chave de API estão preenchidos e se a chave **Enviar evento de lead criado ao cadastrar lead no sistema** está ligada. Lembre que só leads cadastrados depois disso são enviados, e que leads importados ficam de fora.

➜ **Mudei um negócio de etapa e não apareceu nada no histórico. Por quê?** Confira se a chave **Enviar eventos de funil** está ligada e se o negócio tem um lead vinculado. Negócio sem lead vinculado não gera envio.

➜ **Posso digitar o nome do evento, como faço no Meta?** Não. A OpenAI só aceita os eventos da lista, por isso os campos são de seleção. Para identificar uma etapa pelo nome, deixe o campo em branco: o sistema envia um evento personalizado com o título da etapa.

➜ **Preciso escolher um evento em todas as etapas?** Não. Etapa sem evento escolhido também é enviada, como evento personalizado com o título da etapa.

➜ **Os dados do cliente são enviados abertos para a OpenAI?** Não. Antes de sair do sistema, o e-mail, o telefone e o nome do lead são convertidos, de forma irreversível, em uma sequência que não revela o dado original.

➜ **Posso usar a OpenAI Ads e o Meta ao mesmo tempo?** Sim. Cada integração tem a própria configuração e envia os próprios eventos. Desligar uma não interfere na outra.