Skip to main content
Questa pagina dice dove si prendono gli accessi Kross e cosa fa ciascun dato. Zero segreti: nessuna password o chiave reale qui, quelle stanno cifrate nel Vault (la cassaforte) o nel gestore accessi del team.

​
Portali & contatti

Le credenziali del portale sono login web (utente + password), NON la chiave API. Non vanno nei docs/repo: vivono nel gestore accessi del team, che sblocca anche il codice 2FA.

​
Le 3 credenziali del cliente + la chiave, cosa sono

Per far leggere all’assistente i dati Kross di un cliente servono 3 credenziali del cliente + 1 chiave: L’accesso vero e proprio (POST /v5/auth/get-token) usa tutti e 4 i valori insieme.

​
Come arrivano le 3 credenziali di un cliente PARTNER

È la strada che funziona per collegare un nuovo cliente partner.
Il ticket a Kross lo apre il CLIENTE, non noi. Corretto l’08/09/2026 da Mattia, che è chi la esegue: «devono mandare loro ticket in assistenza chiedendo di avere accesso all’API tramite Mattone.co; io mando sempre il messaggio che devono scrivere a Kross».Il cliente chiede accesso all’API tramite Mattone.co, e nient’altro: non nomina gli strumenti a cui lo colleghiamo. Nell’agosto 2026 clienti che hanno chiesto «le API» citando strumenti terzi ci sono costati una contestazione scritta sull’accordo partner.⚠️ Non confondere questo con l’invio della lista endpoint e privilegi a Kross: quello è stato fatto una volta sola, il 31/07/2026, per il nostro profilo partner. Non si rifà a ogni cliente.
1

Il cliente apre un ticket all'assistenza Kross

Gli mandiamo noi il testo da copiare (vedi sotto), lui lo invia all’assistenza Kross chiedendo l’accesso all’API tramite Mattone.co. È il passo che fa partire tutto: finché il ticket non è aperto, non succede niente.
2

Kross genera il link di condivisione

Kross crea un link per quel cliente. Il cliente apre la richiesta dal suo lato e Kross gli comunica il canone previsto dall’accordo partner, a unità al mese (importo nel repo interno).
3

Le 3 credenziali compaiono nel Partner Portal

Dopo l’accettazione, le 3 credenziali del cliente (hotel_id, username, password) compaiono nel Partner Portal → sezione API → voce Credenziali.
4

Il team le copia in 'Collega Kross'

Da lì si incollano nell’admin Collega Kross → vengono cifrate nel Vault. Vedi Collegamento.

​
Accesso (per il partner)

  • L’accesso usa la chiave generica (nostra, nel Vault) + le 3 credenziali del cliente → POST /v5/auth/get-token (base https://api.krossbooking.com/v5).
  • Serve lo header User-Agent browser (se manca, Cloudflare blocca con errore 1010). Il permesso torna in data.auth_token (dura 7 giorni).
  • Nessuno digita la chiave generica a mano: la aggiunge da solo il nostro ponte mcp.mattone.co quando l’assistente lavora.

​
Whitelist IP (lo facciamo noi)

Kross accetta chiamate solo da indirizzi IP autorizzati (whitelist). La whitelist si imposta da soli nella sezione API del Partner Portal (non si chiede al supporto Kross).
  • Va autorizzato l’IP del proxy (il droplet (IP nel repo privato)), perché tutto il traffico Kross esce da lì. Vercel non è autorizzato (cambia IP di continuo): per questo il traffico passa dal proxy.
È il motivo per cui esiste il ponte + proxy: un solo indirizzo IP stabile da autorizzare, invece di rincorrere gli IP che cambiano.

​
Caso “own”, lo studente genera la SUA chiave

Per i clienti own (che hanno una chiave propria), la chiave non viene da noi: la genera lo studente dentro il suo Kross → Utilità → Servizi esterni (ottiene api_key + username api... + password, col suo hotel_id). Poi le 3 credenziali + la sua chiave vanno in Collega Kross come per il partner.
In tutti i casi gli strumenti dell’assistente passano dallo stesso ponte mcp.mattone.co: cambia solo quale chiave usa (la nostra generica, oppure quella dello studente). Vedi Panoramica.

​
📩 Il testo che diamo al cliente da mandare a Kross

Questo è il testo da passare al cliente. Non improvvisarne un altro: la formula è già stata usata su tutti i clienti attivati finora, e Kross la riconosce.
1

Help Center → Richiesta assistenza

Il cliente apre l’Help Center di Kross Booking e sceglie Richiesta assistenza.
2

Categoria: Richiesta informazioni

Non un’altra categoria: le altre finiscono in code diverse.
3

Incolla il messaggio

Il testo qui sotto, compilando le due parentesi.
Messaggio da inviare a Kross
Cosa abbiamo cambiato rispetto alla versione a voce, e perché. Due sole cose, il resto è identico:
  • Aggiunta la struttura e l’hotel id. Senza, l’assistenza deve scrivere per chiedere di quale account si tratta, e si perde un giro. Il cliente questi due dati li ha.
  • «1 € per unità al mese» invece di «1 € per listing». È la formula usata da Kross nell’accordo: «costo di 1 euro unità/mese». «Per listing» è ambiguo sul periodo e può far partire una discussione sul prezzo che non serve.
Il cliente non deve nominare nessuno strumento terzo — non Conduit, non l’assistente AI, niente. Chiede l’accesso all’API tramite Mattone.co, e basta. Nell’agosto 2026 clienti che hanno scritto a Kross citando strumenti terzi ci sono costati una contestazione scritta sull’accordo partner: Kross a quello strumento aveva già rifiutato la connessione e mandato una diffida.
Fatti dire dal cliente quando ha inviato la richiesta. È il momento in cui inizi a guardare il Partner Portal: le credenziali compaiono lì dopo che ha accettato, e nessuno ci avvisa.
Da confermare al primo cliente reale: il percorso esatto di clic nel Partner Portal per far comparire le 3 credenziali (sezione API → Credenziali) può cambiare un po’ nella schermata, verificalo alla prima attivazione e aggiorna questa pagina.
Fonti: memoria reference_krossbooking_partner_sandbox_creds, reference_krossbooking_partner_api_spec, project_krossbooking_partnership (valori reali → nel Vault, non qui). Architettura proxy: api-kross-mattone/architecture/proxy.md.