Quick Start - Notifique

Do zero ao primeiro push na fila em poucos passos: Push App → dispositivo registrado → envio com os device IDs em to.

Em poucas palavras

Crie um Push App, VAPID Web é gerado automaticamente na criação.
Registre cada dispositivo quando o usuário aceitar no navegador e guarde o device ID.
Dispare notificações passando os device IDs em to (até 100 por chamada).

Contexto: Introdução. Escopos: Escopos da API Key.

Antes de começar

Chave com push:apps:manage, push:devices:register e push:send (ou escopo admin em teste)
Plano com push habilitado
Autenticação: Authorization: Bearer sk_live_... ou x-api-key
Base URL: https://api.notifique.dev, use sk_test_... no Sandbox se estiver começando

Chave com pushAppIds no painel só envia para dispositivos desses apps. Outro app → 403 (PUSH_APP_NOT_ALLOWED).

1. Criar Push App

Dois caminhos, escolha o que combina com sua integração:

1A, Pelo painel

Push → Novo app
Informe o nome do produto
Anote o id do app e a chave pública VAPID (para o site)

1B, Pela API

POST /v1/push/apps
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu App"
}

Resposta esperada: 200 com VAPID gerado automaticamente:

{
  "success": true,
  "data": {
    "id": "clxxapp...",
    "name": "Meu App",
    "vapidPublicKey": "BEl62iU...",
    "hasVapidPrivate": true,
    "hasFcm": false,
    "hasApns": false,
    "createdAt": "2025-02-15T10:00:00.000Z"
  }
}

Escopo: push:apps:manage. Guarde o id e use vapidPublicKey no front para registrar a subscription.

VAPID personalizado (opcional)

Se quiser usar seu próprio par de chaves em vez do gerado:

PUT /v1/push/apps/:id
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu App",
  "vapidPublicKey": "BEl62iU...",
  "vapidPrivateKey": "UUxI4S..."
}

A chave privada fica só na Notifique; a pública vai no site.

2. Registrar dispositivo

Quando o usuário autorizar no navegador, envie a subscription ao backend e registre na API:

POST /v1/push/devices
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "appId": "clxxapp...",
  "platform": "web",
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/fcm/send/...",
    "keys": {
      "p256dh": "BEl62iU...",
      "auth": "tBH2..."
    }
  },
  "externalUserId": "user_123"
}

Resposta esperada: 200:

{
  "success": true,
  "data": {
    "id": "clxxdevice...",
    "appId": "clxxapp...",
    "platform": "web",
    "externalUserId": "user_123",
    "createdAt": "2025-02-15T10:05:00.000Z"
  }
}

Guarde o id do dispositivo, é o que vai em to no envio. Escopo: push:devices:register.

Registro público (sem API Key) também existe para fluxos no front, só appId + subscription. Com chave, exige o escopo acima.

3. Enviar notificação

Até 100 device IDs por chamada. Pelo menos title ou body é obrigatório. Cada envio consome 1 crédito.

POST /v1/push/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "to": ["clxxdevice..."],
  "type": "push",
  "payload": {
    "title": "Olá!",
    "body": "Você tem uma nova mensagem.",
    "url": "https://seusite.com/notificacoes",
    "icon": "https://seusite.com/icon.png"
  },
  "options": { "priority": "normal" }
}

Pelo menos title ou body em payload é obrigatório.

Enviar com template

Se você já tem um template do workspace com canal push habilitado:

{
  "to": ["clxxdevice..."],
  "type": "template",
  "payload": {
    "templateId": "ID_DO_TEMPLATE",
    "variables": { "name": "Maria" }
  }
}

Resposta esperada: 202

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clpush1..."],
    "pushIds": ["clpush1..."]
  }
}

messageIds é o campo canônico; pushIds é alias de compatibilidade. Escopo: push:send. Agendar, inclua schedule.sendAt (ISO 8601) no body. Webhook só deste lote: options.webhook com url e secret.

4. Consultar, listar e cancelar

Listar envios

GET /v1/push/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

Filtros opcionais: status, appId. Escopo: push:read. Ver um envio

GET /v1/push/messages/:id
Authorization: Bearer sk_live_xxxxx

Cancelar agendado (só status SCHEDULED):

POST /v1/push/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

Crédito do agendamento volta para o workspace.

5. Evitar duplicata

Header Idempotency-Key no POST de envio. Repetições em até 24 h não criam dois pushes iguais. Veja Segurança e Confiabilidade.

6. Webhooks (opcional)

Configure push.sent, push.delivered, push.clicked, push.failed e push.cancelled para acompanhar sem polling. Guia: Eventos dos webhooks.

Todos os tipos de envio

Na referência da API (aba Push), abra Enviar notificação push (POST /v1/...) e escolha o exemplo no playground: Push completo, Template, Agendado.

Próximos passos

Introdução: quando usar e ciclo de status
Escopos: permissões da chave
Eventos dos webhooks: status em tempo real
Respostas de erro: códigos HTTP e code

​Em poucas palavras

​Antes de começar

​1. Criar Push App

​1A, Pelo painel

​1B, Pela API

​VAPID personalizado (opcional)

​2. Registrar dispositivo

​3. Enviar notificação

​Enviar com template

​4. Consultar, listar e cancelar

​5. Evitar duplicata

​6. Webhooks (opcional)

​Todos os tipos de envio

​Próximos passos

Em poucas palavras

Antes de começar

1. Criar Push App

1A, Pelo painel

1B, Pela API

VAPID personalizado (opcional)

2. Registrar dispositivo

3. Enviar notificação

Enviar com template

4. Consultar, listar e cancelar

5. Evitar duplicata

6. Webhooks (opcional)

Todos os tipos de envio

Próximos passos