Skip to main content

​
O fluxo principal (visão geral)

  1. Criar Push App e configurar VAPID (Web).
  2. No navegador do usuário, obter a subscription da Web Push API e registrar dispositivo → receber device ID.
  3. Enviar com POST /v1/push/messages passando os device IDs em to.
Se a API Key tiver pushAppIds, só dispositivos daqueles apps são aceitos.

​
Pré-requisitos

  • API Key com escopos: push:apps:read, push:apps:manage, push:devices:register, push:send, push:read.
  • Plano que permita push.
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx
Se a API Key tiver pushAppIds definido no dashboard, ela só poderá enviar notificações para dispositivos pertencentes a esses apps. Envio para dispositivos de outro app retorna 403 com code: PUSH_APP_NOT_ALLOWED.

​
1. Criar um app de push

Um Push App representa seu produto (ex.: um app Flutter que roda em Web + Android + iOS). Cada app tem credenciais por plataforma (hoje: Web com VAPID). Criar app 
POST /v1/push/apps
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu App"
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx...",
    "name": "Meu App",
    "workspaceId": "clxx...",
    "vapidPublicKey": null,
    "hasVapidPrivate": false,
    "hasFcm": false,
    "hasApns": false,
    "createdAt": "2025-02-25T12:00:00.000Z",
    "updatedAt": "2025-02-25T12:00:00.000Z"
  }
}
Configurar VAPID (Web) Gere um par de chaves VAPID (ex.: npx web-push generate-vapid-keys) e atualize o app: 
PUT /v1/push/apps/:id
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu App",
  "vapidPublicKey": "BEl62iU...",
  "vapidPrivateKey": "UUxI4S..."
}
Use a chave pública no seu site/app para registrar a subscription do usuário (Web Push API). A chave privada fica apenas no Notifique.

​
2. Registrar dispositivo (subscription Web)

Quando o usuário autorizar notificações no navegador, a Web Push API retorna uma subscription. Envie-a para o Notifique para poder enviar push para esse usuário. Request 
POST /v1/push/devices
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "appId": "clxx...",
  "platform": "web",
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/fcm/send/...",
    "keys": {
      "p256dh": "BEl62iU...",
      "auth": "tBH2..."
    }
  },
  "externalUserId": "user_123"
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxxdevice...",
    "appId": "clxx...",
    "platform": "web",
    "externalUserId": "user_123",
    "createdAt": "2025-02-25T12:00:00.000Z"
  }
}
Opcional: external_user_id identifica o usuário no seu sistema (para listar dispositivos por usuário depois).

​
3. Enviar notificação push

Envie para um ou mais device IDs (até 100 por requisição). Cada envio consome 1 crédito. Request 
POST /v1/push/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
Idempotency-Key: opcional-unico

{
  "to": ["clxxdevice1...", "clxxdevice2..."],
  "title": "Olá!",
  "body": "Você tem uma nova mensagem.",
  "url": "https://seusite.com/notificacoes",
  "icon": "https://seusite.com/icon.png",
  "schedule": { "sendAt": "2025-12-31T14:00:00.000Z" },
  "options": { "priority": "normal" }
}
Response (202) 
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "pushIds": ["clxxpush1...", "clxxpush2..."]
  }
}
Se usar schedule.sendAt, o status será SCHEDULED e a resposta incluirá scheduledAt.

​
4. Consultar status e listar

Consultar um envio 
GET /v1/push/messages/:id
Authorization: Bearer sk_live_xxxxx
Listar envios 
GET /v1/push/messages?page=1&limit=20&status=SENT&app_id=clxx...
Authorization: Bearer sk_live_xxxxx
Cancelar agendado 
POST /v1/push/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

​
5. Webhooks

Configure um webhook com eventos push.sent, push.delivered e push.failed para ser notificado quando um push for enviado ou falhar. O payload inclui pushId, deviceId, appId, status e, em falha, error.