> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Primeiro envio push: criar app, registrar dispositivo Web e disparar notificação.

<Tip>
  Do **zero ao primeiro push na fila** em poucos passos: **Push App** → **dispositivo registrado** → **envio** com os device IDs em `to`.
</Tip>

## 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](/push-api/como-funciona/introducao). Escopos: [Escopos da API Key](/push-api/como-funciona/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](/guides/sandbox/index) se estiver começando

<Note>
  Chave com **`pushAppIds`** no painel só envia para dispositivos desses apps. Outro app → **403** (`PUSH_APP_NOT_ALLOWED`).
</Note>

***

## 1. Criar Push App

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

#### 1A, Pelo painel

1. Push → **Novo app**
2. Informe o **nome** do produto
3. Anote o **`id`** do app e a **chave pública VAPID** (para o site)

#### 1B, Pela API

```http theme={null}
POST /v1/push/apps
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "name": "Meu App"
}
```

Resposta esperada: **200** com VAPID gerado automaticamente:

```json theme={null}
{
  "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:

```http theme={null}
PUT /v1/push/apps/:id
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "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:

```http theme={null}
POST /v1/push/devices
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

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

Resposta esperada: **200**:

```json theme={null}
{
  "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`**.

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

***

## 3. Enviar notificação

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

```http theme={null}
POST /v1/push/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "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](/template-api/como-funciona/variaveis-disponiveis-e-crud) com canal push habilitado:

```json theme={null}
{
  "to": ["clxxdevice..."],
  "type": "template",
  "payload": {
    "templateId": "ID_DO_TEMPLATE",
    "variables": { "name": "Maria" }
  }
}
```

Resposta esperada: **202**

```json theme={null}
{
  "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**

```http theme={null}
GET /v1/push/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
```

Filtros opcionais: `status`, `appId`. Escopo: **`push:read`**.

**Ver um envio**

```http theme={null}
GET /v1/push/messages/:id
Authorization: Bearer sk_live_xxxxx
```

**Cancelar agendado** (só status **SCHEDULED**):

```http theme={null}
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](/guides/conceitos/seguranca-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](/push-api/como-funciona/eventos-do-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](/push-api/como-funciona/introducao): quando usar e ciclo de status
* [Escopos](/push-api/como-funciona/escopos-da-api-key): permissões da chave
* [Eventos dos webhooks](/push-api/como-funciona/eventos-do-webhooks): status em tempo real
* [Respostas de erro](/guides/conceitos/resposta-de-erros): códigos HTTP e `code`