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 utilizza la tabella StoriaModPrenota per identificare 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 (TIPOPRE.ID_TIPOPRE)
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 per i check-in già effettuati. Ideale per estrarre tutte le prenotazioni di una stagione specifica.

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": "PRE001",
    "description": "GRU001",
    "inHouse": "N",
    "arrivalDate": "2025-07-15",
    "leavingDate": "2025-07-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

La struttura della risposta è identica all'endpoint /reservations. Vedere la documentazione completa per i dettagli sui campi.

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 (tabella StoriaModPrenota)
  • /checkins filtra per data di arrivo/check-in (Tipopre.DtInizio e AlbergDay.DtArrivo)

Entrambi gli endpoint restituiscono 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.

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)