Ads
Listar pixels e eventos de conversão do Meta Ads pela API
Duas rotas mostram os pixels da conta de anúncios do cliente e os eventos que cada pixel registrou, com a contagem do período. O id do pixel vai no conjunto de anúncios otimizado para conversão, e você lê tudo pela conexão do cliente, sem implementar a API da Meta.
A chamada
GET /api/ads/facebook_ads/pixels/900000000000001/events?customer_integration=<connection uuid> Authorization: Bearer <merchant token> x-customer-token: <customer token>
O que dá para fazer
- Listar os pixels da conta com GET /ads/facebook_ads/pixels, com id, nome, last_fired_at, created_at e is_unavailable.
- Ver os eventos que um pixel registrou com GET /ads/facebook_ads/pixels/{id}/events, com event_name e count.
- Usar o id do pixel em adset.facebook_ads.promoted_object.pixel_id num conjunto otimizado para conversão.
- Forçar uma leitura nova da plataforma com refresh=true.
Regras e limites
- A contagem de eventos cobre os últimos 90 dias, a janela que a integração usa para que eventos raros não desapareçam.
- Não é paginada: vêm no máximo 200 itens por leitura.
- Cache de 600 s por conexão. meta.cached e meta.cached_at mostram se veio do cache, e refresh=true ignora.
- Um id de pixel que não é da conta da conexão responde 404 ads_object_not_found.
- A conexão vai sempre em ?customer_integration= e a chamada exige Authorization e x-customer-token.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customer_integration | string | Sim | uuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query. |
| id | string | Sim | Em /pixels/{id}/events: o id do pixel, vindo de GET /ads/facebook_ads/pixels. |
| refresh | boolean | Não | Ignora o cache de 600 s e busca de novo na plataforma. |
| event_name | string | Não | Na resposta: o nome do evento que o pixel registrou. |
| count | integer | Não | Na resposta: quantas vezes o evento ocorreu nos últimos 90 dias. |
| last_fired_at | string | Não | Na lista de pixels: quando o pixel disparou pela última vez. |
| is_unavailable | boolean | Não | Na lista de pixels: indica se o pixel está indisponível. |
Para quem
Checar o pixel antes de subir a campanha
Seu SaaS confere se o pixel do cliente registrou Purchase nos últimos 90 dias antes de permitir otimizar por compra.
Diagnóstico de rastreamento numa agência
Uma agência lista os pixels e a data do último disparo para achar quem parou de funcionar.
Agente de IA que escolhe o evento
Um agente lê os eventos do pixel, escolhe o de maior volume e configura o conjunto de anúncios com ele.
Funciona com
Meta Ads
Perguntas frequentes
Qual o período da contagem de eventos?
Os últimos 90 dias, a janela que a integração usa para que eventos raros não desapareçam.
Onde uso o id do pixel?
Em adset.facebook_ads.promoted_object.pixel_id, num conjunto de anúncios otimizado para conversão.
Como sei se o pixel está funcionando?
GET /ads/facebook_ads/pixels traz last_fired_at e is_unavailable, e a rota de eventos mostra quais eventos chegaram e quantas vezes.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
