Skip to main content
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:
​
string
required
Identificativo numerico della struttura nel sistema KrossBooking. Recuperato dal portale Kross nella sezione API.
​
string
required
Nome utente API associato alla struttura. Distinto dal login web standard del portale.
​
string
required
Password API associata all’utente. Cifrata nel Vault Mattone, non viene mai esposta in chiaro nelle chiamate di sistema.
​
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.
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.
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.

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

​
Permessi di scrittura (solo operatività ospite)

  • In uso: reservations/save (modifica/estensione date), reservations/add-payment. Registrazione ospite: check-in-guest, save-guest-pictures.
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.

​
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.
  • 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.