# AI Web Push API — documentação completa em texto puro

Fonte: https://docs.aiwebpush.com — gerada automaticamente da mesma origem do site. Contrato OpenAPI: https://docs.aiwebpush.com/openapi/ai-web-push.yaml

---

URL da página: https://docs.aiwebpush.com/api/

# AI Web Push API

A **AI Web Push API** é a API HTTP da plataforma [AI Web Push](https://aiwebpush.com) para criar, agendar, listar, consultar e excluir campanhas de web push a partir do seu próprio sistema. Ela recebe e devolve JSON, autentica com a chave do site e segmenta o público pelos mesmos tópicos e países que aparecem no painel.

Todas as chamadas usam a mesma base:

```
https://api.aiwebpush.com/v2
```

## Como a API se encaixa na AI Web Push

A AI Web Push é uma plataforma de web push para sites de conteúdo. O fluxo completo tem três partes, e a API cuida só da última:

1. **Inscritos** — os visitantes entram na base pelo plugin WordPress da AI Web Push instalado no site, quando aceitam receber notificações.
2. **Tópicos** — a IA da plataforma classifica o conteúdo que cada inscrito lê e o agrupa em tópicos de interesse (por exemplo `tecnologia`, `esportes`). O dono do site também pode cadastrar e ajustar tópicos no painel. Além dos tópicos, cada inscrito conta num país, listado em `/countries`.
3. **Campanhas** — uma campanha é uma notificação (título, texto, link, ícone, imagem, botão) enviada para um ou mais tópicos e/ou países, na hora ou agendada. É aqui que a API entra: ela cria, consulta e exclui campanhas e lê os resultados de envio.

Tudo que a API faz também existe no painel [app.aiwebpush.com](https://app.aiwebpush.com). Use a API quando quiser que o envio aconteça de dentro do seu CMS, de uma automação de marketing, de um CRM ou de qualquer rotina sua, sem abrir o painel.

## Disponibilidade por plano

O acesso à API, e aos relatórios de campanha via API, está disponível em planos específicos da AI Web Push. Quando a conta não tem o recurso liberado, os métodos de campanha respondem `403` com `{ "message": "This plan does not have permission to..." }`. Já `GET /topics` e `GET /countries` respondem `200` com uma lista vazia — igual a um site que ainda não tem inscritos. Os planos estão em [aiwebpush.com](https://aiwebpush.com/#planos); em caso de dúvida, fale com [contato@aiwebpush.com](mailto:contato@aiwebpush.com).

## Métodos

| Método | Caminho | O que faz |
|---|---|---|
| `POST` | [`/campaign/create`](https://docs.aiwebpush.com/api/reference/create-campaign/) | Cria uma campanha (envia agora, agenda ou salva rascunho) |
| `POST` | [`/campaigns`](https://docs.aiwebpush.com/api/reference/list-campaigns/) | Lista campanhas com resultados de envio, filtros e paginação |
| `GET` | [`/campaign/{campaignId}`](https://docs.aiwebpush.com/api/reference/get-campaign/) | Consulta uma campanha, com analytics |
| `DELETE` | [`/campaign/{campaignId}`](https://docs.aiwebpush.com/api/reference/delete-campaign/) | Exclui uma campanha não enviada (rascunho ou agendada) |
| `GET` | [`/topics`](https://docs.aiwebpush.com/api/reference/list-topics/) | Lista os tópicos do site que têm inscritos |
| `GET` | [`/countries`](https://docs.aiwebpush.com/api/reference/list-countries/) | Lista os países que têm inscritos |

## Convenções

- A chave da API vai no header `Authorization`, sem prefixo `Bearer`. Veja [Autenticação](https://docs.aiwebpush.com/api/autenticacao/).
- Nos `POST`, envie `Content-Type: application/json`.
- Datas usam UTC no formato ISO 8601: `2025-05-02T18:30:00Z`.
- Erro sempre responde `{ "message": "..." }`, seja qual for o status. Veja [Erros](https://docs.aiwebpush.com/api/erros/).
- A chave é vinculada a um site. Toda chamada só alcança as campanhas, os tópicos e os países desse site.
- Nomes de tópico e de país vêm sempre em minúsculas, e países com o prefixo `country__` (ex.: `country__brazil`).

## Fluxo típico de integração

1. Pegue a chave do site no painel e guarde no servidor ([Autenticação](https://docs.aiwebpush.com/api/autenticacao/)).
2. Chame `GET /topics` (e, se for segmentar por país, `GET /countries`) para descobrir os nomes exatos que o site usa.
3. Crie a campanha com `POST /campaign/create`, escolhendo entre enviar agora, agendar ou salvar rascunho. Guarde o `id` devolvido.
4. Acompanhe o resultado com `GET /campaign/{campaignId}` ou liste várias de uma vez com `POST /campaigns` (cliques, impressões, CTR e ITS).

Os quatro passos estão prontos, com `curl` e JSON, em [Receitas](https://docs.aiwebpush.com/api/receitas/).

## Primeira chamada

```bash
curl https://api.aiwebpush.com/v2/topics \
  -H "Authorization: SUA_CHAVE"
```

```json
[
  { "name": "tecnologia", "users": 1840 },
  { "name": "esportes", "users": 920 }
]
```

Se a lista voltar, a chave está funcionando. A partir daí, use a [Referência](https://docs.aiwebpush.com/api/reference/create-campaign/) para montar as demais chamadas, ou siga por [Como testar](https://docs.aiwebpush.com/api/como-testar/) para usar Postman, uma IA ou curl.

---

URL da página: https://docs.aiwebpush.com/api/autenticacao/

# Autenticação

A AI Web Push API autentica cada chamada por uma **chave de API vinculada a um site**, enviada no header `Authorization`, sem prefixo `Bearer`. Não há login, token temporário nem OAuth: a chave copiada do painel é o que você manda em toda requisição.

## Onde pegar a chave

1. Acesse [app.aiwebpush.com/settings](https://app.aiwebpush.com/settings).
2. Clique no site que você quer integrar.
3. Copie o valor do campo **Chave da API**.

Cada site tem a sua própria chave. Se você integra mais de um site, use a chave do site correspondente em cada chamada: a chave de um site não enxerga campanhas, tópicos nem países de outro.

## Como enviar

A chave vai no header `Authorization`, exatamente como foi copiada.

```http
Authorization: SUA_CHAVE
```

```bash
curl https://api.aiwebpush.com/v2/topics \
  -H "Authorization: SUA_CHAVE"
```

Nas chamadas `POST`, acrescente `Content-Type: application/json`:

```bash
curl -X POST https://api.aiwebpush.com/v2/campaigns \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Cada método da [Referência](https://docs.aiwebpush.com/api/reference/create-campaign/) mostra o mesmo header em curl, PHP, Node.js e Python.

## Respostas de autenticação

| Situação | Status | Resposta |
|---|---|---|
| Header ausente ou chave não reconhecida | `403` | `{ "message": "Not authorized" }` |
| Chave válida, mas a conta não tem acesso ao método de campanha (recurso não incluído no plano) | `403` | `{ "message": "This plan does not have permission to..." }` |
| Chave válida sem acesso liberado, em `GET /topics` ou `GET /countries` | `200` | `[]` |
| ID de campanha que não pertence ao site da chave | `404` | `{ "message": "Campaign not found" }` |
| Cursor de paginação gerado com outra chave | `400` | `{ "message": "Invalid pagination cursor" }` |

Os dois `403` têm causas diferentes: o primeiro é chave errada ou ausente; o segundo é chave certa numa conta cujo plano não inclui a API ou os relatórios via API. A mensagem exata varia com o método (`...to create campaigns with API`, `...to access campaign reports via API`, `...to delete campaigns via API`). Veja [Disponibilidade por plano](https://docs.aiwebpush.com/api/#disponibilidade-por-plano).

## Boas práticas com a chave

- **Guarde no servidor.** A chave dá acesso a criar e excluir campanhas do site; trate como senha. Use variável de ambiente ou cofre de segredos, nunca código versionado.
- **Nunca no navegador.** Não chame a API a partir de JavaScript de página pública nem de app mobile: a chave ficaria exposta. Faça a chamada do seu backend.
- **Uma chave por site.** Se integra vários sites, mapeie site → chave do seu lado e não reutilize.
- **Suspeita de vazamento?** Fale com [contato@aiwebpush.com](mailto:contato@aiwebpush.com).

Mais respostas curtas em [Perguntas frequentes](https://docs.aiwebpush.com/api/faq/).

---

URL da página: https://docs.aiwebpush.com/api/como-testar/

# Como testar

Dá para testar a AI Web Push API sem escrever código: importando a coleção do Postman, entregando o arquivo OpenAPI a uma IA para ela escrever a integração, ou chamando direto com `curl`. Em todas você precisa da [chave da API](https://docs.aiwebpush.com/api/autenticacao/).

## Antes de testar

- Tenha a chave do site em mãos ([onde pegar](https://docs.aiwebpush.com/api/autenticacao/#onde-pegar-a-chave)).
- O site precisa ter inscritos: `GET /topics` só lista tópicos com pelo menos um inscrito, e uma campanha sem público não tem para quem ir.
- Para não disparar notificação de verdade enquanto testa, crie campanhas com `"status": "draft"`: elas ficam salvas, aparecem em `POST /campaigns` e podem ser excluídas com `DELETE /campaign/{campaignId}`.

## Postman

1. Baixe a [coleção do Postman](https://docs.aiwebpush.com/downloads/ai-web-push.postman_collection.json).
2. No Postman, clique em **Import** e escolha o arquivo.
3. Abra a coleção, vá em **Variables** e preencha `token` com a sua chave. A variável `baseUrl` já vem pronta.
4. Rode **GET /topics**.

A coleção traz os seis métodos, cada um já com o header de autenticação, e os dois `POST` vêm com um corpo de exemplo preenchido.

## Com uma IA (ChatGPT, Claude, Cursor e afins)

Baixe o [arquivo OpenAPI](https://docs.aiwebpush.com/openapi/ai-web-push.yaml) e anexe na conversa. Ele descreve os endpoints, os campos, os limites e os exemplos, então a IA consegue escrever o código de integração sem você explicar a API.

Pedidos que funcionam bem:

> Anexei o arquivo OpenAPI da AI Web Push API. Escreva uma função em Node.js que cria uma campanha agendada e depois consulta os resultados dela.

> Com o OpenAPI anexado, escreva um script em Python que lista todas as campanhas enviadas em agosto, percorrendo a paginação com `cursor` até `hasMore` vir `false`, e soma os cliques.

O mesmo arquivo pode ser importado em qualquer ferramenta que leia OpenAPI 3.1. Se o agente preferir texto puro, a documentação inteira também está em [`/llms-full.txt`](https://docs.aiwebpush.com/llms-full.txt).

## Com curl

```bash
curl https://api.aiwebpush.com/v2/topics \
  -H "Authorization: SUA_CHAVE"
```

```bash
curl -X POST https://api.aiwebpush.com/v2/campaigns \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"status":["sent"],"limit":10}'
```

Cada método da [Referência](https://docs.aiwebpush.com/api/reference/create-campaign/) traz o `curl` pronto e o JSON de request e response. Para fluxos completos (enviar agora, agendar, paginar, cancelar), veja [Receitas](https://docs.aiwebpush.com/api/receitas/).

---

URL da página: https://docs.aiwebpush.com/api/receitas/

# Receitas

Fluxos completos da AI Web Push API, do jeito que aparecem numa integração real: cada receita mostra a chamada em `curl`, o JSON enviado e o que volta. Os payloads são os mesmos da [Referência](https://docs.aiwebpush.com/api/reference/create-campaign/); troque `SUA_CHAVE` pela [chave do site](https://docs.aiwebpush.com/api/autenticacao/).

## Descobrir o público antes de criar a campanha

Os nomes de tópico e de país precisam existir no site. Consulte-os primeiro:

```bash
curl https://api.aiwebpush.com/v2/topics \
  -H "Authorization: SUA_CHAVE"
```

```json
[
  { "name": "tecnologia", "users": 1840 },
  { "name": "esportes", "users": 920 },
  { "name": "religião", "users": 310 }
]
```

```bash
curl https://api.aiwebpush.com/v2/countries \
  -H "Authorization: SUA_CHAVE"
```

```json
[
  { "name": "country__brazil", "users": 2100 },
  { "name": "country__desconhecido", "users": 45 }
]
```

Use o `name` exatamente como veio — os dois endpoints devolvem tudo em minúsculas, e os países com o prefixo `country__`. Tópicos vão no campo `topics` da campanha, países no campo `countries`. Referência: [Listar tópicos](https://docs.aiwebpush.com/api/reference/list-topics/), [Listar países](https://docs.aiwebpush.com/api/reference/list-countries/).

## Enviar uma notificação agora

`status: published` + `scheduleMode: now` coloca a campanha na fila de envio imediato.

```bash
curl -X POST https://api.aiwebpush.com/v2/campaign/create \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nova oferta da semana",
    "body": "Confira as melhores ofertas com até 50% off",
    "link": "https://example.com/ofertas",
    "topics": ["esportes"],
    "status": "published",
    "scheduleMode": "now",
    "callToAction": "Saiba mais",
    "utmSource": "auto_push",
    "utmMedium": "push",
    "utmCampaign": "push_notification"
  }'
```

```json
{ "id": "abc12--987654" }
```

Guarde o `id`: é com ele que você consulta ou exclui a campanha depois. Referência: [Criar campanha](https://docs.aiwebpush.com/api/reference/create-campaign/).

## Agendar para uma data

`scheduleMode: scheduled` + `scheduleDate` em UTC. Aqui o público combina um tópico e um país, e a notificação vale por 24 horas (`ttl: 86400`) para quem estiver offline.

```bash
curl -X POST https://api.aiwebpush.com/v2/campaign/create \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Black Friday começa agora",
    "body": "Descontos de até 70% só hoje",
    "link": "https://example.com/black-friday",
    "topics": ["tecnologia"],
    "countries": ["country__brazil"],
    "status": "published",
    "scheduleMode": "scheduled",
    "scheduleDate": "2026-11-27T12:00:00Z",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.jpg",
    "callToAction": "Ver ofertas",
    "ttl": 86400
  }'
```

Atenção ao fuso: `2026-11-27T12:00:00Z` é meio-dia em UTC, 9h em Brasília. Referência: [Criar campanha](https://docs.aiwebpush.com/api/reference/create-campaign/).

## Salvar um rascunho (sem enviar)

`status: draft` guarda a campanha sem disparar. Serve para revisar no painel ou para testar a integração sem notificar ninguém.

```bash
curl -X POST https://api.aiwebpush.com/v2/campaign/create \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rascunho da campanha de natal",
    "body": "Texto ainda em revisão",
    "link": "https://example.com/natal",
    "topics": ["decoração"],
    "status": "draft",
    "scheduleMode": "scheduled",
    "scheduleDate": "2026-12-20T15:00:00Z"
  }'
```

## Consultar uma campanha e seus resultados

```bash
curl https://api.aiwebpush.com/v2/campaign/abc12--987654 \
  -H "Authorization: SUA_CHAVE"
```

A resposta traz os campos da campanha e o bloco `analytics`:

```json
{
  "id": "abc12--987654",
  "title": "Nova oferta da semana",
  "status": "published",
  "scheduleMode": "now",
  "scheduleDate": "2025-08-23T10:40:00Z",
  "createdAt": "2025-08-22T10:40:00Z",
  "totalUsers": 12500,
  "analytics": {
    "clicks": 320,
    "impressions": 8400,
    "ctr": 3.81,
    "its": 67.2,
    "totalUsers": 12500
  }
}
```

(Resposta abreviada; a lista completa de campos está em [Obter campanha](https://docs.aiwebpush.com/api/reference/get-campaign/).) `ctr` é cliques ÷ impressões e `its` é impressões ÷ base alcançada, ambos em percentual — definições no [Glossário](https://docs.aiwebpush.com/api/glossario/).

## Listar as campanhas enviadas em um período

Corpo vazio (`{}`) devolve as 10 criadas mais recentemente. Para um relatório mensal, filtre por data de envio e status `sent`:

```bash
curl -X POST https://api.aiwebpush.com/v2/campaigns \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2025-08-01T00:00:00Z",
    "endDate": "2025-08-31T23:59:59Z",
    "dateField": "scheduleDate",
    "status": ["sent"],
    "limit": 10
  }'
```

Cada item vem com `analytics`, então dá para somar cliques e impressões do mês direto da resposta. Referência: [Listar campanhas](https://docs.aiwebpush.com/api/reference/list-campaigns/).

## Percorrer todas as páginas com cursor

A listagem é paginada por cursor. Repita os mesmos filtros e o mesmo `limit`, passando o `nextCursor` da resposta anterior, até `hasMore` vir `false`. (Respostas abreviadas; cada item de `items` tem os campos completos de [Listar campanhas](https://docs.aiwebpush.com/api/reference/list-campaigns/).)

**Passo 1 — primeira página, sem cursor:**

```bash
curl -X POST https://api.aiwebpush.com/v2/campaigns \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"dateField":"createdAt","limit":2}'
```

```json
{
  "items": [ "...2 campanhas..." ],
  "limit": 2,
  "hasMore": true,
  "nextCursor": "eyJrIjoiY2FtcGFpZ24tMTAiLCJkIjoxNzU1ODU5MjAwfQ=="
}
```

**Passo 2 — próxima página, com o cursor recebido:**

```bash
curl -X POST https://api.aiwebpush.com/v2/campaigns \
  -H "Authorization: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"dateField":"createdAt","limit":2,"cursor":"eyJrIjoiY2FtcGFpZ24tMTAiLCJkIjoxNzU1ODU5MjAwfQ=="}'
```

```json
{
  "items": [ "...campanhas restantes..." ],
  "limit": 2,
  "hasMore": false,
  "nextCursor": null
}
```

Copie o cursor exatamente como veio: cursor alterado, ou gerado com a chave de outro site, responde `400 Invalid pagination cursor`.

## Cancelar um agendamento ou apagar um rascunho

`DELETE` exclui rascunhos e cancela campanhas agendadas que ainda não foram enviadas.

```bash
curl -X DELETE https://api.aiwebpush.com/v2/campaign/abc12--987654 \
  -H "Authorization: SUA_CHAVE"
```

```json
{ "id": "abc12--987654", "deleted": true }
```

Se a campanha já foi enviada, nada é excluído e a resposta é `409` com `{ "message": "Cannot delete a campaign that has already been sent" }`. Referência: [Excluir campanha](https://docs.aiwebpush.com/api/reference/delete-campaign/).

## Próximos passos

- Todos os campos e regras: [Limites](https://docs.aiwebpush.com/api/limites/).
- O que cada erro significa e como tratar: [Erros](https://docs.aiwebpush.com/api/erros/).
- Dúvidas rápidas: [Perguntas frequentes](https://docs.aiwebpush.com/api/faq/).

---

URL da página: https://docs.aiwebpush.com/api/erros/

# Erros

Todo erro da AI Web Push API tem o mesmo formato, seja qual for o status HTTP: um JSON com um único campo `message`, em inglês, descrevendo o problema.

```json
{ "message": "..." }
```

Quando mais de um campo está errado na mesma chamada, as mensagens vêm juntas separadas por vírgula:

```json
{ "message": "Title is required, Link is required, TTL must be between 0 and 28 days in seconds" }
```

## O que cada status significa

| Status | Significado | O que fazer |
|---|---|---|
| `400` | Algum dado da chamada está errado | Leia o `message`, corrija o campo e tente de novo |
| `403` | Chave ausente ou inválida, ou operação não liberada para a conta | Confira o header `Authorization` e o [plano](https://docs.aiwebpush.com/api/#disponibilidade-por-plano) |
| `404` | A campanha não existe ou não é do seu site | Confira o ID e a chave usada |
| `409` | A campanha já foi enviada e não pode ser excluída | Nada a fazer, o envio é definitivo |
| `500` | Falha do nosso lado | Tente novamente; se persistir, fale com o suporte |

## Como tratar no código

- **Não repita chamadas que deram `4xx`.** O problema está na requisição (dado, chave ou ID); repetir igual devolve o mesmo erro. Corrija e chame de novo.
- **Repita com cuidado em `500`.** Espere alguns segundos entre tentativas. Se criou uma campanha e recebeu `500`, confira com `POST /campaigns` antes de criar outra, para não duplicar o envio.
- **Guarde o `message` no log.** Ele já diz qual campo falhou; é o que o suporte vai pedir.
- **Trate `409` como sucesso do envio.** Ele só aparece no `DELETE` de uma campanha já enviada.

Se um `500` persistir, mande o horário, o método chamado e o `message` para [contato@aiwebpush.com](mailto:contato@aiwebpush.com) ou pela [página de contato](https://aiwebpush.com/pt/contato/).

## Mensagens de validação (`400`)

**Na criação da campanha:**

| Mensagem | Causa |
|---|---|
| `Title is required` | Faltou o título |
| `Title must be between 3 and 100 characters` | Título curto ou longo demais |
| `Body is required` | Faltou o texto |
| `Body must be between 3 and 300 characters` | Texto curto ou longo demais |
| `Link is required` | Faltou o link de destino |
| `At least one topic or country must be specified` | Nenhum público informado |
| `Call to action must not exceed 20 characters` | Texto do botão longo demais |
| `Icon must be a valid URL` / `Image must be a valid URL` | A URL precisa começar com `https://` |
| `Invalid campaign status` | Use `published`, `draft` ou `failed` |
| `Invalid schedule mode` | Use `now` ou `scheduled` |
| `Schedule date is required for schedule mode` | Faltou a data no agendamento |
| `Invalid schedule date format. Use ISO format (e.g. 2025-05-02T18:30:00Z)` | Data fora do formato UTC |
| `TTL must be between 0 and 28 days in seconds` | TTL fora da faixa permitida |

**Na listagem e na consulta:**

| Mensagem | Causa |
|---|---|
| `limit must be a positive number` | `limit` precisa ser maior que zero |
| `Invalid startDate format. Use ISO format (e.g. 2025-05-02T18:30:00Z)` | `startDate` fora do formato UTC |
| `Invalid endDate format. Use ISO format (e.g. 2025-05-02T18:30:00Z)` | `endDate` fora do formato UTC |
| `startDate must be less than or equal to endDate` | O intervalo está invertido |
| `dateField must be createdAt or scheduleDate` | Valor não permitido em `dateField` |
| `Invalid status values: foo. Allowed: draft, scheduled, sent, failed` | Status desconhecido no filtro |
| `cursor must be a non-empty string` | O `cursor` veio vazio ou não é texto |
| `Invalid pagination cursor` | O cursor foi alterado ou veio de outro site |
| `campaignId is required` | Faltou o ID na URL |
| `Invalid JSON body` | O corpo enviado não é um JSON válido |

As regras de cada campo estão em [Limites](https://docs.aiwebpush.com/api/limites/).

---

URL da página: https://docs.aiwebpush.com/api/limites/

# Limites

Referência rápida do que cada campo da AI Web Push API aceita. Os valores abaixo são os mesmos que a API valida; fora deles a resposta é `400` com a mensagem correspondente em [Erros](https://docs.aiwebpush.com/api/erros/).

## POST /campaign/create

| Campo | Regra |
|---|---|
| `title` | Obrigatório, de 3 a 100 caracteres |
| `body` | Obrigatório, de 3 a 300 caracteres |
| `link` | Obrigatório |
| `topics` / `countries` | Pelo menos um dos dois, com ao menos um valor; use os nomes como `GET /topics` e `GET /countries` devolvem (minúsculas, países com `country__`) |
| `callToAction` | Opcional, até 20 caracteres |
| `icon` / `image` | Opcionais; se enviados, precisam começar com `https://` |
| `status` | `published`, `draft` ou `failed` |
| `scheduleMode` | `now` ou `scheduled` |
| `scheduleDate` | Obrigatório quando `scheduleMode` é `scheduled`; data UTC |
| `ttl` | Número inteiro até 2419200 segundos (28 dias); o padrão é 2419200 e enviar `0` também resulta no padrão |
| `utmSource` / `utmMedium` / `utmCampaign` | Opcionais; são anexados ao `link` |

## POST /campaigns

| Campo | Regra |
|---|---|
| `limit` | De 1 a 60; o padrão é 10 e valores acima de 60 viram 60 |
| `startDate` / `endDate` | Datas UTC; `startDate` não pode ser maior que `endDate` |
| `dateField` | `createdAt` ou `scheduleDate`; padrão `createdAt` |
| `status` | `draft`, `scheduled`, `sent` ou `failed` |
| `cursor` | Use exatamente o valor devolvido em `nextCursor` |

## Dicas para a notificação render mais

Os limites acima são o máximo aceito, não o tamanho ideal. Navegadores e sistemas cortam textos longos, então:

- **Título curto.** É o que aparece inteiro na maioria dos dispositivos; coloque a informação principal no começo.
- **Texto direto.** O `body` aceita 300 caracteres, mas muitos dispositivos mostram bem menos antes de truncar.
- **Botão de até 20 caracteres** (`callToAction`): um verbo e um objeto, como `Ver ofertas`.
- **Ícone quadrado em HTTPS**, 192×192 recomendado. Imagem grande (`image`) opcional, também em HTTPS.
- **TTL coerente com a oferta.** Se a promoção acaba em 24 h, `ttl: 86400` evita entregar a notificação depois do prazo a quem estava offline.
- **UTMs** para ver o tráfego da campanha no seu analytics: `utmSource`, `utmMedium` e `utmCampaign` são anexados ao `link`.

---

URL da página: https://docs.aiwebpush.com/api/faq/

# Perguntas frequentes

Respostas diretas às dúvidas mais comuns de quem integra a AI Web Push API. Cada resposta aponta para a página da documentação que aprofunda o assunto.

### O que é a AI Web Push API?

É a API HTTP da plataforma AI Web Push para criar, agendar, listar, consultar e excluir campanhas de web push a partir do seu próprio sistema. Ela usa JSON, autentica com a chave do site e segmenta o público por tópicos e países. A base de todas as chamadas é https://api.aiwebpush.com/v2.

Mais: https://docs.aiwebpush.com/api/

### Quem pode usar a API?

Contas da AI Web Push cujo plano inclui acesso à API. Os relatórios de campanha via API (listar e consultar campanhas com analytics) também dependem do plano. Quando o recurso não está liberado, os métodos de campanha respondem 403 com a mensagem "This plan does not have permission to...", e GET /topics e GET /countries respondem 200 com uma lista vazia. Os planos estão em aiwebpush.com.

Mais: https://docs.aiwebpush.com/api/#disponibilidade-por-plano

### Onde pego a chave da API?

Em app.aiwebpush.com/settings: clique no site que quer integrar e copie o campo "Chave da API". Cada site tem a sua própria chave, e ela só alcança as campanhas, tópicos e países daquele site.

Mais: https://docs.aiwebpush.com/api/autenticacao/

### Como envio a chave? Preciso do prefixo Bearer?

Não. A chave vai no header Authorization exatamente como foi copiada, sem Bearer. Nos POST, envie também Content-Type: application/json.

Mais: https://docs.aiwebpush.com/api/autenticacao/#como-enviar

### De onde vêm os inscritos que recebem as campanhas?

Dos visitantes que aceitaram receber notificações no site por meio do plugin WordPress da AI Web Push. A API não cadastra inscritos; ela cria e consulta campanhas para a base que o plugin já formou.

Mais: https://docs.aiwebpush.com/api/#como-a-api-se-encaixa-na-ai-web-push

### Qual a diferença entre tópicos e países?

Tópicos são interesses dos inscritos: a IA da AI Web Push classifica o conteúdo que cada um lê e o dono do site também pode cadastrar tópicos no painel. Países agrupam os inscritos por localização e vêm com o prefixo country__ (por exemplo country__brazil). Uma campanha precisa de pelo menos um tópico ou um país; se informar os dois, eles são juntados numa lista só de destinos.

Mais: https://docs.aiwebpush.com/api/glossario/

### Como sei quais tópicos e países posso usar?

Chame GET /topics e GET /countries. Eles listam só os tópicos e países que têm pelo menos um inscrito no site, com a quantidade de inscritos em cada um. Os nomes vêm sempre em minúsculas e devem ser usados exatamente como vieram.

Mais: https://docs.aiwebpush.com/api/receitas/#descobrir-o-público-antes-de-criar-a-campanha

### Como envio uma notificação na hora, agendo ou salvo um rascunho?

Tudo no mesmo POST /campaign/create, combinando dois campos: status draft só guarda a campanha; status published com scheduleMode now envia na hora; status published com scheduleMode scheduled envia na data informada em scheduleDate.

Mais: https://docs.aiwebpush.com/api/receitas/

### Em que fuso horário mando a data de agendamento?

Em UTC, no formato ISO 8601 com Z no fim, como 2025-05-02T18:30:00Z. Para o horário de Brasília (UTC-3), some 3 horas: 9h em Brasília é 12:00:00Z.

Mais: https://docs.aiwebpush.com/api/limites/

### O que é TTL e qual valor usar?

TTL é por quanto tempo, em segundos, a notificação continua valendo se o dispositivo estiver offline. Vai até 2419200 (28 dias), que também é o padrão — enviar 0 resulta no padrão. Para uma oferta de um dia, 86400 evita entregar a notificação depois do prazo. Nas respostas, ttl também vem em segundos e ttlUnit é sempre "seconds".

Mais: https://docs.aiwebpush.com/api/glossario/

### Por que a campanha enviada aparece com status published, e não sent?

No filtro de POST /campaigns, status aceita draft, scheduled, sent e failed. Dentro de cada campanha da resposta, porém, o campo status mostra o valor original de criação: published, draft ou failed. Uma campanha já enviada continua como published.

Mais: https://docs.aiwebpush.com/api/reference/list-campaigns/

### Como vejo os resultados (cliques, impressões) de uma campanha?

Com GET /campaign/{campaignId} ou na lista de POST /campaigns. Cada campanha traz o bloco analytics com clicks, impressions, ctr (cliques sobre impressões, em %), its (impressões sobre a base alcançada, em %) e totalUsers.

Mais: https://docs.aiwebpush.com/api/receitas/#consultar-uma-campanha-e-seus-resultados

### Como funciona a paginação da listagem?

Por cursor. A primeira chamada vai sem cursor; se a resposta vier com hasMore true, repita a chamada com os mesmos filtros e o mesmo limit, passando o nextCursor no campo cursor. Pare quando hasMore vier false. O limit vai de 1 a 60 (padrão 10).

Mais: https://docs.aiwebpush.com/api/receitas/#percorrer-todas-as-páginas-com-cursor

### Dá para excluir ou cancelar uma campanha?

Sim, enquanto ela não foi enviada: DELETE /campaign/{campaignId} apaga rascunhos e cancela agendamentos. Se a campanha já foi enviada, nada é excluído e a resposta é 409.

Mais: https://docs.aiwebpush.com/api/reference/delete-campaign/

### Recebi 403 "Not authorized". O que está errado?

O header Authorization está ausente ou a chave não foi reconhecida. Confira se copiou a chave inteira, sem prefixo Bearer, e se é a chave do site certo. Se a mensagem for "This plan does not have permission...", a chave está certa, mas o plano da conta não inclui o recurso.

Mais: https://docs.aiwebpush.com/api/erros/

### Recebi 404 "Campaign not found" para um ID que existe. Por quê?

A chave é vinculada a um site, e um ID de campanha de outro site responde 404. Confira se está usando a chave do mesmo site que criou a campanha.

Mais: https://docs.aiwebpush.com/api/autenticacao/#respostas-de-autenticação

### Como testo sem disparar notificação de verdade?

Crie a campanha com status draft: ela fica salva, aparece em POST /campaigns e pode ser excluída depois, sem notificar ninguém. Para testar sem código, use a coleção do Postman ou entregue o arquivo OpenAPI a uma IA.

Mais: https://docs.aiwebpush.com/api/como-testar/

### Onde acompanho mudanças na API?

No changelog desta documentação, que registra cada endpoint ou campo novo com a data. O contrato completo e atual fica no arquivo OpenAPI 3.1 público.

Mais: https://docs.aiwebpush.com/api/changelog/

Não achou a resposta? Escreva para [contato@aiwebpush.com](mailto:contato@aiwebpush.com) ou use a [página de contato](https://aiwebpush.com/pt/contato/).

---

URL da página: https://docs.aiwebpush.com/api/glossario/

# Glossário

Os termos que aparecem na AI Web Push API, definidos em poucas linhas. Os nomes de campo estão como a API os usa.

### Campanha

Uma notificação de web push (título, texto, link e, opcionalmente, ícone, imagem e botão) enviada para um conjunto de tópicos e/ou países de um site. É a unidade que a API cria, lista, consulta e exclui. Cada campanha tem um `id` devolvido na criação.

### Web push

Notificação enviada pelo navegador a quem aceitou recebê-la num site, mesmo com o site fechado. Na AI Web Push, os visitantes entram na base pelo plugin WordPress instalado no site.

### Tópico (`topics`)

Interesse de um grupo de inscritos, como `tecnologia` ou `esportes`. A IA da AI Web Push classifica o conteúdo que cada inscrito lê, e o dono do site também pode cadastrar tópicos no painel. `GET /topics` lista os tópicos do site que têm inscritos, em minúsculas — use os nomes exatamente como vieram.

### País (`countries`)

Agrupamento de inscritos por país, em minúsculas e com o prefixo `country__` (por exemplo `country__brazil`; quem não teve o país identificado cai em `country__desconhecido`). `GET /countries` lista os países com inscritos; na criação da campanha, tópicos e países são juntados numa lista só de destinos.

### Inscrito

Visitante que aceitou receber notificações do site. O campo `users` de tópicos e países e o `totalUsers` da campanha contam inscritos.

### `status` (da campanha)

Situação definida na criação: `published` (entra na fila de envio), `draft` (só guarda, não envia) ou `failed` (envio falhou). Uma campanha já enviada continua aparecendo como `published`.

### `status` (filtro da listagem)

No filtro de `POST /campaigns`, o campo aceita outros valores: `draft`, `scheduled` (publicada, envio ainda por acontecer), `sent` (publicada, envio já realizado) e `failed`.

### `scheduleMode`

Como o envio acontece: `now` envia na hora; `scheduled` envia na data de `scheduleDate`.

### `scheduleDate`

Data e hora do envio, em UTC, formato ISO 8601: `2025-05-02T18:30:00Z`. Obrigatória quando `scheduleMode` é `scheduled`.

### TTL (`ttl`)

Time to live: por quanto tempo, em segundos, a notificação continua valendo se o dispositivo estiver offline. Vai até 2419200 segundos (28 dias), que também é o padrão — enviar `0` resulta no padrão. Nas respostas, o `ttl` também vem em segundos e o `ttlUnit` é sempre `seconds`.

### `callToAction`

Texto do botão da notificação, com até 20 caracteres.

### UTM (`utmSource`, `utmMedium`, `utmCampaign`)

Parâmetros de rastreamento anexados ao `link` da campanha, para o clique aparecer identificado no seu analytics.

### Cursor (`cursor` / `nextCursor`)

Marcador de paginação da listagem. A resposta traz `nextCursor` quando há mais páginas (`hasMore: true`); envie esse valor, sem alterar, no campo `cursor` da chamada seguinte, com os mesmos filtros e o mesmo `limit`.

### Impressões (`impressions`)

Quantas vezes a notificação da campanha foi exibida nos dispositivos.

### Cliques (`clicks`)

Quantas vezes a notificação foi clicada, abrindo o `link` da campanha.

### CTR (`ctr`)

Click-through rate: percentual de cliques sobre as impressões, com duas casas decimais. Vem 0 quando não houve exibições.

### ITS (`its`)

Percentual de impressões sobre a base de usuários alcançada (`totalUsers`), com duas casas decimais — quanto da base efetivamente viu a notificação. Vem 0 quando a base é zero.

### `totalUsers`

Audiência estimada quando a campanha foi agendada; é a base usada no cálculo do ITS.

Termo que não está aqui? Procure na [Referência](https://docs.aiwebpush.com/api/reference/campanhas/) — cada campo tem descrição própria — ou pergunte em [contato@aiwebpush.com](mailto:contato@aiwebpush.com).

---

URL da página: https://docs.aiwebpush.com/api/changelog/

# Changelog

Histórico das mudanças da AI Web Push API (base `https://api.aiwebpush.com/v2`), da mais recente para a mais antiga. Qualquer mudança no contrato de um endpoint já publicado — campo novo, endpoint novo ou alteração de comportamento — é registrada aqui com a data.

| Data | Mudança |
|---|---|
| 2026-08-23 | `ttlUnit` passa a responder sempre `seconds`, a unidade em que o `ttl` sempre esteve |
| 2026-08-23 | `POST /campaigns` — lista campanhas com resultados de envio, filtros e paginação |
| 2026-08-23 | `GET /campaign/{campaignId}` — consulta de uma campanha |
| 2026-08-23 | `DELETE /campaign/{campaignId}` — exclusão de campanha não enviada |

O contrato completo e atual está no [arquivo OpenAPI](https://docs.aiwebpush.com/openapi/ai-web-push.yaml).

---

# Referência de endpoints

Base URL: `https://api.aiwebpush.com/v2`. A AI Web Push API cria, agenda, lista, consulta e exclui campanhas de web push
por HTTP, com público segmentado por tópicos e países.

Datas de envio e de resposta usam ISO 8601 UTC, no formato `2025-05-02T18:30:00Z`.
Toda resposta de erro é `{ "message": "..." }`.

Autenticação: header `Authorization` com a chave da API, sem prefixo `Bearer`. A chave é
vinculada a um site — toda operação alcança somente as campanhas desse site.

## Criar campanha — `POST /campaign/create`

URL da página: https://docs.aiwebpush.com/api/reference/create-campaign/

Cria uma campanha de web push: envia na hora, agenda para uma data futura ou salva como rascunho, com público segmentado por tópicos e países.

Escolha o público em `topics` e/ou `countries` — pelo menos um dos dois é obrigatório.
Os dois são juntados em uma lista só de destinos.

Quando a campanha é enviada:

- `status: draft` — só guarda, não envia.
- `status: published` + `scheduleMode: now` — envia na hora.
- `status: published` + `scheduleMode: scheduled` — envia na data informada em `scheduleDate`.

Autenticação: header `Authorization` com a chave da API do site, sem prefixo `Bearer`.

Corpo (JSON, obrigatório):

- `title` (string; obrigatório) — Título da notificação (3–100 caracteres).
- `body` (string; obrigatório) — Corpo da notificação (3–300 caracteres).
- `link` (string; obrigatório) — URL aberta ao clicar. Obrigatório.
- `topics` (array) — Tópicos de destino. Informe `topics` e/ou `countries` — pelo menos um.
- `countries` (array) — Países de destino no formato devolvido por `GET /countries` (ex. `country__brazil`).
- `status` (string; valores: published, draft, failed; obrigatório) — Use `draft` para só guardar a campanha ou `published` para colocá-la na fila de envio.
- `scheduleMode` (string; valores: now, scheduled; obrigatório) — `now` envia na hora. `scheduled` envia na data informada em `scheduleDate`.
- `scheduleDate` (string) — Data e hora do envio em UTC (`2025-05-02T18:30:00Z`). Obrigatório quando `scheduleMode` é `scheduled`.
- `icon` (string) — URL HTTPS do ícone (192×192 recomendado).
- `image` (string) — URL HTTPS da imagem grande da notificação.
- `callToAction` (string) — Texto do botão (até 20 caracteres).
- `utmSource` (string) — UTM source anexado ao `link`.
- `utmMedium` (string) — UTM medium anexado ao `link`.
- `utmCampaign` (string) — UTM campaign anexado ao `link`.
- `ttl` (integer) — Por quanto tempo a notificação continua valendo se o dispositivo estiver offline, em segundos (até 2419200, ou seja 28 dias). Padrão 2419200 — enviar `0` também resulta no padrão.

Exemplo — Enviar agora:

```json
{
  "title": "Nova oferta da semana",
  "body": "Confira as melhores ofertas com até 50% off",
  "link": "https://example.com/ofertas",
  "topics": [
    "esportes"
  ],
  "status": "published",
  "scheduleMode": "now",
  "callToAction": "Saiba mais",
  "utmSource": "auto_push",
  "utmMedium": "push",
  "utmCampaign": "push_notification"
}
```

Exemplo — Agendar para uma data futura:

```json
{
  "title": "Black Friday começa agora",
  "body": "Descontos de até 70% só hoje",
  "link": "https://example.com/black-friday",
  "topics": [
    "tecnologia"
  ],
  "countries": [
    "country__brazil"
  ],
  "status": "published",
  "scheduleMode": "scheduled",
  "scheduleDate": "2026-11-27T12:00:00Z",
  "icon": "https://cdn.example.com/icon.png",
  "image": "https://cdn.example.com/banner.jpg",
  "callToAction": "Ver ofertas",
  "ttl": 86400
}
```

Exemplo — Salvar rascunho:

```json
{
  "title": "Rascunho da campanha de natal",
  "body": "Texto ainda em revisão",
  "link": "https://example.com/natal",
  "topics": [
    "decoração"
  ],
  "status": "draft",
  "scheduleMode": "scheduled",
  "scheduleDate": "2026-12-20T15:00:00Z"
}
```

Resposta `200` — Campanha criada

- `id` (string) — ID da campanha criada. Use em GET e DELETE.

Exemplo:

```json
{
  "id": "abc12--987654"
}
```

Resposta `400` — Algum dado da campanha está errado

```json
{"message":"Title is required"}
```

Resposta `403` — Chave inválida, ou criação de campanha não liberada para a conta

```json
{"message":"Not authorized"}
```

Resposta `500` — Falha ao criar

```json
{"message":"Error creating campaign"}
```

## Listar campanhas — `POST /campaigns`

URL da página: https://docs.aiwebpush.com/api/reference/list-campaigns/

Lista as campanhas do site com resultados de envio (`analytics`), filtros por período e status, e paginação por cursor.

Enviando o corpo vazio (`{}`) você recebe as 10 campanhas criadas mais recentemente.

Atenção ao campo `status`: no **filtro** ele aceita `draft`, `scheduled`, `sent` e
`failed`. Dentro de cada campanha da resposta, o `status` mostra o valor original
(`published`, `draft` ou `failed`) — uma campanha já enviada aparece como `published`.

**Paginação.** Cada resposta traz no máximo `limit` campanhas. Para pegar o resto:

1. Chame sem `cursor` para receber a primeira página.
2. Se a resposta vier com `hasMore: true`, copie o valor de `nextCursor`.
3. Chame de novo mandando esse valor em `cursor`, repetindo os mesmos filtros e o mesmo `limit`.
4. Siga assim até `hasMore` vir `false` — nesse ponto `nextCursor` vem `null` e acabaram as campanhas.

Os exemplos "Primeira página" e "Próxima página", tanto na requisição quanto na resposta,
mostram esse vai e volta com o cursor.

Autenticação: header `Authorization` com a chave da API do site, sem prefixo `Bearer`.

Corpo (JSON, opcional):

- `startDate` (string) — Início do período, em UTC.
- `endDate` (string) — Fim do período, em UTC. Não pode ser menor que `startDate`.
- `dateField` (string; valores: createdAt, scheduleDate) — Qual data o período e a ordenação consideram — a de criação ou a de envio. Padrão `createdAt`.
- `status` (array) — Traz apenas as campanhas nesta situação: - `draft` — salva como rascunho - `scheduled` — publicada, com envio ainda por acontecer - `sent` — publicada, com envio já realizado - `failed` — o envio falhou
- `limit` (integer) — Quantas campanhas trazer por vez. Padrão 10; valores acima de 60 são reduzidos para 60.
- `cursor` (string) — Cursor devolvido em `nextCursor` da página anterior. Copie o valor como veio; cursor alterado ou de outro site responde 400.

Exemplo — Sem filtro, as mais recentes:

```json
{}
```

Exemplo — Somente as enviadas dentro de um intervalo:

```json
{
  "startDate": "2025-08-01T00:00:00Z",
  "endDate": "2025-08-31T23:59:59Z",
  "dateField": "scheduleDate",
  "status": [
    "sent"
  ],
  "limit": 10
}
```

Exemplo — Passo 1 — sem cursor, guarde o nextCursor da resposta:

```json
{
  "dateField": "createdAt",
  "limit": 2
}
```

Exemplo — Passo 2 — mesmos filtros, agora com o nextCursor recebido:

```json
{
  "dateField": "createdAt",
  "limit": 2,
  "cursor": "eyJrIjoiY2FtcGFpZ24tMTAiLCJkIjoxNzU1ODU5MjAwfQ=="
}
```

Resposta `200` — Lista de campanhas

- `items` (array) — As campanhas encontradas.
- `limit` (number) — Quantidade máxima de campanhas considerada nesta resposta.
- `hasMore` (boolean) — `true` quando ainda existem campanhas nas próximas páginas.
- `nextCursor` (string|null) — Valor a enviar em `cursor` para buscar a próxima página. Vem `null` quando `hasMore` é `false`.

Exemplo:

```json
{
  "items": [
    {
      "id": "abc12--987654",
      "title": "Nova oferta da semana",
      "body": "Confira as melhores ofertas com até 50% off",
      "link": "https://example.com/ofertas",
      "topics": [
        "esportes",
        "country__brazil"
      ],
      "status": "published",
      "scheduleDate": "2025-08-23T10:40:00Z",
      "scheduleMode": "scheduled",
      "createdAt": "2025-08-22T10:40:00Z",
      "updatedAt": null,
      "totalUsers": 12500,
      "image": "https://cdn.example.com/image.jpg",
      "icon": "https://cdn.example.com/icon.png",
      "callToAction": "Saiba mais",
      "utmSource": "auto_push",
      "utmMedium": "push",
      "utmCampaign": "push_notification",
      "ttl": 2419200,
      "ttlUnit": "seconds",
      "analytics": {
        "clicks": 320,
        "impressions": 8400,
        "ctr": 3.81,
        "its": 67.2,
        "totalUsers": 12500
      }
    },
    {
      "id": "def34--123456",
      "title": "Chegou a coleção de inverno",
      "body": "Peças novas com frete grátis",
      "link": "https://example.com/inverno",
      "topics": [
        "tecnologia"
      ],
      "status": "published",
      "scheduleDate": "2025-08-21T14:00:00Z",
      "scheduleMode": "now",
      "createdAt": "2025-08-21T13:58:00Z",
      "updatedAt": null,
      "totalUsers": 11800,
      "image": null,
      "icon": "https://cdn.example.com/icon.png",
      "callToAction": "",
      "utmSource": "auto_push",
      "utmMedium": "push",
      "utmCampaign": "push_notification",
      "ttl": 2419200,
      "ttlUnit": "seconds",
      "analytics": {
        "clicks": 210,
        "impressions": 7300,
        "ctr": 2.88,
        "its": 61.86,
        "totalUsers": 11800
      }
    }
  ],
  "limit": 2,
  "hasMore": true,
  "nextCursor": "eyJrIjoiY2FtcGFpZ24tMTAiLCJkIjoxNzU1ODU5MjAwfQ=="
}
```

Resposta `400` — Algum dado da chamada está errado

```json
{"message":"startDate must be less than or equal to endDate"}
```

Resposta `403` — Chave inválida, ou consulta de campanhas não liberada para a conta

```json
{"message":"Not authorized"}
```

Resposta `500` — Falha do nosso lado

```json
{"message":"Internal server error"}
```

## Obter campanha — `GET /campaign/{campaignId}`

URL da página: https://docs.aiwebpush.com/api/reference/get-campaign/

Consulta uma campanha de web push pelo ID e devolve todos os campos, incluindo os resultados de envio (`analytics`).

A resposta tem os mesmos campos que aparecem na listagem — só que uma campanha
sozinha, sem `items`, `hasMore` nem `nextCursor`.

Se o ID não existir ou for de outro site, a resposta é 404.

Autenticação: header `Authorization` com a chave da API do site, sem prefixo `Bearer`.

Resposta `200` — Campanha encontrada

- `id` (string) — ID da campanha.
- `title` (string) — Título da notificação.
- `body` (string) — Texto da notificação.
- `link` (string) — URL aberta ao clicar. Vem vazia se a campanha não tiver link.
- `topics` (array) — Público da campanha, com tópicos e países na mesma lista.
- `status` (string; valores: published, draft, failed) — Situação original da campanha. Uma campanha já enviada continua aparecendo como `published`.
- `scheduleDate` (string) — Data e hora do envio, em UTC.
- `scheduleMode` (string; valores: now, scheduled) — Se o envio foi imediato ou agendado.
- `createdAt` (string) — Data e hora da criação, em UTC.
- `updatedAt` (string|null) — Data e hora da última alteração, em UTC, ou `null` se nunca foi alterada.
- `totalUsers` (number) — Audiência estimada quando a campanha foi agendada.
- `image` (string|null) — URL da imagem grande, ou `null` se não houver.
- `icon` (string|null) — URL do ícone, ou `null` se não houver.
- `callToAction` (string) — Texto do botão. Vem vazio se não foi definido.
- `utmSource` (string) — UTM source usado no link. Vem vazio se não foi definido.
- `utmMedium` (string) — UTM medium usado no link. Vem vazio se não foi definido.
- `utmCampaign` (string) — UTM campaign usado no link. Vem vazio se não foi definido.
- `ttl` (number) — Tempo de vida da notificação, em segundos.
- `ttlUnit` (string; valores: seconds) — Unidade do `ttl`. Sempre `seconds`.
- `analytics` (object)

Exemplo:

```json
{
  "id": "abc12--987654",
  "title": "Nova oferta da semana",
  "body": "Confira as melhores ofertas com até 50% off",
  "link": "https://example.com/ofertas",
  "topics": [
    "esportes",
    "country__brazil"
  ],
  "status": "published",
  "scheduleDate": "2025-08-23T10:40:00Z",
  "scheduleMode": "now",
  "createdAt": "2025-08-22T10:40:00Z",
  "updatedAt": null,
  "totalUsers": 12500,
  "image": "https://cdn.example.com/image.jpg",
  "icon": "https://cdn.example.com/icon.png",
  "callToAction": "Saiba mais",
  "utmSource": "auto_push",
  "utmMedium": "push",
  "utmCampaign": "push_notification",
  "ttl": 2419200,
  "ttlUnit": "seconds",
  "analytics": {
    "clicks": 320,
    "impressions": 8400,
    "ctr": 3.81,
    "its": 67.2,
    "totalUsers": 12500
  }
}
```

Resposta `400` — campaignId ausente

```json
{"message":"campaignId is required"}
```

Resposta `403` — Chave inválida, ou consulta de campanhas não liberada para a conta

```json
{"message":"Not authorized"}
```

Resposta `404` — A campanha não existe ou não pertence ao seu site

```json
{"message":"Campaign not found"}
```

Resposta `500` — Falha do nosso lado

```json
{"message":"Internal server error"}
```

## Excluir campanha — `DELETE /campaign/{campaignId}`

URL da página: https://docs.aiwebpush.com/api/reference/delete-campaign/

Exclui uma campanha de web push que ainda não foi enviada: apaga rascunhos e cancela agendamentos.

- Rascunho — é excluído.
- Agendada para o futuro — o agendamento é cancelado e a campanha é excluída.
- Já enviada — **nada é excluído**, a resposta é 409.
- ID inexistente ou de outro site — 404.

Autenticação: header `Authorization` com a chave da API do site, sem prefixo `Bearer`.

Resposta `200` — Campanha excluída

- `id` (string) — ID da campanha excluída.
- `deleted` (boolean) — Sempre `true` quando a resposta é 200.

Exemplo:

```json
{
  "id": "abc12--987654",
  "deleted": true
}
```

Resposta `400` — campaignId ausente

```json
{"message":"campaignId is required"}
```

Resposta `403` — Chave inválida, ou exclusão de campanha não liberada para a conta

```json
{"message":"Not authorized"}
```

Resposta `404` — A campanha não existe ou não pertence ao seu site

```json
{"message":"Campaign not found"}
```

Resposta `409` — Campanha já enviada

```json
{"message":"Cannot delete a campaign that has already been sent"}
```

Resposta `500` — Falha do nosso lado

```json
{"message":"Internal server error"}
```

## Listar tópicos — `GET /topics`

URL da página: https://docs.aiwebpush.com/api/reference/list-topics/

Lista os tópicos de interesse do site que têm pelo menos um inscrito, do mais popular para o menos popular, com a quantidade de inscritos de cada um.

Os nomes vêm em minúsculas. Use esses nomes, exatamente como vieram, no campo
`topics` da criação de campanha.

A resposta é uma lista vazia quando o site ainda não tem inscritos classificados
ou quando a conta não tem acesso à API liberado.

Autenticação: header `Authorization` com a chave da API do site, sem prefixo `Bearer`.

Resposta `200` — Lista de tópicos

- `[].name` (string) — Nome do tópico ou do país, sempre em minúsculas. Países vêm com o prefixo `country__`.
- `[].users` (number) — Quantidade de inscritos.

Exemplo:

```json
[
  {
    "name": "tecnologia",
    "users": 1840
  },
  {
    "name": "esportes",
    "users": 920
  },
  {
    "name": "religião",
    "users": 310
  }
]
```

Resposta `403` — Chave ausente, errada ou não reconhecida

```json
{"message":"Not authorized"}
```

Resposta `500` — Falha do nosso lado

```json
{"message":"Internal server error"}
```

## Listar países — `GET /countries`

URL da página: https://docs.aiwebpush.com/api/reference/list-countries/

Lista os países que têm inscritos no site, com a quantidade de inscritos de cada um, no mesmo formato de `/topics`.

O `name` vem em minúsculas, com o prefixo `country__` (ex.: `country__brazil`), e é
assim que deve ser enviado no campo `countries` da criação de campanha. Inscritos
sem país identificado aparecem em `country__desconhecido`.

Como em `/topics`, a resposta é uma lista vazia quando não há inscritos localizados
ou quando a conta não tem acesso à API liberado.

Autenticação: header `Authorization` com a chave da API do site, sem prefixo `Bearer`.

Resposta `200` — Lista de países

- `[].name` (string) — Nome do tópico ou do país, sempre em minúsculas. Países vêm com o prefixo `country__`.
- `[].users` (number) — Quantidade de inscritos.

Exemplo:

```json
[
  {
    "name": "country__brazil",
    "users": 2100
  },
  {
    "name": "country__desconhecido",
    "users": 45
  }
]
```

Resposta `403` — Chave ausente, errada ou não reconhecida

```json
{"message":"Not authorized"}
```

Resposta `500` — Falha do nosso lado

```json
{"message":"Internal server error"}
```