CiiRUS

Technical information

CiiRUS uses a [SOAP] API for interacting with its service. Concierge provides a simple SOAP client, API::Support::SOAPClient for such interfaces.

Actually CiiRUS provides two APIs:

Only whitelisted IPs will be allowed access. So Roomorama has a proxy http://proxy.roomorama.com/ciirus with provided access, if you want to request to Ping method https://api.ciirus.com/CiirusXML.15.025.asmx/Ping use the following instead http://proxy.roomorama.com/ciirus/CiirusXML.15.025.asmx/Ping.

Authentication

All calls to CiiRUS's API must be authenticated using an username and password combination. These are sent as xml block for every method call.

<APIUsername>Foo</APIUsername>
<APIPassword>123</APIPassword>

Note: be careful some methods require APIUsername field, but others require APIUserName field.

Quoting Prices

To check a property availability and get the price for a given stay use GetProperties method with PropertyId and ReturnQuote = true parameters. Also to make response more lightweight set ReturnFullDetails = false

Request

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://xml.ciirus.com/"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <GetProperties>
            <APIUsername>Foo</APIUsername>
            <APIPassword>123</APIPassword>
            <ArriveDate>01 Jul 2016</ArriveDate>
            <DepartDate>15 Jul 2016</DepartDate>
            <FilterOptions>  
                <ManagementCompanyID>0</ManagementCompanyID>  
                <CommunityID>0</CommunityID>  
                <PropertyID>38180</PropertyID>  
                <PropertyType>0</PropertyType>  
                <HasPool>2</HasPool>  
                <HasSpa>2</HasSpa>  
                <PrivacyFence>2</PrivacyFence>  
                <CommunalGym>2</CommunalGym>  
                <HasGamesRoom>2</HasGamesRoom>  
                <IsGasFree>false</IsGasFree>  
                <Sleeps>0</Sleeps>  
                <PropertyClass>0</PropertyClass>  
                <ConservationView>2</ConservationView>  
                <Bedrooms>0</Bedrooms>  
                <WaterView>2</WaterView>  
                <LakeView>2</LakeView>  
                <WiFi>2</WiFi>  
                <PetsAllowed>2</PetsAllowed>  
                <OnGolfCourse>2</OnGolfCourse>  
                <SouthFacingPool>2</SouthFacingPool>
            </FilterOptions>
            <SearchOptions>  
                <ReturnTopX>0</ReturnTopX>  
                <ReturnFullDetails>false</ReturnFullDetails>  
                <ReturnQuote>true</ReturnQuote>  
                <IncludePoolHeatInQuote>false</IncludePoolHeatInQuote>
            </SearchOptions>
            <xmlMsg/>
            <jSonMsg/>
        </GetProperties>
    </soap:Body>
</soap:Envelope>

Response

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
  <GetPropertiesResponse xmlns="http://xml.ciirus.com/">
      <GetPropertiesResult>
        <PropertyDetails>
          <PropertyID>38180</PropertyID>
          ...
          <CurrencyCode>USD</CurrencyCode>
          <QuoteExcludingTax>3072.30</QuoteExcludingTax>
          <QuoteIncludingTax>3440.98</QuoteIncludingTax>
          <ErrorMsg></ErrorMsg>
        </PropertyDetails>
      </GetPropertiesResult>
    </GetPropertiesResponse>
  </soap:Body>
</soap:Envelope>

Quotation.total = QuoteIncludingTax (total value including fees, mandatory extras, and the base rental)

Quotation.currency = CurrencyCode

According the documentation if you pass a date range, then only properties that are available for your specified dates will be returned. So an empty response can be interpreted as Quotation.available = false, otherwise Quotation.available = true An indicator of empty response is response with one PropertyDetails where ErrorMsg = "No Properties were found that fit the specified search Criteria."

Other ErrorMsg's values used for response validation.

Create booking

CiiRUS API has two methods for booking:

MakeBooking CiiRUS provides the quote and sets the price for the booking based on user defined rules.
AddBooking The integrating party takes on the responsibility of providing accurate quotes, and setting the price for bookings placed into the system.

Concierge uses the first one.

Request

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <MakeBooking xmlns="http://xml.ciirus.com/">
      <APIUsername>Foo</APIUsername>
      <APIPassword>123</APIPassword>
      <BD>
        <ArrivalDate>1 May 2016</ArrivalDate>
        <DepartureDate>10 May 2016</DepartureDate>
        <PropertyID>10</PropertyID>
        <GuestName>John Buttler</GuestName>
        <GuestEmailAddress>my@email.com</GuestEmailAddress>
        <GuestTelephone>+3 675 45879</GuestTelephone>
        <GuestAddress>Long Island 123</GuestAddress>
        <!-- As well as GuestList cannot be empty add customer as a guest with unknown age. 
             Currently count of guests doesn't affect the price. -->
        <GuestList>
          <sGuests>
            <Name>John Buttler</Name>
            <Age>-1</Age>
          </sGuests>
        </GuestList>
        <PoolHeatRequired>false</PoolHeatRequired>
        <xmlMsg/>
        <jSonMsg/>
      </BD>
    </MakeBooking>
  </soap:Body>
</soap:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <MakeBookingResponse xmlns="http://xml.ciirus.com/">
      <MakeBookingResult>
        <BookingPlaced>true</BookingPlaced>
        <ErrorMessage/>
        <BookingID>873184</BookingID>
        <TotalAmountIncludingTax>2858.850000</TotalAmountIncludingTax>
      </MakeBookingResult>
    </MakeBookingResponse>
  </soap:Body>
</soap:Envelope>

Reservation.reference_number = BookingID

BookingPlaced and ErrorMessage used for response validation.

Cancel booking

Cancel booking implemented by calling the CancelBooking method of the Additional CiiRUS API.

Request

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CancelBooking xmlns="http://xml.ciirus.com/">
      <APIUsername>Foo</APIUsername>
      <APIPassword>123</APIPassword>
      <BookingID>645789</BookingID>
    </CancelBooking>
  </soap:Body>
</soap:Envelope>

Response

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CancelBookingResponse xmlns="http://xml.ciirus.com/">
      <CancelBookingResult></CancelBookingResult>
    </CancelBookingResponse>
  </soap:Body>
</soap:Envelope>

CancelBookingResult is empty in success case.

Synchronisation

The sync process is executed by two workers:

Properties metadata sync Workers::Suppliers::Ciirus::Metadata
Properties availabilities sync Workers::Suppliers::Ciirus::Availabilities

Metadata

Metadata sync uses next CiiRUS API methods (wrapped by Ciirus::Importer class) to create Roomorama::Property instances:

[GetProperties] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetProperties) - fetches general information about properties
[GetPropertyPermissions] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetPropertyPermissions) - fetches property permissions and relationship settings. Used to filter out properties with online_booking_allowed == false and time_share == true. Timeshare properties are not supported by GetReservation method which used to calculate property availability.
[GetImageList] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetImageList) - fetches images for each property
[GetDescriptionsPlainText] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetDescriptionsPlainText) - fetches plain text description for each property (can be absent)
[GetDescriptionsHtml] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetDescriptionsHTML) - fetches html description for each property (used if plain text description is absent)
[GetPropertyRates] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetPropertyRates) - fetches property rates information, used to fill minimum_stay, nightly/weekly/monthly_rate information
[GetExtras] (https://api.ciirus.com/XMLAdditionalFunctions15.025.asmx?op=GetExtras) - fetches property extras, used to fill security deposit information (used an extra with code SD). Because security deposit info is additional information, request to this method is optional, if it fails property will be synced anyway.

Keep in mind that CiiRUS supplier has more then one host. Each host represented in CiiRUS as Management Company. So host.identifier in Roomorama is the same as ManagementCompanyID in CiiRUS. We should use this parameter in GetProperties request for getting only given host's properties.

Availabilities

Calendar sync uses next CiiRUS API methods (wrapped by Ciirus::Importer class) to create Roomorama::Calendar instances:

[GetPropertyRates] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetPropertyRates) - fetches property rate information for all available dateranges
[GetReservations] (https://api.ciirus.com/CiirusXML.15.025.asmx?op=GetReservations) - fetches information about property reservations

The worker marks dates as available if they are not reserved and have not zero rate. Note: the end date of each reservation period is available for new arrival.

Some rates can have rate.daily_rate == 0 we consider those rates as not available.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CiiRUS

Technical information

Authentication

Quoting Prices

Create booking

Cancel booking

Synchronisation

Clone this wiki locally