openapi: 3.0.1
info:
  title: RateHawk / ETG API (WorldOta APIv3)
  description: >-
    B2B hotel and travel booking API operated by Emerging Travel Group (ETG)
    and exposed to partners as the RateHawk API. The Partner API (pAPI) v3
    covers hotel search (SERP by region, hotels, and geo), hotelpage rate
    actualization, prebook, the asynchronous order booking flow (form, finish,
    finish status), order information, cancellation, and static hotel content.
    All endpoints are HTTP POST that accept and return JSON and authenticate
    with HTTP Basic using a key id (username) and key (password).
  termsOfService: https://www.ratehawk.com/
  contact:
    name: ETG API Support
    url: https://docs.emergingtravel.com/
  version: '3.0'
servers:
  - url: https://api.worldota.net/api/b2b/v3
    description: Production
  - url: https://api-sandbox.worldota.net/api/b2b/v3
    description: Sandbox / test
security:
  - basicAuth: []
tags:
  - name: Hotel Search
  - name: Prebook
  - name: Booking
  - name: Orders
  - name: Hotel Content
  - name: Cancellation
paths:
  /overview/:
    get:
      operationId: getOverview
      tags:
        - Orders
      summary: Endpoints overview
      description: >-
        Returns the list of all endpoints available for your contract and
        their settings.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
  /search/serp/region/:
    post:
      operationId: searchRegion
      tags:
        - Hotel Search
      summary: Search Engine Results Page by region
      description: >-
        Preliminary search (SERP) for hotels with available accommodation
        within a region that matches the given search conditions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegionSearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /search/serp/hotels/:
    post:
      operationId: searchHotels
      tags:
        - Hotel Search
      summary: Search Engine Results Page by hotel IDs
      description: >-
        Preliminary search (SERP) for a specific set of hotels by their
        identifiers matching the given search conditions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelsSearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /search/serp/geo/:
    post:
      operationId: searchGeo
      tags:
        - Hotel Search
      summary: Search Engine Results Page by geo coordinates
      description: >-
        Preliminary search (SERP) for hotels within a radius of the given
        latitude and longitude.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeoSearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /search/hp/:
    post:
      operationId: searchHotelPage
      tags:
        - Hotel Search
      summary: Retrieve hotelpage
      description: >-
        Hotel rates actualization for a single hotel. Should be requested only
        after the user has chosen the hotel; returns the up-to-date set of
        bookable rates with their book_hash values.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelPageRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /hotel/prebook/:
    post:
      operationId: hotelPrebook
      tags:
        - Prebook
      summary: Prebook rate from hotelpage step
      description: >-
        Updates the availability and price of the requested rate and attempts
        to find a comparable or similar rate if the original is unavailable.
        Use price_increase_percent to bound how much higher the new price may
        be than the original.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrebookRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
  /hotel/order/booking/form/:
    post:
      operationId: orderBookingForm
      tags:
        - Booking
      summary: Create booking process (order booking form)
      description: >-
        Creates a new reservation process from a prebooked rate's book_hash.
        The process of reserving a rate includes several stages depending on
        whether 3-D Secure and/or fraud checks are required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderBookingFormRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
  /hotel/order/booking/finish/:
    post:
      operationId: orderBookingFinish
      tags:
        - Booking
      summary: Order booking finish
      description: >-
        Completes the reservation. The reservation is carried out
        asynchronously: the partner launches the process via this call and
        then repeatedly polls Order Booking Finish Status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderBookingFinishRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
  /hotel/order/booking/finish/status/:
    post:
      operationId: orderBookingFinishStatus
      tags:
        - Booking
      summary: Order booking finish status
      description: >-
        Status check for the asynchronous order completion process. Poll this
        endpoint until processing changes to ok or a final failure status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderBookingFinishStatusRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
  /hotel/order/info/:
    post:
      operationId: orderInfo
      tags:
        - Orders
      summary: Order information
      description: >-
        Retrieves a created order's information by the partner's booking
        identifier. Relevant only for reservations that were successfully
        created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInfoRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
  /hotel/order/cancel/:
    post:
      operationId: orderCancel
      tags:
        - Cancellation
      summary: Order cancellation
      description: >-
        Cancels a booking by the partner's booking identifier. Relevant for
        reservations with completed / rejected status; allows cancellation of
        non-refundable bookings with applicable charges.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCancelRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
  /hotel/info/:
    post:
      operationId: hotelInfo
      tags:
        - Hotel Content
      summary: Hotel data search (static content)
      description: >-
        Static hotel content lookup by hotel identifier, including address,
        amenities, descriptions, images, metapolicy, room groups, and star
        rating. Used to fill gaps not present in the hotel data dump.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelInfoRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelInfoResponse'
  /hotel/info/dump/:
    post:
      operationId: hotelInfoDump
      tags:
        - Hotel Content
      summary: Hotel data dump
      description: >-
        Returns a URL to the archive of all available ETG hotels' static data
        for one language. The dump is regenerated daily.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelInfoDumpRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. The username is the API key id and the
        password is the API key (uuid). Both are issued per contract for the
        test (sandbox) and production environments.
  schemas:
    GuestsGroup:
      type: object
      required:
        - adults
      properties:
        adults:
          type: integer
        children:
          type: array
          items:
            type: integer
    BaseSearchRequest:
      type: object
      required:
        - checkin
        - checkout
        - guests
      properties:
        checkin:
          type: string
          format: date
        checkout:
          type: string
          format: date
        currency:
          type: string
        residency:
          type: string
        language:
          type: string
        timeout:
          type: integer
        guests:
          type: array
          items:
            $ref: '#/components/schemas/GuestsGroup'
    RegionSearchRequest:
      allOf:
        - $ref: '#/components/schemas/BaseSearchRequest'
        - type: object
          required:
            - region_id
          properties:
            region_id:
              type: integer
    HotelsSearchRequest:
      allOf:
        - $ref: '#/components/schemas/BaseSearchRequest'
        - type: object
          required:
            - ids
          properties:
            ids:
              type: array
              items:
                type: string
    GeoSearchRequest:
      allOf:
        - $ref: '#/components/schemas/BaseSearchRequest'
        - type: object
          required:
            - latitude
            - longitude
            - radius
          properties:
            latitude:
              type: number
              format: float
            longitude:
              type: number
              format: float
            radius:
              type: integer
    HotelPageRequest:
      allOf:
        - $ref: '#/components/schemas/BaseSearchRequest'
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: Hotel identifier.
    PrebookRequest:
      type: object
      required:
        - hash
      properties:
        hash:
          type: string
          description: book_hash of the rate selected on the hotelpage step.
        price_increase_percent:
          type: integer
          description: >-
            Maximum percent the actualized price may exceed the original price.
    OrderBookingFormRequest:
      type: object
      required:
        - partner_order_id
        - book_hash
      properties:
        partner_order_id:
          type: string
          description: Unique partner booking identifier.
        book_hash:
          type: string
        language:
          type: string
        user_ip:
          type: string
    OrderBookingFinishRequest:
      type: object
      required:
        - partner_order_id
        - user
        - rooms
        - payment_type
      properties:
        partner_order_id:
          type: string
        language:
          type: string
        user:
          type: object
          properties:
            email:
              type: string
            phone:
              type: string
            comment:
              type: string
        rooms:
          type: array
          items:
            type: object
            properties:
              guests:
                type: array
                items:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
        payment_type:
          type: object
          properties:
            type:
              type: string
            amount:
              type: string
            currency_code:
              type: string
    OrderBookingFinishStatusRequest:
      type: object
      required:
        - partner_order_id
      properties:
        partner_order_id:
          type: string
    OrderInfoRequest:
      type: object
      properties:
        ordering:
          type: object
        pagination:
          type: object
        search:
          type: object
          properties:
            partner_order_ids:
              type: array
              items:
                type: string
    OrderCancelRequest:
      type: object
      required:
        - partner_order_id
      properties:
        partner_order_id:
          type: string
          minLength: 1
          maxLength: 256
          description: Unique partner booking identifier.
    HotelInfoRequest:
      type: object
      required:
        - id
        - language
      properties:
        id:
          type: string
        language:
          type: string
    HotelInfoDumpRequest:
      type: object
      required:
        - language
      properties:
        language:
          type: string
        inventory:
          type: string
    Region:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        country_code:
          type: string
        iata:
          type: string
        type:
          type: string
    HotelInfoData:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        star_rating:
          type: integer
        kind:
          type: string
        images:
          type: array
          items:
            type: string
        region:
          $ref: '#/components/schemas/Region'
        is_closed:
          type: boolean
    HotelInfoResponse:
      type: object
      properties:
        status:
          type: string
        error:
          type: string
          nullable: true
        data:
          $ref: '#/components/schemas/HotelInfoData'
    SearchResponse:
      type: object
      properties:
        status:
          type: string
        error:
          type: string
          nullable: true
        data:
          type: object
          properties:
            hotels:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  rates:
                    type: array
                    items:
                      type: object
            total_hotels:
              type: integer
    BaseResponse:
      type: object
      properties:
        status:
          type: string
          description: ok or error.
        error:
          type: string
          nullable: true
        debug:
          type: object
          nullable: true
        data:
          type: object
          nullable: true