hotel-reservations-api-spec-2.yaml

openapi: 3.0.0
info:
    version: 1.0.0
    title: Hotel Reservations API
    description: API to manage hotel room bookings, check availability, and apply loyalty benefits.
x-sfdc:
    agent:
        topic:
            name: Hotel_Room_Reservation
            classificationDescription: This API allows agents to book, modify, and cancel hotel reservations, as well as apply loyalty upgrades.
            scope: Your job is to assist customers in booking hotel rooms based on their preferences, loyalty status, and availability. You should also be able to recommend upgrades if the customer qualifies.
            instructions:
                - Always check the customer's loyalty status before finalizing the booking.
                - If the customer asks to create a reservation, check for a check-in date, checkout date, roomType, or any special requests.
                - If the preferred room type is unavailable, suggest alternative options with similar amenities.
                - Never confirm a reservation without validating payment information.
                - If the customer qualifies for an upgrade, apply it automatically and notify them.
paths:
    /reservations:
        post:
            summary: Create a new hotel reservation
            description: Book a hotel room with specified preferences and apply loyalty upgrades if eligible.
            operationId: reservationCreate
            x-sfdc:
                agent:
                    action:
                        publishAsAgentAction: true
            parameters:
                -
                    in: query
                    name: source
                    required: false
                    schema:
                        type: string
                    description: Source of the reservation request (e.g., web, mobile app, agent).
                    x-sfdc:
                        agent:
                            action:
                                isUserInput: true
            requestBody:
                required: true
                description: Customer reservation details including stay dates, room type, and special requests.
                content:
                    application/json:
                        schema:
                            additionalProperties: false
                            type: object
                            x-sfdc:
                                agent:
                                    action:
                                        isUserInput: true
                            properties:
                                customerId:
                                    type: string
                                    description: Unique identifier of the customer making the reservation.
                                checkInDate:
                                    type: string
                                    description: Date of check-in for the reservation.
                                checkOutDate:
                                    type: string
                                    description: Date of check-out for the reservation.
                                roomType:
                                    type: string
                                    description: Preferred room type for the reservation.
                                specialRequests:
                                    type: string
                                    description: Additional requests like pillow type or air freshener choice.
            responses:
                '201':
                    description: Reservation successfully created.
                    content:
                        application/json:
                            schema:
                                additionalProperties: false
                                type: object
                                x-sfdc:
                                    agent:
                                        action:
                                            isDisplayable: true
                                    privacy:
                                        isPii: true
                                properties:
                                    reservationId:
                                        type: string
                                        description: Unique identifier of the created reservation.
                                    upgradeApplied:
                                        type: boolean
                                        description: Indicates whether a loyalty-based upgrade was applied.
                                    totalPrice:
                                        type: number
                                        description: Final price after applying any discounts or upgrades.

    /reservations/{reservationID}:
        get:
            summary: Retrieve reservation details
            description: Get details of a specific reservation by ID.
            operationId: reservationRetrieve
            x-sfdc:
                agent:
                    action:
                        publishAsAgentAction: true
            parameters:
                -
                    in: path
                    name: reservationID
                    required: true
                    schema:
                        type: string
                    description: Unique identifier of the reservation to be retrieved.
                    x-sfdc:
                        agent:
                            action:
                                isUserInput: true
            responses:
                '200':
                    description: Reservation details retrieved successfully.
                    content:
                        application/json:
                            schema:
                                additionalProperties: false
                                x-sfdc:
                                    agent:
                                        action:
                                            isDisplayable: true
                                    privacy:
                                        isPii: true
                                type: object
                                properties:
                                    reservationId:
                                        type: string
                                        description: Unique identifier of the reservation.
                                    customerId:
                                        type: string
                                        description: Unique identifier of the customer who booked the reservation.
                                    roomType:
                                        type: string
                                        description: Type of room booked for the reservation.
                                    checkInDate:
                                        type: string
                                        description: Check-in date of the reservation.
                                    checkOutDate:
                                        type: string
                                        description: Check-out date of the reservation.
                                    upgradeApplied:
                                        type: boolean
                                        description: Indicates whether a loyalty-based upgrade was applied.