canonical: https://jentic.com/apis/hetras-certification.net/hetras-booking-api-version-0

# Hetras Certification hetras Booking API Version 0

The hetras Booking API exposes the booking-side surface of the hetras hotel management platform, used by hotel chains running on the hetras cloud. It covers room availability and occupancy lookups, block and rate retrieval, addon offers for guest stays, and the full reservation lifecycle including create, partial update, room assignment, check-in, check-out, and cancellation. This is the integration point for booking engines, channel managers, and front-desk tools that need to reserve and manage stays on hetras-managed properties.

## For AI agents

Look up hotel availability, fetch rates and addons, create bookings, assign rooms, and run check-in or check-out on the hetras hotel platform.

## Scope

Does not configure hotels, rate plans, or room types - use the hetras Hotel API for those, and this Booking API for availability, rates, addons, and the reservation lifecycle only.

## Capabilities

- Look up room availability and occupancy for a property and date range
- Retrieve daily rates and rate plans for the booking engine
- List blocked inventory holds via the blocks endpoints
- Offer addon services for a specific guest stay through the addons endpoint
- Create a new booking with one or more reservations and assign rooms on arrival
- Run check-in and check-out operations against an existing reservation
- Cancel a reservation and return inventory to the pool

## Use cases

### Direct Booking Engine Integration

Hotel websites running their own booking engine can call the hetras Booking API to check availability, present rates and addons, and create the reservation when the guest confirms. The API returns confirmation IDs that the website can show on the success page and email back to the guest. This avoids reselling inventory through an OTA when the customer has come to the hotel directly.

Example prompt: GET `/api/booking/v0/availability` for the dates, then POST `/api/booking/v0/bookings` with the chosen rate and guest payload.

### Channel Manager Sync

Channel managers that distribute hotel inventory to OTAs and metasearch sites can pull availability and rate data on a tight schedule and push reservations back when an OTA confirms a booking. The hetras Booking API provides the symmetric pull and push surface, so the channel manager can keep all distribution channels in sync. Rates and blocks fetched here become the source of truth for outbound feeds.

Example prompt: GET `/api/booking/v0/availability` and GET `/api/booking/v0/dailyrates` on a schedule and feed each OTA the merged result.

### Front-Desk Check-in and Check-out

Front-desk staff using a custom property management UI can drive the check-in and check-out flow through the reservation sub-resources. Assigning a room, performing check-in, then later check-out, all map cleanly to dedicated endpoints. This keeps the front desk in their preferred UI without losing the platform's lifecycle guarantees.

Example prompt: POST `/api/booking/v0/bookings/{confirmationId}/reservations/{reservationNumber}/assign_room`, then /check_in on arrival and /check_out on departure.

### AI Agent Booking Assistant

An AI travel assistant connected through Jentic can search hetras-managed hotels for availability, present rates, and create a reservation on behalf of the user once a choice is made. Jentic isolates the API access and exposes only the operations the agent needs, so the assistant cannot invent or misuse endpoints. This pattern fits travel concierge agents that own end-to-end booking inside a controlled hotel portfolio.

Example prompt: Search Jentic for 'create a hotel booking', load POST `/api/booking/v0/bookings`, and execute with the chosen hotel, dates, rate, and guest details.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/booking/v0/availability` | Get availability and occupancy for a hotel and timespan |
| GET | `/api/booking/v0/bookings` | Find bookings matching filter criteria |
| POST | `/api/booking/v0/bookings` | Create a new booking |
| GET | `/api/booking/v0/bookings/{confirmationId}` | Load all reservations for a booking |
| PATCH | `/api/booking/v0/bookings/{confirmationId}/reservations/{reservationNumber}` | Partially update a reservation |
| POST | `/api/booking/v0/bookings/{confirmationId}/reservations/{reservationNumber}/check_in` | Check in a reservation |
| POST | `/api/booking/v0/bookings/{confirmationId}/reservations/{reservationNumber}/check_out` | Check out a reservation |
| POST | `/api/booking/v0/bookings/{confirmationId}/reservations/{reservationNumber}/cancel` | Cancel a reservation |

## Key resources

- **Availability** — Availability and occupancy lookups for a hotel and date range
- **Rates** — Daily rates and rate plan information for booking
- **Blocks** — Blocked inventory holds on a property
- **Addons** — Addon services offered for a specific guest stay
- **Bookings** — Create, fetch, and update bookings and their reservations
- **Reservations** — Per-reservation actions: assign room, check-in, check-out, cancel

## Why Jentic

- **Setup:** Wiring the hetras Booking API by hand means handling the partner credentials the platform negotiates and writing your own retry logic across the reservation lifecycle from availability through check-out. Through Jentic you install once, import the hetras Booking API from the API Directory, store the partner credential once, and your agent calls it.
- **Permission scoping:** The Booking API puts the confirmation and reservation number in the URL path (`/bookings/{confirmationId}/reservations/{reservationNumber}`), so a rule can pin your agent to acting on one booking. You choose the operations it may call, so check-in, check-out, or cancel is only included if you add it, while reading availability and bookings stays separate.
- **Credential handling:** Your hetras partner credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check room availability' or 'create a hotel booking', and Jentic returns the matching hetras Booking operation with its input schema so the agent calls the right endpoint without reading the certification documentation.

## Related APIs

- **hetras Hotel API Version 0** — Hotel-side configuration: hotels, rate plans, room types, codes
- **Cloudbeds API** — Cloud property management system for independent hotels
- **Amadeus Hotel Booking API** — Global travel distribution hotel booking API

## FAQ

### What authentication does the hetras Booking API use?

The certification spec exposes the API surface without a defined security scheme - the production hetras platform requires a partner-issued credential negotiated with hetras directly. When called through Jentic, that credential is held in your Jentic One instance and supplied at execution time once configured by the operator.

### Can I check hotel availability and occupancy through the API?

Yes. GET `/api/booking/v0/availability` returns availability and occupancy for a specific hotel and date range. Use the response together with GET `/api/booking/v0/dailyrates` to price a stay before creating a booking.

### How do I create a booking and assign a room on arrival?

POST `/api/booking/v0/bookings` creates the booking with one or more reservations. On arrival, POST `/api/booking/v0/bookings/{confirmationId}/reservations/{reservationNumber}/assign_room` sets the physical room, then /check_in performs the front-desk check-in step.

### What are the rate limits for the hetras Booking API?

Rate limits are not published in the certification spec and are governed by the partner contract with hetras. Treat the certification environment as low-volume - heavy use should be scheduled with the hetras team to avoid throttling.

### How do I cancel a reservation through Jentic?

Search Jentic for 'cancel a hetras reservation', load POST `/api/booking/v0/bookings/{confirmationId}/reservations/{reservationNumber}/cancel`, and execute with the confirmation ID and reservation number. Inventory is returned to the pool on success.

### Can the API offer addons during the booking flow?

Yes. GET `/api/booking/v0/addons` returns the addons available for a specific guest stay (room type, dates, occupancy). Surface those offers in the booking UI before the guest confirms so addon revenue is captured at the point of sale.

### Can I limit what my agent is allowed to do with the hetras Booking API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and you pick the exact hetras Booking operations it can call. You can grant read-only access such as GET `/api/booking/v0/availability` and GET `/api/booking/v0/bookings` while withholding write actions, so check-in, check-out, and cancel are included only if you add them. Since the confirmation and reservation numbers live in the URL path, a rule can also pin the agent to acting on a single booking rather than the whole property.