Skip to main content

Channel Integration Guide

With the channel integration you can subscribe for availability, rates and inventory (ARI), create new bookings and modify existing bookings. 

The Basics

Get your sandbox account and check out this guide to learn how you can connect to the apaleo APIs.

API Client 

All apaleo APIs are described as swagger documents. That lets you generate API clients directly from the swagger.json files. There is a large community, providing client generators for almost every language. For example, swagger code generator is a good project, which allows generation of API clients for Java, PHP, C#, NodeJS and more. This gets you up to speed very fast and as a bonus you can access API documentation within the auto-generated methods and models.

Sandbox

apaleo.io is our – and your – playground to do first steps with the API, up to your final integration. Use it to interactively explore the API or to learn the apaleo concepts by navigating the user interface.

These are the links you need to know

User Interface:
API:
Identity Server:
Distribution API:
Distribution API with credit card data:

Pro tip: Inspect the API usage of the user interface, as it is built on top of just the same API as you are using.

Production

When you’re done building a first version, and want to make the integration available to hotels, you need to switch URLs from apaleo.io to apaleo.com, and have the ability to collect user consent to access the data of a certain apaleo account.

How to get an authorization code and use it to exchange for an access token is described here.

Distribution API

The Distribution API is especially designed for implementing channel apps as easy as possible. You can find the swagger documentation on https://distribution.apaleo.io.

Availability, Rates and Inventory

The first thing to do is to subscribe for availability, rates and inventory (ARI) updates. You can create a subscription and register a URL (the webhook) apaleo should deliver the ARI data to.

https://distribution.apaleo.io/swagger/#!/Subscription/V1SubscriptionsPost

Subscriptions are per API client, so that other channel apps for the same apaleo account cannot accidentally interfere with your subscriptions. It is best not to setup subscriptions via the swagger UI for production, but to have it done by your app based on the mapped rate plans during the setup.

The webhook URL of your app should be protected by a token in the URL and be available over https. An unprotected endpoint would allow everyone to set random prices or availabilities for the hotels.

Full Push

After you created and enabled the subscription, the following data will be pushed to your webhook initially and on whatever fullSyncPeriod you defined. The data will be delivered in chunks of 90 time slices per request.

{
  "accountId""XYZX",
  "propertyId""MUC",
  "timeSlices": [
    {
      "from""2018-11-17T09:00:00Z",
      "to""2018-11-18T08:00:00Z",
      "ratePlanId""MUC-NONREF_DBL",
      "unitGroupId""MUC-DBL",
      "available"23,
      "prices": [
        {
          "persons"1,
          "price": {
            "grossAmount"123,
            "currency""EUR"
          }
        },
        {
          "persons"2,
          "price": {
            "grossAmount"170,
            "currency""EUR"
          }
        }
      ],
      "restrictions": {
        "closed"true,
        "closedOnArrival"false,
        "closedOnDeparture"false,
        "minLengthOfStay"2,
        "maxLengthOfStay"8
      }
    }
  ]

}


Fields
Optional
Description
accountId and propertyId
no
The account id identifies an apaleo customer. The propertyId is only unique within one apaleo account. The combination of accountId and propertyId is globally unique.
timeSlices
no
List of time periods for one rate plan and unit group combination with availability, prices and restrictions. You will at least receive one time slice always.
from and to
no
For standard overnight hotel business this defines the time range for the night. In the example above, it would be the night from November 17th to November 18th. Most   channels consider this the night of November 17th.
ratePlanId
no
The id of the rate plan in apaleo, which is unique per account.
unitGroupId
no
The id of the unit group in apaleo, which is unique per account. The equivalent for the apaleo unit group in channels can be room type, room category or inventory type.
available
no
Number of units available for the unit group during this night. apaleo has shared inventory, so all rate plans selling this unit group on that night will have the same number.
prices
yes
List of gross prices including taxes and all service fees for breakfast etc. You will receive one price for each allowed occupancy. apaleo currently does not support special prices for children. If no rate is set for this night in apaleo you will not receive prices.
restrictions
no
Restrictions set for this night. The Length Of Stay restrictions are arrival-based and they are optional. The closed restrictions will always be send. If no rate is set for this night in apaleo the master closed restriction will be set.

Delta Push

apaleo also keeps track of the data already sent to you for a subscription and calculates the diff. In the interval defined with deltaSyncPeriod apaleo only sends the data changed since the last successful notification. To ensure the delta push works as expected you need to always return a successful http status code of 2xx. The delta is calculated for the following fields and the data will also be delivered in chunks of 90 time slices per request:


Field
Description
available
Only if the number of available units for this night changed it will be send.
prices
If one out of the prices changed you will again receive the whole list of prices.
restrictions
If one of the restrictions changed you will receive the whole set of current restrictions. If a rate in apaleo was removed and a certain night was made unsellable, you will not receive prices, but the master closed restriction.

As a safety net to make sure the incremental changes all add up, you can always request a full push of ARI data to re-sync with the data in apaleo.

http://distribution.apaleo.local:50002/swagger/#!/Subscription/V1SubscriptionsByIdTrigger_full_syncPut

 New Bookings 

To create a new booking all you need to do is send the the details you have to the Distribution API.


Each booking will be accepted and confirmed by apaleo. If we cannot process the booking, we will show the failed booking to the hotelier on the user interface and allow the hotelier to resolve the problems. You do not need to worry about errors on our side as long as you ensure the format and URL of your request is correct.

Credit Cards

apaleo is certified to be compliant with the PCI-DSS standard and we assume you are as well. To achieve compliance, we are using the PCI proxy from DataTrans AG in Switzerland. You will not be able to send plain cardholder data directly to https://distribution.apaleo.io, we will reject it. Instead please use https://secure-distribution.apaleo.io as a base-url whenever you send credit card data through to apaleo. For creating a booking with credit card data, you would have to make a call to POST https://secure-distribution.apaleo.io/v1/bookings.

Credit cards will be handled by apaleo. Some OTAs collect the money for the hotels or allow other payment methods and then issue a virtual credit card for the hotel to capture the money from. Please mark virtual credit cards accordingly by setting the isVirtual property of the credit card to true. Depending on the source of the booking, apaleo will process them right away or, e.g. for Expedia Virtual Cards only on the day of arrival.

Channel and Sources

apaleo does currently support two channels: BookingCom and ChannelManager. The specific channel like BookingCom should only be used by apps directly connecting this channel to apaleo. When you connect multiple travel agents or a Central Reservation System (CRS), please use ChannelManager. When setting ChannelManager as the channel, you can specify more details in the source. The list of allowed sources you can define right now can be retrieved using the apaleo Booking API at https://api.apaleo-staging.com/booking/v1/types/sources.

External Id

Distribution channels do have their own booking codes they use to confirm the booking with the guest. Guests use these codes or IDs when they arrive at the hotel, want to check in online or call the hotel. Therefore, this information also needs to be forwarded to apaleo, using the externalId field of a reservation. It is important to make the externalId unique per reservation. A simple way to achieve this is appending an incremental number.

Booking vs Reservation

When you check the apaleo API, you will see that a booking can consist of multiple reservations. The booking is basically a container for one or more reservations. A reservation in apaleo is always per room. booking.com sends multiple rooms as room stay elements in one reservation. You could combine all of them in one booking to apaleo.

apaleo IDs

After you create a booking, you will receive the booking ID and a list of reservation IDs from apaleo. Use these IDs for subsequent API calls to modify or cancel bookings or reservations.

Modify Bookings

The request model for modifications is very similar to the one for creating bookings.


To make the usage of the API more convenient we decided to deviate from the default behavior of a PUT API in two areas:

Undeletable first level objects

On the first level of the request model for the booking modification we have:
  • Credit Card
  • Booker
  • Comment
  • Booker Comment
  • List of Reservations
If you omit one of those objects, or send an empty object, we will not remove it or cancel it, but simply ignore what you did. This allows you to add a reservation to an existing booking by just sending the new reservation without always having to repeat the data for the booker, the credit card or all the other rooms.

Reservations are identified by the apaleo reservation ID. Reservations without this ID are considered to be new and will be added to the booking. Reservation with a ID id will be updated based on the provided information. The API behaves like a “create or update” request.

Merging of guest and booker data

OTAs often do not provide a rich set of data, and a lot of guest related data is collected by the hotel and put to the guest profile in the PMS. To not accidentally lose this information we only allow you to override the following fields:
  • Guest Data
  • Booker Data
  • Travel Purpose
If you omit these fields or do send some of their properties empty or not at all, we will not remove it, we will just leave it untouched.

Cancel Reservations

You can cancel reservations one by one by using the reservation ID.







Comments

Popular posts from this blog

Getting Started with apaleo APIs

Have a look You can find all of apaleo's API on api.apaleo.io. We use Swagger to describe it, and to generate our documentation.

Sign up The first step is to sign up for an account. After you finish signup you will be able to login to our apaleo app and start configuring your properties. Also you can use the same credentials to access our API using Swagger. Get access for app We're still new and want to get in touch with you before we grant you access. Contact us at api@apaleo.com, to get your very own client credentials that lets you play with the API in our sandbox.
Use it apaleo APIs are protected using OAuth2 - the de-facto standard for API security. Here's a short guide to get you started:

Step 1: To get access to our APIs, you need to use your client id and secret to obtain an access token. Don't have one? Contact us at api@apaleo.com.

Combine your client id and secret into a string, separated by colon yourClientId:YourClientSecret and encode with Base64. This wi…

Connect your app with OAuth 2.0

What is this all about? When you connect your app to apaleo, it can read or modify data, or even trigger entire business flows of a hotel. But before gaining access to any of the resources in the REST API, it must get permission from the hotel. This guide will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification). Note: apaleo's OAuth 2.0 implementation supports the standard authorization code grant type. You should implement the application flow described below to obtain an authorization code and then exchange it for a token. (The implicit grant type is not supported.) Terminology Before learning more about the details of the authorization process, make sure that you are familiar with some of the key terms that are used in this guide: Client: Any application that would like access to a hotel's data. A user (usually the hotel's owner or admin) must grant permission before the client can access any data.API: apaleo REST API. T…