API de anúncios — contas de anúncios da Meta e resumo por anúncio

• Contas de anúncios — conecte as contas de anúncios da Meta cujos anúncios trazem pessoas aos seus números, para a Pilot Status resolver o nome de cada anúncio, do conjunto de anúncios e da campanha.
• Resumo de anúncios — o tráfego Click-to-WhatsApp agrupado por anúncio: conversas, mensagens, os nomes resolvidos e quantos leads do Lead Ads cada anúncio gerou.

​

Endpoints

​

Sem login na Meta: compartilhamento de parceiro

​

Credenciais e permissões

​

GET /v1/ads/accounts

curl https://pilotstatus.com.br/v1/ads/accounts \
  -H "x-api-key: ps_..."

{
  "linked": [
    {
      "adAccountId": "act_1234567890",
      "adAccountName": "MM Design",
      "linkedAt": "2026-10-05T14:02:11.000Z",
      "sharingActive": true
    }
  ],
  "candidates": [
    { "adAccountId": "act_9876543210", "adAccountName": "MM Design — Black Friday", "accountStatus": 1 }
  ],
  "partnerBusinessId": "123456789012345",
  "sharingLookup": "ok"
}

• sharingActive — true enquanto a concessão de parceiro continua valendo, false quando o anunciante a revogou na Meta e null quando não foi possível consultar a Meta agora. Nunca leia null como revogada.
• candidates — contas compartilhadas com a Pilot Status que comprovadamente são do seu workspace, porque um anúncio delas já chegou a um dos seus números, e ainda não vinculadas. Um workspace novo começa com a lista vazia; vincule a sua conta pelo id.
• sharingLookup — ok, unavailable (a Meta não respondeu; linked volta mesmo assim) ou not_configured.

​

POST /v1/ads/accounts

curl -X POST https://pilotstatus.com.br/v1/ads/accounts \
  -H "x-api-key: ps_..." \
  -H "Content-Type: application/json" \
  -d '{ "adAccountId": "act_1234567890" }'

1. A conta precisa ser sua. Se nenhum anúncio dela chegou às suas conversas ainda, a resposta é 409 AD_ACCOUNT_NOT_PROVEN — fale com o suporte para vinculá-la.
2. A concessão de parceiro precisa ter chegado à Meta. Senão, 409 AD_ACCOUNT_NOT_SHARED.

​

DELETE /v1/ads/accounts/{adAccountId}

​

GET /v1/ads/summary

curl "https://pilotstatus.com.br/v1/ads/summary?startDate=2026-10-01T00:00:00Z" \
  -H "x-api-key: ps_..."

{
  "ads": [
    {
      "sourceId": "120249828053880703",
      "sourceType": "ad",
      "conversations": 37,
      "messages": 214,
      "firstAt": "2026-10-02T11:04:19.000Z",
      "lastAt": "2026-10-20T22:41:07.000Z",
      "lastSourceUrl": "https://fb.me/2bXyZ",
      "lastHeadline": "Reforma com 70% de desconto",
      "adName": "Ads 01 - Vídeo dos 70%",
      "adsetId": "120249828053880001",
      "adsetName": "[IG] [LL1% IG + VÍDEOS] - 35 a 50",
      "campaignId": "120249828053870000",
      "campaignName": "[CD-01] [LEADS] - MM Design - Sale 70%",
      "namesResolvedAt": "2026-10-20T23:00:02.000Z",
      "leadCount": 12
    }
  ],
  "total": 1,
  "limit": 200,
  "truncated": false
}

• conversations e messages são contagens separadas: conversas distintas, e mensagens.
• leadCount — leads do Lead Ads que o mesmo anúncio gerou, no mesmo escopo de números e intervalo de datas. Um anúncio que gerou leads mas nunca uma conversa não tem linha aqui: consulte-o em GET /v1/leads.
• Nomes: namesResolvedAt preenchido com todos os nomes null significa que a Pilot Status perguntou à Meta e não recebeu nada — em geral falta a concessão de parceiro. null significa que ainda não perguntou.
• Privacidade: lastHeadline e lastSourceUrl (o texto do anúncio) vêm null para um anúncio visto só em número RELAY_ONLY. As contagens não mudam. O resumo nunca traz conteúdo de conversa.
• Limite: no máximo 200 anúncios, os mais movimentados primeiro. truncated: true avisa que a lista foi cortada — restrinja com startDate/endDate.

​

Erros