Sito Direct Booking: come si crea

Il sito di prenotazione diretta è il sito con cui lo studente vende senza OTA (niente commissioni Airbnb/Booking). Non si parte da zero: si forka il template canonico e si personalizza.

Devi costruirne uno adesso? Non serve leggere tutta questa pagina: apri Claude Code nel repo dei docs e segui la Procedura guidata — è Claude che ti fa le domande, una alla volta, e non passa alla fase dopo finché il controllo non è verde. Questa pagina resta il riferimento su stack, template e vincoli.

Quando si dà allo studente

Il sito direct booking non fa parte dell’onboarding base: è un modulo aggiuntivo che si attiva per lo studente che vuole vendere in diretta. Si affronta dopo che le fondamenta sono a posto, perché ne riusa i pezzi:

PMS collegato (KrossBooking o altro): il sito legge appartamenti e disponibilità dallo stesso adapter PMS, quindi il PMS va collegato prima.
Stripe attivo: il checkout del sito usa la stessa chiave Stripe dell’agente Conduit (una sola credenziale nel Vault).
Conduit / smart check-in (opzionali): se lo studente li ha già, si agganciano al sito come embed.

In pratica lo dai a chi ha completato Anagrafica + PMS + pagamenti e chiede un canale di vendita proprio. Chi non vende in diretta non ne ha bisogno: resta un opt-in.

Prima di partire. Quattro input li raccogli tu, due li chiedi al team: se parti senza, ti fermi a metà.I 4 che raccogli da solo, con lo studente (fase 0 / intake):

Brand — nome commerciale, colori, font, logo, testi e tono di voce.
Dominio — il dominio dello studente e chi ne controlla il DNS (serve per pubblicare stay.{brand}.com).
Appartamenti — l’elenco degli alloggi da mettere in vendita, con il loro identificativo sul PMS.
Integrazioni — quale PMS, valuta e lingue, Stripe single o multi-owner, e quali moduli opzionali (smart check-in, Conduit, CRM, esperienze).

I 2 che chiedi al team, e che nessuno può darti da solo: 5. Accesso in lettura al repository template — vedi «Da dove si parte» qui sotto. 6. Configurazione Kross partner — solo se lo studente è un partner Kross e non ha una chiave propria: vedi Studente partner Kross vs studente con chiave propria.

Due domini, due cose diverse: `stay.` e `book.`

Non confondere i due sottodomini:

stay.{brand}.com = sito di prenotazione diretta (questa pagina): vetrina + motore di prenotazione + checkout Stripe. Serve a vendere il soggiorno senza OTA.
book.{brand}.com = guest portal / self check-in: il portale che l’ospite già prenotato usa per l’accesso (istruzioni, apertura porta smart-lock, extra). È il front-end dello smart check-in, vedi Smart check-in e la skill smart-checkin-mcp.

Uno vende, l’altro accoglie: possono coesistere sullo stesso brand e condividono PMS, Stripe e (se presente) Conduit.

Regola d’oro: si forka, non si scaffolda

Ogni sito studente parte da un fork del template canonico mattone-direct-booking-template, mai da create-next-app. Il template porta già PMS adapter, i18n, tema, Stripe, health endpoint, ricostruirli a mano introduce bug che il template ha già risolto.

Fino al 28/09/2026 il fork partiva da cosmica-booking (il sito reale di Cosmica, stay.cosmicarentals.com). Da questa data il template è un repository separato, estratto da cosmica-booking con storia completa e poi ripulito di tutto ciò che è specifico di Cosmica (pagina /boat, sistema partner/referral B2B, brand hardcoded) — così un aggiornamento al sito di Cosmica non deve più essere replicato a mano nel template, e viceversa. cosmica-booking resta il sito di produzione di Cosmica, non il template.

Da dove si parte

Il template non è una cartella sul computer di qualcuno: è il repository privato mattone-direct-booking-template nell’organizzazione GitHub di Mattone. Se leggi da qualche parte un percorso locale tipo ~/Projects/... o ~/Desktop/..., quello è il computer di chi ha scritto la nota, non un posto che esiste da te. Per lavorarci ti serve l’accesso in lettura, che si chiede al team (non si trova cercando: il repository è privato e non compare). Una volta ottenuto:

git clone <repository template>   # l'URL te lo dà il team insieme all'accesso

L’URL esatto del repository non sta qui, perché questa guida è pubblica: chiedilo al team. Lo trovi nella scheda dello studente in mattone-delivery-private.

Stack (dal template)

Next.js (App Router) + next-intl per le lingue (tipico it, en; aggiungi de/fr se servono i mercati).
Tema in Tailwind (palette + font dello studente).
PMS adapter agnostico dietro un unico contratto PmsAdapter: KrossBooking, Hostaway, Smoobu, Hostify, Lodgify, Hostfully, Guesty. Con caching + coalescing + retry backoff su ogni adapter (difensivo, obbligatorio).
Stripe per i pagamenti (vedi sotto).
Opzionali: embed chatbot Conduit, smart check-in (Shelly/SwitchBot), CRM GHL, esperienze GetYourGuide.

Studente partner Kross vs studente con chiave propria

Il sito di prenotazione diretta non è un’integrazione PMS in più: è un canale di vendita dello studente, legittimo esattamente come il motore di prenotazione di Kross. Quello che cambia fra uno studente e l’altro è da dove arriva la chiave che autorizza a parlare con Kross — la stessa distinzione che vale già per l’assistente, vedi Kross: partner vs own.

Studente partner — il sito usa la chiave partner di Mattone (la nostra, generica, uguale per tutti) insieme all’identificativo struttura e alle credenziali dello studente. Le chiamate verso Kross escono dal server autorizzato di Mattone, non dal sito: è lo stesso percorso che usano già gli strumenti dell’assistente, ed è il motivo per cui funziona senza che lo studente debba autorizzare nulla.
Studente con chiave propria — nulla cambia rispetto a oggi: lo studente genera la chiave dentro il suo Kross e la fornisce insieme alle altre credenziali.

Caso	Cosa serve dallo studente	Cosa mette la Delivery	Chi lo configura
Partner Kross	identificativo struttura + le sue credenziali API	la chiave partner di Mattone e l’uscita dal server autorizzato	il team, su richiesta: la Delivery non tocca la chiave
Chiave propria	identificativo struttura + le sue credenziali API + la sua chiave	niente: si usa quello che dà lo studente	la Delivery, come oggi

La chiave partner non si consegna mai allo studente e non si incolla in chat: la configura il team, e resta nel Vault.

Come si costruisce (fasi)

Intake

Raccogli tutto con lo studente: brand/dominio/colori, paese+valuta, lingue, lista appartamenti, PMS, Stripe (single o multi-owner), CRM, smart-lock, AI inbox, analytics. Usa la checklist della skill.

Stack decision

Blocca i moduli in base all’intake (quale PMS adapter, valuta, locale, Stripe single vs Connect, smart check-in sì/no, Conduit sì/no).

Fork del template

Clona il repository template mattone-direct-booking-template (accesso in lettura su richiesta al team, vedi Da dove si parte), poi rm -rf .git .next .vercel node_modules && git init, rebrand (colori, font, asset, testi, footer, sitemap), npm install, e .env.local con le sole impostazioni che lo studente ha davvero. Grep zero-residui del brand vecchio prima del primo commit — codice e public/: un file immagine del brand di partenza mai citato da una riga di codice non lo trova un grep sulle stringhe, e resta comunque online. Vedi Fase 2.

PMS adapter + pagamenti + moduli

Collega il PMS, Stripe, e i moduli opzionali scelti. Non rimuovere i moduli baseline anche se non usati.

Deploy + dominio

Deploy su Vercel (git push). Dominio: convenzione stay.{brand}.com per il sito di prenotazione (Cosmica usa stay. per il booking e book. per il guest portal/accesso). Aggiungi il dominio su Vercel + record DNS.

Verifica

npm run dev renderizza la home; il flusso di prenotazione arriva fino al checkout Stripe; le pagine appartamento leggono i dati dal PMS.

Cache del token Kross (obbligatoria)

Se il sito usa KrossBooking, la build di produzione si ferma finché non c’è una cache del token configurata, e dopo il deploy /api/health deve rispondere 200 con kross_token_cache: "ok". L’avviso giornaliero lo sorveglia in automatico. Tutto in Cache token Kross.

Pagamenti

Single owner → account Stripe standard (una sk/pk).
Multi-owner (più proprietari con payout separati) → Stripe Connect (un connected account per proprietario, application_fee_amount per prenotazione).
La chiave Stripe è la stessa usata dall’agente Conduit per gli extra: una credenziale sola nel Vault (stripe_key_<token>). Vedi Stripe.

Vincolo Kross. L’uso dell’API partner ha dei limiti nell’accordo con Kross. Se il sito direct booking dovesse diventare un prodotto da vendere, l’accordo va rivisto prima: non è una decisione che si prende in un ticket, parlane col team.

Fonti: skill direct-booking-engine (workflow 10 fasi + lezioni L1-L8), repo mattone-direct-booking-template, memoria project_direct_booking_skill, project_cosmica_domain_migration.

▷ Prompt Claude Code: Crea il sito direct booking · incolla in Claude Code:

Contesto: in questa sessione di Claude Code NON hai il repo/codice caricato.
Per prima cosa apri come riferimento il repository template
`mattone-direct-booking-template`
(repository privato: se non l'hai ancora, chiedi al team l'accesso in lettura,
vedi mattone-docs /integrazioni/direct-booking/panoramica) e LEGGI la pagina
mattone-docs /integrazioni/direct-booking/panoramica; carica la skill
direct-booking-engine.
Poi procedi:

Costruisci il sito direct booking per lo studente [NOME] usando la skill
direct-booking-engine e seguendo mattone-docs /integrazioni/direct-booking/
panoramica. Parti SEMPRE da un fork del template mattone-direct-booking-template
(mai create-next-app, mai cosmica-booking). Guidami nell'intake (brand, dominio stay.{brand}.com,
paese/valuta, lingue, appartamenti, PMS, Stripe single/multi-owner, smart-lock,
Conduit), poi blocca lo stack, forka+rebranda (grep zero-residui su codice E
public/: un asset del brand vecchio mai citato nel codice non lo trova un grep
sulle stringhe), collega PMS
e Stripe, e deploya su Vercel. Se lo studente e' un partner Kross, NON chiedermi
una chiave sua: si usa la chiave partner di Mattone con il suo identificativo
struttura e le sue credenziali, e la configura il team - dimmi solo se manca.
Verifica che la home renderizzi e che il flusso arrivi al checkout Stripe.

Procedura guidata (Claude ti fa le domande)

Le 8 fasi con le domande da fare e il controllo finale di ognuna

Stripe

Chiave unica per checkout + extra Conduit

Personalizzazione studente

Branding, dominio, dati per-studente

Fonti ufficiali

Stripe (checkout/pagamenti): https://docs.stripe.com
PMS (dati appartamenti/prenotazioni): Hostaway https://api.hostaway.com/documentation · KrossBooking v5 non pubblica (richiedere a Kross)
Next.js (framework del template): https://nextjs.org/docs

PMS & CRM

Reconciliation (banca)

Conduit AI

Numeri & WhatsApp (WABA)

Dati & Revenue

Pagamenti & Vendita diretta

Smart Lock

Sito Direct Booking: come si crea

Quando si dà allo studente

Due domini, due cose diverse: `stay.` e `book.`

Regola d’oro: si forka, non si scaffolda

Da dove si parte

Stack (dal template)

Studente partner Kross vs studente con chiave propria

Come si costruisce (fasi)

Pagamenti

Procedura guidata (Claude ti fa le domande)

Stripe

Personalizzazione studente

Fonti ufficiali

​Quando si dà allo studente

​Due domini, due cose diverse: stay. e book.

​Regola d’oro: si forka, non si scaffolda

​Da dove si parte

​Stack (dal template)

​Studente partner Kross vs studente con chiave propria

​Come si costruisce (fasi)

​Pagamenti

Procedura guidata (Claude ti fa le domande)

Stripe

Personalizzazione studente

​Fonti ufficiali

Quando si dà allo studente

Due domini, due cose diverse: `stay.` e `book.`

Regola d’oro: si forka, non si scaffolda

Da dove si parte

Stack (dal template)

Studente partner Kross vs studente con chiave propria

Come si costruisce (fasi)

Pagamenti

Fonti ufficiali