Offers API Documentation¶

Overview¶

The Offers API provides endpoints for managing hotel offers, inquiries, and reservations. These endpoints allow clients to retrieve available room types, create customized offers, generate email templates, and process reservation requests.

Base URL¶

1	`https://[environment-url]`

Environment URLs: - Production: https://bookingservice.apps.gustaffo.com - UAT: https://bookingservice.uat.apps.gustaffo.com - Development: https://bookingservice.dev.apps.gustaffo.com

Authentication¶

Most API endpoints require authentication via OAuth2/JWT tokens. The following roles are used for access control: - ROLE_reservationmanager: Hotel reservation managers - ROLE_admin: System administrators - ROLE_web: Web application access

Some public endpoints are available without authentication for customer-facing applications.

Endpoints¶

List Enabled Hotels¶

Returns a list of hotels that are enabled in the system and that the authenticated user has access to.

1	`GET /enabledhotels`

Authorization¶

Requires ROLE_reservationmanager or ROLE_admin

Response¶

[
  {
    "id": "10001",
    "name": "Hotel Example",
    "description": "A luxury hotel example",
    "address": {
      "street": "Example Street 1",
      "city": "Vienna",
      "country": "Austria",
      "postalCode": "1010"
    },
    "email": "reservations@example.com",
    "phone": "+43 1 123456",
    "website": "https://www.example.com",
    "status": "ENABLED",
    "connectorType": "TRAVEL_CLICK"
  },
  {
    "id": "10002",
    "name": "Mountain Resort",
    "description": "Mountain resort example",
    "address": {
      "street": "Mountain Road 5",
      "city": "Salzburg",
      "country": "Austria",
      "postalCode": "5020"
    },
    "email": "reservations@mountainresort.com",
    "phone": "+43 662 123456",
    "website": "https://www.mountainresort.com",
    "status": "ENABLED",
    "connectorType": "PHOBS"
  }
]

Preview Offer Template¶

Generates a preview of an offer email template based on reservation details.

1	`POST /reservationOffer/template`

Authorization¶

Requires ROLE_reservationmanager or ROLE_admin

Request Body¶

{
  "language": "en",
  "startDate": "2023-07-15",
  "endDate": "2023-07-20",
  "numberAdults": 2,
  "numberChildren": 1,
  "ageChildren": [8],
  "numberRooms": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "hotelRequests": [
    {
      "hotelId": "10001",
      "rooms": []
    }
  ],
  "src": "Website"
}

Response¶

Returns an array of EmailTemplate objects with rendered templates:

[
  {
    "hotel": "Hotel Example",
    "templateContent": "<html>...</html>",
    "subject": "Your Reservation Offer",
    "inquiryId": null
  }
]

Submit Reservation Offer¶

Processes a reservation offer request and sends email confirmations.

1	`POST /reservationOffer`

Authorization¶

Requires ROLE_reservationmanager or ROLE_admin

Request Headers¶

Header	Required	Description
referer	No	Referring URL

Request Parameters¶

Parameter	Required	Description
asm-ticket	No	ASM ticket ID for tracking

Request Body¶

{
  "language": "en",
  "startDate": "2023-07-15",
  "endDate": "2023-07-20",
  "numberAdults": 2,
  "numberChildren": 1,
  "ageChildren": [8],
  "numberRooms": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "hotelRequests": [
    {
      "hotelId": "10001",
      "rooms": []
    }
  ],
  "src": "Website"
}

Response¶

{
  "status": 200,
  "message": "Offer(s) sent successfully"
}

Submit Customer Offer Request¶

Endpoint for customers to submit offer requests directly.

1	`POST /offerRequest`

Request Body¶

{
  "language": "en",
  "startDate": "2023-07-15",
  "endDate": "2023-07-20",
  "numberAdults": 2,
  "numberChildren": 1,
  "ageChildren": [8],
  "numberRooms": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "hotelId": "10001",
  "textField": "Special requests go here",
  "customIntroduction": "Custom introduction text",
  "src": "Website"
}

Response¶

Returns the request object if successful:

{
  "id": null,
  "language": "en",
  "startDate": "2023-07-15",
  "endDate": "2023-07-20",
  "numberAdults": 2,
  "numberChildren": 1,
  "ageChildren": [8],
  "numberRooms": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "hotelId": "10001",
  "textField": "Special requests go here",
  "customIntroduction": "Custom introduction text",
  "src": "Website"
}

Endpoint for embedded widgets to submit offer requests.

1	`POST /offerRequestWidget`

Cross-Origin Access¶

This endpoint supports CORS with wildcard origins and headers.

Request Headers¶

Header	Required	Description
referer	No	Referring URL

Request Body¶

{
  "language": "en",
  "startDate": "2023-07-15",
  "endDate": "2023-07-20",
  "numberAdults": 2,
  "numberChildren": 1,
  "ageChildren": [8],
  "numberRooms": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "hotels": ["10001"],
  "isTextField": true,
  "textField": "Special requests go here",
  "src": "Widget"
}

Response¶

Returns the request object if successful.

Submit Customized Reservation¶

Creates and sends a customized reservation offer.

1	`POST /customReservation/customizedReservation`

Authorization¶

Requires ROLE_reservationmanager or ROLE_admin

Request Headers¶

Header	Required	Description
referer	No	Referring URL

Request Parameters¶

Parameter	Required	Description
asm-ticket	No	ASM ticket ID for tracking

Request Body¶

{
  "customizedOffer": {
    "room": {
      "name": "Deluxe Room",
      "description": "Spacious deluxe room with mountain view",
      "code": "DLX",
      "image1": "https://example.com/images/room1.jpg",
      "image2": "https://example.com/images/room2.jpg",
      "image3": "https://example.com/images/room3.jpg",
      "ratePlan": {
        "ratePlanCode": "BAR",
        "totalAmount": 950.00,
        "arrangement": "Breakfast included",
        "arrangementName": "Bed & Breakfast",
        "cancellation": "Free cancellation until 3 days before arrival",
        "deposit": "No deposit required",
        "ratePlanType": "RATE_PLAN"
      }
    },
    "alternativeRoom": null,
    "alternativeRoom2": null,
    "spiritClubDiscount": 0,
    "room1Available": true,
    "room2Available": false,
    "room3Available": false
  },
  "reservationModel": {
    "language": "en",
    "startDate": "2023-07-15",
    "endDate": "2023-07-20",
    "numberAdults": 2,
    "numberChildren": 0,
    "ageChildren": [],
    "numberRooms": 1,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "hotelRequests": [
      {
        "hotelId": "10001",
        "rooms": []
      }
    ],
    "src": "CRM"
  }
}

Response¶

{
  "status": 200,
  "message": "Offer sent successfully"
}

Get Customized Email Template¶

Generates a preview of a customized offer email template.

1	`POST /customReservation/emailTemplate`

Authorization¶

Requires ROLE_reservationmanager or ROLE_admin

Request Body¶

Same as the request body for /customReservation/customizedReservation

Response¶

Returns the HTML content of the email template or an error response:

{
  "status": 400,
  "message": "Error: Not able to generate Email Template"
}

Make IBE Call for Customized Offer¶

Makes a call to the IBE (Internet Booking Engine) to get offer details.

1	`POST /customReservation/ibecall`

Authorization¶

Requires ROLE_reservationmanager or ROLE_admin

Request Body¶

{
  "hotelId": "10001",
  "startDate": "2023 07 15",
  "endDate": "2023 07 20",
  "numberAdults": 2,
  "numberChildren": 0,
  "ageChildren": [],
  "numberRooms": 1,
  "language": "en",
  "rooms": null,
  "discountCode": "SUMMER2023",
  "accessCode": null
}

Response¶

Returns an Offer object with available rooms and rate plans.

Get Available Room Types¶

Retrieves available room types and rate plans for specified hotels and dates.

1	`POST /availableRoomTypes`

Authorization¶

Requires ROLE_reservationmanager, ROLE_admin, or ROLE_web

Request Parameters¶

Parameter	Required	Default	Description
custom	No	false	Flag for customized offers

Request Body¶

{
  "language": "en",
  "startDate": "2023-07-15",
  "endDate": "2023-07-20",
  "numberAdults": 2,
  "numberChildren": 0,
  "ageChildren": [],
  "numberRooms": 1,
  "hotelRequests": [
    {
      "hotelId": "10001"
    },
    {
      "hotelId": "10002"
    }
  ]
}

Response¶

Returns a map of hotel IDs to available rate plans and room types:

{
  "10001": {
    "{\"ratePlanCode\":\"BAR\",\"arrangement\":\"Breakfast included\",\"arrangementName\":\"Bed & Breakfast\",\"cancellation\":\"Free cancellation until 3 days before arrival\",\"deposit\":\"No deposit required\",\"ratePlanType\":\"RATE_PLAN\"}": [
      {
        "name": "Deluxe Room",
        "description": "Spacious deluxe room with mountain view",
        "code": "DLX",
        "isAvailable": true,
        "image1": "https://example.com/images/room1.jpg",
        "image2": "https://example.com/images/room2.jpg",
        "image3": "https://example.com/images/room3.jpg",
        "ratePlan": {
          "ratePlanCode": "BAR",
          "totalAmount": 950.00,
          "arrangement": "Breakfast included",
          "arrangementName": "Bed & Breakfast",
          "cancellation": "Free cancellation until 3 days before arrival",
          "deposit": "No deposit required",
          "ratePlanType": "RATE_PLAN"
        },
        "checkOutUrl": "https://booking.falkensteiner.com/123?roomtypeid=DLX&rateid=BAR",
        "bookUrl": "https://booking.falkensteiner.com/123"
      }
    ]
  },
  "10002": {
    // Similar structure for second hotel
  }
}

Get Available Rooms Only¶

Retrieves only available rooms for specified hotels and dates.

1	`POST /rooms/available`

Authorization¶

Requires ROLE_reservationmanager, ROLE_admin, or ROLE_web

Request Body¶

Same as the request body for /availableRoomTypes

Response¶

Similar to the response for /availableRoomTypes, but only includes rooms that are available.

Get Offline Available Room Types¶

Retrieves room types from the database when IBE connection is not available.

1	`POST /availableRoomTypes/offline`

Authorization¶

Requires ROLE_reservationmanager or ROLE_admin

Request Body¶

Same as the request body for /availableRoomTypes

Response¶

Similar to the response for /availableRoomTypes, but data comes from the local database rather than the IBE.

Get Email Template¶

Retrieves a specific email template by inquiry ID and timestamp.

1	`GET /emailTemplate/{inquiryId}/{timeStamp}`

Path Parameters¶

Parameter	Required	Description
inquiryId	Yes	ID of the inquiry
timeStamp	Yes	Timestamp of the inquiry creation

Response¶

Returns the HTML content of the email template or an error response:

{
  "status": 400,
  "message": "Error while fetching data for Inquiry"
}

Show Offer Request¶

Returns an empty inquiry object for form initialization.

1	`GET /showOfferRequest`

Request Parameters¶

Parameter	Required	Description
inquiryId	Yes	ID of the inquiry to show

Response¶

Returns an empty Inquiry object.

Error Responses¶

Common Error Codes¶

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
500	Internal Server Error

Error Response Format¶

{
  "status": 400,
  "message": "Error message details"
}

Data Models¶

ReservationOffer¶

Represents a reservation offer request.

{
  "language": "en",          // Language code
  "startDate": "2023-07-15", // Check-in date (yyyy-MM-dd)
  "endDate": "2023-07-20",   // Check-out date (yyyy-MM-dd)
  "numberAdults": 2,         // Number of adults
  "numberChildren": 1,       // Number of children
  "ageChildren": [8],        // Ages of children
  "numberRooms": 1,          // Number of rooms
  "firstName": "John",       // Guest first name
  "lastName": "Doe",         // Guest last name
  "email": "john.doe@example.com", // Guest email
  "phone": "+1234567890",    // Guest phone
  "hotelRequests": [         // List of hotel requests
    {
      "hotelId": "10001",     // Hotel identifier
      "rooms": []             // Selected rooms (optional)
    }
  ],
  "src": "Website",          // Source of the request
  "isTextField": true,       // Whether text field is included
  "textField": "Special requests" // Additional comments
}

CustomizedReservation¶

Represents a customized reservation offer.

{
  "customizedOffer": {        // Customized offer details
    "room": {},               // Primary room selection
    "alternativeRoom": {},    // Alternative room option 1
    "alternativeRoom2": {},   // Alternative room option 2
    "spiritClubDiscount": 0,  // Spirit club discount percentage
    "room1Available": true,   // Primary room availability
    "room2Available": false,  // Alternative room 1 availability
    "room3Available": false   // Alternative room 2 availability
  },
  "reservationModel": {}      // Reservation details (ReservationOffer)
}

Room¶

Represents a hotel room with its details.

{
  "name": "Deluxe Room",       // Room name
  "description": "Spacious room", // Room description
  "code": "DLX",              // Room type code
  "isAvailable": true,        // Availability status
  "image1": "url",            // Primary room image URL
  "image2": "url",            // Secondary room image URL
  "image3": "url",            // Tertiary room image URL
  "ratePlan": {               // Rate plan details
    "ratePlanCode": "BAR",    // Rate plan code
    "totalAmount": 950.00,    // Total price
    "arrangement": "Breakfast included", // Arrangement description
    "arrangementName": "Bed & Breakfast", // Arrangement name
    "cancellation": "Free cancellation", // Cancellation policy
    "deposit": "No deposit",  // Deposit requirements
    "ratePlanType": "RATE_PLAN" // Rate plan type
  },
  "checkOutUrl": "url",       // Direct checkout URL
  "bookUrl": "url"            // Booking URL
}

CustomIBECall¶

Represents a request to the Internet Booking Engine.

{
  "hotelId": "10001",          // Hotel identifier
  "startDate": "2023 07 15",   // Check-in date (yyyy MM dd)
  "endDate": "2023 07 20",     // Check-out date (yyyy MM dd)
  "numberAdults": 2,          // Number of adults
  "numberChildren": 0,        // Number of children
  "ageChildren": [],          // Ages of children
  "numberRooms": 1,           // Number of rooms
  "language": "en",           // Language code
  "rooms": null,              // Preselected rooms
  "discountCode": "SUMMER2023", // Discount code
  "accessCode": null          // Access code
}

Rate Limiting¶

API endpoints are subject to rate limiting to prevent abuse:

100 requests per minute per client for authenticated endpoints
300 requests per minute for public endpoints

Webhook Integration¶

When offers are created or updated, webhooks can be triggered to external systems. To configure webhook destinations, use the webhook management API.

Payment Integration¶

The Offers API integrates with the Payment Processing system to handle deposits and payments for reservations. When a reservation is confirmed, the system can automatically initiate payment requests based on the hotel's deposit policy.

Payment Flow¶

Guest receives and accepts an offer
System creates a reservation in the PMS
If deposit is required, system initiates a payment request
Guest completes payment through the payment gateway
System receives confirmation and updates reservation status
If configured, system posts the deposit to the PMS (e.g., Apaleo)

Payment Methods¶

The following payment methods are supported for reservation deposits:

Credit Cards (Visa, Mastercard, American Express, Diners Club)
Debit Cards
PayPal
Bank Transfers (offline processing)

Payment methods available for a specific reservation may vary based on the hotel's configuration and the guest's location.

For detailed information about payment processing, refer to the Payment Processing API Documentation.

Batch Operations¶

For bulk operations with large volumes of offers, it's recommended to process them in batches and implement appropriate error handling and retry mechanisms.

Offers API Documentation¶

Overview¶

Base URL¶

Authentication¶

Endpoints¶

List Enabled Hotels¶

Authorization¶

Response¶

Preview Offer Template¶

Authorization¶

Request Body¶

Response¶

Submit Reservation Offer¶

Authorization¶

Request Headers¶

Request Parameters¶

Request Body¶

Response¶

Submit Customer Offer Request¶

Request Body¶

Response¶

Submit Widget Offer Request¶

Cross-Origin Access¶

Request Headers¶

Request Body¶

Response¶

Submit Customized Reservation¶

Authorization¶

Request Headers¶

Request Parameters¶

Request Body¶

Response¶

Get Customized Email Template¶

Authorization¶

Request Body¶

Response¶

Make IBE Call for Customized Offer¶

Authorization¶

Request Body¶

Response¶

Get Available Room Types¶

Authorization¶

Request Parameters¶

Request Body¶

Response¶

Get Available Rooms Only¶

Authorization¶

Request Body¶

Response¶

Get Offline Available Room Types¶

Authorization¶

Request Body¶

Response¶

Get Email Template¶

Path Parameters¶

Response¶

Show Offer Request¶

Request Parameters¶

Response¶

Error Responses¶

Common Error Codes¶

Error Response Format¶

Data Models¶

ReservationOffer¶

CustomizedReservation¶

Room¶

CustomIBECall¶

Rate Limiting¶

Webhook Integration¶

Payment Integration¶

Payment Flow¶

Payment Methods¶

Batch Operations¶