API e integrazioni

Il Booking Engine di Hotely espone un set di API REST che permettono di interagire con il sistema di prenotazione in modo programmatico. Che tu stia costruendo un'app mobile, integrando un CRM, collegando un PMS esterno o automatizzando flussi operativi, le API ti offrono accesso completo a disponibilità, prezzi, prenotazioni e pagamenti.

A differenza di molte soluzioni sul mercato che offrono API limitate, riservate a piani enterprise o documentate in modo frammentario, le API di Hotely sono accessibili, ben strutturate e progettate per casi d'uso reali.

Architettura REST

Le API seguono i principi REST standard:

• Base URL: tutte le chiamate partono da /api/booking-engine/
• Formato: richieste e risposte in JSON (Content-Type: application/json)
• Metodi HTTP: GET per lettura, POST per creazione, PUT/PATCH per aggiornamento, DELETE per eliminazione
• Codici di stato: risposte standard HTTP (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error)
• Paginazione: le liste supportano parametri page e limit per la paginazione dei risultati

Convenzioni di naming

Gli endpoint seguono una struttura gerarchica basata sullo slug della proprietà:

/api/booking-engine/{propertySlug}/rooms
/api/booking-engine/{propertySlug}/availability
/api/booking-engine/{propertySlug}/reservations

Ogni proprietà è identificata dal proprio slug univoco, che corrisponde al percorso pubblico della pagina di prenotazione.

Autenticazione

Le API utilizzano un sistema di autenticazione basato su sessione per le operazioni admin e chiavi API per le integrazioni server-to-server.

Autenticazione admin (sessione)

Le chiamate effettuate dalla dashboard utilizzano il cookie di sessione dell'utente autenticato. Questo metodo è utilizzato internamente dall'interfaccia e non richiede configurazione aggiuntiva.

Chiavi API per integrazioni esterne

Per le integrazioni server-to-server, ogni proprietà può generare una chiave API dalla sezione Impostazioni > Integrazioni della dashboard. La chiave va inclusa nell'header di ogni richiesta:

Authorization: Bearer {API_KEY}

Best practice di sicurezza

• Non includere mai la chiave API nel codice frontend o in repository pubblici
• Utilizza variabili d'ambiente sul server per memorizzare la chiave
• Ruota le chiavi periodicamente, specialmente dopo il turnover di personale tecnico
• Monitora l'utilizzo dalla dashboard per rilevare attività anomale

Endpoint principali

Ricerca disponibilità

L'endpoint di ricerca disponibilità è il punto di partenza per qualsiasi flusso di prenotazione. Restituisce le tipologie camera disponibili con i relativi prezzi calcolati per il periodo richiesto.

Richiesta:

GET /api/booking-engine/{propertySlug}/availability

Parametri query:

Risposta:

La risposta include un array di tipologie camera disponibili, ciascuna con:

• Informazioni sulla tipologia (nome, descrizione, foto, capacità, servizi)
• Piani tariffari applicabili con prezzo calcolato per il soggiorno completo
• Tasse e supplementi dettagliati
• Eventuali sconti promozionali applicati
• Politica di cancellazione associata al piano tariffario

Anteprima prezzo

Prima di procedere al checkout, puoi richiedere un'anteprima dettagliata del prezzo per una combinazione specifica di camera, tariffa ed extra.

Richiesta:

POST /api/booking-engine/{propertySlug}/pricing-preview

Body:

{
  "roomTypeId": "clx...",
  "ratePlanId": "clx...",
  "checkIn": "2026-04-15",
  "checkOut": "2026-04-18",
  "adults": 2,
  "children": 1,
  "extras": ["clx_extra_breakfast", "clx_extra_parking"],
  "promoCode": "ESTATE2026"
}

Risposta:

La risposta restituisce il breakdown completo del prezzo:

Creazione prenotazione

L'endpoint di creazione prenotazione gestisce l'intero flusso: validazione disponibilità in tempo reale, calcolo prezzo finale, creazione del record e avvio del pagamento.

Richiesta:

POST /api/booking-engine/{propertySlug}/reservations

Body:

{
  "roomTypeId": "clx...",
  "ratePlanId": "clx...",
  "checkIn": "2026-04-15",
  "checkOut": "2026-04-18",
  "adults": 2,
  "children": 1,
  "guest": {
    "firstName": "Marco",
    "lastName": "Rossi",
    "email": "marco@email.com",
    "phone": "+39 333 1234567",
    "country": "IT"
  },
  "extras": ["clx_extra_breakfast"],
  "specialRequests": "Camera ai piani alti, se possibile",
  "promoCode": "ESTATE2026",
  "arrivalTime": "15:00"
}

La risposta include l'ID della prenotazione, il riepilogo completo e, se il pagamento è configurato in modalità immediata, l'URL della sessione di pagamento Stripe.

Checkout e pagamento

Il flusso di checkout si integra direttamente con Stripe. Dopo la creazione della prenotazione, il sistema genera una sessione di pagamento Stripe Checkout con tutti i dettagli precompilati.

Richiesta:

POST /api/booking-engine/{propertySlug}/checkout

Body:

{
  "reservationId": "clx...",
  "paymentMethod": "full_payment",
  "successUrl": "https://tuosito.com/conferma",
  "cancelUrl": "https://tuosito.com/prenotazione"
}

Gestione prenotazioni

Lista prenotazioni:

GET /api/booking-engine/{propertySlug}/reservations

Supporta filtri per stato (confirmed, pending, cancelled, checked_in, checked_out), intervallo date e ricerca per nome ospite o codice prenotazione.

Dettaglio prenotazione:

GET /api/booking-engine/{propertySlug}/reservations/{reservationId}

Restituisce tutti i dettagli della prenotazione, incluso lo storico pagamenti, le email inviate e le modifiche effettuate.

Aggiornamento prenotazione:

PATCH /api/booking-engine/{propertySlug}/reservations/{reservationId}

Permette di aggiornare date, stato, note interne, assegnazione camera e dati ospite.

Cancellazione:

DELETE /api/booking-engine/{propertySlug}/reservations/{reservationId}

Cancella la prenotazione applicando la politica di cancellazione configurata. Se previsto, avvia automaticamente il rimborso tramite Stripe.

Webhook

I webhook permettono di ricevere notifiche in tempo reale quando si verificano eventi nel Booking Engine. Invece di effettuare polling continuo sulle API, configuri un URL sul tuo server e Hotely invia una richiesta POST ogni volta che un evento rilevante si verifica.

Configurazione

Dalla sezione Impostazioni > Webhook della proprietà:

1. Inserisci l'URL del tuo endpoint (deve essere HTTPS)
2. Seleziona gli eventi che vuoi ricevere
3. Copia il signing secret generato automaticamente
4. Salva la configurazione

Eventi disponibili

Formato del payload

Ogni webhook viene inviato come richiesta POST con body JSON:

{
  "event": "reservation.confirmed",
  "timestamp": "2026-04-15T14:30:00Z",
  "propertySlug": "hotel-bellavista",
  "data": {
    "reservationId": "clx...",
    "confirmationCode": "HBV-2026-0042",
    "checkIn": "2026-04-20",
    "checkOut": "2026-04-23",
    "guest": {
      "firstName": "Marco",
      "lastName": "Rossi",
      "email": "marco@email.com"
    },
    "totalAmount": 45000,
    "currency": "EUR"
  }
}

Gli importi sono espressi in centesimi (45000 = 450,00 EUR) per evitare problemi di arrotondamento con i numeri decimali.

Verifica della firma

Ogni richiesta webhook include un header X-Hotely-Signature che contiene un HMAC-SHA256 del body, calcolato con il signing secret della tua configurazione. Verifica sempre questa firma prima di processare il webhook per assicurarti che provenga da Hotely.

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry e gestione errori

Se il tuo endpoint restituisce un codice di errore (4xx o 5xx) o non risponde entro 10 secondi, Hotely ritenta l'invio con backoff esponenziale:

• 1 minuto dopo il primo fallimento
• 5 minuti dopo il secondo
• 30 minuti dopo il terzo
• 2 ore dopo il quarto
• 12 ore dopo il quinto (ultimo tentativo)

Dalla dashboard puoi visualizzare lo stato di ogni webhook inviato e ritentare manualmente l'invio in caso di problemi.

Costruire integrazioni personalizzate

Integrazione con PMS

Se utilizzi un Property Management System esterno, puoi sincronizzare le prenotazioni tramite webhook:

1. Configura un webhook per l'evento reservation.confirmed
2. Nel tuo server, ricevi il payload e crea la prenotazione corrispondente nel PMS
3. Utilizza l'endpoint di aggiornamento per sincronizzare eventuali modifiche dal PMS verso Hotely

Integrazione con CRM

Per alimentare il tuo CRM con i dati degli ospiti:

1. Configura webhook per reservation.confirmed e reservation.checked_out
2. Alla conferma, crea o aggiorna il contatto nel CRM con i dati dell'ospite
3. Al check-out, arricchisci il profilo con i dettagli del soggiorno per future campagne di marketing

Integrazione con sistemi di messaggistica

Per inviare notifiche su canali aggiuntivi (WhatsApp, Telegram, SMS):

1. Configura webhook per gli eventi rilevanti
2. Nel tuo server, ricevi l'evento e invia il messaggio tramite l'API del servizio di messaggistica scelto
3. Personalizza il contenuto del messaggio in base al tipo di evento

Integrazione con sistemi contabili

Per automatizzare la registrazione contabile:

1. Configura webhook per payment.received e payment.refunded
2. Alla ricezione del pagamento, crea la registrazione nel tuo software contabile
3. In caso di rimborso, genera la nota di credito corrispondente

Limiti e quote

Supporto tecnico

Per domande tecniche sulle API o assistenza nella costruzione di integrazioni personalizzate, contatta il team di supporto a support@hotely.ai. Includi il nome della proprietà, l'endpoint coinvolto e, se possibile, il payload della richiesta e della risposta per velocizzare la diagnosi.