Termino Hotel API (1.2)

API Structure

This API is bi-directional, meaning both sides can request or push information to the other's API. Given that this API covers various system setups, there are multiple ways to establish communication. The synchronization of hotel structure and capacities is typically achieved by CM/PMS pushing information to Termino. A periodic pull of capacity information can also be configured, but push is preferred as it facilitates faster change propagation and reduces traffic between systems.

Typical usage for channel managers includes:

• Implementing the reservation and ping endpoints on your side
• Calling the capacities-update endpoint to push capacity changes
• Using the get-hotel endpoint to retrieve the hotel structure and set up the connection

For property management systems, the typical usage involves:

• Implementing the hotel, reservation, and get-reservation endpoints. The ping endpoint is not needed because the hotel endpoint should provide the same information (whether the hotel is active or not).
• Depending on the pull or push style, implementing the capacities on your side or calling the capacities-update push endpoint on Termino to deliver updates.

All requests are required to communicate over HTTPS. Termino API endpoints support TLS protocol versions 1.2 and higher.

Authentication

All requests contain the property accessToken with a value assigned during the API verification process. These values identify the communicating parties - CM/PMS on one side and Termino on the other.

Both sides accept only HTTP POST. Requests and responses are sent with the Content-Type header set to application/json and a JSON body depending on the operation to be performed. Content encoding is always UTF-8.

If a message is received and processed, the HTTP response code should be 200 OK for successful results and any 4xx for unsuccessful results (the concrete error type is described in the response body).

5xx response codes indicate unexpected and internal errors, and the request can be retried without change. No specific response should be expected for server errors (JSON is not guaranteed). The response header Retry-After (if present) should be respected for retrying the request.

The type of message is determined by the URL.

For push endpoints, the request should be repeated until it is successfully delivered to Termino. Similarly, Termino will repeat requests until they are accepted by your system. Successful delivery means either responding with success or an expected error described in the API specification.

Identifiers

• All identifiers (parameters named id) have to be unique for a given hotel, unless explicitly stated otherwise.
• All identifiers generated on the Termino side are UUIDs.
• All identifiers from your side can be either integers or strings.

Date interval

Date intervals are represented as objects with start and end properties, both formatted as YYYY-MM-DD. The start date is inclusive, while the end date is exclusive.

See DateInterval schema for details.

{
    "start": "2020-01-01",
    "end": "2020-01-31"
}

Basic request

{
    "accessToken": "foobar",
    // other properties
}

Basic success response

{
    "success": true,
}

Basic error response

{
    "error": {
        "code": "invalid-access-token",
        "message": "Access token not found."
    }
}

Common error codes

These errors can occur on any API endpoint.

Code	Description
invalid-format	Unparsable JSON
missing-value	A required property is missing.
invalid-value	A property has invalid format (e.g., wrong date, time, datetime, interval, URL...).
invalid-access-token	Invalid or expired access token

Reservation ID

Each reservation has to have a unique ID for reference between systems. This identifier is later used in case of modification and cancellation of the reservation is needed.

Termino will preferably assign our identifier with reservation creation, or it can accept and later use the reservation ID returned in response. Using Termino's ID simplifies recovery from communication failures (phantom reservations).

Money representation

Money amounts are represented as strings in hundredths of currency unit. Currency is represented using ISO 4217 currency codes (e.g., "CZK" for Czech crowns, "EUR" for euros). Supported currencies are CZK, PLN, EUR and HUF.

For example, an amount of one hundred Euros and fifty cents is represented as:

{
    "amount": "10050",
    "currency": "EUR"
}

Rate plans

Rate plan represents a sellable combination of room type, board type and other commercial conditions (cancellation policy, restrictions, etc.). Each rate plan has:

• id – partner-defined identifier (e.g. "HB", "NRF") - name – human readable name - pricingModel – defines how prices are provided in planning updates (per_room, per_person, per_occupancy) Rate plans are provided in:
• response of /hotel (HotelInfo.ratePlans) - push updates via /hotel-update (ratePlans) - planning data via /planning and /planning-update (RatePlanPlanning)

Pricing models

Three pricing models are supported for receiving planning updates:

• per_room - price is set per room and night
• per_person - price is set for count of persons and night
• per_occupancy - price set per night and occupancy (occupancy is specified count of adults and children)

Changes to API and its documentation

2026

29. 1. 2026

• Added support for synchronization of rates, prices and booking restrictions via /planning-update and /planning endpoints

2023

2. 11. 2023

• Added children ages and bed entitlement to reservation data (reservation.children)
• Added meal plan to reservation data (reservation.meal)
• Added e-mail address to reservation data (reservation.contact.email)
• Deprecate occupations and occupations-update endpoints to be used for blockages. Use capacities instead.
• Deprecate rooms parameter from RoomType structure. Only roomCount parameter is now needed to define room type structure
• Deprecate roomId parameter from Occupation and Reservation structure. Only roomTypeId parameter is now needed to define occupation

2021

24. 11. 2021

• Deprecate checkIn, checkOut and url parameters from hotel structure

2020

9. 1. 2020

• Initial release

Endpoints on Termino side are called from PMS/CM system and mostly used to push data changes.

If unsuccessful response is returned, the request has to be repeated until it is successfully delivered to Termino.

Partner endpoints should be implemented in your PMS/CM system and are called by Termino, either periodically or when specific action is performed (eg. new reservation, hotel connection).