Guida integrazione AlpineBits

Questa guida è rivolta a fornitori/PMS (property management system) che vogliono sincronizzare disponibilità, tariffe e prenotazioni con la piattaforma tramite il protocollo standard AlpineBits.

Cos'è AlpineBits

AlpineBits è un protocollo standard aperto per lo scambio di dati tra sistemi alberghieri (PMS/channel manager) e piattaforme di distribuzione, basato su XML OTA (OpenTravel Alliance) trasportato via HTTP. È largamente adottato nell'area alpina (Alto Adige, Trentino, Tirolo) per la sincronizzazione di inventario, tariffe e prenotazioni.

La piattaforma implementa la versione 2024-10 dello standard, come server (riceve richieste da PMS/channel manager esterni). Per la specifica completa del protocollo, consulta alpinebits.org.

Versione supportata: 2024-10 è l'unica versione di protocollo accettata dal server. Richieste con un header di versione diverso vengono rifiutate con un errore OTA_Error (nessun negoziato multi-versione).

Come ottenere le credenziali

Le credenziali di accesso (username e password) non si ottengono tramite autoregistrazione: vengono create dal referente commerciale/tecnico della struttura con cui stai integrando (il tenant che ti ha richiesto la connessione AlpineBits). Contatta direttamente il tuo interlocutore presso la struttura per richiedere un account fornitore.

Ogni account fornitore è associato a una singola struttura (multi-tenant): le credenziali che ricevi valgono solo per i dati di quella struttura.

Endpoint

POST https://<host>/api/alpinebits
Content-Type: multipart/form-data

Dove <host> è il dominio della piattaforma della struttura con cui stai integrando (es. www.tripmaster.cloud o un dominio custom del tenant).

Autenticazione

L'endpoint usa HTTP Basic Authentication sulle credenziali dell'account fornitore:

Authorization: Basic base64(username:password)

Le credenziali NON sono legate a un utente della piattaforma: sono un account fornitore dedicato, creato appositamente per l'integrazione AlpineBits.

Header obbligatorio

Ogni richiesta deve includere l'header di versione protocollo:

X-AlpineBits-ClientProtocolVersion: 2024-10

Senza questo header la richiesta viene rifiutata con 400 Bad Request. Con un valore diverso da 2024-10 la richiesta viene rifiutata con una risposta OTA_Error XML (200 con <Errors> nel corpo, come da standard AlpineBits).

Formato della richiesta: multipart `action` + `request`

Il body è multipart/form-data con due campi:

Campo	Descrizione
`action`	Identifica l'azione AlpineBits richiesta (vedi tabella sotto)
`request`	Il messaggio XML OTA della richiesta (es. `OTA_PingRQ`, ecc.)

Azioni supportate (fase 1)

Azione (`action`)	Messaggio richiesta → risposta	Capacità dichiarate
`OTA_Ping:Handshaking`	`OTA_PingRQ` → `OTA_PingRS`	Scambio capacità/versioni supportate
`OTA_HotelDescriptiveContentNotif:Inventory`	`OTA_HotelDescriptiveContentNotifRQ` → `...RS`	Sincronizzazione tipi camera/inventory
`OTA_HotelRatePlanNotif:RatePlans`	`OTA_HotelRatePlanNotifRQ` → `...RS`	`NotifType` Full (replace completo del listino mappato) e Remove (cancella il listino mappato); `Delta` non è supportato
`OTA_HotelInvCountNotif:FreeRooms`	`OTA_HotelInvCountNotifRQ` → `...RS`	`UniqueID/@Instance="CompleteSet"` (reset completo) e modalità delta (upsert incrementale, non tocca i giorni non inclusi)
`OTA_Read:GuestRequests` (pull)	`OTA_ReadRQ` → `OTA_ResRetrieveRS`	Estrazione prenotazioni in coda (batch max 50, per data creazione)
`OTA_NotifReport:GuestRequests` (ack)	`OTA_NotifReportRQ` → `OTA_NotifReportRS`	Acknowledgment delle prenotazioni ricevute (marca come "consegnate/lette")

Ogni richiesta viene validata contro lo schema XSD AlpineBits prima del routing: un XML non conforme produce sempre una risposta di errore coerente, anche per azioni non riconosciute o non ancora supportate.

Esempio curl: handshake completo

curl -X POST "https://<host>/api/alpinebits" \
  -u "<username>:<password>" \
  -H "X-AlpineBits-ClientProtocolVersion: 2024-10" \
  -F "action=OTA_Ping:Handshaking" \
  -F "request=<OTA_PingRQ xmlns=\"http://www.opentravel.org/OTA/2003/05\" Version=\"8.000\"><EchoData>{\"versions\":[{\"version\":\"2024-10\",\"actions\":[{\"action\":\"action_OTA_HotelRatePlanNotif_RatePlans\"},{\"action\":\"action_OTA_HotelInvCountNotif\"}]}]}</EchoData></OTA_PingRQ>"

La risposta è un OTA_PingRS XML con header X-AlpineBits-Server: BCMS e, in assenza di errori, nessun elemento <Errors> nel corpo.

Download XSD e campioni

Scarica lo schema XSD usato per validare richieste e risposte.

Campioni XML di riferimento (multipart field request):

Campione	Link
Handshake — richiesta (`OTA_PingRQ`)	Scarica
Handshake — risposta (`OTA_PingRS`)	Scarica
Inventory — richiesta base	Scarica
RatePlans — richiesta	Scarica
FreeRooms — richiesta	Scarica
GuestRequests — risposta con prenotazione	Scarica

Codici di errore comuni

Codice / risposta	Significato
`401 Unauthorized`	Credenziali mancanti, errate o account fornitore disattivato
`402 Payment Required`	L'abbonamento della struttura non è attivo (trial scaduto/cancellato) oppure il pacchetto Channel Manager non è attivo per la struttura (corpo JSON `error` distingue i due casi)
`400 Bad Request` — `ERR:no protocol version`	Header `X-AlpineBits-ClientProtocolVersion` mancante
`OTA_Error` — `ERR:unsupported protocol version`	Header di versione presente ma diverso da `2024-10`
`OTA_*RS` con `<Errors>` — `ERR:...`	Errore di validazione XSD, azione sconosciuta o errore di business specifico dell'azione

Tutti i tentativi (accettati o rifiutati) vengono registrati lato piattaforma per finalità di audit e supporto.

Flusso consigliato

Handshake (OTA_Ping:Handshaking) — verifica connettività e scambia le capacità supportate dalle due parti.
Inventory (OTA_HotelDescriptiveContentNotif:Inventory) — sincronizza i tipi camera prima di inviare tariffe o disponibilità.
RatePlans (OTA_HotelRatePlanNotif:RatePlans) — invia i listini tariffari.
FreeRooms (OTA_HotelInvCountNotif:FreeRooms) — invia la disponibilità (consigliato un CompleteSet iniziale, poi aggiornamenti in delta).
GuestRequests — effettua periodicamente il pull (OTA_Read) delle nuove prenotazioni e invia l'ack (OTA_NotifReport) una volta che il PMS le ha importate correttamente, per evitare di riceverle di nuovo nel pull successivo.