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.

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 can either generate and send our identifier with reservation creation, or it can accept and later use the reservation ID returned in response. Using the ID from Termino is preferred because it allows us to reference the reservation even in case this create request fails with a timeout or other unexpected error. When using your ID, another system or manual intervention is needed in this case.

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.

Changes to API and its documentation

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).