api.yml

# swagger configuration file
openapi: '3.0.0'
info:
  description: TourConnect's Ti2 sync service
  version: 0.0.1 
  title: Ti2
  contact:
    email: engineering@tourconnect.com
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ServerInfo:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        version:
          type: string
        uptime:
          type: string
    Message:
      type: object
      properties:
        value:
          type: string
    Status:
      type: object
      properties:
        success:
          type: boolean
    JobSpec:
      type: object
      properties:
        payload:
          type: object
          description: The job app parameters
          required: true
          example: '{
            "method": "dailyReport"
          }'
        jobParams:
          type: object
          description: Additional bull job params
          example: '{
            "delay": "5000"
          }'
    JobStatus:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          example: 'active'
        result:
          type: object
          description: The job return values
          example: '{ "result": "value" }'
    App:
      type: object
      properties:
        name:
          type: string
          example: expedia
        packageName:
          type: string
          example: ti2-expedia
        adminEmail:
          type: string
          example: ti2+expedia@tourconnect.com
    AnyValue:
      description: Can be anything
      type: object
      properties:
        payload:
          type: object
          example: random lorem
    UserApp:
      description: A user + App configuration
      type: object
      properties:
        tokenHint:
          type: string
          description: An identifier for this token, it should NOT be the token itself but a short description of it
          example: 'expediaTestLocation-23'
        token:
          type: object
          description: this is the secret payload that is passed doen to the plugin
          example: { endpoint: 'http://expedia.penguin.local', apiKey: 'this is a secret key' }
    UserAppDelete:
      description: A user + App configuration to delete
      type: object
      properties:
        tokenHint:
          type: string
          description: An identifier for this token, it should NOT be the token itself but a short safe version of it
          example: 'expediaTestLocation-23'
    UserAppValidate:
      description: A user + App configuration to validate
      type: object
      properties:
        tokenHint:
          type: string
          description: An identifier for this token, it should NOT be the token itself but a short safe version of it
          example: 'expediaTestLocation-23'
    UserId:
      description: userId to create the token for
      type: object
      properties:
        userId:
          type: string
          description: the userId to create the token for
          example: '536830b6ed19afa44a000002'
    IntegrationList:
      type: object
      properties:
        integrations:
          type: array
          items:
            type: object
            properties:
              adminEmail:
                type: string
              createdAt:
                type: string
              lastSeen:
                type: string
              name:
                type: string
              packageName:
                type: string
              updatedAt:
                type: string
    UserList:
      type: object
      properties:
        users:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
              createdAt:
                type: string
              updatedAt:
                type: string
    AppTokenList:
      type: object
      properties:
        userAppKeys:
          type: array
          items:
            type: object
            properties:
              integrationId:
                type: string
              userId:
                type: string
              hint:
                type: string
              createdAt:
                type: string
              updatedAt:
                type: string
    appRequest:
      type: object
      properties:
        tokenHint:
          type: string
          example: 'expediaTestLocation-23'
          required: true
        entity:
          type: string
          required: true
        entityId:
          type: string
          required: false
          default: null
        entityParentId:
          type: string
          required: false
          default: null
    appMethods:
      type: object
      properties:
        methods:
          type: array
          items:
            type: string
    desk:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    agent:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    pickuppoint:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    bookingSearchQuery:
      type: object
      additionalProperties: true
      properties:
        bookingId:
          type: string
          required: false
          default: null
        name:
          type: string
          required: false
          default: null
        purchaseDateStart:
          type: string
          required: false
          default: null
        purchaseDateEnd:
          type: string
          required: false
          default: null
        travelDateStart:
          type: string
          required: false
          default: "01/04/2021"
        travelDateEnd:
          type: string
          required: false
          default: "10/04/2021"
        dateFormat:
          type: string
          required: false
          default: "DD/MM/YYYY"
    bookingDetail:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          required: true
          description: The booking Id
        status:
          type: string
          required: true
          description: The booking status
    bookingSearchQueryResults:
      type: object
      additionalProperties: true
      properties:
        bookings:
          type: object
          required: true
          items:
            $ref: '#/components/schemas/bookingDetail'
    bookingDetailsForCancel:
      allOf:     # Combines the BasicErrorModel and the inline model
        - $ref: '#/components/schemas/bookingDetail'
      type: object
      properties:
        clicked:
          type: integer
          required: true
          description: The unix time the cancellation was sent
    cancellationReturn:
      type: object
      properties:
        cancellation:
          type: object
          allOf:     # Combines the BasicErrorModel and the inline model
            - $ref: '#/components/schemas/bookingDetail'
    packageSearchQuery:
      type: object
      additionalProperties: true
      description: Additional properties may be included
      properties:
        packageName:
          type: string
          required: false
          description: Package Name wildcard match
          example: '*bus*'
    bookingsPackageSearchReturn:
      type: object
      additionalProperties: true
      description: Additional properties may be included
      properties:
        packages:
          type: array
          required: false
          description: Package Search Results
          items: 
            type: object
    bookingsProductQuery:
      type: object
      additionalProperties: true
      description: Additional properties may be included
      properties:
        productName:
          type: string
          required: false
          description: Product Name wildcard match
          example: '*bus*'
    bookingsProductSearchReturn:
      type: object
      additionalProperties: true
      description: Additional properties may be included
      properties:
        products:
          type: array
          required: false
          description: Product Search Results
          items: 
            type: object
        accommodation:
          type: array
          required: false,
          decription: Accommodation search results
          items:
            type: object
    pricingItem:
      type: object
      additionalProperties: true
      properties:
        original:
          type: integer
        retail:
          type: integer
        net:
          type: integer
        currency:
          type: string
          example: "USD"
        currencyPrecision:
          type: integer
        includedTaxes:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              name:
                type: string
              retail:
                type: integer
              net:
                type: integer
    availabilityItem:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          required: true
          description: An availability Id that can be used for quoting
        pricing:
          $ref: '#/components/schemas/pricingItem'
          required: false
        cancelPolicy:
          type: string
          required: false
    bookingRequest:
      type: object
      additionalProperties: true
      required: true
      properties:
        id:
          type: string
          description: a quote Id to make a reservation for
    settingsBody:
      type: object
      required: true
      properties:
        settings:
          type: object
          description: an object with the app+user seettings
paths:
  /ping:
    get:
      tags:
        - public
      summary: Should return basic system status
      operationId: ping
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
  /app:
    post:
      security:
        - bearerAuth: ['admin']
      tags:
        - admin
      summary: Should create a new App, the name of the app should be url safe (no spaces)
      operationId: createApp
      requestBody:
        description: App name to create, should be urlsafe and have a correspondant npm package already in the required npm modules as ti2-appName
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'

  /app/{appKey}:
    delete:
      security:
        - bearerAuth: ['admin']
      tags:
        - admin
      summary: Should delete an App, the name of the app should be url safe (no spaces)
      operationId: deleteApp
      parameters:
        - name: appKey
          in: path
          description: App name to delete, should be urlsafe and have a correspondant npm package already in the required npm modules as ti2-appName
          required: true
          example: 'expedia'
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /app/{appKey}/tokenTemplate:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - admin
        - user
      summary: Should return the token template
      operationId: tokenTemplate
      parameters:
        - name: appKey
          in: path
          description: Ann name to get the token template attributes
          required: true
          example: 'expedia'
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnyValue'
  /apps:
    get:
      security:
        - bearerAuth: ['admin']
      tags:
        - admin
      summary: list all previously created apps
      operationId: listApps
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationList'
  /users:
    get:
      security:
        - bearerAuth: ['admin']
      tags:
        - admin
      summary: list all created users
      operationId: listUsers
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
  /app/resetAppKey/{appKey}:
    get:
      security:
        - bearerAuth: ['admin']
      tags:
        - admin
      summary:
        reset an auth token for an integration
      operationId: resetIntegrationToken
      parameters:
        - name: appKey
          in: path
          description: name of the app to reset the apiKey
          required: true
          example: 'expedia'
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /user:
    post:
      security:
        - bearerAuth: ['admin']
      tags:
        - admin
      summary: Create a new user authentication token
      operationId: createUserToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserId'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /app/encode/{app}:
    security:
      - bearerAuth: ['app']
    put:
      tags:
        - app
      summary: Should encode an arbitriary field body into a hash
      security:
        - bearerAuth: ['app']
      operationId: jwtEncode
      parameters:
        - name: app
          in: path
          description: name of the requesting app
          required: true
          example: 'expedia'
          schema:
            type: string
      requestBody:
        description: Payload to encode
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnyValue'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /app/tokens/{app}:
    get:
      security:
        - bearerAuth: ['app']
      tags:
        - app
      summary: List all users/tokens for this app
      operationId: listAppTokens
      parameters:
        - name: app
          in: path
          description: app name to list the users for
          example: 'expedia'
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppTokenList'
  /{app}/{userId}:
    security:
      - bearerAuth: ['app']
    post:
      tags:
        - app
        - user
        - admin
      summary: Create a user app+Token configuration, the authorization can be either from the app or the user
      security:
        - bearerAuth: ['app', 'user', 'admin']
      operationId: createAppToken
      parameters:
        - name: app
          in: path
          description: app name to create the userId for (must match app token)
          example: 'expedia'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: user to create the app for
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      requestBody:
        description: A new User+App configuration
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserApp'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
    delete:
      tags:
        - app
        - user
      summary: Should delete a user+appToken configuration, the auth token can be from an app or a user
      security:
        - bearerAuth: ['admin', 'app', 'user']
      operationId: deleteAppToken
      parameters:
        - name: app
          in: path
          description: app name to create the userId for (must match app token)
          example: 'expedia'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: user to delete the app for
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      requestBody:
        description: The User+App configuration to remove
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAppDelete'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
    put:
      tags:
        - app
        - user
      summary: Should update a user+appToken configuration
      security:
        - bearerAuth: ['admin', 'app', 'user']
      operationId: updateAppToken
      parameters:
        - name: app
          in: path
          description: app name to read the userId for (must match app token)
          example: 'expedia'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: user to read the app token for
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      requestBody:
        description: The User+App configuration to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAppDelete'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /{app}/{userId}/{hint}/token:
    get:
      tags:
        - app
        - user
        - admin
      summary: Get a user app+Token configuration, the authorization can be either from the app or the user
      security:
        - bearerAuth: ['app', 'user', 'admin']
      operationId: getAppToken
      parameters:
        - name: app
          in: path
          description: app name to read the userId for (must match app token)
          example: 'expedia'
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
        - name: userId
          in: path
          description: user to read the app token for
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserApp'
  /{app}/{userId}/token:
    get:
      tags:
        - app
        - user
        - admin
      summary: Get a user app+Token configuration, the authorization can be either from the app or the user, it will return the first token found (since no hint is required)
      security:
        - bearerAuth: ['app', 'user', 'admin']
      operationId: getAppToken
      parameters:
        - name: app
          in: path
          description: app name to read the userId for (must match app token)
          example: 'expedia'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: user to read the app token for
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserApp'
  /{app}/{userId}/validate:
    post:
      tags:
        - app
        - user
      summary: Should delete a user+appToken configuration, the auth token can be from an app or a user
      security:
        - bearerAuth: ['admin', 'app', 'user']
      operationId: validateAppToken
      parameters:
        - name: app
          in: path
          description: app name to validate (must match app token)
          example: 'expedia'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: owner of the token to validate
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      requestBody:
        description: The User+App configuration to validate
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAppValidate'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'

  /{app}/{userId}/jobRun:
    security:
      - bearerAuth: ['app', 'user', 'admin']
    post:
      tags:
        - jobs
      summary: Run a Job
      security:
        - bearerAuth: ['app', 'user', 'admin']
      operationId: runAppJob
      parameters:
        - name: app
          in: path
          description: app that defines the job
          example: 'ventrata'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: user to run the schedule app against
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      requestBody:
        description: The job parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobSpec'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
  /{app}/{userId}/{hint}/jobRun:
    security:
      - bearerAuth: ['app', 'user', 'admin']
    post:
      tags:
        - jobs
      summary: Run a schedule Job
      security:
        - bearerAuth: ['app', 'user', 'admin']
      operationId: runAppJob
      parameters:
        - name: app
          in: path
          description: app that defines the job
          example: 'ventrata'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: user to run the schedule app against
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: The job parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobSpec'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
  /{app}/{userId}/{jobId}/jobStatus:
    security:
      - bearerAuth: ['app', 'user', 'admin']
    get:
      tags:
        - jobs
      summary: Get the status and/or result from a job
      security:
        - bearerAuth: ['app', 'user', 'admin']
      operationId: getJobStatus
      parameters:
        - name: app
          in: path
          description: app that defines the job
          example: 'ventrata'
          required: true
          schema:
            type: string
        - name: userId
          in: path
          description: user that owns the job
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
        - name: jobId
          in: path
          description: jobId to get the status for
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
  /user/{userId}/apps:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - user
        - admin
      summary: Should get a list of app keys tokens that belong to a user
      operationId: userAppList
      parameters:
        - name: userId
          in: path
          description: id of the owner
          example: '536830b6ed19afa44a000002'
          required: true
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppTokenList'
  /app/{appKey}/methods:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - user
      summary: Should get the methods available for an app
      operationId: getAppMethods
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the methods for
          required: true
          example: 'expedia'
          schema:
            type: string
      responses:
        200:
          description: the methods available
          content:
            appication/json:
              schema:
                $ref: '#/components/schemas/appMethods'
  /settings/{appKey}/{userId}:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - user
      summary: Creates user settings for an app, shared across tokens per user
      operationId: createAppSettings
      parameters:
        - name: appKey
          in: path
          description: name of the app to use for the settings
          required: true
          example: 'expedia'
          schema:
            type: string
        - name: userId
          in: path
          description: user id for the setting to be created
          required: true
          example: '536830b6ed19afa44a000002'
          schema:
            type: string
      requestBody:
        description: Creation Payload
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/settingsBody'
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - user
      summary: Retrieves a user settings for an app, shared across tokens per user
      operationId: getAppSettings
      parameters:
        - name: appKey
          in: path
          description: name of the app to use for the settings
          required: true
          example: 'expedia'
          schema:
            type: string
        - name: userId
          in: path
          description: user id for the setting to be created
          required: true
          example: '536830b6ed19afa44a000002'
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/settingsBody'
    delete:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - user
      summary: Deletes a user settings for an app, shared across tokens per user
      operationId: deleteAppSettings
      parameters:
        - name: appKey
          in: path
          description: name of the app to use for the settings
          required: true
          example: 'expedia'
          schema:
            type: string
        - name: userId
          in: path
          description: user id for the setting to be created
          required: true
          example: '536830b6ed19afa44a000002'
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
                $ref: '#/components/schemas/Status'
  /{appKey}/{userId}/affiliates:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all affiliates for this user
      operationId: getAffiliates
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the affiliates for (defaults to first token found)
          required: true
          example: 'xola'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: affiliates
          content:
            application/json:
              schema:
                type: object
                properties:
                  affiliates:
                    type: array
  /{appKey}/{userId}/{hint}/affiliates:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all affiliates for this user
      operationId: getAffiliates
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the affiliates for the token using the hint
          required: true
          example: 'xola'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'xola-helloworld'
          schema:
            type: string
      responses:
        '200':
          description: affiliates
          content:
            application/json:
              schema:
                type: object
                properties:
                  affiliates:
                    type: array
  /affiliate/{appKey}/{userId}/desks:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all desks for this affiliate
      operationId: getAffiliateDesks
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the desks for (defaults to first token found)
          required: true
          example: 'fareharbor'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: desks
          content:
            application/json:
              schema:
                type: object
                properties:
                  desks:
                    type: array
                    items:
                      $ref: '#/components/schemas/desk'
  /affiliate/{appKey}/{userId}/{hint}/desks:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all desks for this affiliate
      operationId: getAffiliateDesks
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the desks for the token using the hint
          required: true
          example: 'fareharbor'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'fareharbor-helloworld'
          schema:
            type: string
      responses:
        '200':
          description: desks
          content:
            application/json:
              schema:
                type: object
                properties:
                  desks:
                    type: array
                    items:
                      $ref: '#/components/schemas/desk'
  /affiliate/{appKey}/{userId}/agents:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all agents for this affiliate
      operationId: getAffiliateAgents
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the agents for (defaults to first token found)
          required: true
          example: 'fareharbor'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/agent'
  /affiliate/{appKey}/{userId}/{hint}/agents:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all agents for this affiliate
      operationId: getAffiliateAgents
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the agents for the token using the hint
          required: true
          example: 'fareharbor'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'fareharbor-helloworld'
          schema:
            type: string
      responses:
        '200':
          description: agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/agent'
  /{appKey}/{userId}/pickup-points:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all pickup points for this supplier
      operationId: getPickupPoints
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the pickup points from (defaults to first token found)
          required: true
          example: 'fareharbor'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: pickup points
          content:
            application/json:
              schema:
                type: object
                properties:
                  pickupPoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/pickuppoint'
  /{appKey}/{userId}/{hint}/pickup-points:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all pickup points for this supplier
      operationId: getPickupPoints
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the pickup points from (defaults to first token found) using the hint
          required: true
          example: 'fareharbor'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'fareharbor-helloworld'
          schema:
            type: string
      responses:
        '200':
          description: pickup points
          content:
            application/json:
              schema:
                type: object
                properties:
                  pickupPoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/pickuppoint'
  /bookings/{appKey}/{userId}/search:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all Bookings related to the search
      operationId: bookingsSearch
      parameters:
        - name: appKey
          in: path
          description: name of the app to search the bookings for (defaults to first token found
          required: true
          example: 'travelgate'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: both app details
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingSearchQuery'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookingSearchQueryResults'
  /bookings/{appKey}/{userId}/{hint}/search:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all Bookings related to the search for a specific hint
      operationId: bookingsSearch
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the methods for
          required: true
          example: 'travelgate'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belogs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: booking search parameters
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingSearchQuery'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookingSearchQueryResults'
  /bookings/{appKey}/{userId}/cancel:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Sends a Booking cancellation
      operationId: bookingsCancel
      parameters:
        - name: appKey
          in: path
          description: app to cancel the booking for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: both app details
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingDetailsForCancel'
      responses:
        '200':
          description: Cancellation confirmation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancellationReturn'
  /bookings/{appKey}/{userId}/{hint}/cancel:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Sends a Booking cancellation for an specific hint
      operationId: bookingsCancel
      parameters:
        - name: appKey
          in: path
          description: app to cancel the booking for
          required: true
          example: 'travelgate'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: both app details
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingDetailsForCancel'
      responses:
        '200':
          description: Cancellation confirmation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancellationReturn'
  /packages/{appKey}/{userId}/search:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Package Search
      operationId: getProductPackages
      parameters:
        - name: appKey
          in: path
          description: app to search the booking packages, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: Search query
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/packageSearchQuery'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookingsPackageSearchReturn'
  /packages/{appKey}/{userId}/{hint}/search:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Package Search using for an specific hint
      operationId: getProductPackages
      parameters:
        - name: appKey
          in: path
          description: app to search the booking packages, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: Search query
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/packageSearchQuery'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookingsPackageSearchReturn'
  /products/{appKey}/{userId}/search:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Product Search
      operationId: bookingsProductSearch
      parameters:
        - name: appKey
          in: path
          description: app to search the booking products, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: Search query
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingsProductQuery'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookingsProductSearchReturn'
  /products/{appKey}/{userId}/{hint}/search:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Product Search using for an specific hint
      operationId: bookingsProductSearch
      parameters:
        - name: appKey
          in: path
          description: app to search the booking products, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: Search query
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingsProductQuery'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookingsProductSearchReturn'
  /bookings/{appKey}/{userId}/availabilitycalendar:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Availability Search
      operationId: bookingsAvailabilityCalendar
      parameters:
        - name: appKey
          in: path
          description: app to search availability for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: both app details
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnyValue'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  availability:
                    type: array
                    required: true
                    items:
                      $ref: '#/components/schemas/availabilityItem'
  /bookings/{appKey}/{userId}/{hint}/availabilitycalendar:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Availability Search for an specific hint
      operationId: bookingsAvailabilityCalendar
      parameters:
        - name: appKey
          in: path
          description: app to search availability for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: both app details
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnyValue'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  availability:
                    type: array
                    required: true
                    items:
                      $ref: '#/components/schemas/availabilityItem'
  /bookings/{appKey}/{userId}/availability:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Availability Search
      operationId: bookingsAvailabilitySearch
      parameters:
        - name: appKey
          in: path
          description: app to search availability for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: both app details
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnyValue'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  availability:
                    type: array
                    required: true
                    items:
                      $ref: '#/components/schemas/availabilityItem'
  /bookings/{appKey}/{userId}/{hint}/availability:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Availability Search for an specific hint
      operationId: bookingsAvailabilitySearch
      parameters:
        - name: appKey
          in: path
          description: app to search availability for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: both app details
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnyValue'
      responses:
        '200':
          description: search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  availability:
                    type: array
                    required: true
                    items:
                      $ref: '#/components/schemas/availabilityItem'
  /bookings/{appKey}/{userId}/quote:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Quote an Availability
      operationId: searchQuote
      parameters:
        - name: appKey
          in: path
          description: app to quote availability for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: Availability spec to be quoted
        required:  true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                id:
                  type: string
                  required: true
                  description: An availability Id to quote
      responses:
        '200':
          description: Quote Details
          content:
            application/json:
              schema:
                type: object
                required: true
                properties:
                  quote:
                    type: array
                    required: true
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        id:
                          type: string
                          description: a quote Id that can be use to book
  /bookings/{appKey}/{userId}/{hint}/quote:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Quote an Availability for an specific hint
      operationId: searchQuote
      parameters:
        - name: appKey
          in: path
          description: app to quote the availability for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: Availability spec to be quoted
        required:  true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                id:
                  type: string
                  required: true
                  description: An availability Id to quote
      responses:
        '200':
          description: Quote Details
          content:
            application/json:
              schema:
                type: object
                required: true
                properties:
                  quote:
                    type: array
                    required: true
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        id:
                          type: string
                          description: a quote Id that can be use to book
  /bookings/{appKey}/{userId}/booking:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Create a Booking
      operationId: createBooking
      parameters:
        - name: appKey
          in: path
          description: app to create the booking for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      requestBody:
        description: Booking creation payload
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingRequest'
      responses:
        '200':
          description: Booking Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnyValue'
  /bookings/{appKey}/{userId}/{hint}/booking:
    post:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Create a Booking for an specific hint
      operationId: createBooking
      parameters:
        - name: appKey
          in: path
          description: app to create the booking for, defaults to first token
          required: true
          example: 'travelgate-hotelx'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'travelgate-australia'
          schema:
            type: string
      requestBody:
        description: Booking creation payload
        required:  true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bookingRequest'
      responses:
        '200':
          description: Booking Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnyValue'
  /bookings/{appKey}/{userId}/custom-fields:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all custom fields for creating a booking
      operationId: getCreateBookingFields
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the resource for (defaults to first token found)
          required: true
          example: 'fareharbor'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
  /bookings/{appKey}/{userId}/{hint}/custom-fields:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - bookings
      summary: Gets all custom fields for creating a booking
      operationId: getCreateBookingFields
      parameters:
        - name: appKey
          in: path
          description: name of the app to get the resource for the token using the hint
          required: true
          example: 'xola'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'xola-helloworld'
          schema:
            type: string
      responses:
        '200':
          description: fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
  
  /allotment/{appKey}/{userId}:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - allotment
      summary: Query the allotment
      operationId: queryAllotment
      parameters:
        - name: appKey
          in: path
          description: app to create the booking for, defaults to first token
          required: true
          example: 'tourplan'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - in: query
          name: startDate
          schema:
            type: string
          description: the start date of the requested allotment (dd/mm/yyyy)
          default: "01/04/2023"
        - in: query
          name: endDate
          schema:
            type: string
          description: the end date of the requested allotment (dd/mm/yyyy)
          default: "03/04/2023"
        - in: query
          name: keyPath
          schema:
            type: string
          description: a string with the product path separater by pipes ie. supplierId|locationId|productID
          default: "MAGLUX|7CQLDACMAGLUXDELSUI"
      responses:
        '200':
          description: Allotment Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnyValue'
  /allotment/{appKey}/{hint}/{userId}:
    get:
      security:
        - bearerAuth: ['admin', 'user']
      tags:
        - allotment
      summary: Query the allotment with an specific hit
      operationId: queryAllotment
      parameters:
        - name: appKey
          in: path
          description: app to create the booking for, defaults to first token
          required: true
          example: 'tourplan'
          schema:
            type: string
        - name: hint
          in: path
          description: a specific token hint to be used
          required: true
          example: 'tourplan-australia'
          schema:
            type: string
        - name: userId
          in: path
          description: the user/company that the appKey belongs to
          required: true
          schema:
            type: string
        - in: query
          name: startDate
          schema:
            type: string
          description: the start date of the requested allotment (dd/mm/yyyy)
          default: "01/04/2023"
        - in: query
          name: endDate
          schema:
            type: string
          description: the end date of the requested allotment (dd/mm/yyyy)
          default: "03/04/2023"
        - in: query
          name: keyPath
          schema:
            type: string
          description: a string with the product path separater by pipes ie. supplierId|locationId|productID
          default: "MAGLUX|7CQLDACMAGLUXDELSUI"
      responses:
        '200':
          description: Allotment Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnyValue'