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

# Programación y Gestión de Zonas Horarias

> Guía para programar notificaciones con soporte de zonas horarias

## Introducción

Todos los endpoints de notificación de Lovi admiten la programación para entrega futura. Esta función te permite enviar notificaciones en los momentos óptimos teniendo en cuenta las zonas horarias de los destinatarios y el horario comercial.

## 📅 Parámetros de Programación

Tanto las notificaciones de WhatsApp como las de Voz admiten los siguientes parámetros de programación:

### Parámetros

| Parámetro          | Tipo     | Requerido | Descripción                               | Ejemplo                 |
| ------------------ | -------- | --------- | ----------------------------------------- | ----------------------- |
| `datetime_sending` | DateTime | No        | Fecha/hora programada en formato ISO 8601 | `"2024-12-25T10:30:00"` |
| `timezone`         | String   | No        | Zona horaria para la hora programada      | `"Europe/Madrid"`       |

**Comportamiento Predeterminado**: Si no se proporciona `datetime_sending`, la notificación se envía inmediatamente.

***

## 🕐 Formato de Fecha y Hora

### Formatos ISO 8601 Admitidos

```json theme={null}
{
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Madrid"
}
```

**Formatos alternativos:**

```
"2024-12-25T10:30:00"
"2024-12-25T10:30:00.000"
"2024-12-25T10:30:00Z"
"2024-12-25T10:30:00+01:00"
```

### Notas Importantes

* **Se requiere fecha futura**: La fecha y hora deben ser posteriores a la hora actual
* **ISO 8601 estricto**: Usa el formato estándar ISO 8601
* **Zona horaria recomendada**: Especifica siempre la zona horaria para mensajes programados
* **UTC por defecto**: Si se omite la zona horaria, se usa UTC

***

## 🌍 Zonas Horarias Admitidas

### Zonas Horarias Comerciales Comunes

| Región/País        | Código de Zona Horaria           | Descripción                 |
| ------------------ | -------------------------------- | --------------------------- |
| **España**         | `Europe/Madrid`                  | Hora de Europa Central      |
| **México**         | `America/Mexico_City`            | Hora Estándar Central       |
| **Argentina**      | `America/Argentina/Buenos_Aires` | Hora de Argentina           |
| **Colombia**       | `America/Bogota`                 | Hora de Colombia            |
| **Chile**          | `America/Santiago`               | Hora Estándar de Chile      |
| **Perú**           | `America/Lima`                   | Hora de Perú                |
| **Ecuador**        | `America/Guayaquil`              | Hora de Ecuador             |
| **Venezuela**      | `America/Caracas`                | Hora de Venezuela           |
| **Estados Unidos** | `America/New_York`               | Hora Estándar del Este      |
| **Estados Unidos** | `America/Chicago`                | Hora Estándar Central       |
| **Estados Unidos** | `America/Denver`                 | Hora Estándar de Montaña    |
| **Estados Unidos** | `America/Los_Angeles`            | Hora Estándar del Pacífico  |
| **UTC**            | `UTC`                            | Tiempo Universal Coordinado |

### Zonas Horarias Europeas

| País             | Código de Zona Horaria | Descripción                     |
| ---------------- | ---------------------- | ------------------------------- |
| **Reino Unido**  | `Europe/London`        | Hora del Meridiano de Greenwich |
| **Francia**      | `Europe/Paris`         | Hora de Europa Central          |
| **Alemania**     | `Europe/Berlin`        | Hora de Europa Central          |
| **Italia**       | `Europe/Rome`          | Hora de Europa Central          |
| **Países Bajos** | `Europe/Amsterdam`     | Hora de Europa Central          |
| **Portugal**     | `Europe/Lisbon`        | Hora de Europa Occidental       |

***

## 📋 Ejemplos

### Notificación de WhatsApp Programada

**Envío inmediato (sin programación):**

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "name": "Ana García"
  },
  "language_template": "es_ES",
  "name_template": "promocion_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Campaña de Navidad"
}
```

**Programado para un momento específico:**

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "name": "Ana García"
  },
  "language_template": "es_ES",
  "name_template": "promocion_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Campaña de Navidad",
  "datetime_sending": "2024-12-24T09:00:00",
  "timezone": "Europe/Madrid"
}
```

### Notificación de Voz Programada

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "first_name": "María",
    "last_name": "González"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Campaña de Voz",
  "datetime_sending": "2024-12-26T10:00:00",
  "timezone": "Europe/Madrid"
}
```

***

## ⚙️ Reglas de Validación

### Validación de Fecha

* ✅ **Solo fechas futuras**: Deben ser posteriores a la hora actual
* ✅ **Máximo de anticipación**: Hasta 1 año de anticipación
* ✅ **Formato estricto**: Debe seguir ISO 8601
* ❌ **Fechas pasadas**: Serán rechazadas
* ❌ **Formato inválido**: Fechas no ISO serán rechazadas

### Validación de Zona Horaria

* ✅ **Códigos IANA válidos**: Usa la base de datos estándar de zonas horarias
* ✅ **Sensible a mayúsculas**: Se requiere el formato exacto
* ❌ **Abreviaciones**: No uses CET, EST, etc.
* ❌ **Códigos inválidos**: Zonas horarias desconocidas serán rechazadas

***

## 🚀 Mejores Prácticas

### Horarios Óptimos

**Mensajes de WhatsApp:**

* **Horario comercial**: 9:00 - 18:00 hora local
* **Evitar muy temprano/tarde**: Ni antes de las 8:00 ni después de las 21:00
* **Consideración de fines de semana**: Ajustar según las preferencias del fin de semana
* **Conciencia de festivos**: Consultar los festivos locales

**Llamadas de Voz:**

* **Solo en horario comercial**: 9:00 - 17:00 hora local
* **Preferir días laborables**: De lunes a viernes
* **Horas de comida**: Evitar de 14:00 a 16:00
* **Sensibilidad cultural**: Respetar las costumbres locales

### Estrategia de Zona Horaria

1. **Almacenar zonas horarias de usuarios**: Guardar la zona horaria preferida por contacto
2. **Mostrar hora local**: Mostrar las horas en la zona horaria local del usuario
3. **Lógica de horario comercial**: Calcular los tiempos de envío óptimos
4. **Horario de verano**: Los códigos IANA gestionan el DST automáticamente

***

## ⚠️ Errores Comunes

### Error de Fecha Pasada

```json theme={null}
{
  "error": "validation_failed",
  "message": "La hora programada debe ser en el futuro",
  "details": {
    "field": "datetime_sending",
    "provided": "2024-12-20T10:00:00",
    "current_time": "2024-12-20T15:30:00Z"
  }
}
```

### Error de Zona Horaria Inválida

```json theme={null}
{
  "error": "validation_failed",
  "message": "Zona horaria especificada inválida",
  "details": {
    "field": "timezone",
    "provided": "CET",
    "suggestion": "Usa códigos de zona horaria IANA como 'Europe/Madrid'"
  }
}
```