Documentação da API AI Web Push

1. Visão geral

A API do AI Web Push permite consultar os tópicos associados ao seu site e criar campanhas de notificação push por meio de requisições HTTP. Cada site possui sua própria chave de API, que deve permanecer privada.

---

2. Obtendo a chave de API

1. Acesse Configurações → API no painel: https://app.aiwebpush.com/settings
2. Selecione o site que deseja usar a API.
3. Copie a chave exibida.
4. Guarde-a em local seguro – nunca exponha em front‑end ou repositórios públicos.

Dica: armazene a chave em uma variável de ambiente ou arquivo .env no seu back‑end.

---

3. Cabeçalhos obrigatórios

Header	Valor
Content-Type	application/json
Authorization	<sua‑chave‑de‑api>

---

4. Endpoint #1 – Listar Tópicos

GET https://api.aiwebpush.com/v2/topics

Retorna um array com cada tópico e a quantidade de usuários inscritos.

Exemplo de requisição (cURL)

curl --request GET \
  --url https://api.aiwebpush.com/v2/topics \
  --header "Content-Type: application/json" \
  --header "Authorization: abcd1234efgh5678"

Resposta 200 OK

[
  { "name": "esportes",    "users": 542 },
  { "name": "negocios",    "users": 187 },
  { "name": "cinema",      "users": 95  }
]

Códigos de status possíveis

Status	Significado
200	Requisição bem‑sucedida
403	Chave inválida ou ausente
500	Erro interno inesperado

---

5. Endpoint #2 – Criar Campanha

POST https://api.aiwebpush.com/v2/campaign/create

Cria uma nova campanha de push. Envie um objeto JSON com os campos abaixo:

Campo	Tipo	Obrigatório	Regras / Observações
title	string	Sim	3 – 100 caracteres
body	string	Sim	3 – 160 caracteres
status	string	Sim	published ou draft
scheduleMode	string	Sim	now ou scheduled
scheduleDate	string	Condicional	Formato ISO UTC; obrigatório se scheduleMode = scheduled Ex: 2025-05-02T18:30:00Z
icon	string	Não	URL HTTPS de ícone (png/jpg/webp)
image	string	Não	URL HTTPS de imagem de capa
topics	string[]	Sim	Array com nomes (não objetos) dos tópicos
link	string	Sim	URL de destino do clique
callToAction	string	Não	Texto do botão (ex.: “Ler agora”)
utmSource	string	Não	Para tracking opcional
utmMedium	string	Não	—
utmCampaign	string	Não	—
ttl	number	Não	Formato segundos; Define o prazo máximo, em segundos, para entregar a notificação a um dispositivo offline antes que ela seja descartada (max: 28 dias)

Exemplo de requisição (cURL)

curl --request POST \
  --url https://api.aiwebpush.com/v2/campaign/create \
  --header "Content-Type: application/json" \
  --header "Authorization: abcd1234efgh5678" \
  --data '{
    "title": "Lançamento da Semana",
    "body": "Confira os bastidores do nosso novo produto!",
    "status": "published",
    "scheduleMode": "now",
    "scheduleDate": null,
    "icon": "https://exemplo.com/media/icon-96x96.png",
    "image": "https://exemplo.com/media/banner-produto.webp",
    "topics": ["esportes", "negocios"],
    "link": "https://exemplo.com/blog/lancamento",
    "callToAction": "Ver detalhes",
    "utmSource": "api-doc",
    "utmMedium": "push",
    "utmCampaign": "lancamento-semana"
  }'

Resposta 200 OK

{
  "Id": "c_01h9y4c3x1z7p3r5",
}

Status	Significado
200	Campanha criada
403	Chave inválida ou sem permissão
422	Campo inválido/ausente
500	Erro interno

---

6. Boas práticas de segurança

• Nunca exponha a chave em código cliente/JavaScript.
• Valide entradas antes de enviar para a API (tamanho de título, URLs https, etc.).

---

7. Próximos passos

1. Teste primeiro no ambiente de homologação (Postman ou Insomnia).
2. Integre ao seu back‑end (Node, Python, PHP, n8n, make) centralizando o header Authorization.

---

Dúvidas ou sugestões? Entre em contato por e‑mail para [email protected].