> ## 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.

# Inicio rápido

> Primer envío de SMS vía API: envía, consulta y cancela mensajes programados.

<Tip>
  De **cero a tu primer SMS en la cola** en unos pocos pasos. Empieza con `sk_test_...` en [Sandbox](/es/guides/sandbox/index).
</Tip>

## En breve

* **Enviar** texto corto (de 9 a 160 caracteres) a uno o varios números.
* **Consultar** historial o un envío por id.
* **Cancelar** mientras el estado sea `QUEUED` o `SCHEDULED`.

Contexto: [Introducción](/es/sms-api/como-funciona/introducao). Alcances: [Alcances de clave API](/es/sms-api/como-funciona/escopos-da-api-key).

***

## Antes de empezar

| Item                                           | Obligatorio                  |
| ---------------------------------------------- | ---------------------------- |
| Clave con **`sms:send`**                       | Sí                           |
| Números en formato **internacional** (sin `+`) | Sí                           |
| `sms:read` / `sms:cancel`                      | Solo si consultas o cancelas |

URL base: `https://api.notifique.dev`. Reemplaza `sk_live_xxxxx` por tu clave (`sk_test_...` en sandbox).

***

## 1. Enviar SMS

`to` es siempre un **array** (hasta **100** destinatarios).

```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": "Tu código es 482910. Válido por 10 minutos."
  }
}
```

**Respuesta (202)**

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

`messageIds` es el campo canónico. `smsIds` es un alias de compatibilidad.

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

### Enviar con plantilla

Si ya tienes una [plantilla del workspace](/es/template-api/como-funciona/variaveis-disponiveis-e-crud) con SMS habilitado, usa `type: "template"`, el mismo patrón que WhatsApp, Telegram y los demás canales:

```json theme={null}
{
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "ID_DE_LA_PLANTILLA",
    "variables": { "code": "482910", "name": "María" }
  }
}
```

La API resuelve el texto de la plantilla, sustituye variables y encola el SMS.

***

## 2. Listar historial

```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": "Tu código es 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 un envío

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

Misma forma que un elemento de la lista. Requiere **`sms:read`**.

***

## 4. Programar y cancelar

**Programar**, incluye en el POST de envío:

```json theme={null}
{
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Recordatorio mañana a las 9h."
  },
  "schedule": { "sendAt": "2025-03-01T09:00:00.000Z" }
}
```

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

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

Los créditos programados regresan al workspace. Alcance: **`sms:cancel`**.

***

## 5. Evitar duplicados

Header **`Idempotency-Key`** en el POST. Los reintentos dentro de 24 h no crean envíos duplicados. Ver [Seguridad y confiabilidad](/es/guides/conceitos/seguranca-e-confiabilidade).

***

## 6. Webhooks (opcional)

Configura `sms.sent`, `sms.delivered`, `sms.failed` y MO (`sms.received`, `sms.replied`) para seguimiento sin polling.

Guía: [Eventos de webhook](/es/sms-api/como-funciona/eventos-do-webhooks).

***

## Todos los tipos de envío

En la referencia de la API (pestaña SMS), abra **Enviar SMS** y elija un ejemplo en el playground: Texto, Plantilla, Programado, Opciones.

## Próximos pasos

* [Introducción](/es/sms-api/como-funciona/introducao): cuándo usar y ciclo de estados
* [Alcances](/es/sms-api/como-funciona/escopos-da-api-key): permisos de la clave
* [Eventos de webhook](/es/sms-api/como-funciona/eventos-do-webhooks): estado en tiempo real
* [Respuestas de error](/es/guides/conceitos/resposta-de-erros): códigos HTTP y `code`