Skip to content

Avantio

Jump to bottom
Konstantin Kolotyuk edited this page Oct 26, 2016 · 14 revisions

Avantio site https://www.avantio.com/ (previous name 'itsolutions')

Technical information

All required information can be found in official documentation http://feeds.avantio.com/doc/api_for_portals.pdf. This document is updated constantly. Current API version is 2.6.

Briefly, Avantio provides two ways to get data about accommodations:

  1. Via XML files. List of files can be found in the documentation. This way is used by sync workers. Files are updated with different frequency from several hours to several days (more details in documentation). Avantio is multihost supplier. Each host has CODE_PARTNER provided by Avantio. To get access to files you only need CODE_PARTNER.

  2. Via SOAP API. This way is used by Concierge webhooks. Each API method requires username and password to be presented in request:

<Credentials>
  <Language>EN</Language>
  <UserName>Foo</UserName>
  <Password>123</Password>
</Credentials>

NOTE: wsdl.xml contains a lot of methods but only those which described in the documentation works fine. Others return a similar error:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Client</faultcode>
         <faultstring>PolicyFault: the access policy has been violated</faultstring>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Accommodation identifier

Each Avantio accommodation always has three parameters: AccommodationCode, UserCode, LoginGA. This triple used by SOAP API to identify the accommodation. As well as Roomorama requires one identifier for each property these three should be converted to one to be stored in Roomorama. Avantio::PropertyId class responsible for converting Avantio ids to Roomorama id and vice versa. For more details see the class documentation.

Quoting Prices

To check a property availability and get the price for a given stay use IsAvailable and GetBookingPrice methods.

NOTE: GetBookingPrice returns valid response even for unavailable periods, so check with IsAvailable method is required!

IsAvailable Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="ws.avantio.com/crsConnectionServices/xsd" xmlns:crs="ws.avantio.com/crsConnectionServices">
   <soapenv:Header/>
   <soapenv:Body>
      <xsd:IsAvailableRQ>
         <crs:Credentials>
            <crs:Language>EN</crs:Language>
            <crs:UserName>username</crs:UserName>
            <crs:Password>password</crs:Password>
         </crs:Credentials>
         <crs:Criteria>
            <crs:Accommodation>
               <crs:AccommodationCode>55720</crs:AccommodationCode>
               <crs:UserCode>1210075202</crs:UserCode>
               <crs:LoginGA>itsalojamientos</crs:LoginGA>
            </crs:Accommodation>
            <crs:Occupants>
               <crs:AdultsNumber>1</crs:AdultsNumber>
            </crs:Occupants>
            <crs:DateFrom>2016-10-01</crs:DateFrom>
            <crs:DateTo>2016-10-22</crs:DateTo>
         </crs:Criteria>
      </xsd:IsAvailableRQ>
   </soapenv:Body>
</soapenv:Envelope>

Each valid response contains AvailableCode field. Possible values for this field described in the documentation. 1 means available.

Unavailable response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:IsAvailableRS xmlns:ns1="ws.avantio.com/crsConnectionServices/xsd" xmlns:ns2="ws.avantio.com/crsConnectionServices">
         <ns2:Available>
            <ns2:AvailableCode>-3</ns2:AvailableCode>
            <ns2:AvailableMessage>The compulsory arrival date is not fulfilled</ns2:AvailableMessage>
         </ns2:Available>
         <ns2:OccupationalRule>
            <ns2:StartDate>21/06/2016</ns2:StartDate>
            <ns2:EndDate>31/12/2016</ns2:EndDate>
            <ns2:MinimumNights>5</ns2:MinimumNights>
            <ns2:MinimumNightsOnline>1</ns2:MinimumNightsOnline>
            <ns2:CheckInDays>
               <ns2:WeekDay>MONDAY</ns2:WeekDay>
               <ns2:WeekDay>TUESDAY</ns2:WeekDay>
               <ns2:WeekDay>WEDNESDAY</ns2:WeekDay>
            </ns2:CheckInDays>
            <ns2:CheckOutDays>
               <ns2:WeekDay>THURSDAY</ns2:WeekDay>
               <ns2:WeekDay>FRIDAY</ns2:WeekDay>
               <ns2:WeekDay>SATURDAY</ns2:WeekDay>
               <ns2:WeekDay>SUNDAY</ns2:WeekDay>
            </ns2:CheckOutDays>
         </ns2:OccupationalRule>
      </ns1:IsAvailableRS>
   </soapenv:Body>
</soapenv:Envelope>

Available response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:IsAvailableRS xmlns:ns1="ws.avantio.com/crsConnectionServices/xsd" xmlns:ns2="ws.avantio.com/crsConnectionServices">
         <ns2:Available>
            <ns2:AvailableCode>1</ns2:AvailableCode>
            <ns2:AvailableMessage>Available</ns2:AvailableMessage>
         </ns2:Available>
      </ns1:IsAvailableRS>
   </soapenv:Body>
</soapenv:Envelope>

GetBookingPrice Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="ws.avantio.com/crsConnectionServices/xsd" xmlns:crs="ws.avantio.com/crsConnectionServices">
   <soapenv:Header/>
   <soapenv:Body>
      <xsd:GetBookingPriceRQ>
         <crs:Credentials>
            <crs:Language>EN</crs:Language>
            <crs:UserName>username</crs:UserName>
            <crs:Password>password</crs:Password>
         </crs:Credentials>
         <crs:Criteria>
            <crs:Accommodation>
               <crs:AccommodationCode>55720</crs:AccommodationCode>
               <crs:UserCode>1210075202</crs:UserCode>
               <crs:LoginGA>itsalojamientos</crs:LoginGA>
            </crs:Accommodation>
            <crs:Occupants>
               <crs:AdultsNumber>1</crs:AdultsNumber>
            </crs:Occupants>
            <crs:ArrivalDate>2016-10-03</crs:ArrivalDate>
            <crs:DepartureDate>2016-10-22</crs:DepartureDate>
         </crs:Criteria>
      </xsd:GetBookingPriceRQ>
   </soapenv:Body>
</soapenv:Envelope>

Response contains a lot of different prices. We are interested in RoomOnlyFinal.

GetBookingPrice response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:GetBookingPriceRS xmlns:ns1="ws.avantio.com/crsConnectionServices/xsd" xmlns:ns2="ws.avantio.com/crsConnectionServices">
         <ns2:BookingPrice>
            <ns2:RoomOnly>7600</ns2:RoomOnly>
            <ns2:RoomOnlyFinal>7605</ns2:RoomOnlyFinal>
            <ns2:RoomOnlyWithoutOffer>7600</ns2:RoomOnlyWithoutOffer>
            <ns2:RoomOnlyFinalWithoutOffer>7605</ns2:RoomOnlyFinalWithoutOffer>
            <ns2:RoomOnlyPaymentWhenBooking>2660</ns2:RoomOnlyPaymentWhenBooking>
            <ns2:RoomOnlyFinalPaymentDetails>
               <ns2:PaymentDetail>
                  <ns2:PaymentNumber>1</ns2:PaymentNumber>
                  <ns2:PaymentTime>WhenBooking</ns2:PaymentTime>
                  <ns2:Amount>2660</ns2:Amount>
                  <ns2:PaymentDate>2016-09-13</ns2:PaymentDate>
                  <ns2:PaymentMethods>
                     <ns2:PaymentMethod>1</ns2:PaymentMethod>
                     <ns2:PaymentMethod>43</ns2:PaymentMethod>
                  </ns2:PaymentMethods>
               </ns2:PaymentDetail>
               <ns2:PaymentDetail>
                  <ns2:PaymentNumber>2</ns2:PaymentNumber>
                  <ns2:PaymentTime>WhenArrival</ns2:PaymentTime>
                  <ns2:Amount>4945</ns2:Amount>
                  <ns2:PaymentDate>2016-10-03</ns2:PaymentDate>
               </ns2:PaymentDetail>
            </ns2:RoomOnlyFinalPaymentDetails>
            <ns2:Currency>EUR</ns2:Currency>
         </ns2:BookingPrice>
         <ns2:CancellationPolicies>
            <ns2:Description>In case of cancellation the following charges will apply:
- If the reservation is cancelled: the prepayment amount.</ns2:Description>
            <ns2:CancellationPolicyList>
               <ns2:CancellationPolicyItem>
                  <ns2:RoomOnlyAmount>2660</ns2:RoomOnlyAmount>
                  <ns2:Deadline>2016-10-02</ns2:Deadline>
               </ns2:CancellationPolicyItem>
            </ns2:CancellationPolicyList>
            <ns2:NoShow>
               <ns2:RoomOnlyAmount>0</ns2:RoomOnlyAmount>
            </ns2:NoShow>
            <ns2:Currency>EUR</ns2:Currency>
         </ns2:CancellationPolicies>
         <ns2:TermsAndConditions>http://crs.itsolutions.es/verCondicionesGenerales.php?bk=bk_demoss&amp;Idioma=EN&amp;formato=1</ns2:TermsAndConditions>
         <ns2:Services>
            <ns2:Service>
               <ns2:Code>18</ns2:Code>
               <ns2:Amount>1</ns2:Amount>
            </ns2:Service>
            <ns2:Service>
               <ns2:Code>10</ns2:Code>
               <ns2:Amount>1</ns2:Amount>
            </ns2:Service>
         </ns2:Services>
      </ns1:GetBookingPriceRS>
   </soapenv:Body>
</soapenv:Envelope>

Create booking

Avantio API has SetBooking method for booking.

NOTE: SetBooking returns valid response even for unavailable periods, so check with IsAvailable method is required!

SetBooking request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="ws.avantio.com/crsConnectionServices/xsd" xmlns:crs="ws.avantio.com/crsConnectionServices">
   <soapenv:Header/>
   <soapenv:Body>
      <xsd:SetBookingRQ>
         <crs:Credentials>
            <crs:Language>EN</crs:Language>
            <crs:UserName>username</crs:UserName>
            <crs:Password>password</crs:Password>
         </crs:Credentials>
         <crs:BookingData>
            <crs:ArrivalDate>2015-10-03</crs:ArrivalDate>
            <crs:DepartureDate>2016-10-22</crs:DepartureDate>
            <crs:Accommodation>
               <crs:AccommodationCode>55720</crs:AccommodationCode>
               <crs:UserCode>1210075202</crs:UserCode>
               <crs:LoginGA>itsalojamientos</crs:LoginGA>
            </crs:Accommodation>
            <crs:Occupants>
               <crs:AdultsNumber>1</crs:AdultsNumber>
            </crs:Occupants>
            <crs:ClientData>
               <crs:Name>John</crs:Name>
               <crs:Surname>Buttler</crs:Surname>
               <crs:DNI></crs:DNI>
               <crs:Address></crs:Address>
               <crs:Locality></crs:Locality>
               <crs:PostCode></crs:PostCode>
               <crs:City></crs:City>
               <crs:Country></crs:Country>
               <crs:Telephone>+79618492980</crs:Telephone>
               <crs:Telephone2></crs:Telephone2>
               <crs:EMail>sharipov.reg@gmail.com</crs:EMail>
               <crs:Fax></crs:Fax>
               <crs:Language>EN</crs:Language>
            </crs:ClientData>
            <crs:Board>ROOM_ONLY</crs:Board>
            <crs:PaymentMethod>26</crs:PaymentMethod>
            <!-- UNPAID: prebooking without confirmation
                 PETICION_INFORMACION: It does not neither do a booking nor block the period requested. 
It just ask the accommodation owner for information about how the booking would be. We use this value in test mode.-->
            <crs:BookingType>PETICION_INFORMACION</crs:BookingType>
            <crs:Comments></crs:Comments>
            <crs:SendMailToOrganization>true</crs:SendMailToOrganization>
            <crs:SendMailToTourist>false</crs:SendMailToTourist>
         </crs:BookingData>
      </xsd:SetBookingRQ>
   </soapenv:Body>
</soapenv:Envelope>

NOTE: Avantio support comment

in the event that Roomorama is responsible for charging the reservations, the paymentMethod that you have to use is 26.

Take into account that this payment method implies that Roomorama must send the e-mails of the reservations to the tourists, so we need you to use the following SetBooking service configuration:

SendMailToTourist = false SendMailToOrganization = true

Success SetBooking response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:SetBookingRS xmlns:ns1="ws.avantio.com/crsConnectionServices/xsd" xmlns:ns2="ws.avantio.com/crsConnectionServices">
         <ns2:Success>true</ns2:Success>
         <ns2:Localizer>
            <ns2:BookingCode>1494396</ns2:BookingCode>
            <ns2:Localizator>1494396-1210075202</ns2:Localizator>
         </ns2:Localizer>
      </ns1:SetBookingRS>
   </soapenv:Body>
</soapenv:Envelope>

We are interested in storing BookingCode

Error SetBooking response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:SetBookingRS xmlns:ns1="ws.avantio.com/crsConnectionServices/xsd" xmlns:ns2="ws.avantio.com/crsConnectionServices">
         <ns2:Success>false</ns2:Succeed>
         <ns2:ErrorList>
            <ns2:Error>
               <ns2:ErrorId>303</ns2:ErrorId>
            </ns2:Error>
            <ns2:Error>
               <ns2:ErrorId>5005</ns2:ErrorId>
               <ns2:ErrorMessage>Fallo al desbloquear el periodo de disponibilidad</ns2:ErrorMessage>
            </ns2:Error>
         </ns2:ErrorList>
      </ns1:SetBookingRS>
   </soapenv:Body>
</soapenv:Envelope>

Cancel booking

Avantio API provides CancelBooking method.

Cancel request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="ws.avantio.com/crsConnectionServices/xsd" xmlns:crs="ws.avantio.com/crsConnectionServices">
   <soapenv:Header/>
   <soapenv:Body>
      <xsd:CancelBookingRQ>
         <crs:Credentials>
            <crs:Language>EN</crs:Language>
            <crs:UserName>username</crs:UserName>
            <crs:Password>password</crs:Password>
         </crs:Credentials>
         <crs:Localizer>
            <crs:BookingCode>1497922</crs:BookingCode>
         </crs:Localizer>
         <crs:Comments></crs:Comments>
         <crs:SendMailToOrganization>true</crs:SendMailToOrganization>
         <crs:SendMailToTourist>false</crs:SendMailToTourist>
      </xsd:CancelBookingRQ>
   </soapenv:Body>
</soapenv:Envelope>

Cancel success response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:CancelBookingRS xmlns:ns1="ws.avantio.com/crsConnectionServices/xsd" xmlns:ns2="ws.avantio.com/crsConnectionServices">
         <ns2:Succeed>true</ns2:Succeed>
      </ns1:CancelBookingRS>
   </soapenv:Body>
</soapenv:Envelope>

Error Cancel response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:CancelBookingRS xmlns:ns1="ws.avantio.com/crsConnectionServices/xsd" xmlns:ns2="ws.avantio.com/crsConnectionServices">
         <ns2:Succeed>false</ns2:Succeed>
         <ns2:ErrorList>
            <ns2:Error>
               <ns2:ErrorId>303</ns2:ErrorId>
            </ns2:Error>
            <ns2:Error>
               <ns2:ErrorId>5005</ns2:ErrorId>
               <ns2:ErrorMessage>Fallo al desbloquear el periodo de disponibilidad</ns2:ErrorMessage>
            </ns2:Error>
         </ns2:ErrorList>
      </ns1:CancelBookingRS>
   </soapenv:Body>
</soapenv:Envelope>

Synchronisation

The sync process is executed by two workers:

  • Properties metadata sync Workers::Suppliers::Avantio::Metadata
  • Properties availabilities sync Workers::Suppliers::Avantio::Availabilities

which uses XML files provided by Avantio.

Metadata

Uses next files:

  • accommodations - contains list of the accommodations available for given host. Used to fetch basic information for each property.
  • descriptions - used to fetch property description and images
  • occupationalrules - used to fetch property minimum stay
  • rates - used to know property nigthly price
  • availabilities - actually is not used for property building, but used for calendar building. So we should be sure that accommodation has valid availability data, otherwise we skip the property.

There are possible cases when property presented in accommodations file and unknown in some other file. Such properties will be skipped during sync process.

Calendar

Uses next files:

  • occupationalrules - used to fetch property minimum stay, checkin/checkout allowed
  • rates - used to know property nigthly price
  • availabilities - used to know if property available on date

NOTES:

  1. Concierge builds Avantio calendar for period [today, today + 1 year]
  2. If for some date property doesn't have rule, rate or availability this date marked as unavailable. (The same behavior is on the avantio property web page)

Price calculation

Avantio XML files don't provide property price as is, they provides a set of rules how to calculate the price. Rules are not so simple. Below short description of these rules.

Each property has rate entity. Each rate determines the price (per person or per accommodation) for different periods of time. Some rates' periods (if price given per person) can have discounts (always in %) for the third, ..., seventh adult, or first, ..., fourth child.

Some rates' periods can have supplements. There are several kinds of supplements.

  1. Supplement for single person (in % or amount).
  2. Supplement by additional person. Only applicable if price given per accommodation and if amount of people exceeds the given limit.

Also each accommodation can have price modifier

Kinds of modifiers:

  • S Supplement
  • SSS Supplement for short stay
  • D Discount
  • DLS Discount for long stay
  • EB Early booking discount. Booking done before the day (yyyy-mm-dd). See parameter MaxDate.
  • EBD Early booking discount. Bookings done X days before the arrival date. See parameter DaysAdvance.

Each price modifier has seasons (period of time when modifiers applicable), each season have its own kind of modifier, seasons can intersect each other (sometimes in this case their affects accumulate). Each season can have additional conditions:

  • MinNumberOfNights - it means that the discount will take effect only if the number of nights of the booking is greater than this value
  • MaxNumberOfNights - it means that the supplement will take effect only if the number of nights of the booking is fewer than this value
  • NumberOfNights - it means that the supplement or the discount will take effect only if the number of nights of the booking is equal to this value
  • MaxDate and DaysAdvance - described above.

Each season also can have next fields:

  • DiscountSupplementType - if this field is "percent", it means that the amount tag is given in percentage of the final price, if this field is "amount", it means that the Amount tag is the quantity in monetary units to add or subtract to the final price, if this field is "days", it means that the amount tag is the quantity of days that are free.
  • Amount - Amount of supplement or discount. This value can refer either to money (if DiscountSupplementType="amount"), or percentage of the final price (if DiscountSupplementType="%"), or days (if DiscountSupplementType="days"). Positive values for supplements, negative for discounts. Take in mind that even if DiscountSupplementType="days" a negative number means discount and positive supplement.

So the price depends on a lot of factors and currently these rules don't allow Concierge calculate the price correctly as value and send to Roomorama. That is why Concierge during metadata and availabilities sync calculates the price with inaccuracy. Namely:

  • during metadata sync to fill property nigthly_rate it takes property's rate entity, takes actual periods (from daterange [today, today + 1 year] and with RoomOnly/Price > 0) of the entity and calculates min RoomOnly/Price for all these periods. As result it has a price (per accommodation or per 1 person) without applied discounts and supplements.
  • during availabilities sync to fill nigthly_rate for each date it takes property's rate entity, finds period of this entity the date belongs to and takes its RoomOnly/Price. As result it has a price (per accommodation or per 1 person) without applied discounts and supplements.

NOTE: quote webhook returns true price as well as Concierge uses special SOAP API for this case.

Answers from Avantio support

  1. Question: The services.xml provides information about all possible services that an accommodation may have. For some services we found repeats. For example we found 45 services about cleaning:
"10"=>"Final Cleaning"
"23"=>"Extra Cleaning"
"30"=>"Adittional cleaning services"
"42"=>"Extra Cleaning"
"49"=>"Basic facial cleaning"
"54"=>"Complete facial cleaning"
"171"=>"Daily cleaning"
"185"=>"Weekly cleaning of bedrooms and bathrooms"
...

Answer: The standard service of cleaning fee is the "10"=>"Final Cleaning". You can map this service in your system as the info of the cleaning fee.

The reason for the rest of the service is that each company can create a new service (with its own name) and associated accommodation. These services can be considered as an extra service (not as the cleaning fee).

  1. Question: Rules from occupationalrules.xml can contain MinimumNights and MinimumNightsOnline tags at the same time and we thought that MinimumNightsOnline is more actual for us, but lately we found a property with next tags:
<MinimumNights>5</MinimumNights><MinimumNightsOnline>1</MinimumNightsOnline>

which doesn't allow to book less then 5 days on your site. If we book via API what minimum_nights is actual for us?

Answer: You should use MinimumNights.

  1. Question: The API documentation contains two places with info about availabilities.xml update frequency:

This file is updated everyday.

and

The basic property data, pictures and descriptions is updated twice a week, prices file twice a day and availabilities file every 3 hours.

Are we right when conclude that availabilities.xml updated every 3 hours?

Answer: Yes. The Availabilities.xml file is updated every 2-3 hours.

Clone this wiki locally