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. ## Booking flow Quote > Quote single (optional) > Confirm > Prebook > Book. - Every step returns a **new** `combinationKey`. Always send the key from the immediately preceding response. - Use **one auth token for the whole flow**, from Quote to Book. A new token mid-flow means starting again from Quote. - **Never retry Book or Cancel automatically.** Neither is idempotent: after a timeout, reconcile before you try again. - Branch on the Book `status`. A 200 response alone does not mean the room is confirmed. ## Every call - Send `auth-token` (except on Authenticate) and `Accept-Encoding: gzip`, plus `Content-Type: application/json` with a body. - Responses echo your token in `auditData.authToken`. Redact it before you log or store a payload. - 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. - No error schema is documented. Treat any non-2xx response as a failure and keep the raw body and the ids. Properties, 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