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

# Programmation et gestion des fuseaux horaires

> Guide pour la programmation des notifications avec support des fuseaux horaires

## Introduction

Tous les endpoints de notification Lovi prennent en charge la programmation pour une livraison future. Cette fonctionnalité vous permet d'envoyer des notifications à des moments optimaux en tenant compte des fuseaux horaires des destinataires et des heures ouvrables.

## 📅 Paramètres de programmation

Les notifications WhatsApp et vocales prennent en charge les paramètres de programmation suivants :

### Paramètres

| Paramètre          | Type     | Requis | Description                              | Exemple                 |
| ------------------ | -------- | ------ | ---------------------------------------- | ----------------------- |
| `datetime_sending` | DateTime | Non    | Date/heure programmée au format ISO 8601 | `"2024-12-25T10:30:00"` |
| `timezone`         | String   | Non    | Fuseau horaire pour l'heure programmée   | `"Europe/Madrid"`       |

**Comportement par défaut** : Si `datetime_sending` n'est pas fourni, la notification est envoyée immédiatement.

***

## 🕐 Format datetime

### Formats ISO 8601 supportés

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

**Formats alternatifs :**

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

### Notes importantes

* **Date future requise** : La date doit être dans le futur
* **ISO 8601 strict** : Utilisez le format standard ISO 8601
* **Fuseau horaire recommandé** : Spécifiez toujours le fuseau horaire pour les messages programmés
* **UTC par défaut** : Si le fuseau horaire est omis, UTC est utilisé

***

## 🌍 Fuseaux horaires supportés

### Fuseaux horaires professionnels courants

| Région/Pays    | Code fuseau horaire              | Description                 |
| -------------- | -------------------------------- | --------------------------- |
| **Espagne**    | `Europe/Madrid`                  | Heure d'Europe centrale     |
| **Mexique**    | `America/Mexico_City`            | Heure normale du Centre     |
| **Argentine**  | `America/Argentina/Buenos_Aires` | Heure d'Argentine           |
| **Colombie**   | `America/Bogota`                 | Heure de Colombie           |
| **Chili**      | `America/Santiago`               | Heure normale du Chili      |
| **Pérou**      | `America/Lima`                   | Heure du Pérou              |
| **Équateur**   | `America/Guayaquil`              | Heure de l'Équateur         |
| **Venezuela**  | `America/Caracas`                | Heure du Venezuela          |
| **États-Unis** | `America/New_York`               | Heure normale de l'Est      |
| **États-Unis** | `America/Chicago`                | Heure normale du Centre     |
| **États-Unis** | `America/Denver`                 | Heure normale des Rocheuses |
| **États-Unis** | `America/Los_Angeles`            | Heure normale du Pacifique  |
| **UTC**        | `UTC`                            | Temps universel coordonné   |

### Fuseaux horaires européens

| Pays            | Code fuseau horaire | Description                |
| --------------- | ------------------- | -------------------------- |
| **Royaume-Uni** | `Europe/London`     | Heure de Greenwich         |
| **France**      | `Europe/Paris`      | Heure d'Europe centrale    |
| **Allemagne**   | `Europe/Berlin`     | Heure d'Europe centrale    |
| **Italie**      | `Europe/Rome`       | Heure d'Europe centrale    |
| **Pays-Bas**    | `Europe/Amsterdam`  | Heure d'Europe centrale    |
| **Portugal**    | `Europe/Lisbon`     | Heure d'Europe occidentale |

***

## 📋 Exemples

### Notification WhatsApp programmée

**Envoi immédiat (sans programmation) :**

```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": "Christmas Campaign"
}
```

**Programmé pour une heure spécifique :**

```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": "Christmas Campaign",
  "datetime_sending": "2024-12-24T09:00:00",
  "timezone": "Europe/Madrid"
}
```

### Notification vocale programmée

```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": "Voice Campaign",
  "datetime_sending": "2024-12-26T10:00:00",
  "timezone": "Europe/Madrid"
}
```

### Structure plate avec programmation (unflatten=true)

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

***

## ⚙️ Règles de validation

### Validation des dates

* ✅ **Dates futures uniquement** : Doit être postérieur à l'heure actuelle
* ✅ **Avance maximale** : Jusqu'à 1 an à l'avance
* ✅ **Format strict** : Doit suivre ISO 8601
* ❌ **Dates passées** : Seront rejetées
* ❌ **Format invalide** : Dates non-ISO rejetées

### Validation des fuseaux horaires

* ✅ **Codes IANA valides** : Utilisez la base de données standard des fuseaux horaires
* ✅ **Sensible à la casse** : Format exact requis
* ❌ **Abréviations** : N'utilisez pas CET, EST, etc.
* ❌ **Codes invalides** : Fuseaux horaires inconnus rejetés

### Exemples valides/invalides

**✅ Valide :**

```json theme={null}
{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "America/Mexico_City"
}
```

**❌ Datetime invalide :**

```json theme={null}
{
  "datetime_sending": "25/12/2024 14:30",  // Mauvais format
  "timezone": "Europe/Madrid"
}
```

**❌ Fuseau horaire invalide :**

```json theme={null}
{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "CET"  // Utilisez Europe/Madrid à la place
}
```

***

## 🚀 Bonnes pratiques

### Timing optimal

**Messages WhatsApp :**

* **Heures ouvrables** : 9h00 - 18h00 heure locale
* **Évitez tôt/tard** : Pas avant 8h00 ni après 21h00
* **Considération week-end** : Ajustez selon les préférences du week-end
* **Sensibilité aux jours fériés** : Vérifiez les jours fériés locaux

**Appels vocaux :**

* **Heures ouvrables uniquement** : 9h00 - 17h00 heure locale
* **Jours ouvrés préférés** : Du lundi au vendredi
* **Heures de déjeuner** : Évitez 12h00 - 14h00
* **Sensibilité culturelle** : Respectez les coutumes locales

### Stratégie de fuseaux horaires

1. **Stockez les fuseaux horaires des utilisateurs** : Enregistrez le fuseau horaire préféré par contact
2. **Affichage en heure locale** : Affichez les heures dans le fuseau horaire local de l'utilisateur
3. **Logique d'heures ouvrables** : Calculez les heures d'envoi optimales
4. **Heure d'été** : Les codes IANA gèrent automatiquement le changement d'heure

### Flux de programmation

```mermaid theme={null}
graph TD
    A[Saisie utilisateur] --> B[Valider DateTime]
    B --> C[Valider fuseau horaire]
    C --> D[Vérifier date future]
    D --> E[Mettre en file la notification]
    E --> F[Envoyer à l'heure programmée]
```

***

## 📊 Exemples de réponse

### Programmation réussie

```json theme={null}
{
  "success": true,
  "message": "Notification scheduled successfully",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z",
  "local_time": "2024-12-25T11:30:00+01:00",
  "timezone": "Europe/Madrid"
}
```

### Envoi immédiat

```json theme={null}
{
  "success": true,
  "message": "Notification queued for immediate sending",
  "notification_id": "uuid-notification-456",
  "queued_at": "2024-12-20T15:45:30Z"
}
```

***

## ⚠️ Erreurs courantes

### Erreur de date passée

```json theme={null}
{
  "error": "validation_failed",
  "message": "Scheduled time must be in the future",
  "details": {
    "field": "datetime_sending",
    "provided": "2024-12-20T10:00:00",
    "current_time": "2024-12-20T15:30:00Z"
  }
}
```

### Erreur de fuseau horaire invalide

```json theme={null}
{
  "error": "validation_failed",
  "message": "Invalid timezone specified",
  "details": {
    "field": "timezone",
    "provided": "CET",
    "suggestion": "Use IANA timezone codes like 'Europe/Madrid'"
  }
}
```

### Erreur de format invalide

```json theme={null}
{
  "error": "validation_failed",
  "message": "Invalid datetime format",
  "details": {
    "field": "datetime_sending",
    "provided": "25-12-2024 10:30",
    "expected_format": "ISO 8601 (YYYY-MM-DDTHH:MM:SS)"
  }
}
```

***

## 🛠️ Conseils de développement

### Test de la programmation

1. **Utilisez le futur proche** : Testez avec des heures 5-10 minutes en avance
2. **Test des fuseaux horaires** : Testez différents scénarios de fuseaux horaires
3. **Cas limites** : Testez les transitions d'heure d'été
4. **Gestion des erreurs** : Testez avec des dates/fuseaux horaires invalides

### Considérations pour la production

* **Temps tampon** : Ajoutez 2-3 minutes de tampon pour le traitement
* **Surveillance** : Surveillez les heures d'envoi programmées vs réelles
* **Logique de retry** : Gérez les échecs temporaires gracieusement
* **Journaux** : Journalisez les détails de programmation pour le débogage

### Ressources fuseaux horaires

* **Base de données IANA** : [Base de données officielle des fuseaux horaires](https://www.iana.org/time-zones)
* **Convertisseur en ligne** : Utilisez des outils pour vérifier les codes de fuseaux horaires
* **Documentation** : Gardez une référence des fuseaux horaires pour les développeurs