Procedura guidata: costruire il sito di uno studente

Devo costruire il sito di prenotazione diretta per lo studente [NOME]. Usa
mattone-docs /integrazioni/direct-booking/procedura-guidata come fonte: guidami
fase per fase, fammi le domande una alla volta, non andare avanti finché il
controllo della fase non è verde, e cita la pagina da cui prendi ogni regola.

​

Le regole della conversazione (valgono per Claude, in tutte le fasi)

• Una domanda alla volta. Mai una raffica di dieci domande in un messaggio solo.
• Lingua piana. Chi risponde è un operatore, non uno sviluppatore: niente nomi di impostazioni tecniche, niente gergo. «Quale sottodominio vuole usare?», non «quale hostname punta al progetto».
• Le credenziali non si incollano in chat. Le chiavi dello studente e la chiave partner di Mattone stanno nella Piattaforma e nel Vault: si recuperano da lì, non si fanno dettare a voce e non si scrivono in una conversazione.
• Ogni regola citata con la pagina da cui viene, così l’operatore può verificare.
• Controllo finale = prova, non opinione. «Dovrebbe funzionare» non è verde. Verde è: ho aperto la pagina e ha risposto.
• Se una risposta manca, la fase si mette in pausa e si dice chi la deve dare (lo studente, il team, chi coordina la Delivery). Non si inventa un valore per andare avanti.

​

Fase 0 — Intake con lo studente

1. Come si chiama il brand con cui vende, e in una frase come si presenta ai suoi ospiti?
2. In che paese sono gli appartamenti e in che valuta incassa (euro, dirham, dollari, sterline)?
3. In quali lingue deve stare il sito? (italiano e inglese sono il minimo; tedesco o francese solo se ha davvero quei mercati)
4. Quanti appartamenti mette in vendita, e per ognuno: nome, città, indirizzo, camere, bagni, quante persone dormono, prezzo base a notte, dove sono le foto?
5. Quale gestionale (PMS) usa per calendario e prenotazioni?
6. Gli appartamenti sono tutti suoi, o ci sono più proprietari che devono essere pagati separatamente?
7. Usa un CRM per i contatti, e se sì quale?
8. Ha serrature o citofoni smart in qualche appartamento? Quali e su quanti alloggi?
9. Ha già un assistente AI che risponde agli ospiti, e su quale strumento?
10. Vende anche su portali esterni (portali di prenotazione, esperienze), o solo in diretta?
11. Vuole misurare le visite e le conversioni? Se sì, con quale strumento di statistiche o pixel pubblicitario?
12. Vuole rivendere esperienze locali guadagnando una commissione?
13. Che obblighi ha per legge: codice identificativo della struttura, banner cookie, tassa di soggiorno da incassare sul sito, contratto da far firmare prima dell’arrivo?

​

Fase 1 — Stack e template

1. Confermiamo i moduli che accendiamo e quelli che saltiamo, così come vengono fuori dall’intake?
2. Hai già l’accesso al repository template (organizzazione GitHub Mattone-co)? Se no, l’hai chiesto al team?
3. Lo studente ha già un sito o un portale attivo su quel sottodominio, che non deve smettere di funzionare?
4. Come chiamiamo la cartella del progetto?

• Trasforma le risposte dell’intake in un elenco secco di moduli: quale gestionale, quale valuta, quali lingue, pagamenti a un solo proprietario o a più proprietari, check-in smart sì/no, assistente AI sì/no. L’elenco si scrive in un file, non si tiene a mente.
• Si crea il repository del sito dal template privato Mattone-co/mattone-direct-booking-template, direttamente nell’organizzazione Mattone-co e sempre privato (il comando è nel README del template, sezione «Dove si crea il repo»): parte senza la storia del template, come un progetto nuovo. L’accesso al template è su richiesta al team: non si trova cercando, è privato. Niente trasferimenti su account personali: il progetto Vercel si importa da Mattone-co nel team Vercel aziendale. Mai partire da un progetto vuoto: il template porta già le protezioni che un progetto nuovo non ha.
• I moduli di base del template non si tolgono anche se lo studente al momento non li usa. Si aggiunge sopra, non si smonta sotto.

​

Fase 2 — Rebrand e dominio

1. Quali sono i colori del brand? Colore principale, colore di accento, sfondo.
2. Che font vuole usare? (se non ha preferenze, si tiene quello del template)
3. Ha logo e icona pronti? In che formato, e chi te li manda?
4. Quale sottodominio vuole usare? Va bene qualunque sottodominio del suo dominio — non deve per forza essere stay.: può essere prenota., book., casa., quello che preferisce. L’unico vincolo è che sia suo e che sappiamo chi controlla il DNS.
5. Chi gestisce il DNS del dominio? Lo studente, un suo fornitore, o noi?
6. Quali sono i dati che vanno nel piè di pagina: ragione sociale, partita IVA, indirizzo, email e telefono di contatto?

• Sostituisce colori, font, logo e icone; riscrive i testi e le traduzioni con il nome, le città e i contatti dello studente; aggiorna il piè di pagina con i dati legali reali; aggiorna titoli, descrizioni e indirizzo del sito nelle impostazioni delle pagine, nella mappa del sito e nel file per i motori di ricerca.
• Il dominio si imposta in un unico posto (una sola variabile d’ambiente), non riga per riga: se dopo il rebrand un grep sul dominio del template di partenza trova ancora qualcosa — comprese le pagine legali e i link che l’assistente manda all’ospite per aprire la porta — è lì che va sistemato, non nei singoli file.
• Il testo della home scritto per accogliere (“la tua casa lontano da casa” o equivalente) va riscritto per lo studente, non lasciato come lo consegna il template. Un grep-and-replace di nomi e città non lo cambia da solo: resta la stessa frase, identica a quella di un altro studente. Trovato un caso reale il 30/09/2026: due fork diversi mostravano lo stesso identico titolo in home.
• Le card “Where We Operate” (fase 5) hanno una sfumatura scura solo per far leggere il testo sopra la foto — mai un colore del brand di partenza. Trovato un caso reale il 30/09/2026: un fork mostrava ancora la sfumatura viola del brand di partenza sopra le foto vere delle proprie città.
• Prima del primo salvataggio fa una ricerca a tappeto dei residui: nome del brand di partenza, sue città, sue email, suoi numeri, e il suo dominio. Devono tornare zero risultati. Un residuo che passa qui si trova poi in produzione, in una email a un ospite. Lancia tutte le ricerche, non fermarti alla prima che torna vuota: il 30/09/2026 un fork aveva già ripulito nome/città/numeri ma non il dominio, scoperto solo con una ricerca dedicata a quello specifico.
• La ricerca copre anche public/, non solo il codice: un grep sulle stringhe nel sorgente non trova un file immagine morto (logo o foto del brand di partenza mai cancellato, mai citato da nessuna riga di codice) — resta comunque servito in produzione a chiunque ne indovini l’URL. Prima del primo commit: elenca tutto public/ e per ogni file verifica (a) se è davvero referenziato nel codice, (b) se il contenuto è del brand giusto. Trovato un caso reale il 29/09/2026: un fork ereditava cosmica-icon.png/cosmica-logo.png e un’intera cartella di foto (8.8MB) del brand di partenza, mai citate da una riga di codice, ancora online mesi dopo il lancio — scoperte solo controllando public/ a mano, non con un grep.
• Aggiunge il sottodominio al progetto di pubblicazione e passa allo studente (o al suo fornitore) il record DNS da inserire.

​

Fase 3 — Collegare il gestionale (PMS)

1. Quale gestionale usa lo studente? KrossBooking, Hostaway, Smoobu, Hostify, Lodgify, Hostfully, Guesty, un altro, oppure nessuno (solo Airbnb e Booking)?
2. Se è KrossBooking: è partner (usa il collegamento che passa da noi) oppure ha una chiave sua?
3. Il modulo di prenotazione online (Booking Engine) è attivo sulla sua struttura? È il servizio che espone tariffe e prenotabilità: senza, il sito mostra le case ma non i prezzi.
4. Il suo identificativo struttura e le sue credenziali risultano già nella Piattaforma Mattone?
5. Gli appartamenti sono già caricati nel gestionale con foto e prezzi, o vanno caricati prima?
6. Ci sono appartamenti che non devono comparire sul sito?

• Studente partner Kross: il sito usa la chiave partner di Mattone insieme all’identificativo struttura e alle credenziali dello studente, che si prendono dalla Piattaforma Mattone. Le chiamate verso il gestionale escono dal server autorizzato di Mattone, non dal sito dello studente: è lo stesso percorso che usano già gli strumenti dell’assistente. La configurazione la fa il team, su richiesta: la Delivery non tocca la chiave partner e non la consegna mai allo studente.
• Gestionale diverso da KrossBooking (Hostaway, Smoobu, Hostify, Lodgify, Hostfully, Guesty…): il template non parla direttamente con nessun gestionale, ci parla attraverso un unico adattatore. Cambiare gestionale vuol dire scrivere un solo file che risponde a quattro domande — quali appartamenti, che disponibilità, che prezzo, crea la prenotazione — e restituisce sempre la stessa forma di dati. Tutto il resto del sito non cambia. Prima di scriverlo: verifica sulla documentazione del gestionale che quelle quattro cose siano davvero esposte dalla sua interfaccia, e con quali limiti di chiamate; se manca la creazione della prenotazione, il sito nasce come vetrina con richiesta di prenotazione, e va detto allo studente prima di partire. Un adattatore nuovo si aggiunge al catalogo, così il secondo studente con lo stesso gestionale non lo riscrive.
• Nessun gestionale (solo portali): niente calendario in tempo reale. O lo studente ne adotta uno, oppure il sito resta una vetrina con richiesta di disponibilità: è una scelta commerciale, non tecnica, e la fa lui con il coach.
• Studente con chiave propria: nulla di speciale — la chiave la genera lui nel suo gestionale e la fornisce insieme alle altre credenziali. La configura la Delivery, come oggi.
• In entrambi i casi le chiamate al gestionale passano solo dal lato server del sito, mai dal browser dell’ospite.
• Si accende lo strato difensivo obbligatorio: una sola lettura per appartamento per richiesta, richieste identiche in corso unite fra loro, e nuovo tentativo con attesa crescente quando il gestionale rallenta.

​

Fase 4 — Pagamenti

1. Lo studente ha già i pagamenti attivi nella Piattaforma Mattone? (se sì, è quella la chiave da usare: la stessa dell’assistente AI, non una nuova)
2. Gli appartamenti sono tutti suoi, o ci sono più proprietari da pagare separatamente?
3. Se ci sono più proprietari: quale appartamento paga chi, e con quale trattenuta per lo studente?
4. Vuole offrire sia una tariffa rimborsabile sia una non rimborsabile? (la risposta giusta è sì)
5. Da quale indirizzo deve partire la conferma di prenotazione all’ospite? La manda sempre il sito, via email, subito dopo il pagamento: il CRM non ne manda una seconda (vedi CRM per gli ospiti).
6. Verificato che il gestionale NON manda da solo l’email di conferma (vedi il riquadro sotto — vale per KrossBooking, controlla la documentazione se il gestionale è un altro): lo studente ha già un account Resend? Se no, va creato — vedi Resend: come si collega.

• Riusa la chiave di pagamento già presente nella Piattaforma: è la stessa che usa l’assistente Conduit per gli extra. Una sola credenziale, non due. Vedi Stripe: panoramica.
• Se i proprietari sono più d’uno, si passa alla modalità con conti collegati: un conto per proprietario e una trattenuta calcolata su ogni prenotazione. Ogni appartamento deve avere il suo conto associato: un appartamento senza associazione incassa sul conto sbagliato.
• Collega il flusso: creazione del pagamento, conferma, e solo dopo creazione della prenotazione nel gestionale. Al momento della conferma i dati della prenotazione si rileggono e si ricontrollano, non si prendono per buoni da prima. Ogni chiamata verso l’esterno porta un identificativo che impedisce di eseguirla due volte.
• Si pubblicano almeno due tariffe: una rimborsabile e una non rimborsabile. Un solo piano tariffario abbassa le conversioni e toglie una leva di prezzo.
• Riferimento di codice funzionante (non da reinventare): mattone-direct-booking-template, src/lib/stripe.ts + src/app/api/payments/create-intent + src/app/api/payments/confirm + src/lib/email/resend.ts + src/lib/email/templates/welcome.ts. Copre già: stato Klarna processing da trattare come pagato (non solo succeeded — un guard troppo stretto qui ha lasciato un ospite pagante senza prenotazione, caso reale), idempotenza via metadata sul PaymentIntent (reservation_id stampato dopo la creazione, controllato prima di ricrearla), e l’invio email AWAITED — su Vercel una promise “fire-and-forget” dopo la response viene interrotta a metà, non parte mai (successo con il CRM: 0 iscrizioni al workflow finché non si è aggiunto l’await).

​

Fase 5 — Contenuti e SEO

1. Che testi ha già lo studente (descrizioni degli appartamenti, presentazione, foto) e cosa va scritto da zero?
2. In quali lingue vanno tradotti i testi, e chi li traduce?
3. In quali città sono gli appartamenti? (servono per gli indirizzi delle pagine e per le descrizioni)
4. Cosa lo rende diverso dai concorrenti della sua zona, in una frase? (finisce nella presentazione e nella descrizione del sito)
5. Quali sono le domande che gli ospiti gli fanno sempre? (diventano le FAQ, e le FAQ finiscono nei risultati di ricerca)
6. Che prove di fiducia ha: recensioni, anni di attività, numero di ospiti, certificazioni?
7. Ha già un sito vetrina o un profilo del brand? Che indirizzo ha, e chi lo gestisce?
8. Su quali ricerche vuole essere trovato? (per esempio «dove dormire a [città]», «appartamento con terrazzo [quartiere]», «casa vacanze [città] per famiglie»)

• Indirizzi delle pagine leggibili e tradotti, con la lingua davanti e la città nel percorso, non codici: l’indirizzo di una pagina è già una parola chiave.
• Dati strutturati su ogni pagina appartamento — tipo di alloggio, indirizzo, coordinate, camere, bagni, capienza, prezzo e disponibilità — più i dati dell’attività e quelli delle FAQ. Sono le informazioni che permettono a Google di mostrare prezzo e disponibilità direttamente nei risultati.
• Titolo e descrizione generati per ogni appartamento, non uguali per tutti: nome, città, camere, ospiti e la ragione per prenotare in diretta. Più l’immagine di anteprima per le condivisioni.
• Mappa del sito e file per i motori di ricerca con il dominio dello studente, e una voce per ogni lingua di ogni pagina.
• Indirizzo canonico e collegamenti fra le lingue: ogni pagina dichiara qual è la sua versione principale e quali sono le sue traduzioni. Senza questo le versioni in lingua diversa si fanno concorrenza da sole.
• Le pagine che il sito di riferimento ha e che vanno replicate: chi siamo, contatti, domande frequenti, perché fidarsi. Sono le quattro pagine che trasformano una vetrina in una prenotazione, e sono anche quelle che danno al sito abbastanza contenuto per essere indicizzato.
• Articoli: sono la parte che porta visite senza pagarle, e vanno messi in conto dall’inizio. Si parte da cinque articoli per ogni città in cui lo studente ha appartamenti — cosa vedere in due giorni, dove mangiare nel quartiere, come muoversi dall’aeroporto, quando conviene venire, dove dormire e perché in quella zona — ognuno con un titolo che risponde a una ricerca vera, un indirizzo di pagina leggibile, i dati strutturati dell’articolo e un collegamento agli appartamenti di quella città. Non testi generici: dettagli che solo chi vive lì conosce. Chi li scrive e ogni quanto ne esce uno nuovo si decide qui, non dopo: un blog fermo a cinque articoli di due anni fa pesa più che non averlo.
• Collegamento con il sito vetrina o i profili del brand: se lo studente ha già un sito di presentazione, i due si citano a vicenda con collegamenti veri (dalla vetrina «prenota qui», dal sito di prenotazione «chi siamo»), e si sceglie quale dei due è la versione principale per i motori di ricerca, per non farli competere fra loro sulla stessa ricerca. Se la vetrina è su un dominio diverso, va deciso anche dove finisce il traffico delle campagne.
• Card “Where We Operate” in home, una per zona, con una foto vera di quella zona (non uno stock generico, non un placeholder) — stesso pattern del sito di riferimento. Le foto le trova e le carica una persona, non si generano: cerca chi ha già foto delle sue zone (spesso lo studente stesso, o un sopralluogo), altrimenti si acquistano/scaricano foto della località reale con licenza in regola. Le zone da mettere sono quelle con più appartamenti, non tutte — di norma le 3 con più inventario. Passo obbligatorio per ogni sito, non solo per chi lo chiede esplicitamente: una card con foto sbagliata o assente è quello che si nota per primo aprendo la home.
• Velocità: immagini nel formato leggero con caricamento differito, scheletri di caricamento al posto dei salti di layout, pagine degli elenchi rigenerate periodicamente invece che ricalcolate a ogni visita.
• Statistiche: gli eventi di ricerca, visualizzazione appartamento, inizio checkout e acquisto, con importo e valuta, così si sa da dove arrivano le prenotazioni.

​

Fase 6 — Integrazioni opzionali

1. Lo studente ha un assistente AI che risponde agli ospiti, e vuole il chatbot dentro il sito?
2. Ha serrature o citofoni smart, e vuole il check-in autonomo collegato al sito?
3. Vuole rivendere esperienze locali guadagnando una commissione?
4. Ha un CRM dove devono arrivare i contatti di chi prenota?

​

CRM per gli ospiti

​

Quali tag manda il sito

​

Quali impostazioni servono sul sito

1. La chiave privata del CRM del partner (token di integrazione privata, creato dalle impostazioni del CRM → Integrazioni private). Scade: se il sito smette di creare contatti, è la prima cosa da controllare.
2. L’identificativo dell’account del partner nel CRM (la «location» / sottoaccount).
3. Il segreto del controllo giornaliero: una stringa casuale di almeno 24 caratteri. Senza, il controllo non parte (e la pubblicazione di produzione si ferma già oggi).

​

Cosa deve avere il CRM del partner

• una prenotazione di prova compare nel CRM con i campi compilati (non solo i tag) e con l’opportunità in Booked;
• la prova senza scritture del controllo giornaliero, lanciata per la data di arrivo della prenotazione di prova, la elenca fra gli arrivi;
• ogni workflow della tabella è stato inviato a un contatto di prova, con variabili e link giusti;
• nessuna email del CRM conferma la prenotazione (l’ospite di prova ne riceve una sola, quella del sito).

​

Fase 7 — Verifica e go-live

1. Il sottodominio è già occupato da qualcos’altro dello studente (per esempio il portale di check-in)?
2. Chi inserisce il record DNS, e quando?
3. Lo studente è disponibile per mezz’ora di passaggio di consegne a schermo condiviso?
4. Chi lo studente deve chiamare quando qualcosa si rompe, e su quale canale?

• Pubblica il progetto e trasferisce tutte le impostazioni sull’ambiente di produzione. Un’impostazione dimenticata non dà errore: dà una pagina vuota.
• Se il sottodominio è già occupato, il sito nuovo si innesta nel progetto esistente invece di crearne uno nuovo: il DNS e il certificato sono già a posto, e le pagine di check-in devono continuare a rispondere. Prima di sovrascrivere si annota la versione precedente, così si torna indietro in un minuto.
• Quel repository fa DUE cose, non una — e va detto da qualche parte visibile (nel suo README, o annotato qui accanto al suo nome): serve sia il sito di prenotazione (/{lingua}/...) sia l’accesso ospite (/access/{slug}, /api/mcp/{gestore-serratura}), tutti e due sullo stesso sottodominio, separati per percorso, non per dominio o per repository. Non è un dettaglio: un repository con un nome che suggerisce una sola delle due cose (per esempio finisce in “-checkin”) fa presumere a chi lo guarda dopo che il sito di prenotazione sia altrove — e se nel frattempo esiste anche un secondo repository con un nome simile ma senza traffico reale, la confusione è servita. Non è obbligatorio rinominare il repository, ma è obbligatorio che la doppia funzione sia scritta e trovabile.
• Scrive il documento di consegna nella cartella del progetto: indirizzo del sito, come si aggiunge un appartamento, come si sostituiscono le credenziali, come si leggono gli avvisi, chi si contatta se qualcosa si rompe.

​

Errori già fatti, da non rifare

1. Una sola lettura per appartamento a richiesta. Se la stessa pagina chiede lo stesso dato più volte, il gestionale smette di rispondere e il sito sembra rotto. Le richieste identiche in corso vanno unite in una.
2. Il giorno di partenza non è una notte occupata. Chi lo conta come occupato blocca ogni giorno una prenotazione che poteva prendere.
3. La disponibilità si legge dal calendario del gestionale, mai ricostruita dalle prenotazioni: blocchi, minimi di notti e fermi manutenzione non si indovinano, e la ricostruzione diverge dalla realtà entro una settimana.
4. Le email partono da un sottodominio dedicato e verificato, mai dal dominio principale, e nella lingua dell’ospite — non nella lingua della casa.
5. Il contatto nel CRM si crea dal codice al momento del pagamento, non da un’automazione che si accende quando arriva un’email: quella automazione salta in silenzio e perde l’attribuzione.
6. Il controllo di salute deve chiamare davvero gestionale, email e pagamenti, e distinguere un servizio non ancora collegato da uno guasto: verificare che le impostazioni esistano non dice niente su ciò che funziona, e un allarme permanente per qualcosa mai attivato smette di essere letto da chiunque.
7. Si parte sempre dal template, mai da un progetto vuoto — e prima del primo salvataggio si cercano i residui del brand di partenza finché non ne resta nessuno, dominio incluso. Un residuo trovato dopo è un residuo che ha già visto un ospite — nel caso peggiore, un link che gli apre la porta sbagliata.
8. Se il sottodominio ospita già qualcosa, il sito nuovo si innesta lì dentro: creare un progetto nuovo rompe il DNS e spegne i portali attivi.
9. Il riuso della sessione con il gestionale va verificato, non dato per scritto. Impostare le variabili d’ambiente di un meccanismo condiviso non basta se la risorsa che quel meccanismo richiede non è davvero collegata al progetto: resta spento in silenzio, e il sito lo scopre solo quando il tetto di sessioni attive del gestionale si riempie e smette di rispondere — in produzione, non in un test. Dal 08/10/2026 il template lo impone: build di produzione bloccata senza cache, controllo di salute che la prova davvero, avviso giornaliero — vedi Cache token Kross.
10. I testi pensati per accogliere l’ospite (titolo e sottotitolo della home, sfumature sulle foto) vanno riscritti per lo studente, non lasciati come li consegna il template: un grep-and-replace di nomi e città non li rende specifici da solo, e due siti con lo stesso identico titolo in home si notano subito.