openapi: 3.0.3
info:
  title: RoomKeyPMS POS Statistics API
  description: 'RoomKeyPMS''s REST API for pulling reservation and guest data, posting POS charges to a guest folio, and pulling hotel statistics/receipts. Endpoint paths, parameters, and behavior are taken directly from RoomKeyPMS''s public support documentation and version release notes. The API is partner-gated: an API key and per-hotel credentials are issued only after a hotel''s IT team emails RoomKeyPMS support and the property signs off. Responses can be requested as JSON or XML via the request header. There is no endpoint that returns only records changed since the last call; RoomKeyPMS recommends polling on a 10-15 minute cadence without parallel calls, staggered across properties for multi-property integrations. Date-ranged endpoints are capped at a 60-day window. The exact production base host is not published as a standalone value by RoomKeyPMS; it is inferred here from RoomKeyPMS''s own Help/reference portal and should be confirmed once a partner API key is issued.'
  version: 2.8.0.2
  contact:
    name: RoomKeyPMS Support
    url: https://support.roomkeypms.com/a/972656-api-documentation
servers:
- url: https://www.welcometorsi.net/RoomkeyApi/api
  description: RoomKeyPMS production API (base host inferred from the public Help/reference portal; confirm with issued credentials)
security:
- apiKeyAuth: []
tags:
- name: Statistics
  description: Hotel statistics and transaction receipts.
paths:
  /hotels/{hotelId}/statistics/receipts:
    get:
      operationId: listReceipts
      tags:
      - Statistics
      summary: List transaction receipts
      description: Returns transaction/receipt records for a hotel over a date range, including a transaction time for each record. Since API v2.8.0.2, reservation-linked records also carry a ReservationUniqueID array of channel-partner confirmation numbers (ShortCode, Name, ConfirmationNumber) for integrations such as Booking.com, Expedia, SynXis, and TravelClick.
      parameters:
      - $ref: '#/components/parameters/HotelId'
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FromDate'
      - $ref: '#/components/parameters/ToDate'
      responses:
        '200':
          description: A list of transaction receipts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Receipt'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    ApiKeyParam:
      name: key
      in: query
      required: true
      description: API key for the requesting integration.
      schema:
        type: string
    HotelId:
      name: hotelId
      in: path
      required: true
      description: The RoomKeyPMS-assigned identifier for the hotel/property.
      schema:
        type: string
    FromDate:
      name: fromDate
      in: query
      required: true
      description: Start of the date range (local property timezone). Combined with toDate, capped at a 60-day maximum range.
      schema:
        type: string
        format: date
    ToDate:
      name: toDate
      in: query
      required: true
      description: End of the date range (local property timezone). Combined with fromDate, capped at a 60-day maximum range.
      schema:
        type: string
        format: date
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Receipt:
      type: object
      properties:
        transactionId:
          type: string
        transactionTime:
          type: string
          format: date-time
        amount:
          type: number
        details:
          type: string
        reservationUniqueId:
          type: array
          items:
            $ref: '#/components/schemas/ChannelConfirmation'
    ChannelConfirmation:
      type: object
      properties:
        shortCode:
          type: string
          example: BKG
        name:
          type: string
          example: Booking.com
        confirmationNumber:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: key
      description: API key issued by RoomKeyPMS after a hotel's IT team requests access and the property signs off.