> ## 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 de SMS pela API: enviar, consultar e cancelar agendamento.

<Tip>
  Do **zero ao primeiro SMS na fila** em poucos passos. Comece com `sk_test_...` no [Sandbox](/guides/sandbox/index).
</Tip>

## Em poucas palavras

* **Envie** texto curto (9 a 160 caracteres) para um ou vários números.
* **Consulte** histórico ou um envio pelo id.
* **Cancele** enquanto o status for `QUEUED` ou `SCHEDULED`.

Contexto: [Introdução](/sms-api/como-funciona/introducao). Escopos: [Escopos da API Key](/sms-api/como-funciona/escopos-da-api-key).

***

## Antes de começar

| Item                                           | Obrigatório                     |
| ---------------------------------------------- | ------------------------------- |
| Chave com **`sms:send`**                       | Sim                             |
| Números em formato **internacional** (sem `+`) | Sim                             |
| `sms:read` / `sms:cancel`                      | Só se for consultar ou cancelar |

Base URL: `https://api.notifique.dev`. Substitua `sk_live_xxxxx` pela sua chave (`sk_test_...` no sandbox).

***

## 1. Enviar SMS

`to` é sempre um **array** (até **100** destinatários).

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

```json theme={null}
{
  "to": ["5511999999999", "5521988887777"],
  "type": "text",
  "payload": {
    "message": "Seu código é 482910. Válido por 10 minutos."
  }
}
```

**Resposta (202)**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "messageIds": ["clxx123...", "clxx456..."],
    "smsIds": ["clxx123...", "clxx456..."]
  }
}
```

`messageIds` é o campo canônico. `smsIds` é alias de compatibilidade.

<Note>
  Menos de **9 caracteres** em `payload.message` → **400** (`SMS_MESSAGE_TOO_SHORT`).
</Note>

### Enviar com template

Se você já tem um [template do workspace](/template-api/como-funciona/variaveis-disponiveis-e-crud) com canal SMS habilitado, use `type: "template"`, o mesmo padrão de WhatsApp, Telegram e os demais canais:

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

A API resolve o texto do template, substitui variáveis e enfileira o SMS.

***

## 2. Listar histórico

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

```json theme={null}
{
  "success": true,
  "data": [
    {
      "smsId": "clxx123...",
      "to": "5511999999999",
      "message": "Seu código é 482910...",
      "status": "DELIVERED",
      "sentAt": "2025-02-20T14:00:00.000Z",
      "deliveredAt": "2025-02-20T14:00:30.000Z"
    }
  ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
}
```

***

## 3. Consultar um envio

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

Retorna o mesmo formato de um item da listagem. Requer **`sms:read`**.

***

## 4. Agendar e cancelar

**Agendar**, inclua no POST de envio:

```json theme={null}
{
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Lembrete amanhã às 9h."
  },
  "schedule": { "sendAt": "2025-03-01T09:00:00.000Z" }
}
```

**Cancelar** (`QUEUED` ou `SCHEDULED`):

```http theme={null}
POST /v1/sms/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx
```

Créditos do agendamento voltam para o workspace. Escopo: **`sms:cancel`**.

***

## 5. Evitar duplicata

Header **`Idempotency-Key`** no `POST`. Repetições em até 24 h não criam dois envios iguais. Veja [Segurança e Confiabilidade](/guides/conceitos/seguranca-e-confiabilidade).

***

## 6. Webhooks (opcional)

Configure `sms.sent`, `sms.delivered`, `sms.failed` e MO (`sms.received`, `sms.replied`) para acompanhar sem polling.

Guia: [Eventos dos webhooks](/sms-api/como-funciona/eventos-do-webhooks).

***

## Todos os tipos de envio

Na referência da API (aba SMS), abra **Enviar SMS** (`POST /v1/...`) e escolha o exemplo no playground: Texto, Template, Agendado, Opções.

## Próximos passos

* [Introdução](/sms-api/como-funciona/introducao): quando usar e ciclo de status
* [Escopos](/sms-api/como-funciona/escopos-da-api-key): permissões da chave
* [Eventos dos webhooks](/sms-api/como-funciona/eventos-do-webhooks): status em tempo real
* [Respostas de erro](/guides/conceitos/resposta-de-erros): códigos HTTP e `code`