> ## 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 API: autenticazione ed endpoint disponibili

> Autenticazione bearer e tutti gli endpoint KrossBooking usati da Mattone: disponibilità, prenotazioni, portali check-in e accesso.

L'API di KrossBooking utilizza un sistema di autenticazione basato su token bearer. Tutte le chiamate che Mattone effettua verso Kross passano attraverso il gateway multi-tenant `mcp.mattone.co`, che gestisce l'autenticazione, la rotazione dei token e il whitelisting dell'IP, in questo modo le strutture degli studenti non devono aprire accessi multipli o gestire token direttamente.

## Autenticazione

Per ottenere un token valido, il gateway effettua una chiamata `POST` all'endpoint di autenticazione con le credenziali dello studente. Il token restituito è di tipo bearer ed è valido per la durata della sessione.

**Endpoint:** `POST /v5/auth/get-token`

I campi richiesti nel body della richiesta sono:

<ParamField body="hotel_id" type="string" required>
  Identificativo numerico della struttura nel sistema KrossBooking. Recuperato dal portale Kross nella sezione API.
</ParamField>

<ParamField body="username" type="string" required>
  Nome utente API associato alla struttura. Distinto dal login web standard del portale.
</ParamField>

<ParamField body="password" type="string" required>
  Password API associata all'utente. Cifrata nel Vault Mattone, non viene mai esposta in chiaro nelle chiamate di sistema.
</ParamField>

<ParamField body="api_key" type="string" required>
  Chiave API KrossBooking (4° campo). Per gli studenti **partner** è la chiave **generica** Mattone (nel Vault, la aggiunge il gateway); per i clienti **own** è la chiave propria del cliente.
</ParamField>

La risposta include il token bearer (in `data.auth_token`, TTL 7 giorni) da usare nell'header `Authorization: Bearer <token>` per tutte le chiamate successive.

<Info>
  In più alle credenziali dello studente, l'auth richiede una **`api_key`** (4° campo): per gli studenti **partner** è la chiave generica condivisa Mattone (nel Vault); per i clienti **own** (Cosmica) è la loro chiave propria. La `api_key` vera è **32 caratteri esadecimali** (dal pannello Kross → Impostazioni → API); l'`username` API è in formato **`apiNNNNN`**, non l'email. Serve inoltre lo header **User-Agent** browser (`Mozilla/5.0`): senza, Cloudflare blocca con errore **1010**.
</Info>

## Endpoint per scopo

Questa tabella elenca tutti gli endpoint KrossBooking attualmente usati dalla piattaforma Mattone, con il relativo tool MCP esposto tramite gateway e il tipo di operazione.

Tutti gli endpoint KrossBooking sono su **API v5**, in **`POST`** su base `https://api.krossbooking.com/v5/...`.

| Scopo                       | Endpoint v5 (POST)                              | Tool MCP                   | Tipo  |
| --------------------------- | ----------------------------------------------- | -------------------------- | ----- |
| Autenticazione              | `auth/get-token`                                | *(gestito dal gateway)*    | Write |
| Disponibilità               | `calendar/get-availability`                     | `check-availability`       | Read  |
| Stato prenotazione          | `reservations/get-list`                         | `get-reservation-status`   | Read  |
| Ospiti in casa              | `reservations/get-list` (filtro in-house)       | `get-in-house-guests`      | Read  |
| Portali check-in incompleti | `reservations/get-list` (blocco `guest_portal`) | `get-incomplete-portals`   | Read  |
| Stato portale ospite        | `reservations/get-list` (blocco `guest_portal`) | `check-portal-status`      | Read  |
| Istruzioni check-in         | `get-check-in-instructions`                     | `get-checkin-instructions` | Read  |
| Manuale casa / contratto    | `get-house-manual` · `get-contract`             | ,                          | Read  |

<Note>
  I tool MCP sono i nomi usati da Conduit per invocare gli endpoint Kross attraverso il gateway `mcp.mattone.co`. Non è necessario chiamare gli endpoint REST direttamente: Conduit utilizza i tool MCP, che gestiscono autenticazione, token e retry in modo trasparente.
</Note>

<Warning>
  Il path `/apiv5` restituisce la pagina HTML della documentazione KrossBooking, **non dati API**. Usare sempre il path corretto `/v5/...` per tutte le chiamate. Questo è uno degli errori più comuni in fase di configurazione manuale o debug.
</Warning>

<Note>
  I filtri data su alcuni endpoint Kross possono essere ignorati server-side: la risposta potrebbe contenere tutte le prenotazioni indipendentemente dal range richiesto. Verifica sempre la risposta effettiva contando i record restituiti e controllando le date prima di passare i dati a Conduit o ad altri sistemi a valle.
</Note>

## Permessi di scrittura (solo operatività ospite)

* **In uso**: `reservations/save` (modifica/estensione date), `reservations/add-payment`. Registrazione ospite: `check-in-guest`, `save-guest-pictures`.

<Warning>Fuori perimetro (dichiarato "pulito" a Kross): `channel/save-cm` (tariffe/restrizioni OTA) → le governa **PriceLabs**; gestione utenti/permessi; `messaging/*`. Kross **non accetta** partner che commercializzano AI per la messaggistica: la messaggistica la fa Conduit lato canale, mai via Kross.</Warning>

## Limiti tecnici

* Token: **50 sessioni concorrenti per `hotel_id`** (TTL 7 giorni) → la chiave generica non aggrega, ogni struttura ha il suo conteggio.
* Rate limit: **10/min · 300/h · 5.000/giorno per struttura** (negoziabili). Dettagli in [Rate limit & trappole](/integrazioni/kross/rate-limit-trappole).
* Endpoint reali su base `POST /v5/...` (es. `reservations/get-list`, `calendar/get-availability`): `calendar/get-calendar` e `reservations/change-channel` **non esistono**; il token è in `data.auth_token`.