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

# Agendamento e Gerenciamento de Fuso Horário

> Guia para agendamento de notificações com suporte a fuso horário

## Introdução

Todos os endpoints de notificação da Lovi suportam agendamento para entrega futura. Este recurso permite enviar notificações em horários ideais considerando fusos horários dos destinatários e horário comercial.

## 📅 Parâmetros de Agendamento

Tanto notificações WhatsApp quanto de Voz suportam os seguintes parâmetros de agendamento:

### Parâmetros

| Parâmetro          | Tipo     | Obrigatório | Descrição                              | Exemplo                 |
| ------------------ | -------- | ----------- | -------------------------------------- | ----------------------- |
| `datetime_sending` | DateTime | Não         | Data/hora agendada no formato ISO 8601 | `"2024-12-25T10:30:00"` |
| `timezone`         | String   | Não         | Fuso horário para o horário agendado   | `"Europe/Madrid"`       |

**Comportamento Padrão**: Se `datetime_sending` não for fornecido, a notificação é enviada imediatamente.

***

## 🕐 Formato de Datetime

### Formatos ISO 8601 Suportados

```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

* **Data Futura Obrigatória**: O datetime deve estar no futuro
* **ISO 8601 Rigoroso**: Use o formato padrão ISO 8601
* **Fuso Horário Recomendado**: Sempre especifique o fuso horário para mensagens agendadas
* **UTC Padrão**: Se o fuso horário for omitido, UTC é usado

***

## 🌍 Fusos Horários Suportados

### Fusos Horários Comerciais Comuns

| Região/País        | Código do Fuso Horário           | Descrição                  |
| ------------------ | -------------------------------- | -------------------------- |
| **Espanha**        | `Europe/Madrid`                  | Horário da Europa Central  |
| **México**         | `America/Mexico_City`            | Horário Padrão Central     |
| **Argentina**      | `America/Argentina/Buenos_Aires` | Horário da Argentina       |
| **Colômbia**       | `America/Bogota`                 | Horário da Colômbia        |
| **Chile**          | `America/Santiago`               | Horário Padrão do Chile    |
| **Peru**           | `America/Lima`                   | Horário do Peru            |
| **Equador**        | `America/Guayaquil`              | Horário do Equador         |
| **Venezuela**      | `America/Caracas`                | Horário da Venezuela       |
| **Brasil**         | `America/Sao_Paulo`              | Horário de Brasília        |
| **Estados Unidos** | `America/New_York`               | Horário Padrão do Leste    |
| **Estados Unidos** | `America/Chicago`                | Horário Padrão Central     |
| **Estados Unidos** | `America/Denver`                 | Horário Padrão da Montanha |
| **Estados Unidos** | `America/Los_Angeles`            | Horário Padrão do Pacífico |
| **UTC**            | `UTC`                            | Coordenado Universal       |

### Fusos Horários Europeus

| País            | Código do Fuso Horário | Descrição                   |
| --------------- | ---------------------- | --------------------------- |
| **Reino Unido** | `Europe/London`        | Horário de Greenwich        |
| **França**      | `Europe/Paris`         | Horário da Europa Central   |
| **Alemanha**    | `Europe/Berlin`        | Horário da Europa Central   |
| **Itália**      | `Europe/Rome`          | Horário da Europa Central   |
| **Holanda**     | `Europe/Amsterdam`     | Horário da Europa Central   |
| **Portugal**    | `Europe/Lisbon`        | Horário da Europa Ocidental |

***

## 📋 Exemplos

### Notificação WhatsApp Agendada

**Envio imediato (sem agendamento):**

```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"
}
```

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

***

## ⚙️ Regras de Validação

### Validação de Data

* ✅ **Apenas datas futuras**: Deve ser posterior ao horário atual
* ✅ **Máximo de antecedência**: Até 1 ano de antecedência
* ✅ **Formato rigoroso**: Deve seguir ISO 8601
* ❌ **Datas passadas**: Serão rejeitadas
* ❌ **Formato inválido**: Datas não-ISO rejeitadas

### Validação de Fuso Horário

* ✅ **Códigos IANA válidos**: Use o banco de dados de fusos horários padrão
* ✅ **Sensível a maiúsculas**: Formato exato obrigatório
* ❌ **Abreviações**: Não use CET, EST, etc.
* ❌ **Códigos inválidos**: Fusos horários desconhecidos rejeitados

***

## 🚀 Boas Práticas

### Horário Ideal

**Mensagens WhatsApp:**

* **Horário comercial**: 9:00 - 18:00 horário local
* **Evite cedo/tarde**: Não antes das 8:00 ou após as 21:00
* **Consideração de final de semana**: Ajuste para preferências de fim de semana
* **Atenção a feriados**: Verifique feriados locais

**Chamadas de Voz:**

* **Apenas horário comercial**: 9:00 - 17:00 horário local
* **Dias úteis preferidos**: Segunda a Sexta
* **Horário de almoço**: Evite 12:00 - 14:00
* **Sensibilidade cultural**: Respeite costumes locais

### Estratégia de Fuso Horário

1. **Armazene fusos dos usuários**: Salve fuso horário preferido por contato
2. **Exibição em horário local**: Mostre horários no fuso local do usuário
3. **Lógica de horário comercial**: Calcule horários ideais de envio
4. **Horário de verão**: Códigos IANA tratam DST automaticamente

### Fluxo de Agendamento

```mermaid theme={null}
graph TD
    A[Entrada do Usuário] --> B[Validar DateTime]
    B --> C[Validar Fuso Horário]
    C --> D[Verificar Data Futura]
    D --> E[Enfileirar Notificação]
    E --> F[Enviar no Horário Agendado]
```

***

## 🛠️ Dicas de Desenvolvimento

### Testando Agendamento

1. **Use futuro próximo**: Teste com horários 5-10 minutos à frente
2. **Teste de fuso horário**: Teste diferentes cenários de fuso horário
3. **Casos limites**: Teste transições de horário de verão
4. **Tratamento de erros**: Teste com datas/fusos inválidos

### Considerações de Produção

* **Tempo de buffer**: Adicione 2-3 minutos de buffer para processamento
* **Monitoramento**: Monitore horários agendados vs reais de envio
* **Lógica de retry**: Trate falhas temporárias graciosamente
* **Logs**: Registre detalhes de agendamento para debugging

### Recursos de Fuso Horário

* **Banco de Dados IANA**: [Banco de dados oficial de fusos horários](https://www.iana.org/time-zones)
* **Conversor online**: Use ferramentas para verificar códigos de fuso horário
* **Documentação**: Mantenha referência de fusos horários para desenvolvedores