> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Procedura guidata: costruire il sito di uno studente
> La procedura che Claude segue per guidare l'operatore, fase per fase, nella costruzione del sito di prenotazione diretta di uno studente: domande da fare, azioni, controllo finale.
Questa pagina **non è un modulo da compilare**: è la procedura che **Claude segue per guidarti**. Tu apri Claude Code, gli dici per quale studente stai costruendo il sito, e lui ti fa le domande — una alla volta, in italiano semplice — leggendo da qui cosa chiedere, cosa fare e cosa deve risultare vero alla fine di ogni fase.
**Come si usa, in tre righe.**
1. Apri **Claude Code dentro il repository dei docs** (`mattone-docs`), così ha questa pagina come contesto.
2. Incolla il prompt qui sotto sostituendo il nome dello studente.
3. Rispondi alle domande **una alla volta**. Claude **non passa alla fase successiva finché il controllo finale di quella fase non è verde**: se un controllo fallisce, si torna indietro nella stessa fase, non si tira dritto.
Non serve alcuna pagina-wizard e non serve conoscere il codice: le chiavi (pagamenti, PMS) le ha già la Delivery, perché i collegamenti dello studente stanno nella Piattaforma Mattone.
```text theme={null}
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.
Se lo studente non ha ancora **PMS collegato e pagamenti attivi**, questa procedura non parte: il sito di prenotazione diretta è un modulo aggiuntivo che riusa quei pezzi. Vedi [Direct Booking: panoramica](/integrazioni/direct-booking/panoramica).
## Fase 0 — Intake con lo studente
**Obiettivo:** raccogliere tutto quello che serve **prima** di scrivere una riga, così non ci si ferma a metà a chiedere.
**Le domande che Claude fa all'operatore (13, una alla volta):**
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?
**Cosa fa Claude (e cosa fa l'operatore):** l'operatore fa questa intervista **insieme allo studente**, non da solo — metà delle risposte dipendono da cose che ha solo lui. Claude raccoglie le risposte e le scrive in un file di intake nella cartella del progetto, così le fasi successive non le richiedono da capo. Le risposte «non lo so» diventano una **domanda aperta con un nome accanto**, non un buco.
**Controllo finale:** tutte e 13 le domande hanno una risposta **oppure** un «si salta, e sappiamo perché». Il file di intake esiste ed è leggibile. Se manca la risposta 4 (gli appartamenti) o la 5 (il gestionale), la fase **non è verde**: senza quelle il sito non ha niente da vendere.
## Fase 1 — Stack e template
**Obiettivo:** decidere quali pezzi si costruiscono e quali si saltano, e partire dal template invece che da zero.
**Le domande che Claude fa all'operatore:**
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?
**Cosa fa Claude (e cosa fa l'operatore):**
* 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.
**Controllo finale:** il progetto si avvia in locale e **la home si vede nel browser**. L'operatore vede il sito partire con i propri occhi. Finché non lo vede, la fase non è verde.
## Fase 2 — Rebrand e dominio
**Obiettivo:** il sito è dello studente, non del template. E ha un indirizzo suo.
**Le domande che Claude fa all'operatore:**
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?
**Cosa fa Claude (e cosa fa l'operatore):**
* 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**.
**Due sottodomini, due cose diverse.** Se lo studente ha già il **portale di check-in** su un sottodominio, quello serve all'ospite **che ha già prenotato**. Il sito di prenotazione serve a **vendere**. Possono stare sullo stesso brand e perfino sullo stesso sottodominio (vedi fase 7), ma non sono la stessa cosa e non si sovrascrivono a cuor leggero.
**Controllo finale:** la ricerca dei residui (codice **e** `public/`) torna vuota, la home mostra i colori e il logo dello studente, il piè di pagina ha i suoi dati, e il sottodominio scelto è registrato con il record DNS consegnato a chi lo deve inserire.
## Fase 3 — Collegare il gestionale (PMS)
**Obiettivo:** il sito legge appartamenti, calendario e prezzi **dal gestionale dello studente**, qualunque esso sia, non da un elenco scritto a mano.
**Le domande che Claude fa all'operatore:**
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?
**Cosa fa Claude (e cosa fa l'operatore):**
* **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.
**Il modulo di prenotazione online va attivato prima, ed è il primo controllo da fare.** Misurato in produzione il 07/09/2026 su due strutture reali, stessa richiesta e stesso minuto: su una struttura con il modulo attivo la ricerca disponibilità ha restituito **33 tariffe**; su una struttura senza, lo stesso codice ha ricevuto un **rifiuto delle credenziali** — mentre elenco alloggi e servizi rispondevano regolarmente con le stesse credenziali. Un rifiuto **solo** sulla ricerca tariffe, con il resto che funziona, vuol dire quasi sempre **modulo di prenotazione non attivo o non autorizzato per quella struttura**, non credenziali sbagliate. Si risolve dal pannello del gestionale dello studente, attivando il modulo e autorizzando il collegamento: è una richiesta da fare al proprietario **prima** di iniziare il sito.
**Studente partner Kross: il modulo attivo sulla struttura non basta da solo.** Misurato il 12/09/2026 su una struttura con il modulo di prenotazione online già attivo: `calendar/book` sulla **chiave partner** rispondeva comunque 401 "Endpoint not enabled for this api key/hotel id" — non è il modulo della struttura, è lo **scope della chiave partner condivisa** che manca `calendar/book` e `channel/get-rates` (richiesti a KrossBooking il 13/09, non ancora confermati). Se lo studente è partner e la ricerca tariffe fallisce anche col modulo attivo, il problema è probabilmente qui: verifica prima con il team se la chiave partner ha già questi due endpoint abilitati, prima di far riattivare/riautorizzare il modulo allo studente per niente.
**I gestionali contano le chiamate, e il tetto non si alza.** KrossBooking, per struttura: **10 richieste al minuto, 300 all'ora, 5.000 al giorno, 50 sessioni attive**. Chi sfora riceve un errore e per qualche minuto non risponde più: il sito smette di mostrare prezzi proprio mentre qualcuno sta prenotando. Un sito pubblico può superare quel tetto con poche decine di visitatori insieme, quindi: **le risposte di disponibilità e prezzi vanno tenute in cache per qualche minuto**, le richieste identiche in corso vanno unite in una sola, e le sessioni vanno **riusate**, mai ricreate a ogni chiamata. Prima di aprire il sito al pubblico, verifica il comportamento sotto carico e non solo a una richiesta alla volta. Gli altri gestionali hanno limiti propri: **leggili prima di scrivere l'adattatore**.
**Il riuso della sessione Kross non è opzionale, ed esiste già un meccanismo condiviso — non scriverne uno nuovo.** Il template porta già un doppio livello: uno locale (attivo di default) e uno condiviso con tutti gli altri siti Mattone sullo stesso hotel\_id (attivo quando sono presenti le variabili d'ambiente condivise). **Trappola reale (30/09/2026):** se il livello scelto richiede una risorsa esterna da collegare (non solo una variabile d'ambiente da scrivere), quella risorsa va **davvero collegata al progetto**, non solo nominata nelle impostazioni — altrimenti il meccanismo resta silenziosamente spento e ogni riavvio del sito si autentica da zero, fino a riempire il tetto delle 50 sessioni e spegnere la ricerca disponibilità in produzione. Dopo aver collegato il gestionale, **prima di andare oltre**, verifica con il controllo di salute (fase 7) che il gestionale risulti vivo, non solo che le variabili esistano.
**Controllo finale (uguale per qualunque gestionale):** l'elenco degli appartamenti arriva dal gestionale con nomi e prezzi veri, e una ricerca di disponibilità su date reali restituisce almeno una tariffa. Poi si ripete la **stessa ricerca otto volte insieme**: devono rispondere tutte e otto. Se qualcuna cade, lo strato difensivo è incompleto e la fase **non è verde**.
**Come la prenotazione arriva su KrossBooking.** Ogni prenotazione creata dal sito va taggata `cod_channel: 'BE'` + `lead_source: 'Direct'` — è la regola nel template, obbligatoria (vedi skill `direct-booking-engine`). Testato dal vivo il 29/09/2026 (prenotazione di prova creata e subito cancellata, zero residuo) e switchato in produzione lo stesso giorno su Cosmica e Soliséra: `cod_channel: 'BE'` è il valore dell'esempio ufficiale Kross per `reservations/save`, e la prenotazione risulta genuinamente trattata come **Booking Engine nativo** — stessa etichetta "Booking Engine" nel gestionale, non una scrittura API di terzi. `lead_source: 'Direct'` è obbligatorio insieme al canale: senza, Kross marca di default la prenotazione "OTA" (fuorviante, rischio se quel campo alimenta rendiconti proprietari). Dettagli tecnici nella skill `direct-booking-engine`.
L'uso del collegamento partner ha dei limiti nell'accordo con il fornitore del gestionale. Se il sito di prenotazione diretta diventa un prodotto da vendere, **l'accordo va rivisto prima**: non è una decisione da prendere dentro un ticket. Vedi [Kross: panoramica](/integrazioni/kross/panoramica).
## Fase 4 — Pagamenti
**Obiettivo:** l'ospite paga sul sito, e la prenotazione entra nel gestionale.
**Le domande che Claude fa all'operatore:**
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](#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](/integrazioni/resend/panoramica).
**Cosa fa Claude (e cosa fa l'operatore):**
* 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](/integrazioni/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`).
**KrossBooking non manda nessuna email di conferma da solo, e la sua API non ha un endpoint per farglielo fare.** Verificato sul catalogo completo (58 endpoint della chiave account, 30/09/2026): nessun `send-confirmation`, nessun parametro `notify` su `reservations/save`, nessuna "send email" in nessuna sezione. `messaging/send-message` è per la chat ospite-host dentro Kross, non per una ricevuta automatica. **Quello che Kross fa da solo**: le istruzioni di check-in configurate nel pannello (`Reservations - Get check-in instructions`, con `n_days_before_arrival`) partono in automatico su QUALSIASI prenotazione, incluse quelle create via API — ma sono informazioni di arrivo su un calendario fisso, non una ricevuta di pagamento istantanea. Le due cose non si sovrappongono: serve comunque l'invio del sito (Resend) per il "grazie, ecco la tua prenotazione" subito dopo il pagamento — non è un doppione di quello che fa già Kross.
**Controllo finale:** si fa una **prenotazione di prova con la carta di test**, dall'inizio alla fine. La prenotazione deve comparire **nel gestionale entro un minuto**, e nel pannello dei pagamenti si devono ritrovare l'appartamento, il tipo di camera e la tariffa scelta. L'ospite di prova **riceve davvero l'email di conferma, una sola** — non basta che l'API risponda `success`. Se la prenotazione non arriva nel gestionale, o l'email non arriva, la fase non è verde — anche se il pagamento è andato a buon fine.
## Fase 5 — Contenuti e SEO
**Obiettivo:** il sito si trova su Google e convince chi ci arriva. Questa è la fase che la maggior parte delle persone salta, ed è quella che decide se il sito porta prenotazioni o resta una vetrina.
**Le domande che Claude fa all'operatore:**
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»)
**Cosa fa Claude (e cosa fa l'operatore):**
* **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.
**Controllo finale:** i primi articoli per ogni città sono pubblicati e collegati agli appartamenti; se esiste una vetrina, i due siti si citano a vicenda e la versione principale è dichiarata; ogni appartamento ha titolo e descrizione propri (non copiati dal vicino); i dati strutturati passano il test di Google senza errori; la mappa del sito elenca tutte le pagine in tutte le lingue; ogni pagina dichiara la propria versione principale e le traduzioni; le quattro pagine chi siamo / contatti / domande frequenti / fiducia esistono e non sono vuote.
## Fase 6 — Integrazioni opzionali
**Obiettivo:** agganciare quello che lo studente ha già, senza costruirlo da capo. Si fa **solo se serve**: se la risposta all'intake era «no», questa fase si salta per intero.
**Le domande che Claude fa all'operatore:**
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?
**Cosa fa Claude (e cosa fa l'operatore):** ognuno di questi pezzi ha già la sua pagina, e si segue quella — **tranne le esperienze**, vedi sotto. Qui si decide solo **se accenderlo**.
**«Rivendere esperienze locali» è una domanda senza procedura.** A differenza degli altri tre moduli, oggi **non esiste** una pagina che spieghi come si realizza (integrazione GetYourGuide o equivalente, commissioni, come entra nel sito). Se lo studente risponde sì, non promettere una data: segnala che è previsto ma non ancora costruito, e passa la richiesta a chi decide la priorità.
**Mai inventare servizi extra o esperienze che lo studente non ha davvero.** Se non vende esperienze locali, quella sezione del sito non si riempie con contenuto generico — resta assente, o mostra **"coming soon"**. Lo stesso vale per i servizi extra (early check-in, transfer, noleggi…): solo quelli che lo studente offre realmente oggi.
**Pannello admin (self-serve per lo studente)** — non ancora costruito nel template, requisito da avere presente ogni volta che si tocca questa fase: lo studente deve poter cambiare da solo, senza aprire un ticket, un paio di foto e l'elenco di esperienze/servizi extra. Finché non esiste, questi cambi passano dalla Delivery via richiesta diretta.
Chatbot sul sito e knowledge base per-appartamento
Portale ospite e apertura porta
Contatti e opportunità da chi prenota
Stack, fork del template, pagamenti
La knowledge base dell'assistente si scrive **per singolo appartamento**, mai in forma globale: un nodo globale fa arrivare le informazioni di un cliente nelle risposte di un altro. Vedi [Conduit: knowledge base](/integrazioni/conduit/kb).
L'assistente non vede tutte le prenotazioni: cerca solo fra quelle in arrivo nei prossimi giorni e fra gli ospiti già in casa. Su una prenotazione più avanti nel tempo, o già cancellata, risponde di aver trovato informazioni in conflitto e passa la conversazione a una persona. Vedi [Conduit: troubleshooting](/integrazioni/conduit/troubleshooting).
**Controllo finale:** ogni modulo acceso ha superato la prova della sua pagina (il chatbot risponde con l'informazione giusta dell'appartamento giusto; la porta si apre dal telefono; il contatto compare nel CRM entro un minuto dalla prenotazione). Ogni modulo spento è **scritto come spento**, così chi subentra non lo cerca.
## CRM per gli ospiti
**Obiettivo:** il CRM del partner segue l'ospite dalla prenotazione alla recensione **senza che nessuno metta tag a mano**. Si fa se all'intake il partner ha detto di usare un CRM.
Verificato il 07/10/2026 sul CRM di riferimento: i workflow per gli ospiti (arrivo, partenza, richiesta recensione, ospite di ritorno) erano pubblicati ma **non erano mai partiti**, perché nessuno metteva i tag di arrivo e partenza. E i dati della prenotazione mandati dal sito venivano **scartati in silenzio**, perché i campi personalizzati non erano stati creati nel CRM. Da qui le due regole: i tag li mette il sito, e i campi si creano **prima** di andare online.
### Quali tag manda il sito
| Tag | Quando |
| - | - |
| `website-lead` | ogni contatto che arriva dal sito (modulo o prenotazione) |
| `direct-booking-abandoned` | l'ospite ha inserito i suoi dati ma non ha pagato. Il sito lo **toglie** quando la prenotazione va a buon fine |
| `direct-booking` + `direct-booking-` + `property:` | prenotazione pagata |
| `checked-in` | il giorno dell'arrivo |
| `checked-out` | il giorno della partenza |
`checked-in` e `checked-out` li mette un **controllo automatico giornaliero del sito** (ogni mattina): legge le prenotazioni pagate sul sito, mette il tag al contatto giusto e non lo rimette due volte per lo stesso soggiorno. Se un giorno salta, recupera il giorno dopo. Per un ospite che torna, il tag viene tolto e rimesso, così i workflow ripartono anche la seconda volta. Le prenotazioni cancellate nel gestionale **senza rimborso** del pagamento non sono visibili al controllo: vanno tolte a mano dal CRM.
### Quali impostazioni servono sul sito
Tre valori, da inserire nelle impostazioni del progetto di pubblicazione (Production e Preview). I nomi esatti sono nel file di esempio delle impostazioni del template:
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).
Facoltativi: pipeline e fase in cui il sito crea l'opportunità della prenotazione (se mancano, l'opportunità la crea il workflow «Welcome Direct Booking»).
### Cosa deve avere il CRM del partner
**Campi personalizzati del contatto**, con queste chiavi esatte (altrimenti il CRM scarta i valori senza errore):
| Chiave | Contenuto |
| - | - |
| `check_in_date` | data di arrivo (AAAA-MM-GG) |
| `check_out_date` | data di partenza |
| `guest_language` | lingua dell'ospite: `it` o `en` |
| `property_name` | appartamento |
| `booking_amount` | importo |
| `reservation_id` | codice prenotazione del gestionale |
| `booking_source` | provenienza |
**Pipeline «Direct Booking Guests»**, con queste fasi: New Lead · Booked · Checked-in · Checked-out · Returning Guest.
**Workflow:**
| Workflow | Si attiva con | Cosa fa |
| - | - | - |
| Welcome Direct Booking | tag `direct-booking` | **Nessuna email** (la conferma la manda il sito). Mette l'opportunità in Booked, se non la crea già il sito |
| Recupero prenotazione abbandonata | tag `direct-booking-abandoned` | Dopo 1 ora, se l'ospite non ha ancora `direct-booking`: email per riprendere la prenotazione (IT/EN secondo `guest_language`) |
| Guest Checked In | tag `checked-in` | Opportunità in Checked-in |
| Guest Checked Out | tag `checked-out` | Opportunità in Checked-out |
| Richiesta recensione | tag `checked-out` | Dopo 1 giorno: email con il link alla recensione Google, a **tutti** gli ospiti, IT/EN; tag `review-requested` |
| Returning Guest | tag `direct-booking`, se il contatto ha già `checked-out` | Opportunità in Returning Guest, tag `returning-guest` |
**Mai uno sconto, un regalo o un altro premio in cambio di una recensione**, e mai chiederla solo agli ospiti contenti: Google lo vieta, e le recensioni ottenute così possono essere rimosse e la scheda penalizzata. Il recupero dell'abbandono **non** si attiva con `website-lead`: lo hanno anche gli ospiti che hanno già prenotato.
**Modelli email:** il template contiene modelli generici (conferma per le prenotazioni non arrivate dal sito, recupero abbandono, richiesta recensione, email ai proprietari) **senza numeri né nome di un'altra azienda**: brand, telefono, WhatsApp, email e link alla recensione sono **valori personalizzati del CRM** che si compilano una volta. Mai lasciare in un'email i contatti di un altro partner.
**Un solo canale per ogni messaggio:** la conferma di prenotazione la manda il sito; se il gestionale ha un invio automatico di conferma, va escluso per le prenotazioni del sito, altrimenti l'ospite ne riceve due.
**Controllo finale:**
* 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
**Obiettivo:** il sito è online sul dominio dello studente, e lo studente sa usarlo senza di noi.
**Le domande che Claude fa all'operatore:**
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?
**Cosa fa Claude (e cosa fa l'operatore):**
* 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.
**La checklist di go-live (tutte le voci, non alcune):**
Dal sito pubblicato, non da quello locale: ricerca, selezione, dati ospite, pagamento. Deve arrivare fino alla conferma.
L'incasso si ritrova nel pannello pagamenti con l'appartamento e la tariffa corretti, e la prenotazione compare nel gestionale.
Il sottodominio scelto apre il sito, in tutte le lingue attive, con il certificato valido.
Se sul sottodominio c'era già il portale di check-in, quelle pagine rispondono ancora. Un indirizzo di check-in valido non deve dare pagina non trovata.
Il controllo periodico chiama davvero gestionale, email e pagamenti e li trova vivi — non si limita a verificare che le impostazioni esistano. Ogni servizio deve risultare **vivo**, oppure **dichiaratamente non ancora collegato** — mai "guasto" in modo permanente per un servizio che semplicemente non è stato attivato (se lo studente non ha ancora email o pagamenti, il controllo lo dice chiaramente, non manda un allarme rosso ogni dieci minuti per qualcosa che non doveva ancora esserci).
Se il sito usa KrossBooking: `/api/health` sul dominio vero risponde **200** con `kross_token_cache: "ok"` (in produzione risponde 503 se la cache manca o non funziona), (l'avviso giornaliero lo sorveglia in automatico, senza aggiungerlo a mano). Dettagli e cosa fare se non è verde: [Cache token Kross](/integrazioni/direct-booking/cache-token-kross).
Lo studente ha creato **lui** una prenotazione di prova sul sito vero, l'ha ritrovata nel gestionale e nei pagamenti, e sa cosa fare se un ospite segnala un problema.
**Controllo finale:** tutte e sette le voci sono verdi **e le ha viste lo studente**, non solo l'operatore. Finché l'ultima voce non è vera, il sito è pubblicato ma non consegnato.
## Errori già fatti, da non rifare
Dieci lezioni pagate su siti veri. Claude le ricorda all'operatore nella fase in cui servono, non tutte insieme all'inizio.
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](/integrazioni/direct-booking/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.
Fonti: skill `direct-booking-engine` (10 fasi + lezioni L1-L8), il repository template privato, e le pagine [Direct Booking: panoramica](/integrazioni/direct-booking/panoramica), [Stripe](/integrazioni/stripe/panoramica), [Kross](/integrazioni/kross/panoramica), [Conduit](/integrazioni/conduit/panoramica).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.