Prima di iniziare: partner o own?
Prima di collegare qualsiasi cosa, stabilisci in quale dei due casi sei. Non è una scelta: è un fatto sul cliente, e determina quale strada segui da qui in poi.
Il resto di questa pagina — le due procedure sotto — vale per il caso partner, che è quello che incontri quasi sempre con un nuovo studente. Il perché di questa distinzione (i due IP, l’accordo scritto con Kross) è in Panoramica → Conduit non si collega a Kross.
Prerequisiti
Prima di iniziare, assicurati che:- L’anagrafica dello studente su Notion sia completa e approvata
- Lo studente abbia accesso al proprio portale KrossBooking con permessi di amministratore
- Lo studente abbia recuperato, dalla sezione API del portale Kross, i quattro valori che il form chiede:
api_keyhotel_id, identificativo numerico della strutturausername, utente API (formatoapiNNNNN, distinto dal login web)password, password API dedicata (non la password di login dell’account)
Step
1
Lo studente recupera le credenziali API da Kross
Lo studente accede al proprio portale KrossBooking, naviga nella sezione API (o Impostazioni → Integrazioni) e copia i quattro valori:
api_key, hotel_id, username e password. Se la sezione API non è visibile, lo studente deve contattare il supporto Kross per abilitarla.2
Inserisci le credenziali nell'Admin di Mattone
Di norma le inserisce lo studente stesso in /connessioni della piattaforma: e’ il percorso previsto dal prodotto. La via Admin (Connessioni → Collega Kross) si usa quando lo facciamo noi al posto suo, es. onboarding partner-managed. In entrambi i casi si inseriscono i quattro valori e si salva. Il sistema cifra automaticamente le credenziali e le archivia nel Vault, non vengono mai memorizzate in chiaro.
3
Il sistema verifica la connessione via gateway
Dopo il salvataggio, la piattaforma esegue automaticamente un test di connessione passando per
mcp.mattone.co. Attendi che il risultato appaia nell’interfaccia: il processo richiede normalmente meno di 10 secondi.4
Verde: le 4 credenziali sono salvate (cred_secret_id)
Stato verde = la connessione è attiva e le 4 credenziali sono state scritte cifrate (
cred_secret_id) nel Vault. Non devi creare nessuna chiave manuale: la chiave generica partner è già nostra e il gateway la usa in automatico.5
🚀 Provision: monta gli strumenti dell'assistente
Premi Provision per lo studente: la piattaforma monta gli strumenti dell’assistente per Kross (le “custom tool”) con le loro istruzioni (skill) nello spazio Conduit dello studente. Da qui l’assistente sa parlare con Kross.
6
Fatto: l'assistente recupera le credenziali da solo
Quando l’assistente usa uno strumento, il nostro ponte
mcp.mattone.co recupera le credenziali dal Vault mentre lavora (chiave generica + proxy con IP autorizzato) e chiama Kross. Nessun passaggio manuale ulteriore. Verifica con una domanda reale (es. una prenotazione) che tornino dati veri.Se il test è rosso, la causa quasi sempre sono le credenziali (sbagliate, o
hotel_id che non corrisponde). Rigenerale dal portale Kross e ri-salva. Dettaglio: Troubleshooting.Procedura partner ripetibile (template)
Questa è la strada funzionante end-to-end per collegare un nuovo partner Kross, già provata su un partner con l’agente live che legge prenotazioni vere. Replicala per il prossimo partner:1
L'Account Manager contatta Kross per la partnership
L’AM avvia la partnership con Kross e recupera l’accesso al portale partner del cliente (dove compaiono le 4 credenziali).
2
Recupera le 4 credenziali
Dal portale partner → sezione API:
api_key, hotel_id, username (apiNNNNN), password API del cliente.3
Collega Kross
Admin → Collega Kross → incolla le 4 credenziali → verde (scrive
cred_secret_id nel Vault).4
Provision
🚀 monta tool + skill sul workspace Conduit dello studente.
5
Compila le skill policy con i dati dello studente
Le skill policy montate dal Provision arrivano con i campi vuoti o segnaposto: compilale con i dati di questo studente (numeri reperibili, fee, link portale/email). Dettaglio campo per campo: Personalizzazione per studente.
6
KB Notion & telefonia, se servono
Se lo studente ha il registro Notion → genera la KB per-listing (bridge). Se vuole voce/WhatsApp → configura telefonia/WABA.
7
Test end-to-end reale
Ospite realmente presente in Kross → l’agente trova la prenotazione e dà i dati corretti.
Verifica della connessione
Una connessione riuscita si riconosce da questi segnali:- Lo stato nella scheda studente mostra “Kross: connesso” con indicatore verde
- Conduit è in grado di recuperare almeno una prenotazione dalla struttura (puoi verificarlo dalla sezione Debug → Ultime prenotazioni nell’Admin)
- Non sono presenti errori
401nei log di sistema relativi a quelhotel_id, tranne quello sui pagamenti descritto sotto, che è atteso
Pagamenti non disponibili con il collegamento partner (KRO-14)
Con la chiave partner di Mattone, Kross non espone i pagamenti: la lettura dei pagamenti rispondeHTTP 401 — Endpoint not enabled for this api key/hotel id. Non è un guasto e non dipende dalle credenziali dello studente: è un limite della chiave partner, segnalato a Kross come KRO-14.
Cosa vede lo studente (dal 08/10/2026):
- in /connessioni, un riquadro informativo «Pagamenti non disponibili con il collegamento Mattone», non un errore: il collegamento resta verde;
- nella dashboard, la card «Pagamenti ricevuti» mostra «non disponibili con il collegamento Mattone»; «Ancora da incassare» resta calcolato dalle prenotazioni.
Collega Kross (piattaforma)
Inserisci le 4 credenziali (cifrate nel Vault)
Portale KrossBooking → API
Sezione API → credenziali del cliente