Richieste e risposte
Questa pagina descrive i formati del corpo della richiesta, l’envelope della risposta, la paginazione, i formati di date e importi e come interpretare i codici di stato HTTP.
Corpo della richiesta#
Gli endpoint usano uno di due formati per il corpo. La pagina di riferimento di ogni endpoint indica quale si applica.
| Formato | Content-Type | Usato da |
|---|---|---|
| Campi form | application/x-www-form-urlencoded o multipart/form-data | Login, elenco camere, convalida dei coupon, paesi |
| JSON | application/json | Invio della prenotazione (BookingPushRQ), avvio del pagamento |
| Query string | — | Tutti gli endpoint GET |
Nei corpi form i campi array si ripetono con le parentesi quadre: childAges[]=7&childAges[]=12. I corpi JSON devono essere in UTF-8.
Envelope della risposta#
Le risposte sono in JSON. La maggior parte contiene un flag success; gli elenchi tornano con count e items:
{
"success": true,
"count": 3,
"items": [
{
"id": 1,
"titleCode": "TRY",
"symbol": "₺",
"price": 1
},
{
"id": 2,
"titleCode": "EUR",
"symbol": "€",
"price": 47.85000000000000142108547152020037174224853515625
}
]
}Se un controllo di logica applicativa non va a buon fine, la risposta contiene success: false e una descrizione dell’errore, in una di queste due forme:
{
"success": false,
"message": "online_cupon_is_not_found"
}{
"success": false,
"errorMessage": "Invalid parameters.",
"errorCode": 10022
}Eccezioni: l’endpoint dei contatti restituisce un oggetto semplice senza envelope, mentre l’invio della prenotazione restituisce un oggetto BookingPushRS. Entrambi sono mostrati nel riferimento API.
Codici di stato HTTP#
| Codice | Quando | Cosa fare |
|---|---|---|
| 200 | Richiesta elaborata (successo o errore di logica applicativa) | Controlla success, message / errorCode. |
| 401 | Token mancante, non valido o sconosciuto | Ripeti il login; vedi Autenticazione. |
| 404 | Un parametro di percorso non corrisponde ad alcun record (ad es. /hotel/{hotelID}/…, /payment/type/{paymentType}) | Controlla l’ID. |
| 405 | Metodo HTTP errato | Usa il metodo indicato nel riferimento API (paesi ed elenco camere sono POST). |
| 500 | Errore imprevisto del server | Riprova dopo una breve attesa; se l’errore persiste, apri un ticket di supporto allegando la richiesta. |
Paginazione#
Gli endpoint che restituiscono elenchi (/external/currencies, /external/languages, /external/online/social/media, /external/stock/packages) sono paginati per numero di pagina:
| Parametro | Descrizione | Predefinito |
|---|---|---|
limit | Record per pagina. | 20 |
page | Numero di pagina, a partire da 1. | 1 |
offset | Record da saltare. Se indicato, page viene ignorato. | — |
order | Campo di ordinamento; anteponi - per l’ordine decrescente (-id). I campi ammessi sono indicati per ogni endpoint. | — |
count è il numero totale di record; l’elenco è terminato quando page × limit ≥ count.
Date, orari e importi#
| Tipo | Formato | Esempio |
|---|---|---|
| Data nella richiesta | YYYY-MM-DD | 2026-08-18 |
| Data di disponibilità | YYYY-MM-DD o YYYY-MM-DDTHH:MM:SS | 2026-08-18T12:00:00 |
| Data della tariffa per notte (risposta) | DD.MM.YYYY (campo tarih) | 18.08.2026 |
| Intervallo giornaliero di disponibilità (risposta) | YYYY-MM-DD HH:MM:SS, dalle 12:00 alle 12:00 del giorno successivo | 2026-08-18 12:00:00 |
| Importo | Stringa con due decimali e punto come separatore | "965.00" |
| Valuta | ISO 4217; dalle impostazioni del canale online dell’hotel | TRY |
| Fuso orario | Il fuso orario dell’hotel | Europe/Istanbul |
La data di check-out non fa parte del soggiorno: dal 18 al 20 agosto sono due notti. Non sommare gli importi con float; usa una libreria decimale o numeri interi nell’unità minima della valuta.
Lingua#
L’elenco camere accetta un campo language (ISO 639-1: tr, en, de…) e restituisce in quella lingua i nomi delle camere, i titoli delle caratteristiche e i messaggi di errore. L’elenco dei pacchetti richiede invece un languageID; gli ID provengono dall’endpoint Lingue.