# Resultados de campanhas

Acompanhe os disparos feitos no painel e consulte a entrega de cada mensagem, sem enviar outra campanha.

A chave Bearer permite consultar somente as campanhas da sua empresa. Esta consulta lê os registros locais, atualizados pelos envios e pelos webhooks da Meta. Ela não consulta a Meta em tempo real.

## Encontrar a campanha

### GET /public/v1/campaigns

cURL · listar campanhas

```bash
curl "https://api.patrociniotech.com/public/v1/campaigns?limit=20" \
  -H "Authorization: Bearer SUA_CHAVE"
```

| Parâmetro | Regra |
| --- | --- |
| limit | De 1 a 100. Padrão: 20 campanhas por página, da mais recente para a mais antiga. |
| before\_id | Na próxima página, use data.next\_before\_id da resposta anterior. Omita na primeira consulta. |
| data.items | Campanhas, com id, nome, número, template, idioma, agendamento e progresso do disparo. |
| data.has\_more | true quando há outra página. next\_before\_id fica null quando a lista termina. |

O `id` é o mesmo usado na URL de detalhes do painel. `status: done` significa que o processamento do disparo acabou. Ainda podem chegar confirmações de entrega, leitura e falha.

## Resultados e destinatários

### GET /public/v1/campaigns/{campaign_id}/results

cURL · consultar falhas

```bash
curl "https://api.patrociniotech.com/public/v1/campaigns/302/results?status=failed&limit=50" \
  -H "Authorization: Bearer SUA_CHAVE"
```

| Parâmetro | Regra |
| --- | --- |
| campaign\_id | Identificador positivo da campanha. Campanha inexistente ou de outra empresa retorna 404/not\_found. |
| limit | De 1 a 200 destinatários por página. Padrão: 50. |
| status | all, pending, sending, sent, delivered, read, failed, skipped, uncertain, not\_sent ou opted\_out. Padrão: all. |
| after | Copie data.next\_after da resposta anterior e mantenha o mesmo filtro. Omita na primeira página; não altere ou incremente o cursor. |

JSON · exemplo ilustrativo

```json
{
  "success": true,
  "data": {
    "campaign": {
      "id": 302,
      "name": "Oferta de novembro",
      "phone_number_id": "123456789012345",
      "template": "oferta_novembro",
      "language": "pt_BR",
      "status": "done",
      "total": 3,
      "accepted": 3,
      "dispatch_failed": 0,
      "created_at": "2026-11-06T12:00:00Z",
      "scheduled_at": null,
      "started_at": "2026-11-06T12:00:00Z",
      "finished_at": "2026-11-06T12:00:03Z"
    },
    "counts": {
      "pending": 0,
      "sending": 0,
      "sent": 0,
      "delivered": 1,
      "read": 1,
      "failed": 1,
      "skipped": 0,
      "uncertain": 0,
      "not_sent": 0,
      "opted_out": 1
    },
    "delivered_including_read": 2,
    "records": 3,
    "untracked": 0,
    "complete_tracking": true,
    "total_filtered": 1,
    "items": [
      {
        "to": "5511900000000",
        "name": null,
        "contact_wa_id": "5511900000000",
        "message_id": "wamid.exemplo",
        "dispatch_status": "sent",
        "status": "failed",
        "error_code": "marketing_recipient_limited",
        "reason": "Marketing limitado pela Meta para este destinatário",
        "attempted_at": "2026-11-06T12:00:01Z",
        "status_at": null,
        "pricing_category": null,
        "billable": null,
        "opted_out_at": null
      }
    ],
    "has_more": false,
    "next_after": null,
    "snapshot_at": "2026-11-06T12:05:00Z"
  }
}
```

## Como ler os totais

| Campo | Interpretação |
| --- | --- |
| campaign.total | Destinatários selecionados para o disparo. Não significa que receberam a mensagem. |
| campaign.accepted | Envios aceitos pela API da Meta. Uma mensagem aceita ainda pode falhar depois. |
| campaign.dispatch\_failed | Falhas durante o envio. As falhas posteriores de entrega estão em counts.failed. |
| counts.delivered / counts.read | Estados separados: delivered não inclui read. Para o total de entregas, use delivered\_including\_read. |
| counts.opted\_out | Pessoas que pediram para parar promoções e cuja saída foi vinculada à campanha. Sobrepõe a entrega; não some esse valor aos demais estados. |
| counts.sent | Aceitas, ainda sem entrega, leitura ou falha posterior registrada. Não considere entregues nem falhadas. |
| records / untracked | records conta destinatários com evidência disponível; untracked é a diferença positiva para o público selecionado. Ausência de registro não confirma falha. |
| total\_filtered | Total que corresponde ao filtro em toda a campanha. Não é o tamanho da página nem o número restante depois do cursor. |

> Os totais são da campanha inteira e não mudam conforme a página ou o filtro. Em históricos com rastreamento incompleto, `complete_tracking` é false. Nesse caso, não trate os registros ausentes como entregas, falhas ou custo zero.

## O resultado de cada pessoa

| Campo | Interpretação |
| --- | --- |
| to / contact\_wa\_id | to é o telefone solicitado no disparo. contact\_wa\_id é o identificador confirmado pela Meta quando disponível; ele pode vir normalizado. |
| message\_id | WAMID aceito pela Meta. Pode ser usado na consulta de status da mensagem. null quando não há aceite registrado. |
| dispatch\_status / status | dispatch\_status registra a tentativa local; status considera a confirmação posterior de entrega. Um disparo sent pode terminar com status failed. |
| error\_code / reason | Código estável e explicação da falha conhecida. Programe contra error\_code; reason é texto para leitura. null indica informação não registrada. |
| attempted\_at / status\_at | Horário da tentativa e da última atualização disponível na trilha. status\_at não garante o instante exato de entrega. |
| pricing\_category / billable | Categoria e indicação de cobrança recebidas da Meta. null significa não informado. Esta rota não calcula o valor da fatura. |
| opted\_out\_at | Horário da saída de promoções atribuída à campanha. A pessoa ainda pode aparecer com status read ou delivered. |

`marketing_recipient_limited` indica limitação de marketing para aquele destinatário. `marketing_experiment` indica um teste de entrega da Meta. Esses motivos não confirmam banimento do remetente e não justificam reenviar automaticamente.

## Paginação e atualização

Continue enquanto `has_more` for true, usando `next_after` como `after`. A ordem é lexical por telefone e cada resposta lê os registros disponíveis naquele momento. Novos webhooks podem mudar o status entre páginas; para exportar ou reconciliar, guarde pelo par campanha e destinatário, atualize o mesmo registro e faça uma nova leitura depois.

A integração não deve chamar esta rota antes de cada envio. Faça consultas periódicas com pausa e respeite a cota compartilhada por chave. Filtros inválidos retornam 422; autenticação inválida retorna 401; excesso de requisições retorna 429. Um 503 é indisponibilidade temporária da consulta, não evidência de que o disparo falhou: aguarde e repita somente o GET.

---

Fonte: https://patrociniotech.com/documentacao-api/campanhas
Índice para IA: https://patrociniotech.com/documentacao-api/llms.txt