Galaxy HotelCloud
API pubblica, webhook e ambiente di prova

Sviluppatori

L'API pubblica di Galaxy Hotel Cloud: collega il tuo booking engine, channel manager, POS o sistema di serrature a una struttura in pochi passi.

Documento OpenAPI

GET /v1/availability200 OK{ "date": "2026-11-01", "room_type_id": 2, "free": 4}POST /v1/reservations 201X-Product-Key gh_prod_…reservation.createdPOST /webhooks · 200

Come iniziare

  1. 1

    Fai richiesta

    Compila il modulo in fondo alla pagina con la tua azienda e il prodotto che vuoi collegare: esaminiamo la richiesta e ti apriamo il portale integratori.

  2. 2

    Prova sull'ambiente di prova

    Nel portale generi la product key del tuo prodotto e la chiave dell'ambiente di prova. GET /v1/me con le due chiavi risponde con la struttura e i permessi; da lì tipologie, tariffe, disponibilità, prenotazioni.

  3. 3

    Vai in produzione

    Compili la scheda del prodotto (testi, logo, permessi richiesti) e la mandi in revisione. Approvata, il prodotto entra nel Marketplace degli hotel: ognuno lo attiva accettando i permessi e tu ritiri la chiave della struttura dal portale o con l'API, senza copia e incolla. La scheda compare anche nel Marketplace del sito.

Cosa puoi fare

Disponibilità e prezzi

Camere libere per tipologia e notte, piani tariffari e preventivi calcolati dal motore prezzi del PMS. Per channel manager e booking engine, prezzi per numero di ospiti, stop vendita e soggiorno minimo giorno per giorno, con un evento quando cambiano. Per la vetrina foto, logo, descrizioni nelle varie lingue, servizi e superficie delle tipologie; nel preventivo l'imposta di soggiorno, le condizioni di cancellazione, il trattamento e l'acconto richiesto dal listino.

Prenotazioni

Creare, modificare, confermare, annullare; assegnare le camere; check-in e check-out; ospiti in camera con i dati per gli adempimenti. Per i channel manager, le prenotazioni dei portali: mai rifiutate per una tipologia piena, anche modificate o annullate, e quelle che il programma non sa sistemare da solo vanno alla reception.

Conti

Leggere i conti di una prenotazione e addebitare articoli: ciò che fa un POS quando l'ospite firma il conto in camera.

Pagamenti

Metodi di pagamento della struttura, quanto è stato pagato su una prenotazione e la registrazione di un pagamento incassato altrove, sul preconto come una caparra; oppure un link di pagamento del provider di carte dell'hotel per la caparra, il saldo o la garanzia; con un permesso a parte, addebiti e rimborsi sulla carta salvata.

Eventi e webhook

Prenotazioni create, check-in, check-out e annulli in ordine, da leggere a cursore oppure ricevuti sul tuo indirizzo con i webhook firmati.

La prima chiamata

curl https://api.galaxy-hotel.net/v1/me \
  -H "Authorization: Bearer gh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Product-Key: gh_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "key":      { "name": "Booking engine", "scopes": ["availability:read", "reservations:write"] },
  "product":  { "id": 12, "name": "Booking engine", "company": "Acme Software", "status": "live" },
  "property": { "id": 1, "code": "p1", "name": "Hotel Bella Vista" },
  "account":  { "name": "Bella Vista srl", "plan": "subscription" }
}

curl "https://api.galaxy-hotel.net/v1/availability?from=2026-11-01&to=2026-11-04" \
  -H "Authorization: Bearer gh_live_…" -H "X-Product-Key: gh_prod_…"

curl -X POST https://api.galaxy-hotel.net/v1/reservations \
  -H "Authorization: Bearer gh_live_…" -H "X-Product-Key: gh_prod_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: be-2026-000123" \
  -d '{ "external_ref": "BE-2026-000123", "status": "confirmed",
        "new_party": { "first_name": "Maria", "last_name": "Rossi", "email": "maria@example.com" },
        "rooms": [{ "room_type_id": 2, "arrival": "2026-11-01", "departure": "2026-11-04", "adults": 2 }] }'

Le regole in breve

  • Due chiavi in ogni chiamata: quella della struttura in Authorization: Bearer (una per struttura, con i permessi che l'hotel ha accettato) e la product key del tuo prodotto in X-Product-Key.
  • JSON, date AAAA-MM-GG con partenza esclusa, importi decimali in euro, errori con un codice stabile e un messaggio leggibile.
  • 600 chiamate al minuto per chiave. Idempotency-Key sulle scritture per ripetere una chiamata senza effetti doppi; external_ref unico per struttura sulle prenotazioni.
  • La versione è nel percorso (/v1): i campi si aggiungono, non si tolgono né si rinominano.

Server MCP per gli hotel

Per collegare un assistente AI non serve diventare integratori: ogni persona dell'hotel crea la sua chiave nel Marketplace dentro l'app (Assistenti AI (MCP)) o in Il mio profilo e la usa con Claude, ChatGPT, Cursor, n8n o un agente proprio. Il server parla MCP con streamable HTTP: un messaggio JSON-RPC per POST.

  • La chiave gh_mcp_… va in Authorization: Bearer. È di una persona e di una struttura: l'assistente vede solo quello che quella persona vede nel gestionale.
  • Gli strumenti leggono struttura, camere, tipologie, listini, disponibilità, prenotazioni, ospiti e conti. Documenti, recapiti e date di nascita degli ospiti non escono.
  • Con una chiave «Lettura e proposte» check_in, check_out, assign_room e add_charge non eseguono nulla: preparano una proposta che la persona conferma o annulla nell'app entro 15 minuti.
  • È separato dall'API /v1: le chiavi dell'uno non valgono sull'altra, 120 chiamate al minuto per chiave, e sull'ambiente di prova il server MCP non c'è.
claude mcp add --transport http galaxy https://api.galaxy-hotel.net/mcp \
  --header "Authorization: Bearer gh_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

curl -X POST https://api.galaxy-hotel.net/mcp \
  -H "Authorization: Bearer gh_mcp_…" -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": { "name": "search_reservations", "arguments": { "status": "checked_in" } } }'

Ambiente di prova

Un ambiente condiviso con dati di esempio, azzerato ogni notte alle 04:00 (ora italiana). La chiave di prova si crea dal portale integratori, una per prodotto, e ha tutti i permessi: quello che scrivi lo vedono anche gli altri integratori e sparisce all'azzeramento, con i webhook sottoscritti.

Serve aiuto?

Scrivi a support@galaxy-hotel.net con l'operazione, il codice dell'errore e l'ora della chiamata: le chiamate sono tracciate per chiave.

Diventa integratore

Per usare l'API con gli hotel serve un prodotto approvato. Dicci chi sei e cosa vuoi collegare: dopo l'approvazione ricevi l'accesso al portale integratori, con la product key, l'ambiente di prova e la guida.

Leggi le condizioni d'uso dell'API

Richiesta di integrazione

Hai già un accesso? Entra nel portale integratori

Changelog

  • Novembre 2026 · Server MCP per gli integratori (/integrator/mcp): ogni persona del portale integratori crea la sua chiave (Assistente AI (MCP)) e collega Claude Code, Cursor o Codex alla guida e al riferimento dell'API, ai suoi prodotti con i controlli prima della revisione, alle strutture collegate e alle consegne dei webhook; con «azioni leggere» anche la scheda del prodotto e la chiave di prova.
  • Novembre 2026 · Server MCP per gli hotel (/mcp): una chiave per persona, in lettura e con proposte da confermare nell'app, per collegare Claude, ChatGPT o un altro assistente ai dati di una struttura.
  • Ottobre 2026 · Integratori: richiesta dal sito, portale con product key e chiave di prova, scheda del prodotto nel Marketplace degli hotel, chiavi delle strutture da ritirare (GET /v1/connections); le chiamate fatte per un prodotto portano anche l'intestazione X-Product-Key.
  • Settembre 2026 · Prima versione: struttura, disponibilità, preventivi, prenotazioni, ospiti, conti, eventi e webhook.