KIGO RA REST API Integration Guide

Transcription

1 KIGO RA REST API Integration Guide Revision 2 ( ) Kigo, Inc. 1

2 Contents Section Page 1. Introduction 3 2. Properties Overview Working with properties 6 3. Prices Overview Working with prices Availability and Reservations Overview Reservation constraints Working with reservations Other topics FAQ 20 Kigo, Inc. 2

3 Disclaimer Your company will need a competent IT department to integrate your system with Kigo API. Be aware that Kigo IT and Support departments will not check, revise, debug nor correct third-party code. Kigo Support canl only address high level questions and offer general guidelines. 1. INTRODUCTION KIGO RA REST API The Kigo Rental Agency API is a REST-like implementation based on the HTTP protocol, JSON data encoding and Unicode character encoding, over the secure HTTPS transport. Summary of capabilities (for an exhaustive list view section 9 API methods reference from RA REST API v1 specification) Search availability. Create, read, update and cancel confirmed reservations. (currently it is not possible to work with Inquiries, Hold dates and/or Canceled). Create, read and update properties. (currently it is not possible to add or edit properties). Read and update Property pricing ( Rent calculation in the Backoffice). Compute pricing for a set of dates and variables such as number of guests. Read user-defined fields and Kigo fields such as property types and fee types. Onboarding Once you sign up with Kigo, you will get a Kigo Rental Agency account with a Kigo ID, a username and a password. Every Kigo agency has a unique Kigo ID that identifies it. If you request API access, you will get API login credentials with the same username as in your Kigo account but a different, unique password. Kigo, Inc. 3

4 2. PROPERTIES 2.1. OVERVIEW For an API user, a property in Kigo has the following 2 main areas: Property information relates to all the basic information of the property such as its name, size, number of bedrooms, max guest capacity, etc. Property information in Kigo ( Properties -> Edit -> General ) Kigo, Inc. 4

5 Photos property pictures. Property photos in Kigo ( Properties -> Edit -> Photos ) PROPERTY OWNER A Kigo property will always be related to an owner, it is required by the system. Also, it is not possible to change the owner of a property. Owner in Kigo ( Owners ) Kigo, Inc. 5

6 OTHER CONSIDERATIONS Active vs Inactive Properties can be either active or inactive. They cannot be deleted. Only active properties will be accessible from the API. Properties in Kigo ( Properties ) 2.2. WORKING WITH PROPERTIES API Reference 9.2. Managing property owners listowners This method returns the list of property owners connected to the rental agency Kigo account readowner This method returns property owner information addowner This method adds a new owner connected to the rental agency Kigo account. It is required that the property owners be added to the system, either using the API or the application GUI, prior to adding the properties updateowner This method allows modifying a property owner Property owner information 9.3. Managing properties listproperties2 (Property information). This method returns the list of properties (both active and inactive) from the rental agency Kigo account. The method may be invoked periodically to keep your application's list of properties in sync with your Kigo account list of properties readproperty2 (Property information). This method returns property information readpropertyphotofile (Property photos). Kigo, Inc. 6

7 This method returns the binary content of a property JPEG photo file. You may invoke this method to retrieve new property photos discovered in a prior readproperty call.property photo files are immutable, and need to be downloaded only once listuserdefinedpropertyattributes (User-defined fields). This method returns the full list of user-defined property attributes defined in your Kigo Rental Agency account addproperty This method allows adding a new property to the Kigo rental agency account. Only properties provided by an owner (see 10.4 Property provider) may be added using this method updateproperty This method allows modifying property information. Property information that is synchronized with the provider account in the Kigo GUI shall no longer be synchronized after being updated by this method Property information Use-cases Property setup First of all get familiar with Kigo data structures for owner and property, Property owner information and Property information respectively. Every property needs to be linked to an owner, therefore the first has to be either to create an owner or to use an existing one. Use addowner if you wish to create a new owner. Use listowners and readowner to find an existing owner. Use addproperty to create a new property. Remember to pass the OWNER_ID from the previous step. Property synchronization 1. Synchronize property information [PREFERRED] Regardless of whether your solution has a content management user-interface, you want to synchronize all the property information from Kigo. This method is preferred because the user only has to introduce properties once: in their Kigo account. First you will need to grab all the property ids from listproperties and later on you will have to call readproperty for each one in order to fetch all the information. For photos you will have to download them all via readpropertyphotofile and upload them to your servers. Finally, if you want to synchronize user-defined property attributes as well, you will have to save the list of available fields for each user with listuserdefinedpropertyattributes. Kigo, Inc. 7

8 2. Map properties Your solution has a content management user-interface and you want the end-user to fill their property information with it, and just map a property from your system to a property in Kigo. You just need to use listproperties and associate each property ID in your system with Kigo s PROP_ID. 3. PRICES 3.1. OVERVIEW In Kigo we have 2 concepts related to pricing information: Display rates These can be found on the Property information section and are meant for information purposes only since they can only be approximate amounts, such as from 40 / night to 90 / night. Property display rates in Kigo ( Properties -> Edit -> General ) Rent calculation It englobes the different components and rules for calculating an actual price for a given check-in and check-out dates, among other variables such as number of guests. Nightly / weekly rates Rent amounts are introduced in this section. Kigo works with periods (from check-in date to check-out date). Each period can have a different structure, with rent prices varying by night of the week, number of guests and length of stay. In addition, there can also be weekly rental periods. Kigo, Inc. 8

9 Nightly / Weekly rates in Kigo ( Properties -> Edit -> Rent calculation ) Fees Fees are extra costs that can be added to the rent amount. They can be based on a percentage of rent, a fixed amount, on length of stay, and others. The available fees are provided by Kigo, that is, the user cannot add other fees than those present in the system. Fees can be included in the rent amount ( Include in rent checkbox), thus being included in the rent amount.. Kigo, Inc. 9

10 Fees rates in Kigo ( Properties -> Edit -> Rent calculation ) Discounts There are 3 types of discount available: Eary bird, Last minute and Special. Discounts in Kigo ( Properties -> Edit -> Rent calculation ) Kigo, Inc. 10

11 Deposit The agency can also set a damage deposit based on a fixed amount, % of rent or length of stay. Damage deposit in Kigo ( Properties -> Edit -> Rent calculation ) 3.2. WORKING WITH PRICES API Reference readproperty2 You will find display rates as PROP_RATE object ( ) readpropertypricingsetup This method provides the pricing setup (rent computation ingredients) for the specified property. The pricing setup may then be used for remote batch or real-time price computations, as an alternative or a complement to invoking the computepricing or computepricingbulk API methods in real-time diffpropertypricingsetup This methods enables the client system to maintain a local copy of the properties pricing setup by receiving information on new and modified pricing setups computepricing This method provides real-time rent, fees and deposit amounts and due dates computation, based on property pricing setup in your, or the property provider's, Kigo account computepricingbulk This method is a bulk alternative to the computepricing method. It allows processing multiple properties at once, thus significantly decreasing the number of API calls listkigofeetypes This method returns the list of fee types used in Kigo application Property pricing The property pricing setup is stored into an object holding the following members: CURRENCY, RENT, FEES, DISCOUNTS. Not all of them are always available. 11 Property pricing computation algorithm overview Kigo, Inc. 11

12 If your application is making pricing computations based on the property pricing setup such as provided by the readpropertypricingsetup and diffpropertypricingsetup API methods, then you might want to conform tothis computation algorithm overview. Use cases 1. Synchronize Kigo prices in your system [PREFERRED] First of all, you will need to get familiar with Kigo s API pricing structure in Property pricing. You will use readpropertypricingsetup to fetch all the pricing data and store it in your system. You need to update this regularly, which you can do with diffpropertypricingsetup. You have mainly two options: 1) map Kigo s pricing structure to your own system and use your own pricing algorithm, 2) leave Kigo s pricing structure as is and implement Kigo s computation algorithm, described in 11 Property pricing computation algorithm overview (this is, obviously, preffered). Advantages of price synchronization Performance and User experience Storing pricing details by yourself will result in a great improvement in performance. When you compute prices calling the API via computepricing or computepricingbulk, there is a noticeable delay for the user since your server has to wait until Kigo computes the pricing and replies to your call. This will obviously have an impact in the overall user experience and will be a disadvantage towards other portals which have synchronized prices and can compute them faster, without calling the API. Get more customers and properties Our Channel Manager connects agencies and property owners with more than 30 channels. One of the most important factors for them to decide what portals they want to work with is the friction of the connection process. Generally our clients expect to be able to manage everything directly from Kigo and the inability to do so will inevitably lead to a disappointment. In our experience, portals with a frictionless integration get more customers and hence more properties, as a direct result of being easier to connect. 2. Compute prices on search You need to use computepricingbulk to fetch actual rates on bulk for a given availability search. 3. Use Kigo prices to provide approximate rates on search and compute final prices at a later step You need to fetch Display rates via readproperty2 and store them in your database. When a customer performs a search you will show these rates. At a later step when the guest has pre-selected a property (this depends on your booking process), you will use computepricing to calculate the actual price of the booking. Kigo, Inc. 12

13 4. AVAILABILITY AND RESERVATIONS 4.1. OVERVIEW Reservations in Kigo can have 4 different status: Inquiry Inquiries do not block the availability calendar. A guest can make multiple inquiries for different properties on the same check-in and check-out dates and there can be multiple inquiries for the same property, check-in and check-out date. Pricing computation is not necessary. Inquiries are not accessible via API. Hold dates Hold dates block the availability calendar. Hold dates are accessible but cannot be created via API. Confirmed Confirmed reservations block the availability calendar. Only 1 confirmed reservation can exist for a given property, check-in and check-out dates. Confirmed reservations are accessible and can be created via API. Canceled All reservations regardless their status can be canceled. Canceled reservations are not accessible via API. In an API context reservations have 3 main sections: Reservation details This refers to basic details such as check-in and check-out dates, number of guests, guest information, and so on. Reservation details in Kigo ( Reservations -> Edit -> Reservation and guest details ) Kigo, Inc. 13

14 Payment details Payment details in Kigo ( Properties -> Edit -> Payment details ) Guest payments in Kigo have the following structure: 1. Rent down payment This is the amount the guest usually pays at reservation creation time. The amount is usually a marginal percentage, like 10%, but technically it could be any amount, even 100%. 2. Rent remaining payment This is obviously the total amount minus the rent down payment. 3. Fees Individual fees added to the final amount. Please note that fees can be included in rent, and they can have their own payment schedule (i.e. they can be paid together with the down payment, together with the rent remaining payment or in a separate payment). This fields will be automatically populated based on the Rent schedule defined in the user s Kigo Backoffice every time there is a new reservation. This means the API user generally does not have to worry about this structure. Nonetheless, these amounts can be read with updatereservation. This section was only added for completion. Kigo, Inc. 14

15 4.2. RESERVATION CONSTRAINTS Instant booking vs Owner contact first For each property in Kigo the user can choose if it can be booked online or not. This option is located in the Properties section in the Backoffice, under the column Instant booking : Properties in Kigo ( Properties ) From a user experience point of view Instant booking OK means the property can be booked online, while Contact owner first means it only accepts inquiries and the owner needs to confirm availability. However, please note that this setting is used for Kigo s templates feature and it has no limiting effect whatsoever in allowing online bookings to be made via API. Thus, createconfirmedreservation method *will ignore* this setting. The reason is we let it open for portals to implement their own workflow for booking Contact owner first properties. You need to decide whether you want to implement a special procedure or ignore these properties altogether. Minimum and maximum stay times In Kigo it s possible to limit reservations to a minimum and maximum number of nights for each property. It is possible to set a default min / max stay in the Property information section of each property: Kigo, Inc. 15

16 Then, in Rent calculation it is also possible to set a minimum stay time for each period. Maximum number of guests Finally it is also possible to restrict reservations to a maximum number of guests in Property information. Kigo, Inc. 16

17 4.3. WORKING WITH RESERVATIONS API Reference diffpropertycalendarreservations This methods enables the client system to maintain a local copy of the property availability calendar by receiving information on new, updated and canceled reservations that impact the property availability calendar, from three months back from the current date, and up to the very last reservation in the property calendar readreservation This method returns the details of a property reservation. Only reservations that belong to your Rental Agency Kigo account may be read createconfirmedreservation This method creates a new, confirmed property reservation updatereservation This method updates an existing property reservation. Only reservations that belong to your Rental Agency Kigo account may be updated cancelreservation This method cancels a property reservation. Only reservations that belong to your Rental Agency Kigo account may be canceled. Use cases 1. Availability search First of all you will need to call diffpropertycalendarreservations in order to receive the full availability calendar of all your properties. You have to save a local copy of this calendar and update it regularly (we recommend between 2 minutes to 4 hours). This method will also return a parameter called DIFF_ID. You need to store this value as well and send it as input every time you update your availability calendar via this method. This way you will only receive the new reservations which were created, updated or canceled after your last call. 2. Create a confirmed reservation You will use createconfirmedreservation each time you need to create a confirmed reservation. Please note that this method will not enforce any reservation constraints (see above, 4.2. Reservation constraints). Thus, before calling this method, you will need to make sure all the constraints have been checked. a) minimum and maximum stay times readproperty2 method will provide you with PROP_STAYTIME_MIN and PROP_STAYTIME_MAX readpropertypricingsetup method will provide you with STAY_MIN for each period. In case of conflict the highest minimum stay should prevail. Kigo, Inc. 17

18 b) maximum number of guests readproperty2 method will also provide you with PROP_MAXGUESTS, PROP_MAXGUESTS_ADULTS, and so on. c) Instant booking or Contact owner first API users should get this information via listproperties2 or readproperty2, in the PROP_INSTANT_BOOK parameter. After checking these constraints, now you should be able to call createconfirmedreservation safely. 3. Update and/or Cancel a reservation Simply call either updatereservation or cancelreservation with reservation id (RES_ID). If you want to update a reservation you will also send an object holding the new values. When updating reservations, keep in mind that reservation constraints are not taken into account. Kigo, Inc. 18

19 5. OTHER TOPICS KEEP PORTAL HISTORY Some Kigo agencies will already be portal users as well and they might not want to lose their history with the portal by creating a new account. This problem can be solved on the portal s side by matching the properties from the portal and Kigo. It could either be a manual process, or the portal could build an interface for their users to be able to do the matching. If you want to go for this second alternative you need to ask for the user s RA_ID (Rental agency identifier) which is their unique identifier in Kigo. Kigo, Inc. 19

20 6. FAQ Do I need to set up IP filters to access the API? No, this is just a possibility, but is not mandatory. It is a good security measure, though. We suggest not to do it during the development phase. Can I access the User Defined Property Attributes of properties other agencies share with mine? No. Not using the API and also not on your Kigo back office. You can only access your own User Defined Property Attributes. I cannot see my portal commission anywhere in Kigo s rent calculation information. Portal commission is not dealt with in the Kigo rent calculation. It needs to be calculated and dealt with in your own system. I can t find any method to create Hold dates. Correct. Kigo API doesn t currently support the creation of Hold dates, just confirmed reservations. Can I send and receive inquiries using Kigo s API? Unfortunately, at the present Kigo s API doesn t provide support for inquiries. How will I know when my provider / reseller agencies cancel or modify reservation on properties shared with me? The cancellations and modifications are not pushed to your system. Kigo never pushes any information through the API. As you will be controlling your properties availability calendars using diffpropertycalendarreservations, you will be made aware of all the cancellations and modifications on your next call to this method (i.e. every half hour at the shortest). Kigo, Inc. 20