API Integration

Documentazione delle API per l'integrazione con sistemi esterni

Indice

Autenticazione

Autenticazione JWT

Tutte le API (eccetto /login) richiedono un token JWT valido ottenuto tramite l'endpoint di login e il GUID dell'Hotel

Header richiesti:

Authorization: <token>

Il token viene fornito nella risposta dell'endpoint /login e deve essere incluso in tutte le successive richieste.

HOTEL: <guid-hotel>

GUID dell'Hotel ottenuto dal login

POST /ws/integration/login

Login Integrazione

Autentica un utente e restituisce un token JWT per le successive chiamate API. Verifica che l'utente abbia il permesso necessario per l'accesso web.

Request Body

Campo Tipo Obbligatorio Descrizione
code string Sì Codice dell'hotel
username string Sì Nome utente
password string Sì Password dell'utente

Esempio Request

{
  "code": "HOTEL-CODE",
  "username": "user@example.com",
  "password": "mypassword"
}

Response Success (200)

{
  "user": {
    "username": "user@example.com",
    "firstName": "Mario",
    "lastName": "Rossi",
    "email": "user@example.com",
    "operator": "OP001",
    "active": true
  },
  "hotel": {
    "hotelId": "3b3fde9b-943c-44ee-9568-8887aad85d97",
    "hotelCode": "HTL001",
    "workDate": "2025-10-16",
    "company": "Hotel Example S.r.l.",
    "address": "Via Roma, 1",
    "zip": "00100",
    "city": "Roma",
    "province": "RM",
    "vat": "IT12345678901"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Errors

401 Unauthorized Credenziali non valide o utente non attivo

{
  "error": {
    "code": "LOGIN_FAILED",
    "message": "Utente non trovato o non attivo"
  }
}

401 Unauthorized Permesso WEB non disponibile

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Permesso WEB non disponibile per questo utente"
  }
}

503 Service Unavailable Errore di connessione al database

{
  "error": {
    "code": "LOGIN_CONNECTION_FAILED",
    "message": "Connessione al database non riuscita"
  }
}
POST /ws/integration/reservations
🔒 Autenticazione richiesta

Recupero Prenotazioni

Restituisce le prenotazioni modificate in un intervallo di date specificato. Include sia prenotazioni previsionali che confermate (check-in effettuato). La query identifica le prenotazioni modificate nel periodo richiesto.

Request Body

Campo Tipo Obbligatorio Descrizione
startDate string (date) Sì Data inizio periodo (formato ISO: YYYY-MM-DD)
endDate string (date) Sì Data fine periodo (formato ISO: YYYY-MM-DD)

Esempio Request

{
  "startDate": "2025-10-01",
  "endDate": "2025-10-31"
}

Response Success (200)

[
  {
    "id": "PRE001",
    "description": "GRU001",
    "inHouse": "S",
    "arrivalDate": "2025-10-15",
    "leavingDate": "2025-10-20",
    "customerCode": 123,
    "customer": "Mario Rossi",
    "companyCode": 456,
    "company": "Azienda ABC S.r.l.",
    "agencyCode": 789,
    "agency": "Agenzia Viaggi XYZ",
    "marketCode": "ITA",
    "market": "Italia",
    "sourceCode": "WEB",
    "source": "Sito Web",
    "mediaCode": "EMAIL",
    "media": "Email",
    "reasonCode": "VAC",
    "reason": "Vacanza",
    "rooms": [
      {
        "id": "1234",
        "roomCode": "101",
        "roomType": "DBL",
        "arrangement": "BB",
        "amount": 120.00,
        "packageCode": "CONV001",
        "type": "P",
        "allotment": "ALL01",
        "pax": 2,
        "lateCheckout": false
      }
    ]
  }
]

Struttura Dati Response

Campo Tipo Descrizione
id string Codice pratica prenotazione
description string Codice gruppo
inHouse string Stato: 'S' = check-in effettuato, 'N' = previsionale
arrivalDate string Data di arrivo (YYYY-MM-DD)
leavingDate string Data di partenza (YYYY-MM-DD)
customerCode number Codice cliente
customer string Nominativo cliente
companyCode number Codice ditta/azienda
company string Denominazione ditta/azienda
agencyCode number Codice agenzia
agency string Denominazione agenzia
marketCode string Codice mercato (categoria commerciale)
market string Descrizione mercato
sourceCode string Codice sorgente prenotazione
source string Descrizione sorgente
mediaCode string Codice mezzo di comunicazione
media string Descrizione mezzo di comunicazione
reasonCode string Codice provenienza/motivo
reason string Descrizione provenienza/motivo
rooms array Array di camere associate alla prenotazione

Struttura oggetto Room

Campo Tipo Descrizione
id string ID univoco della camera/prenotazione
roomCode string Codice camera
roomType string Tipologia camera (es. DBL, SGL, SUITE)
arrangement string Codice trattamento (es. BB, HB, FB)
amount number Importo in euro
packageCode string Codice convenzione/pacchetto
type string Tipo: 'P' = previsionale, 'C' = confermato
allotment string Codice allotment
pax number Numero persone
lateCheckout boolean Flag late checkout

Response Errors

400 Bad Request Parametri mancanti

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Parametro 'startDate' non specificato"
  }
}

500 Internal Server Error Errore database

{
  "error": {
    "code": "DATABASE_ERROR",
    "message": "Errore nel recupero delle prenotazioni",
    "details": "..."
  }
}
Nota: La query restituisce solo prenotazioni con data di partenza futura rispetto al dataggio corrente dell'hotel. Le prenotazioni vengono raggruppate per codice pratica, con le camere aggregate in un array.
POST /ws/integration/checkins
🔒 Autenticazione richiesta

Recupero Prenotazioni per Check-in

Restituisce le prenotazioni filtrate per data di check-in (arrivo) in un intervallo specificato. A differenza dell'endpoint /reservations che filtra per data di modifica, questo endpoint filtra per data di arrivo effettiva. Supporta sia prenotazioni future che storiche, permettendo di recuperare anche i dati delle stagioni passate. La query combina tre fonti di dati:

Ideale per estrarre tutte le prenotazioni di una stagione specifica, incluse quelle già concluse.

Request Body

Campo Tipo Obbligatorio Descrizione
startDate string (date) Sì Data inizio periodo check-in (formato ISO: YYYY-MM-DD)
endDate string (date) Sì Data fine periodo check-in (formato ISO: YYYY-MM-DD)

Esempio Request

{
  "startDate": "2025-07-01",
  "endDate": "2025-07-31"
}

Questo esempio restituisce tutte le prenotazioni con check-in previsto nel mese di luglio 2025

Response Success (200)

[
  {
    "id": 12345,
    "idUnivoco": "12345_98765PRENO",
    "description": "ROSSI MARIO",
    "inHouse": "S",
    "arrivalDate": "2025-07-15",
    "leavingDate": "2025-07-20",
    "customerCode": 1001,
    "customer": "ROSSI MARIO",
    "customerName": "MARIO",
    "customerSurname": "ROSSI",
    "customerEmail": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
    "customerPhone": "+39 06 12345678",
    "customerMobile": "+39 333 1234567",
    "companyCode": 5001,
    "company": "HOTEL ITALIA S.R.L.",
    "companyEmail": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
    "companyPhone": "+39 06 98765432",
    "companyMobile": "+39 335 9876543",
    "agencyCode": 2001,
    "agency": "AGENZIA VIAGGI MONDO",
    "agencyEmail": "6ca13d52ca70c883e0f0bb101e425a89e8624de51db2d2392593af6a84118090",
    "agencyPhone": "+39 02 11223344",
    "agencyMobile": "+39 348 1122334",
    "marketCode": "100",
    "market": "PUBLIC",
    "sourceCode": "001",
    "source": "DIRETTI",
    "mediaCode": "TEL",
    "media": "TELEFONO",
    "reasonCode": "LEI",
    "reason": "LEISURE",
    "deletionDate": null,
    "cancellationNumber": null,
    "bookingDate": "2025-07-01",
    "rooms": [
      {
        "id": "98765PRENO",
        "roomCode": "201",
        "roomType": "SUI",
        "arrangement": "HB",
        "amount": 180,
        "packageCode": "PACK01",
        "type": "C",
        "allotment": "N",
        "pax": 3,
        "adults": 2,
        "children": 1,
        "babies": 0,
        "infants": 0,
        "lateCheckout": "N"
      },
      {
        "id": "98766PRENO",
        "roomCode": "202",
        "roomType": "DBL",
        "arrangement": "BB",
        "amount": 120,
        "packageCode": "PACK01",
        "type": "C",
        "allotment": "N",
        "pax": 2,
        "adults": 2,
        "children": 0,
        "babies": 0,
        "infants": 0,
        "lateCheckout": "S"
      }
    ]
  },
  {
    "id": 12346,
    "idUnivoco": "12346_98767PRENO",
    "description": "BIANCHI LUCA",
    "inHouse": "N",
    "arrivalDate": "2025-07-18",
    "leavingDate": "2025-07-25",
    "customerCode": 1002,
    "customer": "BIANCHI LUCA",
    "customerName": "LUCA",
    "customerSurname": "BIANCHI",
    "customerEmail": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "customerPhone": "",
    "customerMobile": "+39 340 9876543",
    "companyCode": null,
    "company": null,
    "companyEmail": null,
    "companyPhone": null,
    "companyMobile": null,
    "agencyCode": null,
    "agency": null,
    "agencyEmail": null,
    "agencyPhone": null,
    "agencyMobile": null,
    "marketCode": "201",
    "market": "ONLINE",
    "sourceCode": "002",
    "source": "BOOKING.COM",
    "mediaCode": "WEB",
    "media": "INTERNET",
    "reasonCode": "BUS",
    "reason": "BUSINESS",
    "deletionDate": null,
    "cancellationNumber": null,
    "bookingDate": "2025-07-05",
    "rooms": [
      {
        "id": "98767PRENO",
        "roomCode": "105",
        "roomType": "SUP",
        "arrangement": "BB",
        "amount": 150,
        "packageCode": null,
        "type": "C",
        "allotment": "S",
        "pax": 1,
        "adults": 1,
        "children": 0,
        "babies": 0,
        "infants": 0,
        "lateCheckout": "N"
      }
    ]
  }
]

Struttura Dati Response

Campo Tipo Descrizione
id number Codice pratica prenotazione
idUnivoco string ID univoco della prenotazione (formato: codpratica_idCamera[PRENO])
description string Codice gruppo
inHouse string Stato: 'S' = check-in effettuato, 'N' = previsionale
arrivalDate string Data di arrivo (YYYY-MM-DD)
leavingDate string Data di partenza (YYYY-MM-DD)
customerCode number|null Codice cliente
customer string|null Nominativo completo cliente
customerName string|null Nome del cliente
customerSurname string|null Cognome del cliente
customerEmail string|null Email del cliente (hash SHA-256, lowercase)
customerPhone string|null Numero di telefono del cliente
customerMobile string|null Numero di cellulare del cliente
companyCode number|null Codice ditta/azienda
company string|null Denominazione ditta/azienda
companyEmail string|null Email della ditta (hash SHA-256, lowercase)
companyPhone string|null Numero di telefono della ditta
companyMobile string|null Numero di cellulare della ditta
agencyCode number|null Codice agenzia
agency string|null Denominazione agenzia
agencyEmail string|null Email dell'agenzia (hash SHA-256, lowercase)
agencyPhone string|null Numero di telefono dell'agenzia
agencyMobile string|null Numero di cellulare dell'agenzia
marketCode string|null Codice mercato (categoria commerciale)
market string|null Descrizione mercato
sourceCode string|null Codice sorgente prenotazione
source string|null Descrizione sorgente
mediaCode string|null Codice mezzo di comunicazione
media string|null Descrizione mezzo di comunicazione
reasonCode string|null Codice provenienza/motivo
reason string|null Descrizione provenienza/motivo
deletionDate string|null Data/ora di annullamento della prenotazione (YYYY-MM-DD)
cancellationNumber string|null Numero di cancellazione della prenotazione
bookingDate string|null Data/ora di creazione della prenotazione (YYYY-MM-DD)
rooms array Array di camere associate alla prenotazione

Struttura oggetto Room

Campo Tipo Descrizione
id string ID univoco della camera/prenotazione
roomCode string Codice camera
roomType string Tipologia camera (es. DBL, SGL, SUITE)
arrangement string Codice trattamento (es. BB, HB, FB)
amount number Importo in euro
packageCode string|null Codice convenzione/pacchetto
type string Tipo: 'P' = previsionale, 'C' = confermato
allotment string Codice allotment ('S' = sì, 'N' = no)
pax number Numero totale di persone in camera
adults number Numero di adulti (calcolato: pax - children - babies - infants)
children number Numero di ragazzi
babies number Numero di bambini
infants number Numero di neonati
lateCheckout string Flag late checkout ('S' = sì, 'N' = no)

Response Errors

400 Bad Request Parametri mancanti

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Parametro 'startDate' non specificato"
  }
}

500 Internal Server Error Errore database

{
  "error": {
    "code": "DATABASE_ERROR",
    "message": "Errore nel recupero delle prenotazioni per check-in",
    "details": "..."
  }
}
Differenza con /reservations:
  • /reservations filtra per data di modifica - solo prenotazioni con data di partenza futura
  • /checkins filtra per data di arrivo/check-in - include anche soggiorni storici

Le prenotazioni future e in casa sono filtrate per data di partenza futura rispetto al dataggio corrente dell'hotel, mentre i soggiorni storici sono sempre inclusi se rientrano nel range di date richiesto. Le prenotazioni vengono raggruppate per codice pratica, con le camere aggregate in un array.

Configurazione PAX specifica per MEDITUR:

  • pax: totale persone in camera
  • adults: adulti (calcolato come pax - children - babies - infants)
  • children: ragazzi
  • babies: bambini
  • infants: neonati

Privacy: Gli indirizzi email di cliente, ditta e agenzia sono restituiti come hash SHA-256 in formato lowercase per garantire la conformità GDPR, permettendo comunque di identificare univocamente gli indirizzi senza esporre dati sensibili.

GET /ws/integration/room-types
🔒 Autenticazione richiesta

Tipologie Camera

Restituisce l'elenco delle tipologie di camera disponibili nell'hotel, escludendo quelle estinte. Include informazioni sulla capienza e l'ordinamento.

Request

Questa API non richiede parametri. Includere solo l'header di autenticazione.

Response Success (200)

[
  {
    "code": "DBL",
    "description": "Camera Doppia",
    "numPax": 2,
    "defaultPax": 2,
    "group": "STANDARD",
    "order": 10
  },
  {
    "code": "SGL",
    "description": "Camera Singola",
    "numPax": 1,
    "defaultPax": 1,
    "group": "STANDARD",
    "order": 5
  },
  {
    "code": "SUITE",
    "description": "Suite",
    "numPax": 4,
    "defaultPax": 2,
    "group": "LUXURY",
    "order": 20
  }
]

Struttura Dati Response

Campo Tipo Descrizione
code string Codice tipologia camera
description string Descrizione tipologia
numPax number Numero massimo di persone
defaultPax number Numero di persone predefinito
group string Gruppo tipologia (per raggruppamenti logici)
order number Ordine di assegnazione

Response Errors

500 Internal Server Error Errore database

{
  "error": {
    "code": "DATABASE_ERROR",
    "message": "Errore nel recupero delle tipologie",
    "details": "..."
  }
}
GET /ws/integration/arrangements
🔒 Autenticazione richiesta

Trattamenti

Restituisce l'elenco dei trattamenti disponibili (pensioni/meal plans), escludendo quelli estinti. Include informazioni sui pasti inclusi e validità.

Request

Questa API non richiede parametri. Includere solo l'header di autenticazione.

Response Success (200)

[
  {
    "code": "BB",
    "seasonCode": "ESTATE",
    "description": "Bed & Breakfast",
    "vatCode": "IVA10",
    "breakfast": true,
    "lunch": false,
    "dinner": false,
    "validityDays": 365
  },
  {
    "code": "HB",
    "seasonCode": "ESTATE",
    "description": "Mezza Pensione",
    "vatCode": "IVA10",
    "breakfast": true,
    "lunch": false,
    "dinner": true,
    "validityDays": 365
  },
  {
    "code": "FB",
    "seasonCode": "ESTATE",
    "description": "Pensione Completa",
    "vatCode": "IVA10",
    "breakfast": true,
    "lunch": true,
    "dinner": true,
    "validityDays": 365
  }
]

Struttura Dati Response

Campo Tipo Descrizione
code string Codice trattamento
seasonCode string Codice stagione
description string Descrizione trattamento
vatCode string Codice IVA applicato
breakfast boolean Colazione inclusa
lunch boolean Pranzo incluso
dinner boolean Cena inclusa
validityDays number Giorni di validità del trattamento unico

Response Errors

500 Internal Server Error Errore database

{
  "error": {
    "code": "DATABASE_ERROR",
    "message": "Errore nel recupero dei trattamenti",
    "details": "..."
  }
}

Note Generali

Formato Date

Tutte le date devono essere fornite e vengono restituite nel formato ISO 8601: YYYY-MM-DD

Codici Errore Comuni

Codice Descrizione
LOGIN_FAILED Credenziali non valide o utente non attivo
LOGIN_CONNECTION_FAILED Errore di connessione al database durante il login
PERMISSION_DENIED L'utente non ha i permessi necessari
MISSING_PARAMETER Parametro obbligatorio non fornito
DATABASE_ERROR Errore generico del database

Header HTTP

Header Descrizione
AUTHORIZATION Token JWT ottenuto dal login (obbligatorio per tutti gli endpoint tranne /login)
HOTEL GUID dell'Hotel ottenuto dal login (obbligatorio per tutti gli endpoint tranne /login)