Approfondimento Tecnico — Sistema Calendario ICS

Il problema di partenza

L’Agriturismo La Bertorella utilizza Booking.com per ricevere una parte delle prenotazioni. Tuttavia, Booking non mette a disposizione un’API completamente aperta per leggere in tempo reale la disponibilità delle camere.

Questo crea un problema concreto:
come evitare che un utente invii una richiesta di prenotazione in un giorno già occupato?

Era necessario trovare un modo per sincronizzare il sito con le prenotazioni già presenti su Booking, senza:
• strumenti server-side costosi;
• plugin di terze parti;
• dipendenze esterne;
• manutenzione complicata per il cliente.

La soluzione: sincronizzazione tramite file ICS

Booking.com permette l’esportazione delle prenotazioni tramite file .ics, lo stesso formato utilizzato da Google Calendar, Apple Calendar e Outlook.

Questi file vengono aggiornati automaticamente da Booking ad ogni nuova prenotazione o cancellazione.

Il sito utilizza questi file per:

• • leggere la disponibilità reale delle camere
• • oscurare automaticamente le date non disponibili
• • evitare richieste su date già prenotate
• • mantenere il calendario sempre aggiornato

Snippet di codice

// Inizializza i calendari con le date non disponibili
function setupCalendars() {
  flatpickr("#checkin", {
    dateFormat: "d/m/Y",
    altInput: true,
    altFormat: "l, d F Y",
    locale: "it",
    minDate: "today",
    disable: bookedDates
  });

  flatpickr("#checkout", {
    dateFormat: "d/m/Y",
    altInput: true,
    altFormat: "l, d F Y",
    locale: "it",
    minDate: "today",
    disable: bookedDates
  });
}

// Setup completo al caricamento pagina
document.addEventListener("DOMContentLoaded", async () => {
  await loadBookedDates();  // Scarica dal repo GitHub
  setupCalendars();         // Inizializza Flatpickr
});

Perché ospitare i file ICS su GitHub?

I file .ics vengono esportati da Booking tramite un link pubblico. Per utilizzarli nel sito serviva un luogo stabile, affidabile e accessibile via HTTPS.

La scelta più efficace è stata:
creare un repository GitHub dedicato ai file ICS.

Vantaggi:

• • Hosting HTTPS gratuito
• • Percorsi stabili e permanenti
• • Facilità di aggiornamento tramite GitHub Actions
• • Separazione perfetta tra codice del sito e dati
• • Caricamento rapido lato client senza server dedicato

Architettura del sistema

Il sistema si basa su una pipeline semplice, stabile e scalabile.

1. Booking.com → Esporta file ICS
Ogni camera ha un link ICS generato da Booking.

2. GitHub Actions → Scarica e aggiorna i file ICS
Un workflow automatico li scarica ogni ora e li salva nel repository.

3. Il sito → Legge i file ICS da GitHub
La pagina prenotazioni effettua una richiesta fetch ai file ospitati nel repo.

4. Flatpickr → Oscura le date prenotate
Le prenotazioni vengono convertite in un array di date disabilitate.

Flusso di lavoro

1. 1. GitHub Actions scarica i file ICS aggiornati.
2. 2. I file vengono salvati nella cartella /ics del repository.
3. 3. Il sito, quando si apre la pagina prenotazioni, fa una richiesta ai file nel repo.
4. 4. Le date presenti negli eventi ICS vengono parse e trasformate in formato leggibile da Flatpickr.
5. 5. Il calendario si aggiorna automaticamente, oscurando le date impossibili da prenotare.

Sicurezza

I file ICS non contengono dati sensibili: solo date e numero di prenotazioni. Per questo possono essere ospitati in un repository pubblico.

Inoltre:
• nessuna informazione del cliente viene esposta
• nessuna API privata viene utilizzata
• tutto avviene lato client con massima trasparenza

Possibili sviluppi futuri

• • Gestione anche delle prenotazioni ricevute via telefono o email
• • Aggiunta di eventi ricorrenti (es. chiusure stagionali)
• • Dashboard privata per il titolare
• • Validazioni dinamiche avanzate