{ "openapi": "3.1.0", "info": { "title": "Nava Hotels API", "version": "1.0.0", "description": "Search, price and book hotels through Nava (nava.travel). Credentials (username, password and microsite id) come from your Nava account manager; there is no self-registration.\n\n## Booking flow\n\nQuote > Quote single (optional) > Confirm > Prebook > Book.\n\n- Every step returns a **new** `combinationKey`. Always send the key from the immediately preceding response.\n- Use **one auth token for the whole flow**, from Quote to Book. A new token mid-flow means starting again from Quote.\n- **Never retry Book or Cancel automatically.** Neither is idempotent: after a timeout, reconcile before you try again.\n- Branch on the Book `status`. A 200 response alone does not mean the room is confirmed.\n\n## Every call\n\n- Send `auth-token` (except on Authenticate) and `Accept-Encoding: gzip`, plus `Content-Type: application/json` with a body.\n- Responses echo your token in `auditData.authToken`. Redact it before you log or store a payload.\n- Log `auditData.traceId` and the `x-request-id` header on every call. The trace id belongs to the token (one per booking flow); `x-request-id` identifies the single request. For calls with no trace id, keep the full request and response for support.\n- No error schema is documented. Treat any non-2xx response as a failure and keep the raw body and the ids.\n\nProperties, parameters and operations marked `x-unverified: true` describe inferred behaviour that has not been verified. Test them with your test account before you rely on them.", "contact": { "name": "Nava", "url": "https://nava.travel" } }, "servers": [ { "url": "https://sandbox.nava.travel/resources", "description": "Test (sandbox). Use your test credentials; the test microsite only has test suppliers." }, { "url": "https://nava.travel/resources", "description": "Production. Use your production credentials, issued after certification." } ], "security": [ { "authToken": [] } ], "tags": [ { "name": "Authentication", "description": "Get the token that every other endpoint needs in the `auth-token` header.", "externalDocs": { "url": "/docs/guides/authentication" } }, { "name": "Booking flow", "description": "Quote, Quote single, Confirm, Prebook and Book. Every step returns a new `combinationKey`, and one token must carry the whole flow.", "externalDocs": { "url": "/docs/guides/booking-flow" } }, { "name": "Post-booking", "description": "Read, refresh, cancel and price the cancellation of a booked hotel, using the trip reference and the hotel's service reference from Book.", "externalDocs": { "url": "/docs/guides/cancellations" } }, { "name": "Bookings", "description": "The generic booking endpoints: read a whole trip, list bookings, cancel a hotel service, refund payments and manage client requests.", "externalDocs": { "url": "/docs/guides/reading-bookings" } }, { "name": "Static content", "description": "The hotel catalogue: accommodation list, datasheets, preferred hotels, facilities, meal plans, destinations and supplier connections. Never a source of prices or availability.", "externalDocs": { "url": "/docs/guides/hotel-catalogue" } } ], "paths": { "/authentication/authenticate": { "post": { "operationId": "authenticate", "tags": [ "Authentication" ], "summary": "Authenticate", "description": "Exchange your API username, password and microsite id for a token that lasts 7200 seconds. Send it in the `auth-token` header on every other call, and use the same token for a whole booking flow.", "externalDocs": { "url": "/docs/api/authenticate" }, "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication" } } } }, "responses": { "200": { "description": "The token and its lifetime.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAuthenticationRS" } } } }, "400": { "description": "Bad request. Observed when `micrositeId` is missing from the body.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/authentication/otp": { "post": { "operationId": "authenticateOtp", "tags": [ "Authentication" ], "summary": "OTP", "description": "Get a single-use token for single sign-on of an existing platform user. It only works with a special API user: ask your Nava account manager for one.", "externalDocs": { "url": "/docs/api/otp" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationOTP" } } } }, "responses": { "200": { "description": "A single-use token, in the same shape as the Authenticate response.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAuthenticationRS" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/accommodations/quote": { "post": { "operationId": "quote", "tags": [ "Booking flow" ], "summary": "Quote", "description": "Use this token for the whole flow through Book. Searches up to 3000 hotel codes or one destination and returns room combinations, each with the `combinationKey` you send to Confirm. Stays are limited to 30 nights. `tripType` and `filter` are optional (defaults `ONLY_HOTEL` and the default filter). Prices, policies and remarks are informational until Confirm.", "externalDocs": { "url": "/docs/api/quote" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationQuoteRequestVO" }, "example": { "checkIn": "2026-11-10", "checkOut": "2026-11-14", "distributions": [ { "persons": [ { "age": 30 }, { "age": 30 } ] } ], "language": "EN", "sourceMarket": "AE", "tripType": "ONLY_HOTEL", "timeout": 8000, "filter": { "bestCombinations": true, "maxCombinations": 4, "includeOnRequestOptions": false }, "destinationId": "MAD" } } } }, "responses": { "200": { "description": "The hotels with availability and their combinations.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationQuoteResponseVO" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/accommodations/{accommodationId}/quote": { "parameters": [ { "$ref": "#/components/parameters/AccommodationId" } ], "post": { "operationId": "quoteSingleAccommodation", "tags": [ "Booking flow" ], "summary": "Quote single", "description": "Never call it in parallel for many hotels: send one Quote with a code list instead. Returns every room combination of one hotel, for a hotel page or when Quote marked the hotel `quoteSingleNeeded`.", "externalDocs": { "url": "/docs/api/quote-single" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationQuoteSingleAccommodationRequestVO" } } } }, "responses": { "200": { "description": "The hotel and all its combinations.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationQuoteSingleAccommodationResponseVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/accommodations/{accommodationId}/confirm": { "parameters": [ { "$ref": "#/components/parameters/AccommodationId" } ], "post": { "operationId": "confirm", "tags": [ "Booking flow" ], "summary": "Confirm", "description": "Send the key from Quote or Quote single and use the **new** key in the response for Prebook. Confirm returns the authoritative price, cancellation policies and remarks, the guest fields Prebook needs, and any `warnings[]`: show those to the guest and get fresh consent.", "externalDocs": { "url": "/docs/api/confirm" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationConfirmRequestVO" }, "example": { "accommodation": { "combinationKey": "157117||14449||RO||d7oNg" } } } } }, "responses": { "200": { "description": "The confirmed offer, with a new `combinationKey` for Prebook.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationConfirmResponseVO" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/accommodations/{accommodationId}/prebook": { "parameters": [ { "$ref": "#/components/parameters/AccommodationId" } ], "post": { "operationId": "prebook", "tags": [ "Booking flow" ], "summary": "Prebook", "description": "Send the rooms in the Quote's order, with the same people and every guest's `requestedAge` equal to the quoted age. Prebook takes the key from Confirm, re-validates the offer with the supplier and returns a new key for Book. Compare price, meal plan and cancellation policies with Confirm before you book.", "externalDocs": { "url": "/docs/api/prebook" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationPrebookRequestVO" }, "example": { "accommodation": { "combinationKey": "", "commentToAccommodation": "Adjoining rooms if possible" }, "distributions": [ { "persons": [ { "name": "Ana", "lastName": "Ruiz", "requestedAge": 30, "courtesyTitle": "MRS", "email": "ana@example.com", "phoneCountryCode": "+34", "phone": "600000000" }, { "name": "Luis", "lastName": "Ruiz", "requestedAge": 30, "courtesyTitle": "MISTER" } ] }, { "persons": [ { "name": "Marta", "lastName": "Gil", "requestedAge": 40, "courtesyTitle": "MS", "email": "marta@example.com" }, { "name": "Leo", "lastName": "Gil", "requestedAge": 5, "courtesyTitle": "MISTER" } ] } ] } } } }, "responses": { "200": { "description": "The re-validated offer, with a new `combinationKey` for Book.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationPreBookResponseVO" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/accommodations/{accommodationId}/book": { "parameters": [ { "$ref": "#/components/parameters/AccommodationId" } ], "post": { "operationId": "book", "tags": [ "Booking flow" ], "summary": "Book", "description": "Never retry Book automatically: it has no idempotency key, and a call that timed out may still have booked. Send the key from Prebook, persist both references from the response at once, and branch on `status`.", "externalDocs": { "url": "/docs/api/book" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationBookRequestVO" }, "example": { "accommodation": { "combinationKey": "" }, "externalReference": "ORDER-8812" } } } }, "responses": { "200": { "description": "The booking. Check `status`: only `BOOKED` means confirmed.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationBookedResponseVO" }, "example": { "auditData": { "processTime": 11230, "authToken": "[REDACTED]", "traceId": "D4AE54C6-…" }, "bookingReference": "TST-1464", "externalReference": "ORDER-8812", "status": "BOOKED", "accommodation": { "code": "MASTER-1782232", "giataId": 1312624, "name": "Cristine Bedfor Mahón", "category": { "code": "S4", "name": "4 STARS" }, "checkIn": "2026-11-10", "checkOut": "2026-11-14", "bookingReference": "TST-1464-0", "status": "BOOKED", "combination": { "rooms": [ { "description": "Garden room" } ], "mealPlan": { "id": "BH", "type": "HALF_BOARD" }, "onRequest": false, "price": { "amount": 134.05, "currency": "EUR" } } }, "distributions": [ { "id": "TST-1464-0", "person": [ { "id": "TST-1464-0-0", "name": "Ana", "lastName": "Ruiz", "requestedAge": 34 }, { "id": "TST-1464-0-1", "name": "Luis", "lastName": "Ruiz", "requestedAge": 36 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/accommodations/{accommodationBookingReference}": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" }, { "$ref": "#/components/parameters/AccommodationBookingReference" } ], "get": { "operationId": "getAccommodationBookedDetail", "tags": [ "Post-booking" ], "summary": "Booking detail", "description": "Reads stored data only, with no supplier call, so use it for routine polling of `RQ` and `PENDING_BOOK` bookings. It returns your `externalReference` under that name. A `fakeBooking` booking is never saved, so it returns 404 here.", "externalDocs": { "url": "/docs/api/booking-detail" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "The booked hotel, in the Book response shape.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationBookedResponseVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "refresh", "tags": [ "Post-booking" ], "summary": "Refresh", "description": "Refresh calls the supplier and returns the status it reports, for example to resolve `RQ`: unchanged if nothing changed at the supplier, and 406 if the supplier doesn't support refreshing. Use Booking detail for routine polling. Some test suppliers answer every Refresh with `CANCELED`; real suppliers don't.", "externalDocs": { "url": "/docs/api/refresh" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "The booked hotel with the status the supplier reported, in the Book response shape.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationBookedResponseVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "description": "The supplier doesn't support refreshing. Don't retry; read Booking detail instead." }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "cancel", "tags": [ "Post-booking" ], "summary": "Cancel", "description": "Never retry Cancel automatically: it is not safely retryable, so after a timeout read Booking detail first. Cancels the hotel at the supplier and returns the booking with `status: CANCELED`; it does not refund the guest.", "externalDocs": { "url": "/docs/api/cancel" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "The booking in the Book response shape. `CANCELED` at both levels on success.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAccommodationBookedResponseVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/accommodations/{accommodationBookingReference}/cancellation-fee": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" }, { "$ref": "#/components/parameters/AccommodationBookingReference" } ], "get": { "operationId": "getCancellationFee", "tags": [ "Post-booking" ], "summary": "Cancellation fee", "description": "A read-only quote: it cancels nothing and refunds nothing. Returns the penalty if you cancelled the booked hotel today.", "externalDocs": { "url": "/docs/api/cancellation-fee" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "The fee for cancelling today.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiBookCancellationFeeResponseVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/getBookings/{micrositeId}/{bookingReference}": { "parameters": [ { "name": "micrositeId", "in": "path", "required": true, "description": "The microsite the booking was made on. On a 404, try your other microsites. Don't rely on a mismatched microsite resolving the booking: that has worked in the past and is expected to stop.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/BookingReference" } ], "get": { "operationId": "getBookings", "tags": [ "Bookings" ], "summary": "Get booking", "description": "The webhook is a signal and this is the truth: read the whole trip here after every webhook. The hotel is in `hotelservice[]`, and a 404 means the reference does not exist in this microsite.", "externalDocs": { "url": "/docs/api/get-booking" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "The whole trip.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookedTripVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/bookings": { "get": { "operationId": "bookings", "tags": [ "Bookings" ], "summary": "List bookings", "description": "Strictly scoped to one microsite and bounded by **creation** date (`from` and `to` are required). Returns each booking's reference, status, creation date and microsite, 100 per page, with no status or channel filter. The older listing variant of `getBookings` is deprecated.", "externalDocs": { "url": "/docs/api/list-bookings" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "name": "operator", "in": "query", "description": "Operator filter. Send this or `microsite`; with neither, the call fails with 400 `Microsite or operator is required`.", "schema": { "type": "string" } }, { "name": "microsite", "in": "query", "description": "The microsite to list. Send this or `operator`; with neither, the call fails with 400.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "First **creation** date, `yyyyMMdd`, for example `20261110`.", "schema": { "type": "string", "pattern": "^[0-9]{8}$" } }, { "name": "to", "in": "query", "required": true, "description": "Last **creation** date, `yyyyMMdd`.", "schema": { "type": "string", "pattern": "^[0-9]{8}$" } }, { "name": "fromtime", "in": "query", "description": "Time of day for the start of the creation window, `HH:mm:ss`.", "schema": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}:[0-9]{2}$" } }, { "name": "totime", "in": "query", "description": "Time of day for the end of the creation window, `HH:mm:ss`.", "schema": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}:[0-9]{2}$" } }, { "name": "fromDepartureDate", "in": "query", "description": "Start of a departure date range. The format is not documented.", "schema": { "type": "string" } }, { "name": "toDepartureDate", "in": "query", "description": "End of the departure date range. The format is not documented.", "schema": { "type": "string" } }, { "name": "ufrom", "in": "query", "description": "Start of a last-update date range. The format is not documented.", "schema": { "type": "string" } }, { "name": "uto", "in": "query", "description": "End of the last-update date range. The format is not documented.", "schema": { "type": "string" } }, { "name": "cfrom", "in": "query", "description": "Start of a cancellation date range. The format is not documented.", "schema": { "type": "string" } }, { "name": "cto", "in": "query", "description": "End of the cancellation date range. The format is not documented.", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "description": "One reference: a booking reference, a provider reference, an order number, a deferred order number or a PNR. Your `externalReference` is not searchable.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "Offset of the first result, for paging.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Page size. Pages of 100 results have been observed.", "schema": { "type": "integer" } }, { "name": "username", "in": "query", "description": "Only bookings made by this user, for example your API user.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of booking references.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingsVO" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/{serviceType}/{serviceId}/cancel": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" }, { "$ref": "#/components/parameters/ServiceType" }, { "$ref": "#/components/parameters/ServiceId" } ], "put": { "operationId": "cancelService", "tags": [ "Bookings" ], "summary": "Cancel service", "description": "Never retry it automatically: after a timeout, read the trip with Get booking first. The generic cancel for a hotel service (`serviceType` `HOTEL`), with `cancellationType` `PROVIDER` or `MANUAL` and optional manual fees.", "externalDocs": { "url": "/docs/api/cancel-service" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBookingRequestVO" } } } }, "responses": { "200": { "description": "The result of the cancellation.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBookingResponseVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/{serviceType}/{serviceId}/cancellation-fee": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" }, { "$ref": "#/components/parameters/ServiceType" }, { "$ref": "#/components/parameters/ServiceId" } ], "get": { "operationId": "getServiceCancellationFee", "tags": [ "Bookings" ], "summary": "Service cancellation fee", "description": "Call it before Cancel service, with the same path values. Returns the fee for a hotel service, the cancellation types the service supports, and any related service with its own fee.", "externalDocs": { "url": "/docs/api/service-cancellation-fee" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "The fee and the supported cancellation types.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationFeeResponseVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/refund": { "post": { "operationId": "refund", "tags": [ "Bookings" ], "summary": "Refund", "description": "A refund is money only: it does not cancel any service. Refunds a payment through the original payment gateway, or registers a refund handled outside the platform, and fires a `REFUND` webhook on success.", "externalDocs": { "url": "/docs/api/refund" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } } }, "responses": { "200": { "description": "The refund and the payment's refund status.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/client-requests": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" } ], "post": { "operationId": "createClientRequest", "tags": [ "Bookings" ], "summary": "Create a client request", "description": "A client request is a conversation, not a change: it changes no booking data, and a `CANCELLATION` request cancels nothing. Creating one fires a `CLIENT_REQUEST` webhook.", "externalDocs": { "url": "/docs/api/client-requests" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestVO" } } } }, "responses": { "200": { "description": "The new request. Keep its `id`.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/client-requests/{clientRequestId}/reply": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" }, { "$ref": "#/components/parameters/ClientRequestId" } ], "post": { "operationId": "replyClientRequest", "tags": [ "Bookings" ], "summary": "Reply to a client request", "description": "Adds a message to a client request's thread. A reply fires a `CLIENT_REQUEST` webhook.", "externalDocs": { "url": "/docs/api/client-requests" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestReply" } } } }, "responses": { "200": { "description": "The updated request.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/client-requests/{clientRequestId}/open": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" }, { "$ref": "#/components/parameters/ClientRequestId" } ], "put": { "operationId": "openClientRequest", "tags": [ "Bookings" ], "summary": "Reopen a client request", "description": "Reopens a client request. There is no request body.", "externalDocs": { "url": "/docs/api/client-requests" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "The updated request.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/booking/{bookingReference}/client-requests/{clientRequestId}/close": { "parameters": [ { "$ref": "#/components/parameters/BookingReference" }, { "$ref": "#/components/parameters/ClientRequestId" } ], "put": { "operationId": "closeClientRequest", "tags": [ "Bookings" ], "summary": "Close a client request", "description": "Closes a client request. There is no request body.", "externalDocs": { "url": "/docs/api/client-requests" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "The updated request.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accommodations": { "get": { "operationId": "getAccommodations", "tags": [ "Static content" ], "summary": "Accommodation list", "description": "Download the list weekly and fetch a datasheet again only when its `lastUpdate` changed; never take prices from it. Pages through every hotel your microsite can sell, up to 20000 per page.", "externalDocs": { "url": "/docs/api/accommodations" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "name": "first", "in": "query", "required": true, "description": "Offset of the first result. Start at `0` and add `limit` for each page.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": true, "description": "Page size, at most `20000`.", "schema": { "type": "integer", "maximum": 20000 } } ], "responses": { "200": { "description": "One page of hotels.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiStaticContentAccommodationsVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accommodations/{accommodationId}/datasheet": { "parameters": [ { "$ref": "#/components/parameters/AccommodationId" } ], "get": { "operationId": "getAccommodationDatasheet", "tags": [ "Static content" ], "summary": "Datasheet", "description": "Static content only, never prices or availability. Returns the full datasheet of one hotel: images, facilities, description, ratings and category.", "externalDocs": { "url": "/docs/api/datasheets" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "One datasheet.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiStaticContentAccommodationDataSheetVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accommodations/datasheet": { "get": { "operationId": "getAccommodationDatasheets", "tags": [ "Static content" ], "summary": "Datasheets", "description": "Up to 100 hotels per call: repeat `accommodationId` once per hotel and never comma-join the ids. Returns the datasheets of those hotels.", "externalDocs": { "url": "/docs/api/datasheets" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "name": "accommodationId", "in": "query", "required": true, "description": "Hotel codes, one parameter per hotel: `?accommodationId=1000&accommodationId=MASTER-1782232`. At most 100.", "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 100, "items": { "type": "string" } } }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "The datasheets.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiStaticContentAccommodationsDataSheetVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/accommodations/preferred/{micrositeId}": { "parameters": [ { "$ref": "#/components/parameters/MicrositeId" } ], "get": { "operationId": "getPreferredAccommodations", "tags": [ "Static content" ], "summary": "Preferred hotels", "description": "Static content only: quote the hotels before you show a price. Returns the hotels your microsite promotes, as full datasheets.", "externalDocs": { "url": "/docs/api/preferred" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "name": "destinationId", "in": "query", "description": "A destination code, for example `MAD`.", "schema": { "type": "string" } }, { "name": "countryCode", "in": "query", "description": "A country code, for example `ES`.", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "Offset of the first result.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Maximum number of hotels to return.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "The promoted hotels.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetHotelRS" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/facilites/accommodation": { "get": { "operationId": "getAccommodationFacilities", "tags": [ "Static content" ], "summary": "Accommodation facilities", "description": "The path is spelled `facilites` (sic) and `lang` is required. Returns the hotel facility catalogue, with icon classes, priorities and translated labels.", "externalDocs": { "url": "/docs/api/facilities" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "$ref": "#/components/parameters/LangRequired" } ], "responses": { "200": { "description": "Every hotel facility.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccommodationFacilityListVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/facilites/room": { "get": { "operationId": "getRoomFacilities", "tags": [ "Static content" ], "summary": "Room facilities", "description": "The path is spelled `facilites` (sic) and `lang` is required. Returns the room facility catalogue; each facility also has a `category`.", "externalDocs": { "url": "/docs/api/facilities" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "$ref": "#/components/parameters/LangRequired" } ], "responses": { "200": { "description": "Every room facility.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomFacilityListVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/mealplan/{micrositeId}": { "parameters": [ { "$ref": "#/components/parameters/MicrositeId" } ], "get": { "operationId": "getMealPlans", "tags": [ "Static content" ], "summary": "Meal plans", "description": "Show guests the `description`, not the `type`: mixed plans collapse to the nearest type. Returns the meal plans configured on your microsite, to label the `mealPlan.id` codes from Quote.", "externalDocs": { "url": "/docs/api/meal-plans" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "The microsite's meal plans.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMealPlanRS" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/destination/{micrositeId}": { "parameters": [ { "$ref": "#/components/parameters/MicrositeId" } ], "get": { "operationId": "getDestinations", "tags": [ "Static content" ], "summary": "List destinations", "description": "A destination's `code` is exactly what Quote expects in `destinationId`. Lists the destinations of your microsite, optionally by country or airport.", "externalDocs": { "url": "/docs/api/destinations" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "name": "countryCode", "in": "query", "description": "Country code, for example `ES`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Lang" }, { "name": "iata", "in": "query", "description": "Airport code, for example `MAD`, for an airport-based search.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The destinations.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDestinationRS" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/destination/{micrositeId}/{destinationId}": { "parameters": [ { "$ref": "#/components/parameters/MicrositeId" }, { "name": "destinationId", "in": "path", "required": true, "description": "Destination code, for example `MAD`.", "schema": { "type": "string" } } ], "get": { "operationId": "getDestination", "tags": [ "Static content" ], "summary": "Get a destination", "description": "Returns one destination with the same fields as the list, plus its `description`.", "externalDocs": { "url": "/docs/api/destinations" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "The destination.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationVO" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/destination/countries/{micrositeId}": { "parameters": [ { "$ref": "#/components/parameters/MicrositeId" } ], "get": { "operationId": "getCountries", "tags": [ "Static content" ], "summary": "List countries", "description": "Returns the countries of your microsite, each with an `id` and a `name`.", "externalDocs": { "url": "/docs/api/destinations" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "The countries.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCountryRS" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/providers/configurations/{micrositeId}": { "parameters": [ { "$ref": "#/components/parameters/MicrositeId" } ], "get": { "operationId": "getProviderConfigurations", "tags": [ "Static content" ], "summary": "Provider configurations", "description": "Check it first when a destination or hotel search returns nothing. Lists the supplier connections on your microsite; the body is a bare array with no `auditData` and there is no `Travelc-Trace-Id` header, so log the `x-request-id` header and keep the full request and response for support.", "externalDocs": { "url": "/docs/api/provider-configurations" }, "parameters": [ { "$ref": "#/components/parameters/AcceptEncoding" } ], "responses": { "200": { "description": "One entry per supplier connection.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderConfigurationVO" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "authToken": { "type": "apiKey", "in": "header", "name": "auth-token", "description": "The `token` from `POST /authentication/authenticate`, sent in the custom `auth-token` header (not `Authorization: Bearer`). It lasts 7200 seconds. Use the same token for a whole booking flow, from Quote to Book, and start a flow only when it has at least 60 minutes left. Static content calls accept any valid token." } }, "parameters": { "AcceptEncoding": { "name": "Accept-Encoding", "in": "header", "required": true, "description": "Always `gzip`. The API may reject requests without it.", "schema": { "type": "string", "const": "gzip" } }, "AccommodationId": { "name": "accommodationId", "in": "path", "required": true, "description": "Hotel code, for example `MASTER-1782232` or `157117`. In the booking flow, use the `code` from the Quote response.", "schema": { "type": "string" } }, "BookingReference": { "name": "bookingReference", "in": "path", "required": true, "description": "Trip reference from the Book response, for example `TST-1464`.", "schema": { "type": "string" } }, "AccommodationBookingReference": { "name": "accommodationBookingReference", "in": "path", "required": true, "description": "Service reference from the Book response (`accommodation.bookingReference`), for example `TST-1464-0`; in Get booking it is `hotelservice[].id`. The supplier's reference (`hotelservice[].bookingReference`) is accepted too.", "schema": { "type": "string" } }, "MicrositeId": { "name": "micrositeId", "in": "path", "required": true, "description": "Your microsite id, from your credentials. Test and production accounts have different microsite ids.", "schema": { "type": "string" } }, "ServiceType": { "name": "serviceType", "in": "path", "required": true, "description": "The service type. Send `HOTEL`.", "schema": { "$ref": "#/components/schemas/ServiceType" } }, "ServiceId": { "name": "serviceId", "in": "path", "required": true, "description": "The service's id. Unverified: probably `hotelservice[].id` from Get booking (the same value as Book's `accommodation.bookingReference`). These generic endpoints need an API user enabled for the Booking API; otherwise they return 401 `not allowed to access here`.", "x-unverified": true, "schema": { "type": "string" } }, "ClientRequestId": { "name": "clientRequestId", "in": "path", "required": true, "description": "The client request's `id`.", "schema": { "type": "string" } }, "Lang": { "name": "lang", "in": "query", "description": "Language of the text fields, for example `EN`.", "schema": { "$ref": "#/components/schemas/Language" } }, "LangRequired": { "name": "lang", "in": "query", "required": true, "description": "Language of the labels, for example `EN`.", "schema": { "$ref": "#/components/schemas/Language" } } }, "headers": { "TravelcTraceId": { "description": "The trace id of the token: the same value as `auditData.traceId`, and the same on every call made with one token. Sent on authenticate (where it is the new token's trace id) and on the POST, PUT and DELETE booking calls, error responses included. Not sent on the GET calls tested (static content, booking detail, Get booking, cancellation fee, bookings listing).", "schema": { "type": "string" } }, "XRequestId": { "description": "A per-request id, sent on every response tested and different on every call. Log it next to the trace id. On responses with neither `auditData` nor `Travelc-Trace-Id` (meal plans, facilities, provider configurations, bookings listing), keep the full request and response for support as well.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "The request failed validation. Schema validation runs before the permission check, so a malformed request gets 400 even from an account that can't call the endpoint; `error` names the failing field as a path and the body has no `auditData`. Business rules checked later (for example `You cannot select more than 30 nights`, or a missing guest field at Prebook) also return 400, with `auditData`. Some messages include internal class names and the values you sent: log them, don't show them to guests.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" }, "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "schemaValidation": { "summary": "Schema validation (no auditData)", "value": { "error": [ "quote.request.quote.stay.checkIn: must not be null" ], "status": "BAD_REQUEST" } }, "businessRule": { "summary": "Business rule (with auditData)", "value": { "auditData": { "authToken": "[REDACTED]", "traceId": "5B0C2E71-0D8E-4C1A-9F3E-2A6C1D7B4E90" }, "error": [ "You cannot select more than 30 nights" ], "status": "BAD_REQUEST" } } } } } }, "Unauthorized": { "description": "On authenticate, `User not authorized to access`: the credentials were rejected. A wrong password and a deleted API user return the same body, and a sudden 401 on every call usually means the API user was deleted or its password rotated: alert a person instead of retrying. On any other call, `User … not allowed to access here`: the token is valid but the account isn't enabled for this endpoint in this environment. A new token won't help.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" }, "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "credentialsRejected": { "summary": "Authenticate with wrong credentials", "value": { "error": [ "User not authorized to access" ], "status": "UNAUTHORIZED" } }, "endpointNotEnabled": { "summary": "Valid token, endpoint not enabled for the account", "value": { "error": [ "User not allowed to access here" ], "status": "UNAUTHORIZED" } } } } } }, "NotFound": { "description": "The reference does not exist (in this microsite). It is not an outage: check both references and the credentials' microsite.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" }, "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "auditData": { "authToken": "[REDACTED]", "traceId": "…" }, "error": [ "Booking reference not found" ], "status": "NOT_FOUND" } } } }, "Error": { "description": "Any other non-2xx response. No error schema or status codes are documented: treat it as a failure, and keep the raw body, the trace id (`auditData.traceId` or the `Travelc-Trace-Id` header, when present) and the `x-request-id` header for support.", "headers": { "Travelc-Trace-Id": { "$ref": "#/components/headers/TravelcTraceId" }, "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "description": "Undocumented. The 400, 401 and 404 bodies seen so far have the `ErrorResponse` shape; other errors may differ." } } } } }, "schemas": { "AuditResponseVO": { "type": "object", "description": "Returned as `auditData` on most responses. It identifies the token's calls for support and echoes your live token. Not returned by authenticate, meal plans, facilities, provider configurations, the bookings listing, schema-validation 400s or 401s. Business-rule 400s and 404s do carry it.", "properties": { "timestamp": { "type": "string", "description": "Server time. The spec types it as date-time; the documented value looks like `2022-11-15 09:05:14`." }, "processTime": { "type": "integer", "format": "int64", "description": "Processing time in milliseconds." }, "authToken": { "type": "string", "description": "**Your live token.** Redact it before you log or store a payload." }, "traceId": { "type": "string", "description": "The trace id of your token: every call made with the same token returns the same value, so it names a booking flow rather than one call. Log it on every call with the `x-request-id` header, which names the single request." }, "availabilityId": { "type": "integer", "format": "int32", "description": "Ties the calls of one quote flow together." }, "server": { "type": "string", "description": "The server that handled the call." } } }, "ErrorResponse": { "type": "object", "description": "The body seen on 400, 401 and 404 responses. Schema-validation 400s and 401s have no `auditData`; business-rule 400s and 404s include it. No error schema is documented.", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "error": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } }, "MoneyVO": { "type": "object", "description": "An amount with its currency.", "properties": { "amount": { "type": "number", "format": "double" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 code, for example `EUR`. The spec enumerates 167 currencies. Booking flow prices are always in the microsite currency." } } }, "MoneyAmountVO": { "type": "object", "description": "The same amount in the microsite currency and in the operator currency.", "properties": { "microsite": { "$ref": "#/components/schemas/MoneyVO" }, "operator": { "$ref": "#/components/schemas/MoneyVO" } } }, "GeolocationVO": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } }, "PaginationVO": { "type": "object", "description": "Where a page sits in the full list. Stop paging when `firstResult + pageResults` reaches `totalResults`, or a page comes back empty.", "properties": { "firstResult": { "type": "integer", "description": "Offset of this page." }, "pageResults": { "type": "integer", "description": "Number of items on this page." }, "totalResults": { "type": "integer", "description": "Number of items in the whole list." } } }, "MealPlanVO": { "type": "object", "description": "A meal plan. Show `description` to guests, because mixed plans collapse to one `type`.", "properties": { "id": { "type": "string", "description": "Provider or microsite code, for example `RO` or `BH`." }, "type": { "$ref": "#/components/schemas/MealPlanType" }, "description": { "type": "string", "description": "The label to show, for example `1 BED AND BREAKFAST + 1 HALF BOARD`." }, "providerDescription": { "type": "string", "description": "The supplier's own wording." } } }, "CancellationPolicyVO": { "type": "object", "description": "One step of a cancellation policy: from `date` on, cancelling costs `amount`. A policy is a list of cumulative steps; a `0` step means free until the next step's date, and the last step is usually the full price.", "properties": { "date": { "type": "string", "format": "date", "description": "From this date on, the step applies." }, "amount": { "$ref": "#/components/schemas/MoneyVO", "description": "The penalty from `date` on." }, "netPrice": { "description": "Net price." }, "nonCommissionableAmount": { "description": "Non-commissionable amount." }, "commissionPriceAmount": { "description": "Commission amount." }, "policyAmount": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "The penalty in the microsite and operator currencies." } } }, "CancellationTypeVO": { "type": "object", "description": "One-line summary of a combination's cancellation policy, returned as `currentCancellationType`. Only present in quote responses.", "properties": { "deadline": { "type": "string", "format": "date", "description": "For `REFUNDABLE`, free cancellation ends on this date." }, "type": { "$ref": "#/components/schemas/CancellationPolicyType" } } }, "WarningVO": { "type": "object", "description": "A change since the previous step. Show it to the guest and get fresh consent.", "properties": { "type": { "$ref": "#/components/schemas/WarningType" }, "description": { "type": "string", "description": "For example `Price has changed`." } } }, "BookingFlowCategory": { "type": "object", "description": "The hotel category as the booking flow returns it: an object. Datasheets return a plain `HotelCategory` string instead, so normalise both.", "properties": { "code": { "$ref": "#/components/schemas/HotelCategory" }, "name": { "type": "string", "description": "For example `4 STARS` or `0 KEYS`." } } }, "ApiAccommodationRoomVO": { "type": "object", "description": "One room of a combination.", "properties": { "description": { "type": "string", "description": "For example `Studio (2 adults)`." }, "groupingRoomType": { "description": "Room type for grouping combinations by room." } } }, "CombinationPriceBreakdown": { "type": "object", "description": "Price breakdown of a combination.", "properties": { "agencyFee": { "$ref": "#/components/schemas/MoneyVO" }, "rsp": { "type": "object", "description": "Recommended selling price.", "properties": { "applied": { "type": "boolean" }, "price": { "$ref": "#/components/schemas/MoneyVO" } } } } }, "CombinationOffer": { "type": "object", "description": "Only populated when the supplier sends an offer. Don't depend on it.", "properties": { "strikethroughPrice": { "$ref": "#/components/schemas/MoneyVO" } } }, "FakeBooking": { "type": "object", "description": "Testing only. Forces the outcome: the response is HTTP 200 with the requested status, and references like `FAKE-1043` and `FAKE-ACCOMMODATION-1043`. A fake booking is **not persisted and not sent to suppliers, even in production**: Booking detail returns 404 for it.", "properties": { "status": { "$ref": "#/components/schemas/ServiceStatus", "description": "`BOOKED` or `BOOK_ERROR`." } } }, "Authentication": { "type": "object", "required": [ "username", "password", "micrositeId" ], "properties": { "username": { "type": "string", "description": "Your API username, from your Nava account manager." }, "password": { "type": "string", "description": "Its password. Read it from an environment variable or a secret store, never from code." }, "micrositeId": { "type": "string", "description": "Your microsite id. A missing `micrositeId` returns 400." } } }, "AuthenticationOTP": { "type": "object", "required": [ "userName", "micrositeId" ], "properties": { "userName": { "type": "string", "description": "The existing platform user to sign in. Mind the capital N; Authenticate uses `username`." }, "micrositeId": { "type": "string", "description": "The microsite id." } } }, "GetAuthenticationRS": { "type": "object", "properties": { "token": { "type": "string", "description": "A JWT. Send it as the `auth-token` header. From OTP, a single-use token for single sign-on." }, "expirationInSeconds": { "type": "integer", "format": "int64", "description": "Token lifetime in seconds. `7200` for Authenticate." } } }, "ApiBookDistributionRequestVO": { "type": "object", "description": "One room in a quote request.", "required": [ "persons" ], "properties": { "persons": { "type": "array", "minItems": 1, "maxItems": 6, "description": "The people in the room: 1 to 6, children included (enforced with 400). At least one adult and at most 5 children, per the docs; those two rules are not checked when the request arrives. At most 15 people per booking.", "items": { "type": "object", "required": [ "age" ], "properties": { "age": { "type": "integer", "format": "int32", "description": "Each guest's age **at checkout**. Children are 0-17. Prebook's `requestedAge` must equal it." } } } } } }, "ApiAccommodationQuoteFilterRequestVO": { "type": "object", "description": "Optional, and so is every field inside it. Leave it out to get the defaults.", "properties": { "bestCombinations": { "type": "boolean", "default": true, "description": "`true`: only the best combination for each available meal plan and refundability. `false`: all combinations." }, "maxCombinations": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Combinations per hotel, enforced with 400. Defaults to `1` when `bestCombinations` is `true` and `60` when it is `false`." }, "includeOnRequestOptions": { "type": "boolean", "default": true, "description": "`false` removes on-request combinations." } } }, "ApiAccommodationQuoteRequestVO": { "type": "object", "description": "Send exactly one of `accommodations` and `destinationId`.", "required": [ "checkIn", "checkOut", "distributions" ], "properties": { "checkIn": { "type": "string", "format": "date", "description": "Check-in date, `yyyy-MM-dd`." }, "checkOut": { "type": "string", "format": "date", "description": "Check-out date, `yyyy-MM-dd`. At most 30 nights after `checkIn` (checkOut minus checkIn); a longer stay gets 400 `You cannot select more than 30 nights`. Suppliers may add their own restrictions." }, "distributions": { "type": "array", "minItems": 1, "maxItems": 4, "description": "One entry per room, 1 to 4 rooms (enforced with 400).", "items": { "$ref": "#/components/schemas/ApiBookDistributionRequestVO" } }, "language": { "$ref": "#/components/schemas/Language" }, "sourceMarket": { "type": "string", "description": "ISO 3166-1 alpha-2 code of the customer's market or nationality, for example `ES`. Drives market-specific rates." }, "tripType": { "$ref": "#/components/schemas/TripType", "description": "Optional; defaults to `ONLY_HOTEL`. An unknown value gets 400." }, "timeout": { "type": [ "integer", "null" ], "format": "int32", "minimum": 3000, "description": "Maximum wait for supplier availability, in milliseconds. Below 3000 gets 400. Send `null` or leave it out to use the account's default. The whole call can take longer, so set your HTTP timeout well above it." }, "accommodations": { "type": "array", "maxItems": 3000, "uniqueItems": true, "description": "Hotel codes within about 200 km of each other. More than 3000 gets 400. Deduplicate before sending. Send this **or** `destinationId`, never both; sending both is not rejected up front.", "items": { "type": "string" } }, "destinationId": { "type": "string", "description": "A destination code such as `MAD`, from List destinations. Send this **or** `accommodations`." }, "filter": { "$ref": "#/components/schemas/ApiAccommodationQuoteFilterRequestVO" } } }, "ProviderTraceVO": { "type": "object", "description": "Per-supplier timing and errors. Check it when results are empty.", "properties": { "provider": { "description": "The supplier." }, "providerDescription": { "description": "The supplier's description." }, "start": { "description": "When the supplier call started." }, "end": { "description": "When the supplier call ended." }, "processTime": { "description": "Time the supplier took." }, "error": { "description": "The supplier's error, if any." }, "quoteResults": { "description": "The supplier's results." } } }, "ApiAccommodationQuoteCombinationVO": { "type": "object", "description": "One bookable offer from Quote.", "properties": { "combinationKey": { "type": "string", "description": "Send it to Confirm. Opaque and unbounded: a short string such as `157117||14449||RO||d7oNg` or a signed JWT. Keep it server-side (sample keys decode to net prices) and never persist it long term. It expires 40 minutes after the Quote response." }, "rooms": { "type": "array", "description": "One entry per requested room.", "items": { "$ref": "#/components/schemas/ApiAccommodationRoomVO" } }, "mealPlan": { "$ref": "#/components/schemas/MealPlanVO" }, "onRequest": { "type": "boolean", "description": "`true`: only on-request quota exists, so the supplier has to accept. Always `false` when `includeOnRequestOptions` is `false`." }, "price": { "$ref": "#/components/schemas/MoneyVO", "description": "Always in the microsite currency. Informational until Confirm." }, "provider": { "type": "string", "description": "The supplier, for example `Expedia`." }, "recommendedSellingPrice": { "$ref": "#/components/schemas/MoneyVO", "description": "Only when the microsite or provider supplies one. Don't depend on it." }, "priceBreakdown": { "$ref": "#/components/schemas/CombinationPriceBreakdown" }, "offer": { "$ref": "#/components/schemas/CombinationOffer" }, "cancellationPolicies": { "type": "array", "description": "Penalty steps. Informational until Confirm.", "items": { "$ref": "#/components/schemas/CancellationPolicyVO" } }, "remarks": { "type": "array", "description": "Supplier remarks. Informational until Confirm.", "items": { "type": "string" } }, "currentCancellationType": { "$ref": "#/components/schemas/CancellationTypeVO" } } }, "ApiAccommodationQuoteAccommodationsVO": { "type": "object", "description": "One hotel with availability.", "properties": { "code": { "type": "string", "description": "Hotel code. Use it as `accommodationId` in the next steps." }, "quoteSingleNeeded": { "type": "boolean", "description": "`true`: a supplier returned a partial set. The combinations you have are bookable; call Quote single to see the rest." }, "combinations": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccommodationQuoteCombinationVO" } } } }, "ApiAccommodationQuoteResponseVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "total": { "type": "integer", "description": "Number of hotels returned." }, "accommodations": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccommodationQuoteAccommodationsVO" } }, "providerTraces": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderTraceVO" } } } }, "ApiAccommodationQuoteSingleAccommodationRequestVO": { "type": "object", "description": "The Quote body without `accommodations` or `destinationId`; the hotel is in the path.", "required": [ "checkIn", "checkOut", "distributions" ], "properties": { "checkIn": { "type": "string", "format": "date", "description": "Check-in date, `yyyy-MM-dd`." }, "checkOut": { "type": "string", "format": "date", "description": "Check-out date, `yyyy-MM-dd`. At most 30 nights after `checkIn` (checkOut minus checkIn); a longer stay gets 400 `You cannot select more than 30 nights`. Suppliers may add their own restrictions." }, "distributions": { "type": "array", "minItems": 1, "maxItems": 4, "description": "One entry per room, 1 to 4 rooms (enforced with 400).", "items": { "$ref": "#/components/schemas/ApiBookDistributionRequestVO" } }, "language": { "$ref": "#/components/schemas/Language" }, "sourceMarket": { "type": "string", "description": "ISO 3166-1 alpha-2 code of the customer's market or nationality." }, "tripType": { "$ref": "#/components/schemas/TripType", "description": "Optional; defaults to `ONLY_HOTEL`." }, "timeout": { "type": [ "integer", "null" ], "format": "int32", "minimum": 3000, "description": "Maximum wait for supplier availability, in milliseconds. `null` or omitted uses the account's default." }, "filter": { "type": "object", "description": "Only one field. You always get every combination.", "properties": { "includeOnRequestOptions": { "type": "boolean", "default": true, "description": "`false` removes on-request combinations." } } } } }, "ApiAccommodationQuoteSingleCombinationVO": { "type": "object", "description": "One bookable offer from Quote single. The same fields as a Quote combination, without `remarks`.", "properties": { "combinationKey": { "type": "string", "description": "Send it to Confirm. Opaque and unbounded; keep it server-side and never persist it long term." }, "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccommodationRoomVO" } }, "mealPlan": { "$ref": "#/components/schemas/MealPlanVO" }, "onRequest": { "type": "boolean", "description": "`true`: only on-request quota exists, so the supplier has to accept." }, "price": { "$ref": "#/components/schemas/MoneyVO", "description": "Always in the microsite currency. Informational until Confirm." }, "provider": { "type": "string", "description": "The supplier." }, "recommendedSellingPrice": { "$ref": "#/components/schemas/MoneyVO", "description": "Only when supplied. Don't depend on it." }, "priceBreakdown": { "$ref": "#/components/schemas/CombinationPriceBreakdown" }, "offer": { "$ref": "#/components/schemas/CombinationOffer" }, "cancellationPolicies": { "type": "array", "description": "Penalty steps. Informational until Confirm.", "items": { "$ref": "#/components/schemas/CancellationPolicyVO" } }, "currentCancellationType": { "$ref": "#/components/schemas/CancellationTypeVO" } } }, "ApiAccommodationQuoteSingleAccommodationResponseVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "accommodation": { "type": "object", "properties": { "code": { "type": "string", "description": "Hotel code." }, "combinations": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccommodationQuoteSingleCombinationVO" } } } } } }, "ApiAccommodationConfirmRequestVO": { "type": "object", "required": [ "accommodation" ], "properties": { "accommodation": { "type": "object", "required": [ "combinationKey" ], "properties": { "combinationKey": { "type": "string", "description": "The key from the **Quote** or **Quote single** response." } } } } }, "ApiBookRequiredFieldResponseVO": { "type": "object", "description": "The guest data Prebook needs, per role. `requestedAge` is always mandatory even when it is not listed.", "properties": { "contactPerson": { "type": "array", "description": "For the first person of the first room.", "items": { "$ref": "#/components/schemas/RequiredPassengerData" } }, "otherPersons": { "type": "array", "description": "For every guest who is neither the contact person nor a room holder.", "items": { "$ref": "#/components/schemas/RequiredPassengerData" } }, "roomHolders": { "type": "array", "description": "For the first person of each other room.", "items": { "$ref": "#/components/schemas/RequiredPassengerData" } } } }, "ApiAccommodationConfirmCombinationResponseVO": { "type": "object", "description": "The authoritative offer, with the key for Prebook.", "properties": { "combinationKey": { "type": "string", "description": "**New** key. Send it to Prebook; the Quote key no longer works. It expires 60 minutes after this response." }, "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccommodationRoomVO" } }, "mealPlan": { "$ref": "#/components/schemas/MealPlanVO" }, "onRequest": { "type": "boolean", "description": "`true`: no confirmed quota, so the supplier has to accept." }, "price": { "$ref": "#/components/schemas/MoneyVO", "description": "The authoritative price, in the microsite currency." }, "provider": { "type": "string", "description": "The supplier." }, "recommendedSellingPrice": { "$ref": "#/components/schemas/MoneyVO", "description": "Only when supplied. Don't depend on it." }, "priceBreakdown": { "$ref": "#/components/schemas/CombinationPriceBreakdown" }, "offer": { "$ref": "#/components/schemas/CombinationOffer" }, "cancellationPolicies": { "type": "array", "description": "The authoritative penalty steps.", "items": { "$ref": "#/components/schemas/CancellationPolicyVO" } }, "remarks": { "type": "array", "description": "The authoritative supplier remarks.", "items": { "type": "string" } } } }, "ApiAccommodationConfirmAccommodationResponseVO": { "type": "object", "description": "The hotel's full identity and the confirmed offer.", "required": [ "checkIn", "checkOut" ], "properties": { "code": { "type": "string", "description": "Hotel code." }, "giataId": { "type": [ "integer", "null" ], "description": "GIATA id. Can be `null`." }, "name": { "type": "string" }, "category": { "$ref": "#/components/schemas/BookingFlowCategory" }, "geolocation": { "$ref": "#/components/schemas/GeolocationVO" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "combination": { "$ref": "#/components/schemas/ApiAccommodationConfirmCombinationResponseVO" } } }, "ApiAccommodationConfirmResponseVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "warnings": { "type": "array", "description": "Show each warning to the guest and get fresh consent before you continue.", "items": { "$ref": "#/components/schemas/WarningVO" } }, "requiredField": { "$ref": "#/components/schemas/ApiBookRequiredFieldResponseVO" }, "accommodation": { "$ref": "#/components/schemas/ApiAccommodationConfirmAccommodationResponseVO" } } }, "PersonVO": { "type": "object", "description": "A guest. Prebook sends it and booking responses return it. Only `requestedAge` is required by the spec; Confirm's `requiredField` tells you which other fields a booking needs.", "required": [ "requestedAge" ], "properties": { "id": { "type": "string", "description": "Set by Book as `--`, for example `TST-1464-0-1`. Use it as the passenger identity." }, "name": { "type": "string", "pattern": "^[\\p{Script=Latin} .'-]+$", "description": "First name, for `FIRST_NAME`. Latin script only: transliterate Arabic, Cyrillic, CJK and other scripts before sending. The spec pattern is `^[\\p{IsLatin} .'-]+$`." }, "lastName": { "type": "string", "pattern": "^[\\p{Script=Latin} .'-]+$", "description": "Surname, for `LAST_NAME`. Latin script only. The spec pattern is `^[\\p{IsLatin} .'-]+$`." }, "requestedAge": { "type": "integer", "format": "int32", "description": "Age at the **end** of the stay. Always mandatory, even when `requiredField` doesn't list it, and it must equal the age sent in Quote." }, "birthDate": { "type": "string", "format": "date", "description": "For `BIRTH_DATE`. Must match `requestedAge` at the end of the trip. Some documentation samples spell it `birthdate`, so accept both when parsing." }, "documentNumber": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z0-9]+(?:-[A-Za-z0-9]+){0,2}$", "description": "For `DOCUMENT` or `PASSPORT`, with `documentType`. Letters and digits with at most two hyphens." }, "courtesyTitle": { "$ref": "#/components/schemas/CourtesyTitle", "description": "For `TITLE`." }, "academyTitle": { "$ref": "#/components/schemas/AcademyTitle", "description": "Unverified: probably the field for `ACADEMY_TITLE` (inferred from the field names).", "x-unverified": true }, "documentType": { "$ref": "#/components/schemas/DocumentType", "description": "Sent with `documentNumber`. Must be `PASSPORT` when `requiredField` asks for `PASSPORT`. Unverified: for a `DOCUMENT` that is not a passport, `IDENTITY_CARD` or `NIE` is probably right.", "x-unverified": true }, "email": { "type": "string", "format": "email", "description": "For `EMAIL`." }, "phoneCountryCode": { "type": "string", "minLength": 2, "maxLength": 4, "pattern": "^\\+[0-9]*$", "description": "For `PHONE`, with `phone`. `+` and digits, for example `+34`; `0034` is rejected. The spec pattern is `\\+[0-9]*$`." }, "phone": { "type": "string", "maxLength": 15, "pattern": "^[0-9]+$", "description": "Digits only. The spec pattern is `[0-9]+`." }, "country": { "description": "Country. For `COUNTRY`, send `countryId`." }, "countryId": { "type": "string", "description": "For `COUNTRY`." }, "municipality": { "type": "object", "description": "For Spanish resident discounts.", "properties": { "id": { "description": "Municipality id." }, "name": { "description": "Municipality name." }, "discount": { "type": "string", "enum": [ "BALEARIC", "CANARY", "MELILLA", "CEUTA" ] } } }, "address": { "type": "object", "description": "For `ADDRESS`.", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "postCode": { "type": "string" } } }, "billingNumber": { "type": "string", "description": "For `BILLING_DOCUMENT`." }, "kinship": { "type": "string", "enum": [ "MY_SELF", "SPOUSE", "CHILD", "PARENT", "CHILD_IN_LAW", "PARENT_IN_LAW", "SIBLING" ] }, "socialInsuranceNumber": { "type": "string", "description": "For `SOCIAL_INSURANCE_NUMBER`." }, "clubDocumentNumber": { "description": "Club document number." }, "passportExpirationDate": { "type": "string", "description": "For `DOCUMENT_EXPIRY_DATE`. Must be after the end of the trip." } } }, "DistributionVO": { "type": "object", "description": "One room and its guests, as responses return it. Responses name the array `person` (whichever name Prebook was sent); some documentation samples use `persons`, so accept both when parsing.", "properties": { "id": { "type": "string", "description": "Set by Book, for example `TST-1464-0`." }, "person": { "type": "array", "items": { "$ref": "#/components/schemas/PersonVO" } } } }, "PrebookDistribution": { "type": "object", "description": "One room and its guests, as Prebook requests send it.", "required": [ "persons" ], "properties": { "persons": { "type": "array", "maxItems": 6, "description": "The guests. `persons` is the recommended name; Prebook also accepts `person`. Responses use `person`. Send every field Confirm's `requiredField` lists for each person, or Prebook returns 400 (`Missing the following required field of the contact person: ...`).", "items": { "$ref": "#/components/schemas/PersonVO" } } } }, "ApiAccommodationPrebookRequestVO": { "type": "object", "required": [ "accommodation", "distributions" ], "properties": { "accommodation": { "type": "object", "required": [ "combinationKey" ], "properties": { "combinationKey": { "type": "string", "description": "The key from the **Confirm** response." }, "commentToAccommodation": { "type": "string", "description": "Free text forwarded to the hotel. The only way to pass a special request." } } }, "distributions": { "type": "array", "minItems": 1, "maxItems": 4, "description": "One entry per room, in the Quote's order and with the Quote's number of people.", "items": { "$ref": "#/components/schemas/PrebookDistribution" } } } }, "ApiAccommodationPreBookResponseVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "warnings": { "type": "array", "description": "Show each warning to the guest and get fresh consent before Book.", "items": { "$ref": "#/components/schemas/WarningVO" } }, "accommodation": { "type": "object", "description": "The hotel and the re-validated offer.", "properties": { "code": { "type": "string" }, "giataId": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "category": { "$ref": "#/components/schemas/BookingFlowCategory" }, "geolocation": { "$ref": "#/components/schemas/GeolocationVO" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "combination": { "type": "object", "description": "Compare price, meal plan and cancellation policies with Confirm before Book.", "properties": { "combinationKey": { "type": "string", "description": "**New** key. Send it to Book; the Confirm key no longer works. It expires 60 minutes after this response." }, "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccommodationRoomVO" } }, "mealPlan": { "$ref": "#/components/schemas/MealPlanVO" }, "onRequest": { "type": "boolean" }, "price": { "$ref": "#/components/schemas/MoneyVO" }, "recommendedSellingPrice": { "$ref": "#/components/schemas/MoneyVO" }, "priceBreakdown": { "$ref": "#/components/schemas/CombinationPriceBreakdown" }, "offer": { "$ref": "#/components/schemas/CombinationOffer" }, "cancellationPolicies": { "type": "array", "items": { "$ref": "#/components/schemas/CancellationPolicyVO" } }, "remarks": { "type": "array", "items": { "type": "string" } }, "commentToAccommodation": { "type": "string", "description": "Echo of your comment." } } } } }, "distributions": { "type": "array", "description": "Echo of the guests. The array key is `person`.", "items": { "$ref": "#/components/schemas/DistributionVO" } } } }, "ApiAccommodationBookRequestVO": { "type": "object", "required": [ "accommodation" ], "properties": { "accommodation": { "type": "object", "required": [ "combinationKey" ], "properties": { "combinationKey": { "type": "string", "description": "The key from the **Prebook** response." } } }, "externalReference": { "type": "string", "maxLength": 50, "description": "Your own order id, echoed back and stored on the booking. Save it **before** calling Book so you can reconcile a timeout. Booking detail returns it as `externalReference`; Get booking returns it as `agencyBookingReference`." }, "fakeBooking": { "$ref": "#/components/schemas/FakeBooking" } } }, "ApiAccommodationBookCombinationVO": { "type": "object", "description": "The offer as booked. There is no `combinationKey` any more.", "properties": { "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccommodationRoomVO" } }, "mealPlan": { "$ref": "#/components/schemas/MealPlanVO" }, "onRequest": { "type": "boolean" }, "price": { "$ref": "#/components/schemas/MoneyVO" }, "provider": { "type": "string", "description": "The supplier." }, "recommendedSellingPrice": { "$ref": "#/components/schemas/MoneyVO" }, "priceBreakdown": { "$ref": "#/components/schemas/CombinationPriceBreakdown" }, "offer": { "$ref": "#/components/schemas/CombinationOffer" }, "cancellationPolicies": { "type": "array", "items": { "$ref": "#/components/schemas/CancellationPolicyVO" } }, "remarks": { "type": "array", "items": { "type": "string" } }, "commentToAccommodation": { "type": "string", "description": "The comment forwarded to the hotel." } } }, "ApiAccommodationBookedAccommodationVO": { "type": "object", "description": "The booked hotel.", "required": [ "checkIn", "checkOut" ], "properties": { "code": { "type": "string" }, "giataId": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "category": { "$ref": "#/components/schemas/BookingFlowCategory" }, "geolocation": { "$ref": "#/components/schemas/GeolocationVO" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "bookingReference": { "type": "string", "description": "Service reference, for example `TST-1464-0`. Every post-booking call needs it with the trip `bookingReference`. Get booking returns the same value as `hotelservice[].id`." }, "status": { "$ref": "#/components/schemas/ServiceStatus", "description": "Service-level status." }, "errorMessage": { "type": "string", "description": "Why the booking failed, when it did." }, "combination": { "$ref": "#/components/schemas/ApiAccommodationBookCombinationVO" } } }, "ApiAccommodationBookedResponseVO": { "type": "object", "description": "Returned by Book, Booking detail, Refresh and Cancel. Persist `bookingReference`, `accommodation.bookingReference`, `externalReference` and `auditData.traceId` immediately.", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "bookingReference": { "type": "string", "description": "Trip reference, for example `TST-1464`. Every post-booking call needs it." }, "externalReference": { "type": "string", "description": "Echo of your order id." }, "status": { "$ref": "#/components/schemas/ServiceStatus", "description": "Booking-level status. Branch on it: `BOOKED`, `RQ`, `PENDING_BOOK`, `PRICE_ERROR`, `BOOK_ERROR`, `NOT_BOOKED`. Treat any other value as needing a person, never as success." }, "accommodation": { "$ref": "#/components/schemas/ApiAccommodationBookedAccommodationVO" }, "distributions": { "type": "array", "description": "Guests, now with ids. The array key is `person`.", "items": { "$ref": "#/components/schemas/DistributionVO" } } } }, "ApiBookCancellationFeeResponseVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "cancellationFee": { "$ref": "#/components/schemas/MoneyVO", "description": "The penalty if you cancel today. `0` means cancelling today is free." } } }, "PriceBreakdownVO": { "type": "object", "description": "Booking-level amounts. Each amount has a `microsite` and an `operator` leg. For single-currency accounting, the `.operator` legs are the safer choice. The booking total can exceed the sum of its hotel services.", "properties": { "totalPrice": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "What the customer pays (selling price)." }, "netProvider": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "Supplier net cost. The `microsite` leg can be in the supplier's currency." }, "totalOperatorRevenue": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "The operator's revenue for the booking." }, "operatorFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "operatorManagementFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "micrositeFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "agencyFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "agencyManagerFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "agencyManagementFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "paymentFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "groundServicesManagementFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "taxes": { "$ref": "#/components/schemas/MoneyAmountVO" }, "withHoldings": { "type": "array", "items": {} }, "countryTaxes": { "type": "array", "items": {} }, "taxBreakdowns": { "type": "array", "items": {} }, "nonCommissionableNetPrice": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "The portion excluded from commission, such as taxes." }, "pricePayableAtProperty": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "Paid at the hotel (resort fees, city tax), not in the prepaid total." }, "providerNetPrice": { "$ref": "#/components/schemas/MoneyVO", "description": "Supplier-side net price, possibly in the supplier's currency." }, "netProviderPrice": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "providerFee": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "consolidatorFee": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "marketPlaceFee": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "consolidatorNetPrice": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "exchangeRateMicrosite": { "description": "Exchange rate applied." }, "exchangeRateCommissionMicrosite": { "description": "Exchange rate applied to the commission." } } }, "ServicePriceBreakdownVO": { "type": "object", "description": "Service-level amounts, in the same model as `PriceBreakdownVO`. The sources describe the fields of both breakdowns together, so a field may be absent at one level. Supplier currencies can appear in the cost legs.", "properties": { "totalPrice": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "What the customer pays for the service." }, "netProvider": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "Supplier net cost. The `microsite` leg can be in the supplier's currency." }, "totalOperatorRevenue": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "The operator's revenue for the service." }, "operatorFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "operatorManagementFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "micrositeFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "agencyFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "agencyManagerFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "agencyManagementFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "paymentFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "groundServicesManagementFee": { "$ref": "#/components/schemas/MoneyAmountVO" }, "taxes": { "$ref": "#/components/schemas/MoneyAmountVO" }, "withHoldings": { "type": "array", "items": {} }, "countryTaxes": { "type": "array", "items": {} }, "taxBreakdowns": { "type": "array", "items": {} }, "nonCommissionableNetPrice": { "$ref": "#/components/schemas/MoneyAmountVO" }, "pricePayableAtProperty": { "$ref": "#/components/schemas/MoneyAmountVO", "description": "Paid at the hotel, not in the prepaid total." }, "providerNetPrice": { "$ref": "#/components/schemas/MoneyVO", "description": "Supplier-side net price, possibly in the supplier's currency." }, "netProviderPrice": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "providerFee": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "consolidatorFee": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "marketPlaceFee": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "consolidatorNetPrice": { "description": "Supplier-side detail, possibly in the supplier's currency." }, "exchangeRateMicrosite": { "description": "Exchange rate applied." }, "exchangeRateCommissionMicrosite": { "description": "Exchange rate applied to the commission." } } }, "BookedHotelServiceVO": { "type": "object", "description": "One booked hotel service in `BookedTripVO.hotelservice[]`. A cancelled-then-rebooked room leaves two services at the same hotel and dates (one `CANCELED` at price 0, one `BOOKED`): never deduplicate by hotel and dates.", "properties": { "id": { "type": "string", "description": "Service id, for example `TST-1464-0`: the same value as Book's `accommodation.bookingReference`, so it works as the `accommodationBookingReference` of the post-booking endpoints. Unverified: probably also the `serviceId` of Cancel service and Service cancellation fee." }, "bookingReference": { "type": "string", "description": "The supplier's reference for the service (a test supplier returns `FAKE-...`). The per-accommodation post-booking endpoints accept it in place of `id`. The best stable identity for a hotel service; occasionally missing." }, "status": { "$ref": "#/components/schemas/ServiceStatus", "description": "Service-level status." }, "hotelId": { "type": "string", "description": "Hotel code." }, "hotelName": { "type": "string" }, "providerHotelId": { "description": "The supplier's hotel code." }, "globalMappingId": { "description": "Mapping id." }, "startDate": { "type": "string", "description": "Check-in, as a date-time string." }, "endDate": { "type": "string", "description": "Check-out, as a date-time string." }, "nights": { "type": "integer" }, "mealPlan": { "type": "string", "description": "A plain string here, not the `MealPlanVO` object of the booking flow." }, "category": { "$ref": "#/components/schemas/HotelCategory" }, "locationName": { "type": "string" }, "destinationCode": { "type": "string" }, "destinationName": { "type": "string" }, "country": { "description": "Country." }, "hotelData": { "type": "object", "properties": { "address": { "description": "Address." }, "postalCode": { "description": "Postal code." }, "phoneNumber": { "description": "Phone number." }, "accomodationType": { "description": "Accommodation type (sic)." } } }, "room": { "type": "array", "description": "One entry per room.", "items": { "type": "object", "properties": { "id": { "description": "Room id." }, "roomTypeDescription": { "type": "string" }, "pricebreakdown": { "description": "The room's price breakdown." } } } }, "remarks": { "type": "array", "description": "Supplier remarks. They can carry raw HTML, so strip markup before display.", "items": { "type": "string" } }, "commentsToAccommodation": { "type": "string", "description": "Plural here, singular (`commentToAccommodation`) in the booking flow." }, "cancelPolicy": { "type": "array", "description": "The service's cancellation steps. Dates are serialised in UTC and can be a day before the booking-level `cancellationPolicies[]` near midnight. There is no service-level `currentCancellationType`.", "items": { "$ref": "#/components/schemas/CancellationPolicyVO" } }, "pricebreakdown": { "$ref": "#/components/schemas/ServicePriceBreakdownVO", "description": "Current amounts. A repricing updates them, and a cancelled service can drop to 0." }, "originalpricebreakdown": { "$ref": "#/components/schemas/ServicePriceBreakdownVO", "description": "Amounts at booking time." }, "provider": { "type": "string" }, "providerDescription": { "type": "string" }, "providerConfigurationId": { "description": "The supplier connection that sold it." }, "operatorProvider": { "description": "Operator provider." }, "apiPlatform": { "description": "API platform." }, "rate": { "description": "Rate." }, "supplierId": { "description": "The supplier as a business entity, for payables." }, "supplierName": { "type": "string" }, "providerBookingReference": { "type": "string", "description": "The supplier's own confirmation number, which the hotel recognises." }, "priceType": { "$ref": "#/components/schemas/PriceType" }, "cancelationDate": { "type": "string", "description": "(sic) Set once cancelled." }, "providerCancellationDate": { "type": "string", "description": "Set once cancelled." }, "cancellationType": { "description": "Set once cancelled." }, "confirmationErrorCause": { "type": "string", "description": "Why it failed, for `BOOK_ERROR` or `NOT_BOOKED`." }, "amendments": { "type": "array", "description": "Post-booking changes.", "items": { "type": "object", "properties": { "id": { "description": "Amendment id." }, "reference": { "description": "Amendment reference." }, "description": { "description": "What changed." }, "priceBreakDown": { "description": "Amounts after the amendment." }, "originalPriceBreakDown": { "description": "Amounts before the amendment." } } } }, "repricing": { "type": "object", "description": "Set when the service was repriced into another booking.", "properties": { "bookingReference": { "type": "string" }, "serviceId": { "description": "The service id in that booking." } } }, "lastUpdateDate": { "type": "string" }, "consolidated": { "description": "Consolidated." }, "reav": { "description": "Reav." }, "externalCode": { "description": "External code." }, "fiscalInformation": { "description": "Fiscal information." }, "membershipSavedPrice": { "description": "Membership saved price." } } }, "BookedTripVO": { "type": "object", "description": "The whole trip, every service type included. The hotel is in `hotelservice[]`; manually added hotels are in `manualServices.hotel[]`. Your `externalReference` from Book comes back as `agencyBookingReference`.", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "bookingReference": { "type": "string", "description": "Trip reference." }, "customBookingReference": { "type": "string", "description": "The number of the trip reference, zero-padded, for example `00001464` for `TST-1464`." }, "agencyBookingReference": { "type": "string", "description": "Your order id, as sent in `externalReference` to Book." }, "status": { "$ref": "#/components/schemas/ServiceStatus", "description": "Booking-level status, derived from the service statuses." }, "tripType": { "type": "string", "description": "`ONLY_HOTEL` for a hotel booking. Parse unknown values leniently." }, "creationDate": { "type": "string" }, "lastUpdateDate": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "nightsCount": { "type": "integer" }, "adultCount": { "type": "integer" }, "childCount": { "type": "integer" }, "infantCount": { "type": "integer" }, "contactPerson": { "$ref": "#/components/schemas/PersonVO" }, "originalBookingAgency": { "type": "string", "description": "A plain string with the agency name, not an object." }, "user": { "description": "The user who made the booking." }, "payment": { "description": "Payment information." }, "cancellationPolicies": { "type": "array", "description": "Booking-level policy. Dates are in operator local time, as agents see them in the back office. Show these to people.", "items": { "$ref": "#/components/schemas/CancellationPolicyVO" } }, "pricebreakdown": { "$ref": "#/components/schemas/PriceBreakdownVO" }, "distribution": { "type": "array", "description": "Passengers per room. `name` is the first name and `lastName` the surname.", "items": { "$ref": "#/components/schemas/DistributionVO" } }, "hotelservice": { "type": "array", "description": "One entry per booked hotel service.", "items": { "$ref": "#/components/schemas/BookedHotelServiceVO" } }, "manualServices": { "type": "object", "description": "Services added by an agent. Other keys can carry money too.", "properties": { "hotel": { "type": "array", "description": "Manually added hotels, which are not in `hotelservice[]`.", "items": {} }, "other": { "type": "array", "items": {} }, "accountingAdjustment": { "type": "array", "items": {} } } }, "historical": { "type": "array", "description": "A readable audit trail of changes.", "items": { "type": "object", "properties": { "dateTime": { "type": "string" }, "message": { "type": "string" } } } }, "bookedNotes": { "type": "array", "items": {} }, "notes": { "description": "Notes." }, "invoices": { "type": "array", "items": {} }, "clientrequest": { "type": "array", "description": "Conversations on the booking.", "items": { "$ref": "#/components/schemas/ClientRequestVO" } }, "salesChannel": { "description": "Sales channel." }, "language": { "description": "Booking language." }, "sourceMarket": { "type": "string" }, "voucherUrl": { "type": "string" }, "pdfs": { "type": "array", "items": {} } } }, "BookingsVO": { "type": "object", "description": "This response has no `auditData`.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationVO" }, "bookings": { "type": "array", "description": "Reference, status, creation date and microsite only. Read each booking with Get booking.", "items": { "type": "object", "properties": { "bookingReference": { "type": "string" }, "status": { "$ref": "#/components/schemas/ServiceStatus" }, "creationDate": { "type": "string" }, "micrositeId": { "type": "string" } } } } } }, "CancelBookingRequestVO": { "type": "object", "required": [ "cancellationType" ], "properties": { "cancellationType": { "$ref": "#/components/schemas/CancellationType", "description": "`PROVIDER` or `MANUAL`. The spec gives no descriptions. Unverified: `PROVIDER` most likely cancels at the supplier, and `MANUAL` records a cancellation handled offline, with `manualCancellationFee`.", "x-unverified": true }, "emailNotifyCancel": { "type": "string", "format": "email", "description": "An email address. The spec does not describe it." }, "manualCancellationFee": { "type": "number", "description": "A manual cancellation fee." }, "relatedManualCancellationFee": { "type": "number", "description": "A related manual cancellation fee. The spec does not describe it." } } }, "CancelBookingResponseVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "status": { "description": "The result of the cancellation." }, "cancellationType": { "$ref": "#/components/schemas/CancellationType" }, "cancellationDate": { "type": "string" }, "providerCancellationDate": { "type": "string" } } }, "CancellationFeeResponseVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "cancellationFee": { "$ref": "#/components/schemas/MoneyVO" }, "relatedService": { "type": "object", "description": "A related service and its own fee.", "properties": { "serviceId": { "description": "The related service's id." }, "cancellationFee": { "description": "Its cancellation fee." } } }, "supportedCancellationTypes": { "type": "array", "description": "The values Cancel service accepts for this service.", "items": { "$ref": "#/components/schemas/CancellationType" } } } }, "RefundRequest": { "type": "object", "required": [ "orderNumber" ], "properties": { "orderNumber": { "type": "string", "description": "The order number of the payment to refund." }, "amount": { "type": "number", "description": "How much to refund. `0` or omitted refunds the full remaining amount." }, "manualRefund": { "type": "boolean", "default": false, "description": "Unverified: `false` most likely refunds through the original payment gateway, and `true` registers a refund handled outside the platform.", "x-unverified": true } } }, "RefundResponse": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "bookingReference": { "type": "string" }, "orderNumber": { "type": "string" }, "amount": { "type": "number" }, "manualRefund": { "type": "boolean" }, "paymentRefundStatus": { "$ref": "#/components/schemas/PaymentRefundStatus" }, "secondPaymentRefundStatus": { "description": "Not described by the spec. Unverified: probably the refund status of a second payment on the order.", "x-unverified": true } } }, "ClientRequestVO": { "type": "object", "description": "A conversation thread on a booking. The same objects appear in `BookedTripVO.clientrequest[]`.", "required": [ "type" ], "properties": { "id": { "description": "The request id. Use it as `clientRequestId`." }, "creationDate": { "description": "When the request was created." }, "closingDate": { "description": "When the request was closed." }, "type": { "$ref": "#/components/schemas/ClientRequestType" }, "requestClosed": { "type": "boolean", "description": "Whether the request is closed." }, "message": { "type": "array", "description": "The thread, one entry per message.", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "The text." }, "user": { "description": "Who wrote it." }, "date": { "description": "When it was written." } } } } } }, "ClientRequestReply": { "type": "object", "properties": { "message": { "type": "string", "description": "The reply text. Unverified: the body is documented as `{ message }`, and the plain string type is assumed.", "x-unverified": true } } }, "AccommodationFacilityVO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Facility id." }, "icon": { "type": "string", "description": "A CSS class, for example `fa-regular fa-grill` or `ico-tc-SPA`. Map it to your own icon set." }, "priority": { "type": "integer", "description": "Higher means more prominent." }, "translations": { "type": "object", "description": "Map of language to label.", "additionalProperties": { "type": "string" } } } }, "RoomFacilityVO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Facility id." }, "icon": { "type": "string", "description": "A CSS class. Map it to your own icon set." }, "priority": { "type": "integer", "description": "Higher means more prominent." }, "translations": { "type": "object", "description": "Map of language to label.", "additionalProperties": { "type": "string" } }, "category": { "$ref": "#/components/schemas/RoomFacilityCategory" } } }, "AccommodationFacilityListVO": { "type": "object", "description": "This response has no `auditData`.", "properties": { "facilities": { "type": "array", "items": { "$ref": "#/components/schemas/AccommodationFacilityVO" } } } }, "RoomFacilityListVO": { "type": "object", "description": "This response has no `auditData`.", "properties": { "facilities": { "type": "array", "items": { "$ref": "#/components/schemas/RoomFacilityVO" } } } }, "IdeaPlaceVO": { "type": "object", "description": "A place, such as the hotel's destination.", "properties": { "type": { "description": "Place type." }, "code": { "type": "string" }, "name": { "type": "string" } } }, "IdeaHotelDataVO": { "type": "object", "description": "A hotel datasheet: static content only, never prices or availability. Optional text fields can be empty strings.", "properties": { "id": { "type": "string", "description": "Hotel code. Formats vary, for example `1000` or `MASTER-2267891`." }, "giataId": { "type": [ "integer", "null" ], "description": "GIATA code. Can be `null`. A valid GIATA licence is required to use the API." }, "name": { "type": "string" }, "category": { "$ref": "#/components/schemas/HotelCategory", "description": "A plain string such as `S4`. The booking flow returns an object `{ code, name }` instead, so normalise both." }, "images": { "type": "array", "description": "Full-size originals, which can be more than 5000 px wide. There is no thumbnail: use `images[0]`.", "items": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "classification": { "type": "object", "properties": { "type": { "anyOf": [ { "$ref": "#/components/schemas/ImageClassificationType" }, { "type": "string" } ], "description": "What the image shows. The spec values are `ImageClassificationType`; the docs samples use upper-case forms such as `POOL` or `HALLWAY_OR_STAIRCASE`, so normalise before comparing." }, "confidence": { "description": "Classification confidence." } } } } } }, "accommodationFacilities": { "type": "array", "items": { "$ref": "#/components/schemas/AccommodationFacilityVO" } }, "roomFacilities": { "type": "array", "items": { "$ref": "#/components/schemas/RoomFacilityVO" } }, "destination": { "$ref": "#/components/schemas/IdeaPlaceVO" }, "geolocation": { "$ref": "#/components/schemas/GeolocationVO" }, "description": { "type": "string", "description": "Plain text with `\\n` line breaks, in the requested language." }, "ratings": { "type": "array", "description": "Review scores. Hide entries with `numReviews` of 0.", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "Booking.com", "Tripadvisor", "Expedia" ] }, "numReviews": { "type": "integer" }, "score": { "type": "string", "description": "A string. Booking.com scores out of 10, Tripadvisor and Expedia out of 5." } } } }, "phoneNumber": { "type": "string" }, "chain": { "type": "string" }, "address": { "type": "string" }, "internalRemark": { "type": "string", "description": "Internal. Never show it to customers." }, "accommodationType": { "$ref": "#/components/schemas/AccommodationType" }, "accommodationSubtype": { "$ref": "#/components/schemas/AccommodationSubtype" } } }, "ApiStaticContentAccommodationDataSheetVO": { "description": "One hotel datasheet, with `auditData`.", "allOf": [ { "$ref": "#/components/schemas/IdeaHotelDataVO" }, { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" } } } ] }, "ApiStaticContentAccommodationsDataSheetVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "accommodations": { "type": "array", "items": { "$ref": "#/components/schemas/IdeaHotelDataVO" } } } }, "ApiStaticContentAccommodationsVO": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "accommodations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Hotel code. Use it as your primary key." }, "giataId": { "type": [ "integer", "null" ], "description": "GIATA code. Can be `null`. Use it as a secondary key." }, "name": { "type": "string" }, "geolocation": { "$ref": "#/components/schemas/GeolocationVO" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2, for example `ES`." }, "lastUpdate": { "type": "string", "description": "When the hotel's content last changed, for example `2022-10-30 18:36`." } } } }, "pagination": { "$ref": "#/components/schemas/PaginationVO" } } }, "GetHotelRS": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "hotel": { "type": "array", "description": "The promoted hotels as full datasheets. The array is named `hotel`.", "items": { "$ref": "#/components/schemas/IdeaHotelDataVO" } } } }, "GetMealPlanRS": { "type": "object", "description": "This response has no `auditData`.", "properties": { "mealplan": { "type": "array", "items": { "$ref": "#/components/schemas/MealPlanVO" } } } }, "DestinationVO": { "type": "object", "description": "A destination. `description` is only returned by Get a destination.", "properties": { "code": { "type": "string", "description": "Destination code. Send it as `destinationId` in Quote." }, "name": { "type": "string" }, "geolocation": { "$ref": "#/components/schemas/GeolocationVO" }, "country": { "description": "Country of the destination." }, "provincePostalPrefix": { "description": "Province postal prefix." }, "active": { "description": "Active flag." }, "images": { "type": "array", "items": {} }, "iata": { "type": "string", "description": "IATA code." }, "description": { "type": "string" } } }, "GetDestinationRS": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "destination": { "type": "array", "items": { "$ref": "#/components/schemas/DestinationVO" } } } }, "GetCountryRS": { "type": "object", "properties": { "auditData": { "$ref": "#/components/schemas/AuditResponseVO" }, "country": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Country id." }, "name": { "type": "string" } } } } } }, "ProviderConfigurationVO": { "type": "object", "description": "One supplier connection on a microsite.", "properties": { "id": { "description": "Id of the connection." }, "description": { "description": "Description of the connection." }, "provider": { "description": "The supplier." } } }, "ServiceStatus": { "type": "string", "description": "Status of a service and of a booking. Only `BOOKED`, `BOOK_ERROR`, `CANCELED`, `PRICE_ERROR`, `NOT_BOOKED`, `RQ` and `PENDING_BOOK` are documented as outcomes. Map any other value, including ones not listed here, to \"needs attention\": don't crash and never treat it as success.", "enum": [ "NOT_QUOTED", "QUOTED", "LOAD_CANCELLATION_POLICIES_ERROR", "CONFIRMATION_ERROR", "CONFIRMED", "PREBOOKED", "PAID", "BOOKED", "NEED_QUOTE", "BOOK_ERROR", "RQ", "NOT_BOOKED", "PENDING_BOOK", "CANCELED", "CANCEL_ERROR", "PRICE_ERROR", "LOCKED", "PENDING_UPDATE", "WITH_PROPOSALS", "WAITING_SUPPLIER", "WAITING_ACCEPTANCE" ] }, "MealPlanType": { "type": "string", "description": "Mixed plans collapse to the nearest type (\"1 bed and breakfast + 1 half board\" becomes `HALF_BOARD`), so show the meal plan's `description`.", "enum": [ "ROOM_ONLY", "BED_AND_BREAKFAST", "HALF_BOARD", "FULL_BOARD", "ALL_INCLUSIVE" ] }, "CancellationPolicyType": { "type": "string", "description": "`REFUNDABLE` means free cancellation until the `deadline`.", "enum": [ "REFUNDABLE", "PARTIALLY_REFUNDABLE", "NON_REFUNDABLE", "UNKNOWN" ] }, "WarningType": { "type": "string", "enum": [ "PRICE_CHANGE", "CANCELLATION_POLICIES_CHANGE" ] }, "HotelCategory": { "type": "string", "description": "`S1` to `S6` stars, `L1` to `L5` keys, `H1` to `H5` suns, `IN` none or indeterminate.", "enum": [ "S1", "S2", "S3", "S4", "S5", "S6", "L1", "L2", "L3", "L4", "L5", "H1", "H2", "H3", "H4", "H5", "IN" ] }, "AccommodationType": { "type": "string", "description": "The spec names this enum `AccomodationType` (sic).", "enum": [ "HOTEL", "APARTMENT" ] }, "AccommodationSubtype": { "type": "string", "enum": [ "HOTEL", "MOTELS", "RESORTS", "BED_AND_BR", "RYOKANS", "INNS", "RIADS", "ECONOMY_H", "HEALTH_RESORTS", "CAPSULE_HOTELS", "LOVE_HOTELS", "HOSTEL", "LUXURY_TENTS", "STUDENT_AC", "APARTHOTELS", "OTHER", "APARTMENT", "GUEST_AC", "RESIDENCES", "FARM_STAYS", "HOLIDAY_PARKS", "VILLAS", "CAMPSITES", "BOATS", "GUEST_HOUSES", "HOLIDAY_HOMES", "LODGES", "HOMESTAYS", "COUNTRY_HOUSES", "CHALETS", "CONDOS", "COTTAGES", "GITES" ] }, "Language": { "type": "string", "enum": [ "EN", "EN_IE", "EN_US", "ES", "IT", "FR", "PT", "PT_BR", "AR", "RO", "EL", "FI", "DE", "NL", "SV", "ZH", "ZH_TW", "RU", "HU", "FA", "PL", "CA", "BG", "JA", "MS", "NO", "TR", "SK", "SL", "CS", "HR", "AZ", "HE", "DA", "TH", "SQ", "KA", "SR", "UZ", "EU" ] }, "TripType": { "type": "string", "description": "Send `ONLY_HOTEL`. On Quote it is optional and defaults to `ONLY_HOTEL`.", "enum": [ "ONLY_HOTEL" ] }, "CourtesyTitle": { "type": "string", "enum": [ "MISTER", "MRS", "MS" ] }, "AcademyTitle": { "type": "string", "enum": [ "Dr", "Prof", "ProfDr" ] }, "DocumentType": { "type": "string", "enum": [ "IDENTITY_CARD", "NIE", "PASSPORT" ] }, "RequiredPassengerData": { "type": "string", "description": "A guest field that Confirm's `requiredField` asks for. `FREQUENT_TRAVELLER_NUMBER`, `EMERGENCY_CONTACT`, `DOCUMENT_DATE_OF_ISSUE`, `SEAT_SELECTION` and `INVOICE_DATA` have no documented hotel mapping; if one appears for a hotel, ask your Nava account manager.", "enum": [ "FIRST_NAME", "LAST_NAME", "TITLE", "ACADEMY_TITLE", "BIRTH_DATE", "COUNTRY", "PHONE", "DOCUMENT", "PASSPORT", "DOCUMENT_DATE_OF_ISSUE", "DOCUMENT_EXPIRY_DATE", "ADDRESS", "EMAIL", "EMERGENCY_CONTACT", "BILLING_DOCUMENT", "SEAT_SELECTION", "SOCIAL_INSURANCE_NUMBER", "FREQUENT_TRAVELLER_NUMBER", "INVOICE_DATA" ] }, "PriceType": { "type": "string", "enum": [ "RETAIL", "RETAIL_OVER", "NET", "NET_BASE", "NET_RETAIL" ] }, "ServiceType": { "type": "string", "description": "The service type in the generic cancel and cancellation fee paths. Send `HOTEL`.", "enum": [ "HOTEL" ] }, "CancellationType": { "type": "string", "description": "The spec does not describe the values. See `CancelBookingRequestVO.cancellationType`.", "enum": [ "PROVIDER", "MANUAL" ] }, "ImageClassificationType": { "type": "string", "description": "The spec values. The docs samples write them in upper case with underscores.", "enum": [ "Aerial View", "Bathroom", "Beach", "Building", "Business Center", "Cleanliness badge", "Garden", "Hallway-Staircase", "Kitchen", "Living Area", "Lobby-Reception", "Meeting Facility", "Parking", "Pool", "Restaurant-Bar", "Room", "Spa-Sauna", "Sports Facility", "Terrace", "Food", "Waterpark" ] }, "RoomFacilityCategory": { "type": "string", "enum": [ "GENERAL", "ACTIVITIES", "BATHROOM", "MEDIA_AND_TECHNOLOGY", "FOOD_AND_DRINK", "INTERNET", "KITCHEN", "OUTDOORS", "VIEW", "LIVING_AREA", "BEDROOM", "EXCLUSIVE_SERVICES" ] }, "ClientRequestType": { "type": "string", "enum": [ "AMENDMENT", "CANCELLATION", "QUESTION", "COMPLAINT", "OTHER" ] }, "PaymentRefundStatus": { "type": "string", "description": "How much of the payment has been refunded.", "enum": [ "NONE", "PARTIAL", "COMPLETE" ] } } } }