Skip to main content
KrossBooking è il sistema di gestione prenotazioni (PMS) usato dalla maggior parte degli studenti Mattone. Attraverso questa integrazione, Conduit legge in tempo reale le prenotazioni attive, i dati degli ospiti e lo stato del check-in, permettendo all’assistente AI di rispondere con informazioni sempre aggiornate e di automatizzare i flussi operativi legati agli arrivi e alle partenze.

​
Un solo ponte per tutti (mcp.mattone.co)

Tutti gli strumenti dell’assistente (i “custom tool”) di ogni studente passano dallo stesso ponte tecnico mcp.mattone.co (l’MCP Gateway, multi-tenant, cioè che serve tanti studenti da un unico posto). Il ponte legge dalla cassaforte (Vault) le credenziali di quello specifico studente, riconosciuto da un suo codice, X-Student-Token, e lì si può anche personalizzare per studente. L’unica differenza tra studenti è QUALE chiave usa il ponte: In entrambi i casi credenziali e chiave stanno nel Vault e il ponte le usa quando l’assistente lavora. Non esiste uno studente con “un ponte tutto suo”: il ponte è sempre mcp.mattone.co.

​
🔴 Conduit non si collega a Kross. Mai, per i clienti partner

È la domanda che torna ogni volta, e la risposta è sempre la stessa: non esiste un collegamento diretto fra Conduit e KrossBooking, e non è una scelta di comodo. L’assistente arriva ai dati Kross solo attraverso i custom tool → mcp.mattone.co → proxy → Kross. Le ragioni sono due, e nessuna delle due si aggira:
  1. Kross accetta chiamate solo da indirizzi IP autorizzati, e il filtro non si spegne. Conduit chiama dai propri server, i cui IP non sono nostri e non possiamo autorizzare. Una chiamata che non esce dal nostro proxy viene rifiutata, e l’errore parla di credenziali anche quando le credenziali sono sane.
  2. È un impegno che abbiamo preso per iscritto con Kross il 31/08/2026: nessuna credenziale a Conduit o a fornitori terzi, e chiamate solo dai nostri server dietro l’unico IP autorizzato. Kross alla connessione di Conduit ha detto no, e ha mandato una diffida per far togliere il proprio logo dal loro sito. Condividere le credenziali con Conduit viola l’accordo partner.
Non cercare di replicare i collegamenti fatti per Domos Sardinia o Soliséra. Quelli sono clienti own: usano una chiave loro con il filtro IP spento sul loro account, e per questo hanno potuto agganciarsi in modo diretto. Un cliente partner usa la nostra chiave generica, che vive dietro il nostro IP: quella strada per lui non esiste. Se ci provi ottieni un errore che sembra di credenziali, e passi ore a rigenerare chiavi sane.
Quindi, per un cliente partner, la via è una sola: i custom tool montati sul suo workspace, che sono proxy verso il gateway. È il pattern già in produzione su The Concept Studio (Andres) e HostManager, ed è quello da replicare su ogni nuovo cliente partner. Il token di ogni cliente è distinto: è l’id (uuid) della sua riga in pms_integrations, mai lo slug. Altri PMS (non Kross): pochi studenti usano un gestionale diverso (es. Hostaway): non seguono questa integrazione ma quella del loro PMS.
Sia “partner” sia “own” hanno bisogno degli strumenti dell’assistente + le loro istruzioni (skill), montati col bottone Provision: non pensare che “own” salti la configurazione. La connessione base di Conduit dà solo i dati grezzi; gli strumenti (disponibilità, check-in, apertura porta, pagamenti) servono in tutti e due i casi.
In sintesi: nuovo studente → chiave generica nostra; cliente con chiave sua → chiave sua; PMS diverso → altra integrazione. Ma il ponte è sempre mcp.mattone.co e i dati Kross arrivano via API v5. Vedi Accessi e Collegamento.
Prima di collegare un nuovo cliente, stabilisci in quale dei due casi sei: Collegamento → Prima di iniziare: partner o own?. Su un own, il Provision di questa integrazione risponde 400 apposta: non è un errore da aggirare.

​
Come funziona sotto (per il team tecnico)

Un solo percorso canonico, uguale per tutti gli studenti:
  • Ogni studente è un tenant identificato dall’id (uuid) della sua riga in pms_integrations.
  • Quella riga ha un cred_secret_id che punta alle credenziali cifrate nel Vault (le 3 credenziali del cliente + la chiave).
  • Il ponte, riconosciuto lo studente, legge quelle credenziali e chiama Kross sempre attraverso il proxy (unico IP autorizzato).
  • L’unica cosa che cambia tra studenti è quale api_key c’è dentro le credenziali: la propria per gli own, la generica nostra per i partner. Percorso, ponte ed egress (proxy) sono identici per tutti.

​
Cosa riconosce l’assistente per canale di prenotazione (clienti partner)

Per un cliente partner collegato con la chiave generica Mattone, il collegamento base di Conduit copre solo Airbnb: è il caso quando in Conduit si usa “Use Airbnb as your PMS” per far comparire gli alloggi, anche se in piattaforma il cliente ha Kross partner collegato. In quella configurazione, fino a poco tempo fa, le prenotazioni Booking.com e le prenotazioni dirette non venivano mai riconosciute dalla knowledge base ospiti: non esisteva nessuna prenotazione Conduit sincronizzata per quei canali, solo per Airbnb. Questo buco oggi si chiude, ma non per tutti gli alloggi in automatico. Il ponte mcp.mattone.co legge la prenotazione da KrossBooking, alloggio, date, riferimento, e la scrive sul contatto Conduit dell’ospite: la ricerca nella knowledge base trova così l’alloggio giusto anche per questi canali. Il meccanismo è verificato dal vivo su ospiti reali.
Copertura parziale, non ancora automatica al 100%. Il cron gira da solo ogni 3 ore, ma copre solo gli alloggi la cui riga nel registro appartamenti è collegata e confermata (badge verde, non arancione “Suggerito”). Per un alloggio non ancora confermato lì, Booking.com e diretto restano scoperti come prima. Non è “risolto per tutti i clienti partner”: è un meccanismo pronto, da estendere alloggio per alloggio.

​
Come sapere se il tuo assistente lo sta davvero usando

Il meccanismo sopra ha tre pezzi separati. Se uno manca, gli altri non contano: un cron che gira ma non trova un alloggio collegato non scrive niente, e dati scritti bene non servono a nulla se l’assistente non è (ancora) istruito a leggerli prima di rispondere. Prima di dare per scontato che funzioni, controlla tutti e tre:
1

I tuoi alloggi sono collegati e CONFERMATI, non solo suggeriti

Vai su Appartamenti nella piattaforma. In alto vedi un contatore tipo “X di Y confermati”: X deve coprire tutti gli alloggi per cui vuoi che Booking.com/diretto funzionino. Un badge 🟠 Suggerito è un abbinamento automatico che nessuno ha ancora controllato: non conta come pronto, va confermato a mano (guardando indirizzo e dettagli reali, non solo il nome — Kross spesso tronca il nome che vedi nell’annuncio).
2

I dati della prenotazione arrivano davvero sul contatto dell'ospite

Prendi un ospite Booking.com o diretto recente (check-in nelle ultime 24-48 ore) su un alloggio che al punto 1 risultava confermato. Apri la sua scheda contatto su Conduit e cerca gli attributi personalizzati “Reservation Listing”, “Reservation Check-in”, “Reservation Check-out”, “Reservation Reference” (tag “Gradino 2”). Devono esserci e le date devono corrispondere alla sua prenotazione reale — non a una prenotazione vecchia.
3

L'assistente li usa davvero per rispondere all'alloggio giusto

Su quello stesso ospite, guarda (o simula) una domanda che ha una risposta diversa alloggio per alloggio — non generica: “come si accende il forno?”, “qual è la password del WiFi?”. Se la risposta è specifica e corretta per quel preciso alloggio, tutto funziona. Se è generica, dice di non trovare l’informazione, o parla dell’alloggio sbagliato — anche con i primi due punti a posto — significa che l’assistente non sta ancora usando quei dati per cercare nella knowledge base: non è un problema della tua configurazione, è un pezzo del meccanismo ancora in lavorazione. Segnalalo al supporto Mattone con il nome dell’ospite e l’alloggio.

​
Shelly (apertura porta): gated sul portale completato, anche per i clienti partner

Se un cliente partner ha anche una serratura Shelly collegata (vedi Smart check-in), il ponte mcp.mattone.co non apre la porta e non mostra il link di apertura finché il Guest Portal Kross di quell’ospite non risulta completato. È lo stesso principio già descritto in Check-in non completato: qui la differenza è dove vive il controllo.
Verificato nel codice il 25/09/2026. Il controllo vive nel codice condiviso del gateway (mattone-mcp-gateway), non in una configurazione per singolo cliente: si applica in automatico a chiunque abbia sia Kross-partner sia Shelly, appena il tool Shelly viene montato sul suo workspace, con lo stesso principio già in produzione lato Kross (get_checkin_instructions).
Come funziona: il ponte, con lo stesso X-Student-Token del cliente, guarda chi sta usando quella proprietà adesso (chi è in casa oggi, poi chi arriva entro un giorno) e ne legge il portal_completed già misurato dagli stessi tool di lettura (check_portal_status/get_reservation_status), senza nessuna chiamata Kross in più. Se non trova esattamente un ospite compatibile, o non riesce a verificarlo (Kross irraggiungibile, credenziali rifiutate), blocca comunque: mai un’apertura concessa su un dato incompleto.
Questo è diverso dal percorso Cosmica/own-account (cosmica-booking, stay.cosmicarentals.com), che ha il proprio Shelly MCP separato e il proprio gate a livello di skill Conduit (check-in-access-manager). I due percorsi non condividono codice: un cliente partner passa sempre da mcp.mattone.co, mai dal percorso Cosmica. Vedi Panoramica Shelly.

​
Sezioni correlate

Accessi & credenziali

Portale partner, sandbox, come arrivano le 3 credenziali di un cliente, IP whitelist. Dove si prendono le cose (mai valori reali).

Collegamento

Come collegare l’account di uno studente alla piattaforma Mattone (Collega Kross → Provision → runtime).

Endpoint & Scope

Autenticazione, endpoint disponibili e scopo di ciascuna chiamata API verso KrossBooking.

Rate Limit & Trappole

Limiti di frequenza delle chiamate e comportamenti non ovvi dell’API che causano errori silenziosi.

Troubleshooting

Tabella sintomo → causa → soluzione per i problemi più comuni dell’integrazione KrossBooking.
L’agente riconosce la struttura anche se l’ospite dà solo l’indirizzo, non il nome. address/city/post_code arrivano già in rooms/get-room-types (con with_be_info:true) e alimentano lo stesso matching tollerante usato per i nomi. Non serve nessuna chiamata Kross in più: se resta ambiguo fra più strutture, l’agente chiede. Dettaglio: Troubleshooting → matching per proprietà.
In caso di IP blocking su Kross, verifica che l’MCP Gateway (mcp.mattone.co) sia aggiornato con l’IP corretto nella whitelist Kross. Se il blocco persiste, contatta il team tecnico per aggiornare la configurazione dell’MCP Gateway.

​
Fonti ufficiali

  • KrossBooking API v5: non c’è una doc pubblica: è riservata al partner (accessibile dal portale partner / apiv5 con la chiave). Per la doc → richiedere a Kross (fabiod@krossbooking.com).
  • La consuma Conduit (nostro assistente): doc Conduit → https://docs.conduit.ai