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

# Recordatorios

> API Externa de Recordatorios: crea eventos y citas para tus contactos desde tu propio sistema

### Introducción

Los **Pools de Recordatorios** permiten programar el envío automático de mensajes de WhatsApp (plantillas o encuestas de satisfacción) antes o después de un evento/cita de un contacto.

Cuando el origen de eventos del pool es **API Externa**, Plazbot genera un **API Key** único (con prefijo `rpk_`) para que puedas crear, actualizar, eliminar y listar eventos desde tu propio sistema (ERP, agenda médica, e-commerce, etc.).

En esta guía encontrarás:

* Cómo autenticarte con el API Key.
* Cómo se crean los contactos automáticamente.
* Cómo se interpretan las fechas y zonas horarias.
* Los 5 endpoints disponibles con ejemplos en `curl`.

### Obtener el API Key

1. Ve a **Automatizaciones → Recordatorios**.
2. Crea o edita un pool de recordatorios.
3. En **Origen de eventos** selecciona **API Externa**.
4. Copia el **API Key** generado (formato `rpk_...`) y el **ID del pool** que aparece en las URLs de la documentación del modal.

<Warning>
  El API Key es secreto. No lo expongas en código del lado del cliente (navegador, apps móviles). Úsalo únicamente desde tu backend.
</Warning>

### Autenticación

Todos los endpoints requieren el header `x-api-key` con el API Key del pool:

```bash theme={null}
-H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Si el API Key no corresponde al pool indicado en la URL, la API responde `401 UNAUTHORIZED`.

### Creación automática de contactos

Al crear un evento, Plazbot busca el contacto por su número de teléfono (`contactPhone`) dentro del workspace:

* **Si el contacto existe**, el evento se agrega a su calendario.
* **Si el contacto NO existe, se crea automáticamente** con estos datos:

| Campo                    | Valor                                                           |
| ------------------------ | --------------------------------------------------------------- |
| Nombre                   | `contactName` del request (si no se envía, se usa el teléfono)  |
| Número de WhatsApp       | `contactPhone` del request                                      |
| Canal                    | **WhatsApp**                                                    |
| Visible en el chat       | **Sí** (aparece en el Chat en línea y en la lista de contactos) |
| Agente asignado          | Sin asignar                                                     |
| Etiquetas / Segmentación | Vacías                                                          |

<Tip>
  ✅ El contacto creado por la API se comporta igual que cualquier contacto de WhatsApp: aparece en el módulo de Chats, puedes asignarle agentes, etiquetas y verás sus eventos en el calendario del contacto.
</Tip>

### Fechas y zona horaria

Las fechas se envían en formato ISO 8601 y se interpretan así:

* **Sin sufijo `Z`** (ej: `"2026-03-15T10:00:00"`): se interpretan en la **zona horaria del workspace** y se convierten internamente a UTC.
* **Con sufijo `Z`** (ej: `"2026-03-15T15:00:00Z"`): se consideran ya en UTC y se usan tal cual.
* Si no envías `endDate`, se usa automáticamente `startDate + 30 minutos`.

<Note>
  Ejemplo: si tu workspace está en UTC-5 (Lima/Bogotá) y envías `"2026-03-15T10:00:00"`, el evento queda registrado a las 10:00 a.m. hora local (15:00 UTC).
</Note>

### Endpoints

La URL base es:

```
https://api.plazbot.com/api/reminders/{poolId}
```

| Método   | Ruta                | Descripción                      |
| -------- | ------------------- | -------------------------------- |
| `POST`   | `/events`           | Crear un evento                  |
| `POST`   | `/events/bulk`      | Crear eventos en lote (máx. 100) |
| `PUT`    | `/events/{eventId}` | Actualizar un evento             |
| `DELETE` | `/events/{eventId}` | Eliminar un evento               |
| `GET`    | `/events`           | Listar eventos del pool          |

***

### Crear evento

Crea un evento/cita para un contacto. Si el contacto no existe, se crea automáticamente.

**Campos del body:**

| Campo          | Tipo     | Requerido | Descripción                                                  |
| -------------- | -------- | --------- | ------------------------------------------------------------ |
| `contactPhone` | string   | ✅ Sí      | Teléfono de WhatsApp con código de país (ej: `+51999888777`) |
| `contactName`  | string   | No        | Nombre del contacto (usado solo si el contacto no existe)    |
| `title`        | string   | ✅ Sí      | Título del evento                                            |
| `description`  | string   | No        | Descripción del evento                                       |
| `startDate`    | datetime | ✅ Sí      | Fecha/hora de inicio                                         |
| `endDate`      | datetime | No        | Fecha/hora de fin (por defecto `startDate + 30 min`)         |

```bash theme={null}
curl -X POST "https://api.plazbot.com/api/reminders/{poolId}/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "contactPhone": "+573001234567",
    "contactName": "Juan Pérez",
    "title": "Cita odontológica",
    "description": "Limpieza dental",
    "startDate": "2026-03-15T10:00:00",
    "endDate": "2026-03-15T10:30:00"
  }'
```

**Respuesta exitosa:**

```json theme={null}
{
  "success": true,
  "code": 200,
  "message": "Evento creado correctamente.",
  "data": {
    "eventId": "a1b2c3d4-...",
    "contactId": "e5f6g7h8-..."
  }
}
```

<Tip>
  Guarda el `eventId` que retorna la API: lo necesitarás para actualizar o eliminar el evento después.
</Tip>

***

### Crear eventos en lote

Crea múltiples eventos en una sola solicitud. **Máximo 100 eventos por request.** Los eventos se agrupan por teléfono, por lo que puedes crear varios eventos para el mismo contacto.

```bash theme={null}
curl -X POST "https://api.plazbot.com/api/reminders/{poolId}/events/bulk" \
  -H "Content-Type: application/json" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "events": [
      {
        "contactPhone": "+573001234567",
        "contactName": "Juan Pérez",
        "title": "Cita odontológica",
        "startDate": "2026-03-15T10:00:00"
      },
      {
        "contactPhone": "+573009876543",
        "contactName": "María López",
        "title": "Control mensual",
        "startDate": "2026-03-16T14:00:00",
        "endDate": "2026-03-16T14:30:00"
      }
    ]
  }'
```

**Respuesta:** un arreglo con el resultado de cada evento. Si un evento falla la validación (falta `title` o `startDate`), no bloquea al resto:

```json theme={null}
{
  "success": true,
  "code": 200,
  "message": "2 evento(s) creado(s) correctamente.",
  "data": [
    {
      "eventId": "a1b2c3d4-...",
      "contactId": "e5f6g7h8-...",
      "contactPhone": "+573001234567",
      "title": "Cita odontológica",
      "success": true
    },
    {
      "contactPhone": "+573009876543",
      "title": "Control mensual",
      "success": false,
      "error": "title y startDate son requeridos."
    }
  ]
}
```

***

### Actualizar evento

Actualiza los datos de un evento existente. **Solo envía los campos que deseas cambiar**; los demás conservan su valor.

```bash theme={null}
curl -X PUT "https://api.plazbot.com/api/reminders/{poolId}/events/{eventId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "title": "Cita reprogramada",
    "startDate": "2026-03-20T15:00:00Z"
  }'
```

**Respuesta exitosa:**

```json theme={null}
{
  "success": true,
  "code": 200,
  "message": "Evento actualizado correctamente.",
  "data": { "eventId": "a1b2c3d4-..." }
}
```

***

### Eliminar evento

Elimina un evento y cancela sus recordatorios pendientes.

```bash theme={null}
curl -X DELETE "https://api.plazbot.com/api/reminders/{poolId}/events/{eventId}" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

<Note>
  Eliminar un evento **NO elimina el contacto**. El contacto permanece en tu CRM y en el Chat en línea; solo se elimina el evento de su calendario y dejan de enviarse los recordatorios asociados a ese evento.
</Note>

***

### Listar eventos

Obtiene todos los eventos registrados en el pool.

```bash theme={null}
curl -X GET "https://api.plazbot.com/api/reminders/{poolId}/events" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

**Respuesta:**

```json theme={null}
{
  "success": true,
  "code": 200,
  "data": [
    {
      "eventId": "a1b2c3d4-...",
      "contactId": "e5f6g7h8-...",
      "contactName": "Juan Pérez",
      "contactPhone": "+573001234567",
      "title": "Cita odontológica",
      "description": "Limpieza dental",
      "startDate": "2026-03-15T15:00:00Z",
      "endDate": "2026-03-15T15:30:00Z",
      "eventStatus": "pending",
      "creationDate": "2026-03-01T18:22:10Z"
    }
  ]
}
```

<Note>
  Las fechas en las respuestas siempre se devuelven en **UTC** (con sufijo `Z`).
</Note>

***

### Envío de recordatorios

Una vez creado el evento, Plazbot envía los recordatorios configurados en el pool de forma automática:

1. Cada recordatorio define **cuándo enviarse**: X minutos/horas/días **antes** del inicio del evento o **después** de su finalización.
2. El **tipo de acción** puede ser una **Plantilla de WhatsApp** aprobada o una **Encuesta de satisfacción**.
3. Cada recordatorio se envía **una sola vez** por evento (no hay reenvíos duplicados).
4. El pool debe estar **Habilitado** para que los recordatorios se envíen.

<Tip>
  ✅ Puedes combinar recordatorios: por ejemplo, una plantilla de confirmación 24 horas antes de la cita y una encuesta de satisfacción 1 hora después de finalizada.
</Tip>

### Códigos de error

| Código | Error            | Descripción                                                                             |
| ------ | ---------------- | --------------------------------------------------------------------------------------- |
| `200`  | —                | Operación exitosa                                                                       |
| `101`  | `MISSING_FIELDS` | Faltan campos requeridos (`contactPhone`, `title`, `startDate` o el header `x-api-key`) |
| `194`  | `DATA_NOT_FOUND` | El evento no existe en este pool                                                        |
| `401`  | `UNAUTHORIZED`   | API Key inválido o no corresponde al pool                                               |
| `5000` | `ERROR`          | Error interno del servidor                                                              |

**Ejemplo de respuesta de error:**

```json theme={null}
{
  "success": false,
  "code": 401,
  "errorCode": "UNAUTHORIZED",
  "message": "API Key inválida o pool no encontrado.",
  "data": null
}
```