> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Resumo de anúncios (CTWA) > Agrupa o tráfego de Click-to-WhatsApp do número vinculado por anúncio/post, ordenado por número de conversas desc. `conversations` conta conversas DISTINTAS e `messages` conta mensagens — duas mensagens da mesma conversa são 1 conversa e 2 mensagens. `lastSourceUrl` e `lastHeadline` vêm da mensagem mais recente daquele anúncio: a copy pode ser editada, e a útil é a última que a Meta enviou. A lista tem teto de 200 anúncios; quando estoura, `truncated` vem `true` e um `notice` explica — estreite a janela com startDate/endDate. `referral.sourceId` é o **id do anúncio (ou do post)** da Meta, exposto como chave opaca de agrupamento. Não há nome de campanha nem de conjunto aqui, e isso não é omissão: ler o objeto do anúncio (`GET /{ad_id}?fields=id,name,adset{id,name},campaign{id,name}`) exige a permissão `ads_read` na conta de anúncios do anunciante, e o token de usuário de sistema por trás de um número conectado carrega apenas `whatsapp_business_management` e `whatsapp_business_messaging`. Para resolver os nomes, chame a Marketing API da Meta com um token autorizado naquela conta, usando este `sourceId`. Privacidade (PII): os CONTADORES seguem corretos num número RELAY_ONLY (saem da identidade do anúncio, que não é dado pessoal); só `lastSourceUrl` e `lastHeadline` voltam nulos, com `piiNotice: "PII_RELAY_ONLY"`. **Requer key escopada a número.** O objeto `referral` também traz os nomes RESOLVIDOS do anúncio — `adName`, `adsetId`, `adsetName`, `campaignId`, `campaignName` — e mais `namesResolvedAt`. ⚠️ Esses seis voltam **null** enquanto o anunciante não tiver compartilhado aquela conta de anúncios com o portfólio empresarial da Pilot Status como parceiro. Nome nulo é estado SUPORTADO, não erro: a conversa continua contada e o `sourceId` continua vindo. Nenhum endpoint resolve nome sob demanda — a resolução é assíncrona, fora do caminho da requisição, então consultar nunca dispara chamada à Marketing API e um null pode virar nome minutos depois sem você fazer nada. O `namesResolvedAt` é o que torna isso observável: null significa "ainda não resolvido", enquanto data preenchida com nomes nulos significa "perguntamos e a Meta não devolveu" (anúncio apagado, ou compartilhamento ausente). ## OpenAPI ````yaml openapi.pt.json GET /v1/referrals/summary openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/referrals/summary: get: tags: - Conversations summary: Resumo de anúncios (CTWA) description: >- Agrupa o tráfego de Click-to-WhatsApp do número vinculado por anúncio/post, ordenado por número de conversas desc. `conversations` conta conversas DISTINTAS e `messages` conta mensagens — duas mensagens da mesma conversa são 1 conversa e 2 mensagens. `lastSourceUrl` e `lastHeadline` vêm da mensagem mais recente daquele anúncio: a copy pode ser editada, e a útil é a última que a Meta enviou. A lista tem teto de 200 anúncios; quando estoura, `truncated` vem `true` e um `notice` explica — estreite a janela com startDate/endDate. `referral.sourceId` é o **id do anúncio (ou do post)** da Meta, exposto como chave opaca de agrupamento. Não há nome de campanha nem de conjunto aqui, e isso não é omissão: ler o objeto do anúncio (`GET /{ad_id}?fields=id,name,adset{id,name},campaign{id,name}`) exige a permissão `ads_read` na conta de anúncios do anunciante, e o token de usuário de sistema por trás de um número conectado carrega apenas `whatsapp_business_management` e `whatsapp_business_messaging`. Para resolver os nomes, chame a Marketing API da Meta com um token autorizado naquela conta, usando este `sourceId`. Privacidade (PII): os CONTADORES seguem corretos num número RELAY_ONLY (saem da identidade do anúncio, que não é dado pessoal); só `lastSourceUrl` e `lastHeadline` voltam nulos, com `piiNotice: "PII_RELAY_ONLY"`. **Requer key escopada a número.** O objeto `referral` também traz os nomes RESOLVIDOS do anúncio — `adName`, `adsetId`, `adsetName`, `campaignId`, `campaignName` — e mais `namesResolvedAt`. ⚠️ Esses seis voltam **null** enquanto o anunciante não tiver compartilhado aquela conta de anúncios com o portfólio empresarial da Pilot Status como parceiro. Nome nulo é estado SUPORTADO, não erro: a conversa continua contada e o `sourceId` continua vindo. Nenhum endpoint resolve nome sob demanda — a resolução é assíncrona, fora do caminho da requisição, então consultar nunca dispara chamada à Marketing API e um null pode virar nome minutos depois sem você fazer nada. O `namesResolvedAt` é o que torna isso observável: null significa "ainda não resolvido", enquanto data preenchida com nomes nulos significa "perguntamos e a Meta não devolveu" (anúncio apagado, ou compartilhamento ausente). operationId: get_referrals_summary parameters: - name: startDate in: query required: false description: Início do período (sobre providerTimestamp). Deve ser ≤ endDate. schema: type: string description: (string (ISO 8601)) example: '2026-08-01T00:00:00Z' - name: endDate in: query required: false description: Fim do período (sobre providerTimestamp). schema: type: string description: (string (ISO 8601)) example: '2026-08-17T23:59:59Z' responses: '200': description: Resumo de anúncios content: application/json: example: ads: - sourceId: '120249828053880703' sourceType: ad conversations: 12 messages: 31 firstAt: '2026-07-28T10:00:00.000Z' lastAt: '2026-08-16T12:00:00.000Z' lastSourceUrl: https://www.instagram.com/p/DcJhrlpA3Pl/ lastHeadline: SALE MM DESIGN adName: Ads 01 - Vídeo dos 70% adsetId: '120249828053990703' adsetName: '[IG] [LL1% IG + VÍDEOS] - 35 a 50' campaignId: '120249677595590703' campaignName: '[CD-01] [WHATSAPP] - MM Design - Sale 70%' namesResolvedAt: '2026-08-17T21:04:00.000Z' - sourceId: '120249828075420703' sourceType: ad conversations: 4 messages: 9 firstAt: '2026-08-02T09:00:00.000Z' lastAt: '2026-08-15T18:30:00.000Z' lastSourceUrl: https://www.instagram.com/p/DcAbcdEfGh/ lastHeadline: MM DESIGN — Outlet adName: null adsetId: null adsetName: null campaignId: null campaignName: null namesResolvedAt: null total: 2 limit: 200 truncated: false '400': description: Período inválido content: application/json: example: error: startDate must be before or equal to endDate code: INVALID_DATE_RANGE '401': description: Header `x-api-key` / `x-api-key-id` ausente ou inválido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '403': description: Chave com escopo de tenant usada em endpoint com escopo de número content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Tenant-scoped keys cannot call number endpoints code: TENANT_SCOPE_NOT_ALLOWED components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ````