Option method [ORS Documentation]

ors-soap-api:public:option

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.

====== Option method ======

Create an "optional" booking (this is also called an "option"). This method creates booking in ORS with possibility to **cancel it without cancellation costs**. Options have a timeout period (usually 2 or 3 days - depending on touroperator). After this period (depending on touroperator settings) an option will be either automatically cancelled or booked (fixed). If you wish to cancel option after it was fixed, then you'll probably have cancellation costs. 

In some cases you can also set option timeout (this is useful when creating internet booking pages with online payment). Currently not many touroperators support this option so use this method with care.

Option is not always possible it depends on a number of days before checkin and a touroperator setup, so make sure to check returned status.
===== Valid content types =====

  * ''pauschal''
  * ''hotel''
  * ''trips''
  * ''charter''
  * ''oneway''
  * ''extras''

===== Description =====

<code php>
public array option( array $searchData, array $trip, array $headerData, boolean $testMode = false )
</code>


===== Parameters =====

  * ''searchData (array)'' : search and info parameters. Enter the same search parameters that you've used with [[trips|trips method]], because this will ensure that session won't expire, also use this for information about a customer and travellers.
  * ''trip (array)'' : trip parameters (you will get this info from [[trips|trips method]]). Required params are (''hsc'' and ''toc'', also ''sid'' when using ''trips'' content type.
  * ''headerData (array)'' : [[soap_header|SOAP Header Information]]
  * ''testMode (bool)'' : if ''true'' then a method will only test a booking in ORS (this is not possible for all touroperators that's why you should use [[register|register method]] for testing instead. If ''false'' then a valid booking will be made.


===== Return Values =====

Returns option status, booking number and total price for all passengers. If session hasn't expired then this method will also return offer and trip info. Output is almost identical to [[book|book method]]. When an option will expire is defined in ''info'' array as text.

<code>
Array
(
    [offerTripInfo] => Array
        (
            [xmlReq] => 

            [searchtermin_xmlReq] => 
            [header] => Array
                (
                    [typ] => hotel
                    [offers] => 1
                    [rgc] => 
                    [rgn] => 0
                    [rgg] => 
                    [rggn] => 
                    [pages] => 1
                    [perpage] => 20
                    [offset] => 
                    [sid] => 9h0f8a8kvi73h13mrju67cjbn0
                )

            [offer] => Array
                (
                    [pic] => http://www.ors.si/giata-pics/71088//full.jpg
                    [gid] => 71088
                    [htn] => Feral
                    [stc] => 4.0
                    [ovr] => 0
                    [oid] => 23887
                    [hon] => Brna
                    [fcts] => bea=1,ben=1,chf=0,clb=0,ani=0,pol=1,wel=0,spt=1,sgl=0,stn=0,ski=0
                    [dtemp] => 
                    [wtemp] => 
                    [rgc] => 659
                    [rgn] => Dalmatia
                    [rgg] => 100023
                    [rggn] => Croatia
                    [geo] => 1
                    [lat] => 42.9045823966052000
                    [lon] => 16.8566189525687980
                )

            [trip] => Array
                (
                    [sub] => catalog
                    [gid] => 71088
                    [toc] => PALM
                    [tockoda] => 80657677
                    [ton] => Palma
                    [rgc] => 659
                    [oid] => 2288
                    [zac] => EC
                    [zackoda] => 6967
                    [zan] => economy room
                    [vpc] => AI
                    [vpckoda] => 6573
                    [vpn] => all inclusive
                    [od] => aid=,iid=,lid=,vid=,zid=palm_22412
                    [htc] => LEHRV5041414
                    [svc] => 22412 EC AI
                    [ahckoda] => 
                    [vnd] => 2014-10-16
                    [bsd] => 2014-10-18
                    [tdc] => 2
                    [md5p] => 097327bb91f2aafa0ebde7687bf4b412
                    [md5t] => 33e14d43b65576a64e5dafcb4380558f
                    [hsc] => 33e14d43b65576a64e5dafcb4380558f
                    [ppc] => 76
                    [alt] => 0
                    [top] => 0
                    [tocpic] => http://www.ors.si/ibe/ikonce/toc/palm.gif
                    [aid] => 
                    [atx] => 
                    [iid] => 
                    [itx] => 
                    [lid] => 
                    [ltx] => 
                    [vid] => 
                    [vtx] => 
                    [zid] => palm_22412
                    [ztx] => 1/2+1 ECO AC; ALL LIGHT
                )

        )

    [response] => Array
        (
            [mid] => 201
            [ttp] => 213.00
            [ttpd] => 0.00
            [ppc] => 76.00
            [txt] => Option ok
            [status] => 1
        )

    [offer] => Array
        (
            [typ] => hotel
            [toc] => PALM
            [ton] => Palma
            [tocp] => http://www.ors.si/ibe/ikonce/toc/palm.gif
            [htc] => LEHRV504141486
            [gid] => 71088
            [hon] => KORČULA
            [oid] => 
            [desc] => 
            [zac] => EC
            [zan] => economy room
            [vpc] => AI
            [vpn] => all inclusive
            [svc] => 22412 EC AI
            [stc] => 
            [htn] => Hotel Feral 4*
            [zhc] => DBV
            [zhn] => Dubrovnik (Kroatien)
            [ahc] => 
            [ahn] => 
            [vnd] => 16.10.2014
            [bsd] => 18.10.2014
            [tdc] => 2
            [sub] => catalog
            [sid] => 
            [sin] => 
            [ovr] => 0
            [pic] => http://www.ors.si/giata-pics/71088/full.jpg
        )

    [operator] => Array
        (
            [toc] => PALM
            [hsc] => 33e14d43b65576a64e5dafcb4380558f
            [agt] => 454085
            [rmk] => My remark
            [prc] => 409842
            [bkc] => 20140818140737609            
        )

    [customer] => Array
        (
            [sur] => Smith
            [pre] => Smith
            [eml] => myemail@gmail.com
            [str] => 31st Park street
            [zip] => 12345
            [cty] => London
            [tel] => 00386 03 123 456
            [mob] => 00386 41 222 444
            [fax] =>
        )

    [travellers] => Array
        (
            [0] => Array
                (
                    [id] => 1
                    [typ] => H
                    [sur] => Smith
                    [pre] => John
                    [tvp] => 76
                    [age] => 09091982
                    [str] => 
                    [cty] => 
                    [zip] => 
                    [eml] => 
                    [tel] => 
                    [personalID] => 
                    [country] => 
                    [vatnr] => 
                    [promo] => 
                )

            [1] => Array
                (
                    [id] => 2
                    [typ] => D
                    [sur] => Smith
                    [pre] => Martha
                    [tvp] => 76
                    [age] => 08101981
                    [str] => 
                    [cty] => 
                    [zip] => 
                    [eml] => 
                    [tel] => 
                    [personalID] => 
                    [country] => 
                    [vatnr] => 
                    [promo] => 
                )

            [2] => Array
                (
                    [id] => 3
                    [typ] => K
                    [sur] => Smith
                    [pre] => Tony
                    [tvp] => 61
                    [age] => 12012000
                    [str] => 
                    [cty] => 
                    [zip] => 
                    [eml] => 
                    [tel] => 
                    [personalID] => 
                    [country] => 
                    [vatnr] => 
                    [promo] => 
                )

        )

    [info] => Array
        (
            [0] => Option until: 21.08.2014
            [1] => Room type: 1/2+1 ECO AC; ALL LIGHT
            [2] => Hotel Feral 4*
            [3] => Code: LEHRV504141486
            [4] => City: KORCULA
            [5] => Room: economy room
            [6] => Service: all inclusive
            [7] => Service code: 22412 EC AI
            [8] => --------------------------------------------------------------
            [9] => CRS powered by ORS XTREME
        )

    [errorNr] => 
    [error] => 
    [xmlReq] => 
</code>

===== Return parameters =====

  * ''offerTripInfo'' (array) : offer and trip info (check [[offertripinfo|offertripinfo]])
    * ''xmlReq'' : for internal use only
    * ''searchtermin_xmlReq'' : for internal use only
    * ''header (array)'' : information about a selected region and paging information (check [[trips|trips method]] for this return array)
    * ''offer (array)'' : check [[trips|trips method]] for this return array
    * ''trip (array)'' : check [[trips|trips method]] for this return array
  * ''xmlReq'' : ors xml request used with this method
  * ''xmlRes'' : ors xml response used with this method
  * ''response (array)'' : availability status, message and a total price
    * ''mid'' : availability message ID (check [[Message IDs]] for a list of possible values)
    * ''txt'' : availability text message (message is in selected language and it depends on ''mid'' value)
    * ''status'' : availability status. 
      * **0** : offer is not free
      * **1** : offer is free and option was successfull
      * **2** : offer is on request and option was successfull. If offer is on request, a person must wait for a touroperator confirmation.
      * **3** : communication error (something went wrong with communication between ORS and touroperator).
      * **4** : offer is sold out (same as status 0)
      * **5** : booking is not possible, you must check availability text message for detailed description of a problem
    * ''ttp'' : total price for all passengers
    * ''ppc'' : price per person (in situations when there is a price per room then this value will be empty or zero)
    * ''ttpd'' : this is a reserved parameter!
  * ''offer (array)'' : this are an offer information directly from touroperator. This values may differ from ''offerTripInfo'' information!
    * ''typ'' : content type
    * ''sub'' : sub category
    * ''toc'' : touroperator code
    * ''ton'' : touroperator name
    * ''tocp'' : touroperator logo
    * ''htc'' : hotel code (or product code)
    * ''gid'' : accommodation GIATA ID
    * ''hon'' : city name
    * ''oid'' : city ID
    * ''desc'' : reserved parameter
    * ''zac'' : room type code
    * ''zan'' : room type name
    * ''vpc'' : service type code
    * ''vpn'' : service type name
    * ''svc'' : service code
    * ''htn'' : accommodation name
    * ''stc'' : hotel category
    * ''zhc'' : destination code (IATA code)
    * ''zhn'' : destination name
    * ''ahc'' : departure airport code (IATA code)
    * ''ahn'' : departure airport name
    * ''vnd'' : checkin date
    * ''bsd'' : checkout date
    * ''tdc'' : duration
    * ''sid'' : bus stop id (only for ''trips'' content type)
    * ''sin'' : bus stop name
    * ''idp'' : offer ID (use this to search ''extras'' services that are in combination with accommodation)
    * ''ovr'' : overall rating
    * ''pic'' : full picture
  * ''actions (array)'' : promotions used with this offer. This is currently experimental because not all touroperator return this info.
  * ''operator (array)'' : used action, touroperator info and trip hash code
    * ''act'' : action
    * ''toc'' : touroperator code
    * ''hsc'' : unique trip hash code used for this check method 
    * ''agt'' : agency number
    * ''rmk'' : user remarks (if user hasn't sent any remarks then this parameter is empty)
    * ''prc'' : boking number (if this parameter is empty then booking was not successfull)
    * ''bkc'' : ORS internal registration number
  * ''customer (array)'' : customer info (to whom the reservation is made)
    * ''sur'' : last name
    * ''pre'' : first name
    * ''eml'' : email address
    * ''str'' : street
    * ''zip'' : zip code
    * ''cty'' : city
    * ''tel'' : telephone
    * ''mob'' : mobile
    * ''fax'' : fax number
  * ''travellers (array)'' : passengers info
    * ''id'' : passenger sequence number
    * ''typ'' : passenger sex / type. Possible values: 
      * **H** : mr.
      * **D** : mrs.
      * **K** : child
      * **B** : baby (infant)
    * ''sur'' : last name
    * ''pre'' : first name
    * ''age'' : age / birthday
    * ''tvp'' : price for this person
    * ''str'' : street
    * ''cty'' : city
    * ''zip'' : zip code
    * ''eml'' : email
    * ''tel'' : telephone
    * ''personalID'' : personal ID number
    * ''country'' : ISO country code
  * ''info'' : touroperator information text. This text is directly from selectged touroperator and can be in different language. Usually this text contains important information about checked offer.
  * ''errorNr'' : error number
  * ''error'' : error message

===== Examples =====

  * Example of option

<code php>
$searchParams = array(
  'vnd' => '30.10.2014',       // start date
  'bsd' => '15.11.2014',       // end date
  'tdc' => '1-4',              // duration [min-max] days
  'epc' => '2',                // number of adults
  'ka1' => '14',               // age of first child
  'gid' => '71088',            // selected hotel by GIATA ID
  'eml' => 'myemail@gmail.com',  // required parameter !
  'zip' => '12345',              // required parameter !
  'str' => '31st Park street',   // required parameter !
  'cty' => 'London',             // required parameter !
  'tel' => '00386 03 123 456',   // telephone
  'mob' => '00386 41 222 444',   // mobile 
  'sur1' => 'Smith',             // required parameter !
  'pre1' => 'John',              // required parameter !
  'sur2' => 'Smith',             // required parameter !
  'pre2' => 'Martha',            // required parameter ! 
  'sur3' => 'Smith',             // required parameter ! 
  'pre3' => 'Tony',              // required parameter !
  'anrede1' => 'H',              // required parameter !
  'anrede2' => 'D',              // required parameter !
  'anrede3' => 'K',              // required parameter !
  'age1' => '19820909',          // birth day of first passenger (format: 'Ymd') - 9th sep 1982
  'age2' => '19811008',          // birth day of second passenger (format: 'Ymd') - 8th oct 1081
  'age3' => '20001201',          // birth day of third passenger (format: 'Ymd') - 1st dec 2000
);
$trip = array(
  'hsc' => '33e14d43b65576a64e5dafcb4380558f',  // unique trip hash code
  'toc' => 'PALM'                               // toruoperator code
);

// create option
$book = $soapClient->orsxml_hotel_api_call( 'option', $searchParams, $trip, $headerData );

// check status and total price
if ($book['response']['status'] == 1) {

  echo "Booking was successfull. Booking number is: " . $book['response']['prc'] . "\n";
  echo "Total price: " . $book['response']['ttp'];
 
}
  
if ($book['response']['status'] == 2) {

  echo "Booking on request was successfull. Booking number is: " . $book['response']['prc'] . "\n";
  echo "Total price: " . $book['response']['ttp'];
    
}

if ($book['response']['status'] == 0 || $book['response']['status'] == 4) {

  echo "Can't create booking, offer is not available";

}

if ($book['response']['status'] == 3) {

  echo "Can't create booking, Communication error. Please try again. \n";
  echo "Touroperator message: " . $book['response']['txt'];
  
}

if ($book['response']['status'] == 5) {

  echo "Can't create booking, Check touroperator message: " . $book['response']['txt'];
  
}

</code>

  * Example of setting timeout (this option supports only a few touroperators)

<code php>
$searchParams = array(
  ...                                           // same parameters as before...
  'datum_option' => '2014-11-30 23:59:59',      // when option ends
)

// create option
$book = $soapClient->orsxml_hotel_api_call( 'option', $searchParams, $trip, $headerData );
</code>

  * Example for advance payment (this option supports only a few touroperators)

<code php>
$searchParams = array(
  ...                                           // same parameters as before...
  'advance_payment' => '140',   // set the advance payment amount (ie. 140 -- for 140€)
)

// create option
$book = $soapClient->orsxml_hotel_api_call( 'option', $searchParams, $trip, $headerData );
</code>

  * Example booking fee (this option supports only a few touroperators)

<code php>
$searchParams = array(
  ...                     // same parameters as before...
  'bfee' => '3%',         // set booking fee for entire booking (ie. 3%)
)

// create option
$book = $soapClient->orsxml_hotel_api_call( 'option', $searchParams, $trip, $headerData );
</code>

  * Example payment method (this option supports only a few touroperators)

<code php>
$searchParams = array(
  ...                             // same parameters as before...
  'payment_method' => 'cc',       // set payment method (supported: 'cc' - credit cards, 'upn' - wire transfer, 'paypal' - Pay Pal)
)

// create option
$book = $soapClient->orsxml_hotel_api_call( 'option', $searchParams, $trip, $headerData );
</code>
===== Examples (Extras) =====

Before making an option with extras you must fist make ''offers'' request to get extras hash codes. Check [[offers method|offers]] on how to get different extras.

  * Example of simple option with extras (packages accommodation + extras). When booking packages a ''$searchParams'' is a bit different. Accommodations and extras are entered as arrays. You can book different accommodations with more then one room (be careful that you place persons correctly). 

<code php>
$searchParams = array(
  'vnd' => '30.10.2014',         // start date
  'bsd' => '15.11.2014',         // end date
  'tdc' => '1-4',                // duration [min-max] days
  'epc' => '4',                  // number of adults
  'eml' => 'myemail@gmail.com',  // required parameter !
  'zip' => '12345',              // required parameter !
  'str' => '31st Park street',   // required parameter !
  'cty' => 'London',             // required parameter !
  'tel' => '00386 03 123 456',   // telephone
  'mob' => '00386 41 222 444',   // mobile
  'sur1' => 'Smith',             // required parameter !
  'pre1' => 'John',              // required parameter !
  'sur2' => 'Smith',             // required parameter !
  'pre2' => 'Martha',            // required parameter ! 
  'sur3' => 'Forrester',         // required parameter !
  'pre3' => 'Tim',               // required parameter !
  'sur4' => 'Forrester',         // required parameter !
  'pre4' => 'Amanda',            // required parameter ! 
  'anrede1' => 'H',              // required parameter !
  'anrede2' => 'D',              // required parameter !
  'anrede3' => 'H',              // required parameter !
  'anrede4' => 'D',              // required parameter !
  
  // accommodations
  'hotel' => array(
  
    // first accommodation
    '2262:4862:ZAD22627102:7102:OV:2014-08-16:2014-08-23' => array(
    
      // first room (for 1st and 2nd person)
      0 => array(
        'hsc' => '2262:4862:ZAD22627102:7102:OV:2014-08-16:2014-08-23',   // offer hash code
        'psn' => '1,2',                                                   // 1st and 2nd person
      ),
      
      // second room (for 3rd and 4th person)
      1 => array(
        'hsc' => '2262:4862:ZAD22627102:7102:OV:2014-08-16:2014-08-23',   // offer hash code
        'psn' => '3,4',                                                   // 3rd and 4th person
      )
      
    )
  )

  // extras
  'extras' => array(  
  
    // 1st extras (for all persons)
    '199|0||0|2014-08-18|2014-08-18|2014-08-18' => array( 
      'hsc' => '199|0||0|2014-08-18|2014-08-18|2014-08-18',
      'psn' => '1,2,3,4'
    ),
    
    // 2nd extras (for first two persons)
    '751|0||0|2014-08-18|2014-08-18|2014-08-18' => array( 
      'hsc' => '751|0||0|2014-08-18|2014-08-18|2014-08-18',
      'psn' => '1,2'
    )

  ),
);
$trip = array(
  'hsc' => 'x',      // when booking packages, then just place 'x' for this parameter
  'toc' => 'CMT'     // touroperator code
);

// book method
$book = $soapClient->orsxml_hotel_api_call( 'option', $searchParams, $trip, $headerData, true );

</code>

 * Example of booking only extra services (without accommodation) 

<code php>
$searchParams = array(
  'epc' => '2',                  // number of adults
  'eml' => 'myemail@gmail.com',  // required parameter !
  'zip' => '12345',              // required parameter !
  'str' => '31st Park street',   // required parameter !
  'cty' => 'London',             // required parameter !
  'tel' => '00386 03 123 456',   // telephone
  'mob' => '00386 41 222 444',   // mobile
  'sur1' => 'Smith',             // required parameter !
  'pre1' => 'John',              // required parameter !
  'sur2' => 'Smith',             // required parameter !
  'pre2' => 'Martha',            // required parameter ! 
  'anrede1' => 'H',              // required parameter !
  'anrede2' => 'D',              // required parameter !
  
  // extras
  'extras' => array(  
  
    // 1st extras (for all persons)
    '199|0||0|2014-08-18|2014-08-18|2014-08-18' => array( 
      'hsc' => '199|0||0|2014-08-18|2014-08-18|2014-08-18',
      'psn' => '1,2'
    ),
    
  ),
);
$trip = array(
  'hsc' => 'x',      // when booking packages, then just place 'x' for this parameter
  'toc' => 'CMT'     // touroperator code
);

// book method (when booking only extras, use 'extras' API call!!)
$book = $soapClient->orsxml_extras_api_call( 'option', $searchParams, $trip, $headerData );

</code>

ors-soap-api/public/option.txt · Last modified: 2015/01/24 16:40 (external edit)