> ## 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.

# KrossBooking: PMS e prenotazioni per studenti Mattone

> Scopri come KrossBooking si integra con Mattone: lettura prenotazioni, dati ospiti e stato check-in in tempo reale tramite gateway.

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` (il 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:**

| Modello     | Chiave che il ponte usa                                                                | Chi                                                                             |
| ----------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Partner** | la **nostra chiave generica** (uguale per tutti) + le 3 credenziali del cliente        | i **nuovi** studenti. Verificato live: partner HostManager360 → 13 ospiti reali |
| **Own**     | la **chiave propria** dello studente (che genera nel suo Kross) + le sue 3 credenziali | clienti attrezzati: **Cosmica, Solisera, SevenHome, MbaPrime**                  |

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`.

**Altri PMS (non Kross)**: pochi studenti usano un gestionale diverso (es. **Hostaway**): non seguono questa integrazione ma quella del loro PMS.

<Warning>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.</Warning>

<Info>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](/integrazioni/kross/accessi) e [Collegamento](/integrazioni/kross/collegamento).</Info>

### 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 (es. Solisera), la **generica nostra** per i partner (es. HostManager360). Percorso, ponte ed egress (proxy) sono **identici per tutti**.

## Sezioni correlate

<CardGroup cols={2}>
  <Card title="Accessi & credenziali" icon="key" href="/integrazioni/kross/accessi">
    Portale partner, sandbox, come arrivano le 3 credenziali di un cliente, IP whitelist. Dove si prendono le cose (mai valori reali).
  </Card>

  <Card title="Collegamento" icon="link" href="/integrazioni/kross/collegamento">
    Come collegare l'account di uno studente alla piattaforma Mattone (Collega Kross → Provision → runtime).
  </Card>

  <Card title="Endpoint & Scope" icon="code" href="/integrazioni/kross/endpoint-scope">
    Autenticazione, endpoint disponibili e scopo di ciascuna chiamata API verso KrossBooking.
  </Card>

  <Card title="Rate Limit & Trappole" icon="triangle-exclamation" href="/integrazioni/kross/rate-limit-trappole">
    Limiti di frequenza delle chiamate e comportamenti non ovvi dell'API che causano errori silenziosi.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrazioni/kross/troubleshooting">
    Tabella sintomo → causa → soluzione per i problemi più comuni dell'integrazione KrossBooking.
  </Card>
</CardGroup>

<Note>
  In caso di IP blocking su Kross, verifica che il 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 del gateway.
</Note>

## 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](https://docs.conduit.ai)