Public API Documentation

This guide provides all the information you need to interact with the XORB HOTELS Public API. Use these endpoints to build custom booking websites, check room availability, and integrate with other services.

Authentication

All requests to the Public API must be authenticated using a Bearer token. You can generate a unique API key for each of your properties from the property's "Edit" page in the dashboard.

Include your API key in the `Authorization` header of your requests:

bash

"Authorization": "Bearer YOUR_PROPERTY_API_KEY"

If the API key is missing, invalid, or does not correspond to the requested property, you will receive a `401 Unauthorized` error.

json

{
  "error": "Not authorized"
}

Get Property Details

Retrieve the public details of a specific property, such as its name, type, amenities, and description. This is useful for displaying property information on your website.

GET

`/api/public/properties/'{propertyId}'/details`

URL Parameters

`propertyId` (string, required): The ID of the property you want to retrieve.

Success Response (200 OK)

json

{
  "id": "clxk1q2w30001w8tnhz9o4a5b",
  "name": "Sunset Villas",
  "propertyType": "GUEST_HOUSE",
  "amenities": ["Pool", "Gym", "WiFi"],
  "description": "A beautiful property with stunning views...",
  "logoUrl": "https://your-s3-bucket.com/logo.png"
}

Error Response (404 Not Found)

json

{
  "error": "Property not found."
}

Check Room Availability

Fetches a list of rooms that are available for a given date range. This is the primary endpoint to use before creating a reservation.

GET

`/api/public/properties/{propertyId}/availability`

URL Parameters

`propertyId` (string, required): The ID of the property.

Query Parameters

`checkinDate` (ISO 8601 string, required): The desired check-in date. Example: `2024-08-15T00:00:00.000Z`
`checkoutDate` (ISO 8601 string, required): The desired check-out date. Example: `2024-08-18T00:00:00.000Z`

Success Response (200 OK)

Returns an array of available room objects. If no rooms are available, an empty array `[]` is returned.

json

[
  {
    "id": "clxm5r6s7000bw8tnb2c1d3e4",
    "roomNumber": "101",
    "roomType": "Deluxe Double Room",
    "pricePerNight": 120.00,
    "pricePerNightLocal": 100.00
  },
  {
    "id": "clxm5t7u8000dw8tnf4g5h6i7",
    "roomNumber": "102",
    "roomType": "Deluxe Double Room",
    "pricePerNight": 120.00,
    "pricePerNightLocal": 100.00
  }
]

Error Responses

400 Bad Request (Invalid dates)

json

{
  "error": "Invalid date parameters"
}

Create a Reservation

Creates a new reservation for a specific room and date range. The reservation will be created with a `PENDING` status.

POST

`/api/public/properties/{propertyId}/reservations`

URL Parameters

`propertyId` (string, required): The ID of the property where the reservation will be made.

Request Body

The request body must be a JSON object with the following fields:

json

{
  "expectedCheckinDate": "2024-08-15T00:00:00.000Z",
  "expectedCheckoutDate": "2024-08-18T00:00:00.000Z",
  "roomId": "clxm5r6s7000bw8tnb2c1d3e4",
  "name": "John Doe",
  "nationality": "United States of America",
  "identification": "A12345678",
  "emailAddress": "john.doe@example.com",
  "contactNumber": "+1-202-555-0174",
  "numberOfPax": 2,
  "specialRequests": "Late check-in, around 11 PM."
}

Success Response (201 Created)

Returns a success message and a simplified reservation object.

json

{
  "success": "Reservation created successfully!",
  "reservation": {
    "id": "clxm6a2b3000gw8tnc9d8e7f6",
    "bookingReference": "BKG-A9B3C2D1",
    "status": "PENDING",
    // ...other reservation details
  }
}

Error Responses

409 Conflict (Room is not available)

json

{
  "error": "The selected room is not available for the chosen dates. Please select different dates or another room."
}

400 Bad Request (Invalid data in request body)

You will receive a standard validation error if any required fields are missing or incorrectly formatted.