Programmazione e gestione fusi orari

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.

​

Introduzione

​

📅 Parametri di programmazione

​

Parametri

​

🕐 Formato data e ora

​

Formati ISO 8601 supportati

{
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Madrid"
}

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

​

Note importanti

• Data futura obbligatoria: La data deve essere nel futuro
• ISO 8601 rigoroso: Usa il formato standard ISO 8601
• Fuso orario raccomandato: Specifica sempre il fuso orario per i messaggi programmati
• UTC predefinito: Se il fuso orario viene omesso, viene usato UTC

​

🌍 Fusi orari supportati

​

Fusi orari aziendali comuni

​

Fusi orari europei

​

📋 Esempi

​

Notifica WhatsApp programmata

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

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

​

Notifica vocale programmata

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

​

Struttura piatta con programmazione (unflatten=true)

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

​

⚙️ Regole di validazione

​

Validazione delle date

• ✅ Solo date future: Deve essere successiva all’ora corrente
• ✅ Anticipo massimo: Fino a 1 anno di anticipo
• ✅ Formato rigoroso: Deve seguire ISO 8601
• ❌ Date passate: Saranno rifiutate
• ❌ Formato non valido: Date non-ISO rifiutate

​

Validazione del fuso orario

• ✅ Codici IANA validi: Usa il database standard dei fusi orari
• ✅ Case sensitive: Formato esatto richiesto
• ❌ Abbreviazioni: Non usare CET, EST, ecc.
• ❌ Codici non validi: Fusi orari sconosciuti rifiutati

​

Esempi di valido/non valido

{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "America/Mexico_City"
}

{
  "datetime_sending": "12/25/2024 2:30 PM",  // Formato errato
  "timezone": "Europe/Madrid"
}

{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "CET"  // Usa Europe/Madrid invece
}

​

🚀 Migliori pratiche

​

Tempistica ottimale

• Orario lavorativo: 9:00 - 18:00 ora locale
• Evita orari estremi: Non prima delle 8:00 o dopo le 21:00
• Considerazione weekend: Regola per le preferenze del fine settimana
• Consapevolezza festività: Controlla le festività locali

• Solo orario lavorativo: 9:00 - 17:00 ora locale
• Giorni lavorativi preferiti: Da lunedì a venerdì
• Ore di pranzo: Evita 12:00 - 14:00
• Sensibilità culturale: Rispetta le usanze locali

​

Strategia fuso orario

1. Memorizza i fusi orari degli utenti: Salva il fuso orario preferito per contatto
2. Visualizzazione ora locale: Mostra gli orari nel fuso orario locale dell’utente
3. Logica orario lavorativo: Calcola gli orari di invio ottimali
4. Ora legale: I codici IANA gestiscono automaticamente l’ora legale

​

Flusso di lavoro di programmazione

​

📊 Esempi di risposta

​

Programmazione riuscita

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

​

Invio immediato

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

​

⚠️ Errori comuni

​

Errore data passata

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

​

Errore fuso orario non valido

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

​

Errore formato non valido

{
  "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)"
  }
}

​

🛠️ Suggerimenti per lo sviluppo

​

Testare la programmazione

1. Usa il futuro prossimo: Testa con orari 5-10 minuti avanti
2. Test fusi orari: Testa diversi scenari di fuso orario
3. Casi limite: Testa le transizioni dell’ora legale
4. Gestione errori: Testa con date/fusi orari non validi

​

Considerazioni per la produzione

• Tempo buffer: Aggiungi 2-3 minuti di buffer per l’elaborazione
• Monitoraggio: Monitora gli orari di invio programmati vs effettivi
• Logica di retry: Gestisci i fallimenti temporanei con grazia
• Log: Registra i dettagli di programmazione per il debug

​

Risorse fusi orari

• Database IANA: Database ufficiale dei fusi orari
• Convertitore online: Usa strumenti per verificare i codici dei fusi orari
• Documentazione: Mantieni un riferimento dei fusi orari per gli sviluppatori