info:
  description: Niara Sales API (V2)
  title: Booking API V2
  version: 1.0.0
servers: []
paths:
  /v2/ping:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
      operationId: PingLambda
      summary: Health Check
      description: |-
        ## Introduction

        Simple health-check endpoint, used to confirm the API is up and that authentication
        (Username/Password) is working.
      requestBody:
        summary: Health-check request, no parameters.
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PingPayload'
      security:
      - apiKey: []
        secretKey: []
  /v2/hotels/availability:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelAvailabilityResponse'
      operationId: AvailabilityLambda
      summary: Hotel Availability
      description: |-
        ## Introduction

        Returns rate availability for specific hotels, a registered region, or a geographic
        radius search, for a given period and occupancy.

        ## Search destination

        Exactly one of the three destination criteria must be provided in `destinations`:

        - `hotelIds`: list of internal Niara hotel IDs.
        - `regionId`: ID of a registered region.
        - `circleInfo`: radius search around a geographic point (latitude/longitude/radius).

        Providing more than one is not an error: the search follows the same internal
        precedence order used by the availability engine (`circleInfo` > `regionId` > `hotelIds`),
        using only the first one present.

        ## Pagination

        Results are paginated at 50 hotels per page — see `page` on the request and
        `totalPages` on the response.
      requestBody:
        summary: Hotel availability search criteria.
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelAvailabilityPayload'
            examples:
              default:
                summary: Search by hotel ID
                value:
                  destinations:
                    hotelIds:
                    - HOTEL_OMNI_10027
                  checkin: '2026-10-29'
                  checkout: '2026-10-30'
                  occupancy:
                    adults: 1
                    children: 1
                    childrenAges:
                    - 5
      security:
      - apiKey: []
        secretKey: []
  /v2/hotels/checkrate:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckRateResponse'
      operationId: CheckRateLambda
      summary: Check Rate
      description: |-
        ## Introduction

        Re-confirms the current price and availability of specific room rates previously
        returned by a `v2/hotels/availability` search, immediately before booking. Suppliers
        are queried live (not from cache), so this call is slower than a plain search and is
        meant to be used right before creating a reservation, not for browsing.

        A rate that is no longer available comes back as a 404 — treat that as "this specific
        rate is gone," not as a generic search returning no results.
      requestBody:
        summary: Criteria to re-confirm the current price/availability of specific
          room rates
        description: |2-

          Deliberately minimal: `rateTokens` alone identifies the hotel(s), room rates, dates
          and occupancy.

          Room rates from different hotels can be mixed in the same call, but they must all
          share the same checkin/checkout/occupancy.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckRatePayload'
            examples:
              default:
                summary: Re-confirm a room rate
                value:
                  rateTokens:
                  - <rateToken from a previous v2/hotels/availability search>
      security:
      - apiKey: []
        secretKey: []
  /v2/booking:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
      operationId: BookingLambda
      summary: Booking
      description: |-
        ## Introduction

        Books one or more previously check-priced room rates. Booking is asynchronous: this call
        only confirms the request was accepted for processing, not that the reservation itself is
        confirmed yet — see `status` on the response.
      requestBody:
        summary: Books one or more previously checked-rate room rates.
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingPayload'
            examples:
              default:
                summary: Book a room rate
                value:
                  items:
                  - item:
                      type: hotel
                      bookingToken: <bookingToken from a previous v2/hotels/checkrate
                        call>
                      totalPrice:
                        value: 2.0
                        currency: BRL
                      guests:
                      - ageQualifying: ADULT
                        firstName: Teste
                        lastName: API Nova
                        email: teste@niara.tech
                        cpf: '00000000000'
                      - ageQualifying: CHILD
                        firstName: Teste Filho
                        lastName: API Nova
                        age: 5
                  buyer:
                    name: Teste API Nova
                    email: teste@niara.tech
                  payments:
                  - paymentOptionId: 407fc136-d4b6-42ba-b766-424d56723946__DIR__EXT_DIR
                    creditCard:
                      brand: VISA
                      holder: Teste API Nova
                      number: '4111111111111111'
                      expiryDate: '1230'
                      cvv: '123'
                    paidItems:
                    - itemIndex: 0
                      amount: 2.0
                      currency: BRL
      security:
      - apiKey: []
        secretKey: []
  /v2/booking/cancel:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResponse'
      operationId: CancelLambda
      summary: Cancel
      description: |-
        ## Introduction

        Cancels a previously created order, in full or in part. Pass `itemIds` to cancel only
        specific items within a multi-item order; omit it to cancel the entire order.
      requestBody:
        summary: Cancels a previously created order, in full or in part.
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelPayload'
            examples:
              default:
                summary: Cancel specific items in an order
                value:
                  orderId: BCDEFGH
                  itemIds:
                  - BCDEFGH
      security:
      - apiKey: []
        secretKey: []
openapi: 3.0.2
components:
  schemas:
    PingPayload:
      description: Health-check request, no parameters.
      type: object
      properties: {}
    PingResponse:
      description: Health-check result.
      type: object
      properties:
        status:
          type: string
          description: Always "ok" when the API is up.
      required:
      - status
    CircleInfo:
      type: object
      properties:
        lat:
          type: number
          description: Latitude of the search circle's center.
        lon:
          type: number
          description: Longitude of the search circle's center.
        radius:
          type: number
          description: Search radius from the center.
        unit:
          default: km
          enum:
          - km
          - mi
          description: 'Unit of measure for the radius: kilometers ("km") or miles
            ("mi").'
      required:
      - lat
      - lon
      - radius
    Destinations:
      type: object
      properties:
        hotelIds:
          type: array
          default: null
          description: List of Niara hotel IDs to search. Mutually exclusive with
            `regionId` and `circleInfo`.
          items:
            type: string
          nullable: true
        regionId:
          type: string
          default: null
          description: ID of a region registered in Niara. Mutually exclusive with
            `hotelIds` and `circleInfo`.
          nullable: true
        circleInfo:
          default: null
          description: Radius search around a geographic point. Mutually exclusive
            with `hotelIds` and `regionId`.
          allOf:
          - $ref: '#/components/schemas/CircleInfo'
          nullable: true
    Occupancy:
      type: object
      properties:
        adults:
          type: integer
          description: Number of adults per room.
        children:
          type: integer
          default: 0
          description: Number of children per room.
        childrenAges:
          type: array
          description: Ages of the children, one entry per child (must match the `children`
            count).
          items:
            type: integer
      required:
      - adults
    HotelAvailabilityPayload:
      description: Hotel availability search criteria.
      type: object
      properties:
        destinations:
          description: 'Search destination criteria: by hotelIds, region, or geographic
            radius.'
          allOf:
          - $ref: '#/components/schemas/Destinations'
        checkin:
          type: string
          description: Check-in date (ISO 8601, e.g. 2026-10-01).
        checkout:
          type: string
          description: Check-out date (ISO 8601, e.g. 2026-10-02).
        occupancy:
          description: Desired occupancy (adults, children and children's ages).
          allOf:
          - $ref: '#/components/schemas/Occupancy'
        preferredOnly:
          type: boolean
          default: false
          description: When true, restricts the result to the client's favorite hotels.
        awards:
          type: array
          default: null
          description: Filters hotels by star rating. A hotel is included only if
            its rating exactly matches one of the values listed here (e.g. `[4, 5]`
            returns only 4- and 5-star hotels — it is not a "4 stars and up" threshold).
            Hotels with no rating on file are always excluded once this filter is
            set.
          items:
            enum:
            - 1
            - 2
            - 3
            - 4
            - 5
          nullable: true
        bestOnly:
          type: boolean
          default: false
          description: When true, returns only the cheapest rate per hotel/credential.
        page:
          type: integer
          default: 1
          description: Page number (1-indexed). Each page returns up to 50 hotels
            — see `totalPages` on the response.
        includeUnavailableRoomRates:
          type: boolean
          default: false
          description: 'When true, hotels also include `unavailableRoomRates`: rates
            that were found but aren''t currently bookable, with the reason why.'
        locale:
          type: string
          default: null
          description: Desired language/locale for the response's text.
          nullable: true
      required:
      - checkin
      - checkout
      - destinations
      - occupancy
    Position:
      type: object
      properties:
        latitude:
          type: number
          default: null
          description: Latitude of the hotel.
          nullable: true
        longitude:
          type: number
          default: null
          description: Longitude of the hotel.
          nullable: true
    Hotel:
      type: object
      properties:
        id:
          type: string
          description: Internal Niara ID of the hotel.
        name:
          type: string
          description: Hotel name.
        cityName:
          type: string
          default: null
          description: Name of the hotel's city.
          nullable: true
        countryName:
          type: string
          default: null
          description: Name of the hotel's country.
          nullable: true
        address:
          type: string
          default: null
          description: Hotel address.
          nullable: true
        position:
          default: null
          description: Geographic coordinates of the hotel.
          allOf:
          - $ref: '#/components/schemas/Position'
          nullable: true
      required:
      - id
      - name
    RoomType:
      type: object
      properties:
        id:
          type: string
          description: Room type ID.
        name:
          type: string
          description: Room type name.
      required:
      - id
      - name
    Time:
      type: object
      properties:
        startDate:
          type: string
          description: Rate start date.
        endDate:
          type: string
          description: Rate end date.
      required:
      - endDate
      - startDate
    AmountTotal:
      type: object
      properties:
        value:
          type: number
          description: Monetary amount.
        currency:
          type: string
          description: Currency code (ISO 4217).
      required:
      - currency
      - value
    PriceComposition:
      type: object
      properties:
        net:
          default: null
          description: Net value (before taxes), when available.
          allOf:
          - $ref: '#/components/schemas/AmountTotal'
          nullable: true
        taxes:
          default: null
          description: Tax amount, when available.
          allOf:
          - $ref: '#/components/schemas/AmountTotal'
          nullable: true
        total:
          default: null
          description: Total value (net + taxes), when available.
          allOf:
          - $ref: '#/components/schemas/AmountTotal'
          nullable: true
    CancelPolicy:
      type: object
      properties:
        nonRefundable:
          type: boolean
          default: null
          description: Indicates whether the rate is non-refundable, when known.
          nullable: true
        inPenalty:
          type: boolean
          default: null
          description: Indicates whether cancellation is currently within the penalty
            period.
          nullable: true
        penaltyDate:
          type: string
          default: null
          description: Date from which cancellation starts incurring a penalty.
          nullable: true
    IncludeExtraOption:
      type: object
      properties:
        id:
          type: string
          description: Extra item ID.
        label:
          type: string
          default: null
          description: Extra item label.
          nullable: true
      required:
      - id
    PaymentOption:
      type: object
      properties:
        type:
          type: string
          description: Payment option type (e.g. credit card, PIX, pay-at-hotel).
        id:
          type: string
          description: Payment option ID.
        enabled:
          type: boolean
          default: null
          description: Whether this payment option is currently usable for this rate,
            when known.
          nullable: true
        internalType:
          type: string
          default: null
          description: Internal payment-option classification.
          nullable: true
        alias:
          type: string
          default: null
          description: Display name for the payment option.
          nullable: true
        description:
          type: string
          default: null
          description: Human-readable description.
          nullable: true
        disabledReason:
          type: string
          default: null
          description: Why this option is disabled, when `enabled` is false.
          nullable: true
        credentialType:
          type: string
          default: null
          description: Supplier credential type behind this payment option, when relevant.
          nullable: true
        includeExtraOptions:
          type: array
          default: null
          description: Extras that can be bundled with this payment option.
          items:
            $ref: '#/components/schemas/IncludeExtraOption'
          nullable: true
      required:
      - id
      - type
    Meal:
      type: object
      properties:
        breakfast:
          type: boolean
          default: null
          description: Whether breakfast is included.
          nullable: true
        lunch:
          type: boolean
          default: null
          description: Whether lunch is included.
          nullable: true
        dinner:
          type: boolean
          default: null
          description: Whether dinner is included.
          nullable: true
        allInclusive:
          type: boolean
          default: null
          description: Whether the rate is all-inclusive.
          nullable: true
        name:
          type: string
          default: null
          description: Meal plan name.
          nullable: true
        description:
          type: string
          default: null
          description: Meal plan description.
          nullable: true
    RatePlanInclusion:
      type: object
      properties:
        id:
          type: string
          default: null
          description: Inclusion ID.
          nullable: true
        name:
          type: string
          default: null
          description: Inclusion name.
          nullable: true
        description:
          type: string
          default: null
          description: Inclusion description.
          nullable: true
    RatePlan:
      type: object
      properties:
        id:
          type: string
          default: null
          description: Rate plan ID.
          nullable: true
        name:
          type: string
          default: null
          description: Rate plan name.
          nullable: true
        type:
          type: string
          default: null
          description: Rate plan type.
          nullable: true
        public:
          type: boolean
          default: null
          description: Whether the rate plan is publicly published.
          nullable: true
        package:
          type: boolean
          default: null
          description: Whether the rate plan is a package (bundled with extras).
          nullable: true
        inclusions:
          type: array
          default: null
          description: Items included in the rate plan.
          items:
            $ref: '#/components/schemas/RatePlanInclusion'
          nullable: true
    Description:
      type: object
      properties:
        name:
          type: string
          default: null
          description: Description name/title.
          nullable: true
        description:
          type: string
          default: null
          description: Description text.
          nullable: true
    Descriptions:
      type: object
      properties:
        roomType:
          type: array
          default: null
          description: Room type descriptions.
          items:
            $ref: '#/components/schemas/Description'
          nullable: true
        meal:
          type: array
          default: null
          description: Meal plan descriptions.
          items:
            $ref: '#/components/schemas/Description'
          nullable: true
        ratePlan:
          type: array
          default: null
          description: Rate plan descriptions.
          items:
            $ref: '#/components/schemas/Description'
          nullable: true
        cancelPolicy:
          type: array
          default: null
          description: Cancellation policy descriptions.
          items:
            $ref: '#/components/schemas/Description'
          nullable: true
        generalPolicies:
          type: array
          default: null
          description: General policy descriptions.
          items:
            $ref: '#/components/schemas/Description'
          nullable: true
        payment:
          type: array
          default: null
          description: Payment-related descriptions.
          items:
            $ref: '#/components/schemas/Description'
          nullable: true
    Offer:
      type: object
      properties:
        name:
          type: string
          default: null
          description: Offer name.
          nullable: true
        discount:
          type: number
          default: null
          description: Discount value/percentage.
          nullable: true
        freeNights:
          type: integer
          default: null
          description: Number of free nights granted by the offer, when applicable.
          nullable: true
        discountType:
          default: null
          enum:
          - STAY_DISCOUNT
          - DISCOUNT
          - FREE_NIGHT
          - LAST_MINUTE
          - null
          description: Discount type.
          nullable: true
        nightsRequired:
          type: integer
          default: null
          description: Nights required to qualify for the offer, when applicable.
          nullable: true
    AvailableRoomRate:
      type: object
      properties:
        rateToken:
          type: string
          description: Opaque token identifying this rate. Pass it to `v2/hotels/checkrate`
            to re-confirm it before booking.
        roomType:
          description: Room type associated with the rate.
          allOf:
          - $ref: '#/components/schemas/RoomType'
        time:
          description: Rate validity period.
          allOf:
          - $ref: '#/components/schemas/Time'
        priceComposition:
          description: Rate price composition.
          allOf:
          - $ref: '#/components/schemas/PriceComposition'
        cancelPolicy:
          description: Rate cancellation policy.
          allOf:
          - $ref: '#/components/schemas/CancelPolicy'
        paymentOptions:
          type: array
          default: null
          description: Payment/guarantee options available for this rate.
          items:
            $ref: '#/components/schemas/PaymentOption'
          nullable: true
        meal:
          default: null
          description: Meal plan included with the rate.
          allOf:
          - $ref: '#/components/schemas/Meal'
          nullable: true
        ratePlan:
          default: null
          description: Rate plan the rate belongs to.
          allOf:
          - $ref: '#/components/schemas/RatePlan'
          nullable: true
        descriptions:
          default: null
          description: Human-readable descriptions for the rate.
          allOf:
          - $ref: '#/components/schemas/Descriptions'
          nullable: true
        offers:
          type: array
          default: null
          description: Promotional offers applied to the rate.
          items:
            $ref: '#/components/schemas/Offer'
          nullable: true
      required:
      - cancelPolicy
      - priceComposition
      - rateToken
      - roomType
      - time
    UnavailableRoomRate:
      type: object
      properties:
        id:
          type: string
          description: Rate/room ID. Informational only — cannot be rechecked via
            checkrate or booked.
        roomType:
          default: null
          description: Room type associated with the rate, when known.
          allOf:
          - $ref: '#/components/schemas/RoomType'
          nullable: true
        reason:
          type: string
          default: null
          description: Why this rate is unavailable.
          nullable: true
        minAdultCount:
          type: integer
          default: null
          description: Minimum number of adults required, when the unavailability
            is an occupancy restriction.
          nullable: true
        maxAdultCount:
          type: integer
          default: null
          description: Maximum number of adults allowed, when the unavailability is
            an occupancy restriction.
          nullable: true
        minChildCount:
          type: integer
          default: null
          description: Minimum number of children required, when the unavailability
            is an occupancy restriction.
          nullable: true
        maxChildCount:
          type: integer
          default: null
          description: Maximum number of children allowed, when the unavailability
            is an occupancy restriction.
          nullable: true
        cancelPolicy:
          default: null
          description: Rate cancellation policy, when known.
          allOf:
          - $ref: '#/components/schemas/CancelPolicy'
          nullable: true
        ratePlan:
          default: null
          description: Rate plan the rate belongs to, when known.
          allOf:
          - $ref: '#/components/schemas/RatePlan'
          nullable: true
        meal:
          default: null
          description: Meal plan included with the rate, when known.
          allOf:
          - $ref: '#/components/schemas/Meal'
          nullable: true
        priceComposition:
          default: null
          description: Rate price composition, when known — what this rate would have
            cost.
          allOf:
          - $ref: '#/components/schemas/PriceComposition'
          nullable: true
      required:
      - id
    HotelAvailabilityItem:
      type: object
      properties:
        hotel:
          description: Hotel data.
          allOf:
          - $ref: '#/components/schemas/Hotel'
        roomRates:
          type: array
          description: Available rates for the hotel, for the searched period/occupancy.
          items:
            $ref: '#/components/schemas/AvailableRoomRate'
        unavailableRoomRates:
          type: array
          default: null
          description: Rates that were found but aren't currently bookable. Only present
            when `includeUnavailableRoomRates` was set on the request.
          items:
            $ref: '#/components/schemas/UnavailableRoomRate'
          nullable: true
      required:
      - hotel
    HotelAvailabilityResponse:
      description: Hotel availability search result.
      type: object
      properties:
        hotels:
          type: array
          description: List of hotels found with their rates.
          items:
            $ref: '#/components/schemas/HotelAvailabilityItem'
        searchId:
          type: string
          default: null
          description: Search identifier to be included in the payload of the subsequent
            calls of the booking flow, useful for correlating them.
          nullable: true
        count:
          type: integer
          default: null
          description: Number of hotels returned on this page.
          nullable: true
        totalCount:
          type: integer
          default: null
          description: Total number of hotels available for the given criteria (before
            pagination).
          nullable: true
        page:
          type: integer
          default: null
          description: The page number returned, echoing the request's `page`.
          nullable: true
        totalPages:
          type: integer
          default: null
          description: Total number of pages available for the given criteria.
          nullable: true
    CheckRatePayload:
      description: 'Criteria to re-confirm the current price/availability of specific
        room rates

        previously returned by a hotel availability search, immediately before booking.


        Deliberately minimal: `rateTokens` alone identifies the hotel(s), room rates,
        dates

        and occupancy.


        Room rates from different hotels can be mixed in the same call, but they must
        all

        share the same checkin/checkout/occupancy.

        '
      type: object
      properties:
        rateTokens:
          type: array
          description: Tokens of the room rates to re-confirm, as returned by a prior
            availability search (`roomRates[].rateToken`). Can span multiple hotels,
            but must all share the same checkin/checkout/occupancy.
          items:
            type: string
        locale:
          type: string
          default: null
          description: Desired language/locale for the response's text.
          nullable: true
        searchId:
          type: string
          default: null
          description: The `searchId` returned by the availability search these room
            rates came from. Passing it back links this check into that search for
            correlation purposes. If omitted, the response comes back with a new,
            unrelated `searchId`.
          nullable: true
      required:
      - rateTokens
    BookableRoomRate:
      type: object
      properties:
        bookingToken:
          type: string
          description: Opaque token identifying this re-confirmed rate. Pass it to
            `v2/booking` to book it. Expires 15 minutes after being issued.
        roomType:
          description: Room type associated with the rate.
          allOf:
          - $ref: '#/components/schemas/RoomType'
        time:
          description: Rate validity period.
          allOf:
          - $ref: '#/components/schemas/Time'
        priceComposition:
          description: Rate price composition.
          allOf:
          - $ref: '#/components/schemas/PriceComposition'
        cancelPolicy:
          description: Rate cancellation policy.
          allOf:
          - $ref: '#/components/schemas/CancelPolicy'
        paymentOptions:
          type: array
          default: null
          description: Payment/guarantee options available for this rate.
          items:
            $ref: '#/components/schemas/PaymentOption'
          nullable: true
        meal:
          default: null
          description: Meal plan included with the rate.
          allOf:
          - $ref: '#/components/schemas/Meal'
          nullable: true
        ratePlan:
          default: null
          description: Rate plan the rate belongs to.
          allOf:
          - $ref: '#/components/schemas/RatePlan'
          nullable: true
        descriptions:
          default: null
          description: Human-readable descriptions for the rate.
          allOf:
          - $ref: '#/components/schemas/Descriptions'
          nullable: true
        offers:
          type: array
          default: null
          description: Promotional offers applied to the rate.
          items:
            $ref: '#/components/schemas/Offer'
          nullable: true
      required:
      - bookingToken
      - cancelPolicy
      - priceComposition
      - roomType
      - time
    CheckRateHotelResult:
      type: object
      properties:
        hotel:
          description: Hotel data.
          allOf:
          - $ref: '#/components/schemas/Hotel'
        roomRates:
          type: array
          description: Re-confirmed rates for the hotel.
          items:
            $ref: '#/components/schemas/BookableRoomRate'
      required:
      - hotel
    CheckRateResponse:
      description: Check Rate result.
      type: object
      properties:
        hotels:
          type: array
          description: List of hotels with their re-confirmed rates.
          items:
            $ref: '#/components/schemas/CheckRateHotelResult'
        searchId:
          type: string
          default: null
          description: Search identifier to be included in the payload of the subsequent
            calls of the booking flow, useful for correlating them.
          nullable: true
    Price:
      type: object
      properties:
        value:
          type: number
        currency:
          type: string
      required:
      - currency
      - value
    Guest:
      type: object
      properties:
        ageQualifying:
          enum:
          - ADULT
          - CHILD
          description: Age category of the guest.
        firstName:
          type: string
          description: Guest's first name.
        lastName:
          type: string
          default: null
          description: Guest's last name.
          nullable: true
        email:
          type: string
          default: null
          nullable: true
        phone:
          type: string
          default: null
          nullable: true
        dob:
          type: string
          default: null
          description: Date of birth (ISO 8601).
          nullable: true
        age:
          type: integer
          default: null
          nullable: true
        country:
          type: string
          default: null
          nullable: true
        nationality:
          type: string
          default: null
          nullable: true
        addressZipCode:
          type: string
          default: null
          nullable: true
        addressStreet:
          type: string
          default: null
          nullable: true
        addressNumber:
          type: string
          default: null
          nullable: true
        addressComplement:
          type: string
          default: null
          nullable: true
        addressDistrict:
          type: string
          default: null
          nullable: true
        addressCity:
          type: string
          default: null
          nullable: true
        addressState:
          type: string
          default: null
          nullable: true
        cpf:
          type: string
          default: null
          description: Brazilian CPF, when applicable.
          nullable: true
        rg:
          type: string
          default: null
          description: Brazilian RG, when applicable.
          nullable: true
        rgOrgaoEmissor:
          type: string
          default: null
          description: Brazilian RG's issuing organ, when applicable.
          nullable: true
        passport:
          type: string
          default: null
          nullable: true
        birthCertificate:
          type: string
          default: null
          nullable: true
      required:
      - ageQualifying
      - firstName
    HotelBookingItem:
      type: object
      properties:
        type:
          default: hotel
          enum:
          - hotel
        bookingToken:
          type: string
          description: The re-confirmed room rate to book, as returned by `v2/hotels/checkrate`
            (`roomRates[].bookingToken`). Expires 15 minutes after being issued.
        totalPrice:
          description: The room rate's total price, as returned by `v2/hotels/checkrate`
            (`roomRates[].priceComposition.total`).
          allOf:
          - $ref: '#/components/schemas/Price'
        guests:
          type: array
          description: One entry per guest staying in the room.
          items:
            $ref: '#/components/schemas/Guest'
        comments:
          type: string
          default: null
          description: Free-text special requests for the hotel (e.g. late check-in,
            accessible room).
          nullable: true
      required:
      - bookingToken
      - guests
      - totalPrice
    BookingItem:
      type: object
      properties:
        item:
          description: The product being booked.
          allOf:
          - $ref: '#/components/schemas/HotelBookingItem'
      required:
      - item
    Buyer:
      type: object
      properties:
        name:
          type: string
          default: null
          nullable: true
        email:
          type: string
          default: null
          nullable: true
    CreditCard:
      type: object
      properties:
        brand:
          type: string
          default: null
          nullable: true
        holder:
          type: string
          default: null
          nullable: true
        number:
          type: string
          default: null
          nullable: true
        expiryDate:
          type: string
          default: null
          nullable: true
        cvv:
          type: string
          default: null
          nullable: true
    PaidItem:
      type: object
      properties:
        itemIndex:
          type: integer
          description: Index into `items` this portion of the payment applies to.
        amount:
          type: number
          description: Portion of that item's totalPrice covered by this payment.
        currency:
          type: string
      required:
      - amount
      - currency
      - itemIndex
    Payment:
      type: object
      properties:
        paymentOptionId:
          type: string
          description: The payment option being charged, as returned by `v2/hotels/checkrate`
            (`roomRates[].paymentOptions[].id`).
        creditCard:
          default: null
          description: Required when the chosen payment option is a credit card.
          allOf:
          - $ref: '#/components/schemas/CreditCard'
          nullable: true
        installments:
          type: integer
          default: 1
          description: Number of installments, for payment options that support it.
        paidItems:
          type: array
          description: Which item(s) this payment covers, and how much of each.
          items:
            $ref: '#/components/schemas/PaidItem'
      required:
      - paidItems
      - paymentOptionId
    BookingPayload:
      description: Books one or more previously checked-rate room rates.
      type: object
      properties:
        items:
          type: array
          description: The item(s) to book in this single purchase.
          items:
            $ref: '#/components/schemas/BookingItem'
        buyer:
          default: null
          description: Purchaser identity, if different from all the guests.
          allOf:
          - $ref: '#/components/schemas/Buyer'
          nullable: true
        payments:
          type: array
          description: Payment(s) to charge for this purchase.
          items:
            $ref: '#/components/schemas/Payment'
        searchId:
          type: string
          default: null
          description: 'The `searchId` from the availability search/checkrate these
            room rates came from. Recommended: also drives internal cross-call correlation.'
          nullable: true
        locale:
          type: string
          default: null
          description: Desired language/locale for the response's text.
          nullable: true
      required:
      - items
      - payments
    BookingItemResult:
      type: object
      properties:
        id:
          type: string
          description: ID of the created reservation/order item.
        index:
          type: integer
          description: Index into the request's `items` this result corresponds to.
      required:
      - id
      - index
    PriceChange:
      type: object
      properties:
        id:
          type: string
        index:
          type: integer
          default: null
          nullable: true
        referenceTotal:
          type: number
          default: null
          description: The total price this item was booked at.
          nullable: true
        supplierTotal:
          type: number
          default: null
          description: The item's current, live total price.
          nullable: true
        difference:
          type: number
          default: null
          nullable: true
        currency:
          type: string
          default: null
          nullable: true
      required:
      - id
    BookingResponse:
      description: 'Booking is asynchronous: a non-`FAILED` status here does not mean
        the reservation is

        confirmed yet — only that it was accepted for processing.

        '
      type: object
      properties:
        orderId:
          type: string
        status:
          enum:
          - INPROGRESS
          - FAILED
          - PRICE_CHANGED
          description: '`PRICE_CHANGED` means the price moved since checkrate; see
            `priceChanges`. Re-submitting to confirm the new price isn''t wired up
            yet.'
        items:
          type: array
          items:
            $ref: '#/components/schemas/BookingItemResult'
        priceChanges:
          type: array
          default: null
          description: Populated only when `status` is `PRICE_CHANGED`.
          items:
            $ref: '#/components/schemas/PriceChange'
          nullable: true
      required:
      - items
      - orderId
      - status
    CancelPayload:
      description: Cancels a previously created order, in full or in part.
      type: object
      properties:
        orderId:
          type: string
          description: ID of the order to cancel, as returned by `orderId` on the
            booking response.
        itemIds:
          type: array
          default: null
          description: IDs of specific items to cancel, as returned by `items[].id`
            on the booking response. Omit to cancel the entire order.
          items:
            type: string
          nullable: true
      required:
      - orderId
    CancelItemResult:
      type: object
      properties:
        id:
          type: string
          description: ID of the cancelled item.
        success:
          type: boolean
          description: Whether this item was successfully cancelled.
        status:
          type: string
          description: Item status after the cancellation attempt.
      required:
      - id
      - status
      - success
    CancelError:
      type: object
      properties:
        code:
          type: string
          default: null
          description: Error code.
          nullable: true
        message:
          type: string
          default: null
          description: Error description.
          nullable: true
    CancelResponse:
      description: CancelResponse()
      type: object
      properties:
        orderId:
          type: string
          description: ID of the cancelled order.
        status:
          enum:
          - CANCELLED
          - FAILED
          description: '''CANCELLED'' if at least one item in the order was cancelled
            successfully, ''FAILED'' otherwise.'
        items:
          type: array
          description: Per-item cancellation results.
          items:
            $ref: '#/components/schemas/CancelItemResult'
        errors:
          type: array
          description: Unexpected errors encountered during cancellation, if any.
          items:
            $ref: '#/components/schemas/CancelError'
      required:
      - orderId
      - status
  securitySchemes:
    apiKey:
      description: Niara API Username
      type: apiKey
      name: Username
      in: header
    secretKey:
      description: Niara API Password
      type: apiKey
      name: Password
      in: header