.. meta::
  :description: Wired API, handling extras, opportunities, special offers
  :keywords: Wired, xml, api, channel manager, booking engine, handling extras, opportunities, special offers

======
Extras
======

Introduction
************

This chapter will describe how to manage property's extras, like Opportunities (also called Add-ons and Reductions within the WuBook Extranet) and Special Offers.

.. warning:: Extras are only used within the WuBook Extranet and shown on WuBook Booking Engine; they have no involvement with Channel Manager.


Opportunities
*************

Opportunities can suppose a price add-on or reduction within a reservation, and can be generic or Room related:

* Generic: excursions, city tours, etc.
* Room related: extra bed for a double room, adding a cradle, etc.

Opportunity characteristics
---------------------------

Each Opportunity will be defined for these fields:

+------------+------------------------------------------------------------+
| Field      | Meaning                                                    |
+============+============================================================+
| oid        | The ID of the Opportunity                                  |
+------------+------------------------------------------------------------+
| name       | The main name of the Opportunity                           |
+------------+------------------------------------------------------------+
| active     | 1 if enabled, 0 otherwise                                  |
+------------+------------------------------------------------------------+
| perday     | 1 for daily price, 0 for global price                      |
+------------+------------------------------------------------------------+
| extra      | 1 if it's an add-on, 0 if it's a reduction                 |
+------------+------------------------------------------------------------+
| price      | Price of the Opportunity                                   |
+------------+------------------------------------------------------------+
| how        | Number of times that can be sold per reservation.          |
|            | A value between 1 and 30 is required                       |
+------------+------------------------------------------------------------+
| dfrom      | Starting date for the Opportunity                          |
+------------+------------------------------------------------------------+
| dto        | Ending date for the Opportunity                            |
+------------+------------------------------------------------------------+
| wdays      | An array indicating which days of the week the Opportunity |
|            | applies to. First day of the list is Monday.               |
|            | For example, if the array is: [1,0,1,0,1,0,1]              |
|            | then the Opportunity is shown on Monday, Wednesday, Friday |
|            | and Sunday.                                                |
+------------+------------------------------------------------------------+
| rooms      | An array of the Room's IDs for which the Opportunity is    |
|            | related to. An empty array ([]), indicates that the        |
|            | Opportunity is generic and not Room-related.               |
|            | See :doc:`rooms`                                           |
+------------+------------------------------------------------------------+
| name_XX    | Where XX is the language code: specific names for each     |
|            | language                                                   |
+------------+------------------------------------------------------------+
| descr_XX   | Where XX is the language code: descriptions of the         |
|            | Opportunity for each language                              |
+------------+------------------------------------------------------------+


Fetching existing Opportunities
-------------------------------

To retrieve the Opportunities of one property, the function is:

.. function:: fetch_opportunities(token, lcode[, dfrom, dto, ancillary= 0])

It returns a list of Opportunities, each one being represented by a Key→Value 
structure. Each structure has the keys explained in `Opportunity characteristics`_.
The names and descriptions for each language (name_XX, descr_XX), will be returned just if 'ancillary=1'.

Here is an example of a fetch Opportunities request, followed by the response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>fetch_opportunities</methodName>
    <params>
      <param>
        <value><string>1234567890.1234</string></value>
      </param>
      <param>
        <value><int>1234567890</int></value>
      </param>
      <param>
        <value><string>01/04/2015</string></value>
      </param>
      <param>
        <value><string>30/04/2015</string></value>
      </param>
      <param>
        <value><int>1</int></value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value>
          <array><data>
                <value><struct>
                  <member>
                    <name>oid</name>
                    <value><int>123</int></value>
                  </member>
                  <member>
                    <name>name</name>
                    <value><string>Bicycle City Tour</string></value>
                  </member>
                  <member>
                    <name>active</name>
                    <value><int>1</int></value>
                  </member>
                  <member>
                    <name>perday</name>
                    <value><int>1</int></value>
                  </member>
                  <member>
                    <name>extra</name>
                    <value><int>1</int></value>
                  </member>
                  <member>
                    <name>price</name>
                    <value><double>12.5</double></value>
                  </member>
                  <member>
                    <name>how</name>
                    <value><int>5</int></value>
                  </member>
                  <member>
                    <name>dfrom</name>
                    <value><string>01/01/2016</string></value>
                  </member>
                  <member>
                    <name>dto</name>
                    <value><string>31/12/2016</string></value>
                  </member>
                  <member>
                    <name>rooms</name>
                    <value><array><data></data></array></value>
                  </member>
                  <member>
                    <name>wdays</name>
                    <value><array><data>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>0</int></value>
                      <value><int>0</int></value>
                      </data></array></value>
                  </member>
                  <member>
                    <name>name_en</name>
                    <value><string>City Bike Tour</string></value>
                  </member>
                  <member>
                    <name>descr_en</name>
                    <value><string>Discover the city riding a bike!</string></value>
                  </member>
                <value><struct>
                  <member>
                    <name>oid</name>
                    <value><int>124</int></value>
                  </member>
                  <member>
                    <name>name</name>
                    <value><string>Additional Cradle</string></value>
                  </member>
                  <member>
                    <name>active</name>
                    <value><int>1</int></value>
                  </member>
                  <member>
                    <name>perday</name>
                    <value><int>1</int></value>
                  </member>
                  <member>
                    <name>extra</name>
                    <value><int>1</int></value>
                  </member>
                  <member>
                    <name>price</name>
                    <value><double>5</double></value>
                  </member>
                  <member>
                    <name>how</name>
                    <value><int>1</int></value>
                  </member>
                  <member>
                    <name>dfrom</name>
                    <value><string>01/01/2016</string></value>
                  </member>
                  <member>
                    <name>dto</name>
                    <value><string>31/12/2016</string></value>
                  </member>
                  <member>
                    <name>rooms</name>
                    <value><array><data>
                    <value><int>1001</int></value>
                    <value><int>1002</int></value>
                    <value><int>1005</int></value>
                    </data></array></value>
                  </member>
                  <member>
                    <name>wdays</name>
                    <value><array><data>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      <value><int>1</int></value>
                      </data></array></value>
                  </member>
                  <member>
                    <name>name_en</name>
                    <value><string>Extra Cradle</string></value>
                  </member>
                  <member>
                    <name>descr_en</name>
                    <value><string>Add a cradle to your reserved room</string></value>
                  </member>
                </struct></value>
          </data></array>
        </value>
      </param>
    </params>
  </methodResponse>


Adding a new Opportunity
------------------------

The function for adding a new Opportunity is:

.. function:: new_opportunity(token, lcode, name, active, perday, extra, price, how, dfrom, dto, wdays=[][, rooms=[] names={}, descrs={}])

The parameters are explained in `Opportunity characteristics`_. 'names' 
and 'descrs' are structures of K→V values, each key representing a 
language ('name_XX', 'descr_XX').

The function returns, in case of success, the assigned ID for the new Opportunity.

Let's see it with an example of request and response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>new_opportunity</methodName>
    <params>
      <param>
        <value><string>1234567890.1234</string></value>
      </param>
      <param>
        <value><int>1234567890</int></value>
      </param>
      <param>
        <value><string>Early Check-Out</string></value>
      </param>
      <param>
        <value><int>1</int></value>
      </param>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><double>3.5</double></value>
      </param>
      <param>
        <value><int>1</int></value>
      </param>
      <param>
        <value><string>01/07/2016</string></value>
      </param>
      <param>
        <value><string>31/08/2016</string></value>
      </param>
      <param>
        <value><array><data>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        </data></array></value>
      </param>
      <param>
        <value><array><data>
        </data></array></value>
      </param>
      <param>
        <value><struct>
          <member>
            <name>name_en</name>
            <value><string>Early Check-Out discount</string></value>
          </member>
        </struct></value>
      </param>
      <param>
        <value><struct>
          <member>
            <name>descr_en</name>
            <value><string>Check-Out before than 9AM and enjoy this discount</string></value>
          </member>
        </struct></value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><int>125</int></value>
      </param>
    </params>
  </methodResponse>


Modifying an existing Opportunity
---------------------------------

To modify an existing Opportunity, the function is:

.. function:: mod_opportunity(token, lcode, oid[, name, active, perday, extra, price, how, dfrom, dto, wdays, rooms, names, descrs])

The parameters are explained in `Opportunity characteristics`_. 'names' and
'descrs' are structures of K→V values, each key representing a language 
('name_XX', 'descr_XX'). If you want to delete a name or a description for 
an specific language, you should specify an empty string for this own language.

The function returns, in case of success, 0; the error code otherwise.

Let's see it with an example of request and response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>mod_opportunity</methodName>
    <params>
      <param>
        <value><string>1234567890.1234</string></value>
      </param>
      <param>
        <value><int>1234567890</int></value>
      </param>
      <param>
        <value><int>125</int></value>
      </param>
      <param>
        <value><string>Early Check-in / Check-Out</string></value>
      </param>
      <param>
        <value><int>1</int></value>
      </param>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><double>5</double></value>
      </param>
      <param>
        <value><int>1</int></value>
      </param>
      <param>
        <value><string>01/07/2016</string></value>
      </param>
      <param>
        <value><string>31/08/2016</string></value>
      </param>
      <param>
        <value><array><data>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        <value><int>1</int></value>
        </data></array></value>
      </param>
      <param>
        <value><array><data>
        </data></array></value>
      </param>
      <param>
        <value><struct>
          <member>
            <name>name_en</name>
            <value><string>Early Check-In and Check-Out discount</string></value>
          </member>
        </struct></value>
      </param>
      <param>
        <value><struct>
          <member>
            <name>descr_en</name>
            <value><string>Check-In and Check-Out before than 9AM and enjoy this discount</string></value>
          </member>
        </struct></value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><string>Ok</string></value>
      </param>
    </params>
  </methodResponse>


Deleting an existing Opportunity
--------------------------------

To detele an existing Opportunity, the function is:

.. function:: del_opportunity(token, lcode, oid)

Where 'oid' is the Opportunity ID, as explained in `Opportunity characteristics`_. It
returns, in case of success, 0; the error code otherwise.

Let's see an example of request and response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>del_opportunity</methodName>
    <params>
      <param>
        <value><string>1234567890.1234</string></value>
      </param>
      <param>
        <value><int>1234567890</int></value>
      </param>
      <param>
        <value><int>125</int></value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><string>Ok</string></value>
      </param>
    </params>
  </methodResponse>


Special Offers
**************

With the Special Offers you can improve your website and compete better with the OTA (Special Offers are less subject to the control of parity rate). 


Special Offers characteristics
------------------------------

Each Special Offer will be defined for this fields:

+--------------+------------------------------------------------------------+
| Field        | Meaning                                                    |
+==============+============================================================+
| sid          | The ID of the Special Offer                                |
+--------------+------------------------------------------------------------+
| name         | The main name of the Special Offer                         |
+--------------+------------------------------------------------------------+
| ddp          | No discount on First Step. If '1', Special Offer won't be  |
|              | shown on the first step within the WuBook's Booking        |
|              | Engine. Otherwise if '0'                                   |
+--------------+------------------------------------------------------------+
| id_policy    | ID of the Policy associated with the Special Offer.        |
|              | If 0, no Policy is associated.                             |
|              | See :doc:`cpolicies`                                       |
|              |                                                            |
+--------------+------------------------------------------------------------+
| dtype        | Discount type for the Special Offer.                       |
|              |                                                            |
|              | * 1: Percentage                                            |
|              | * 2: Fixed                                                 |
|              | * 0: Related to a Pricing Plan.                            |
|              |                                                            |
|              | See :doc:`prices`                                          |
+--------------+------------------------------------------------------------+
| dvalue       | Discount value. It depends on 'dtype':                     |
|              |                                                            |
|              | * if 'dtype' is 1 or 2: discount value.                    |
|              | * if 'dtype' is 0: ID of the Pricing Plan.                 |
|              |                                                            |
+--------------+------------------------------------------------------------+
| apply_to     | Depending on 'dtype':                                      |
|              |                                                            |
|              | * if 'dtype' is 1 or 2: 'apply_to' must be a list of       |
|              |   comma-separated Room IDs which the discount applies to.  |
|              |   A string “*” indicates that applies to all Rooms.        |
|              | * if 'dtype' is 0: 'apply_to' has to be “*” (the Rooms     |
|              |   relation is defined at the Pricing Plan)                 |
|              |                                                            |
+--------------+------------------------------------------------------------+
| guarantee    | Independently by your reservation model (see Facility >    |
|              | Facility > Reservation Model), you can require a different |
| deposit      | guarantee for a Special Offer. This is mainly used when    |
|              | you set a Deferred Reservation Model for standard          |
|              | reservations, but you want a Credit Card guarantee to      |
|              | realize a Not-Refundable offer. Or even to require the     |
|              | payment of a deposit. To require a CC, please, activate    |
|              | the Credit Card System (Manage > Credit Cards). To require |
|              | a deposit, at least one Payment Gateway (Facility >        |
|              | Facility > Payment Gateway).                               |
|              |                                                            |
|              | So, possible values for this two fields are:               |
|              |                                                            |
|              | ========= ======= =============                            |
|              | guarantee deposit Meaning                                  |
|              | ========= ======= =============                            |
|              | 0         0       None                                     |
|              | 0         >0      Deposit                                  |
|              | 1         0       CC guarantee                             |
|              | ========= ======= =============                            |
|              |                                                            |
+--------------+------------------------------------------------------------+
| dfrom        | Starting date of the validity period for the Special Offer |
+--------------+------------------------------------------------------------+
| dto          | Ending date of the validity period for the Special Offer   |
+--------------+------------------------------------------------------------+
| wdays        | An array indicating which days of the week the Special     |
|              | Offer applies to. First day of the list is Monday. For     |
|              | example if the array is: [1,0,1,0,1,0,1]                   |
|              | the Special Offer is shown on Monday, Wednesday, Friday    |
|              | and Sunday.                                                |
+--------------+------------------------------------------------------------+
| wdays_type   | Constraint for the previous 'wdays' value:                 |
|              |                                                            |
|              | * 1: Selected days must be required                        |
|              | * 2: At least one day must be required                     |
|              | * 3: Not selected days mustn't be required                 |
|              | * 4: Selected days (and only these) must be required       |
|              |                                                            |
+--------------+------------------------------------------------------------+
| must_advance | Required advance (number of days) for the Special Offer    |
+--------------+------------------------------------------------------------+
| max_advance  | Maximum advance (number of days) for the Special Offer     |
+--------------+------------------------------------------------------------+
| must_stay    | Required stay (number of days) for the Special Offer       |
+--------------+------------------------------------------------------------+
| max_stay     | Maximum stay (number of days) for the Special Offer        |
+--------------+------------------------------------------------------------+
| .. warning:: at least one requirement (min_advance, max_advance, min_stay |
|              or max_stay) must be set (greater than zero)                 |
+--------------+------------------------------------------------------------+
| must_rooms   | List of comma-separated Room IDs which are mandatory for   |
|              | the Special Offer. An empty list (“” or “,”), indicates    |
|              | all Rooms. See :doc:`rooms`                                |
+--------------+------------------------------------------------------------+
| must_opps    | List of comma-separated Opportunity IDs which are          |
|              | mandatory for the Special Offer. An empty list             |
|              | (“” or “,”), indicates all Opportunities.                  |
|              | See `Opportunities`_                                       |
+--------------+------------------------------------------------------------+
| must_type    | Constraint for the previous 'must_rooms' and 'must_opps':  |
|              |                                                            |
|              | * 1: All rooms and extras selected                         |
|              | * 2: At least one of rooms and extras selected             |
|              |                                                            |
+--------------+------------------------------------------------------------+
| nations      | If Special Offer is geographically limited, here you have  |
|              | to specify a list of valid country codes for the Special   |
|              | Offer. An empty list ([]), means all countries included    |
+--------------+------------------------------------------------------------+
| .. note:: Nation codes are specified by standard ISO 3166-2. More info    |
|              | here: http://www.iso.org/iso/country_codes                 |
+--------------+------------------------------------------------------------+
| periods      | Here you can specify more periods of time for which the    |
|              | Special Offer will be valid too. For example:              |
|              | [[“01/08/2016”,“15/08/2016”], [“01/09/2016”,“15/09/2016”]] |
+--------------+------------------------------------------------------------+
| name_XX      | Where XX is the language code: specific names of the       |
|              | Special Offer for each language                            |
+--------------+------------------------------------------------------------+
| descr_XX     | Where XX is the language code: specific descriptions of    |
|              | the Special Offer for each language                        |
+--------------+------------------------------------------------------------+
| rplan        | ID of the Restriction Plan. It allows to show Special      |
|              | Offers only when the conditions specified inside a         |
|              | Restriction Plan are satisfied. Due to this, dfrom, dto    |
|              | and period parameters are ignored. If 0, no Restriction    |
|              | Plan is associated.                                        |
+--------------+------------------------------------------------------------+

Fetching existing Special Offers
--------------------------------

To retrieve the Special Offers of one property, the function is:

.. function:: fetch_soffers(token, lcode[, dfrom, dto, ancillary= 0])

It returns a list of Special Offers, each one being represented by a Key→Value structure. Each structure having the keys explained in `Special Offers characteristics`_. The
names and descriptions for each language (name_XX, descr_XX), will be returned just if 'ancillary=1'.

Here is an example of a fetch Special Offers request, followed by the response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>fetch_soffers</methodName>
    <params>
      <param>
        <value>
          <string>9330239232.1623</string>
        </value>
      </param>
      <param>
        <value>
          <string>1213394817</string>
        </value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value>
          <array>
            <data>
              <value>
                <int>0</int>
              </value>
              <value>
                <array>
                  <data>
                    <value>
                      <struct>
                        <member>
                          <name>id_policy</name>
                          <value>
                            <string/>
                          </value>
                        </member>
                        <member>
                          <name>wdays</name>
                          <value>
                            <array>
                              <data>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>0</int>
                                </value>
                                <value>
                                  <int>0</int>
                                </value>
                              </data>
                            </array>
                          </value>
                        </member>
                        <member>
                          <name>wdays_type</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>dtype</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>periods</name>
                          <value>
                            <array>
                              <data>
                              </data>
                            </array>
                          </value>
                        </member>
                        <member>
                          <name>apply_to</name>
                          <value>
                            <string>*</string>
                          </value>
                        </member>
                        <member>
                          <name>rplan</name>
                          <value>
                            <int>8880</int>
                          </value>
                        </member>
                        <member>
                          <name>guarantee</name>
                          <value>
                            <int>0</int>
                          </value>
                        </member>
                        <member>
                          <name>dvalue</name>
                          <value>
                            <double>10.0</double>
                          </value>
                        </member>
                        <member>
                          <name>must_stay</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>ddp</name>
                          <value>
                            <int>0</int>
                          </value>
                        </member>
                        <member>
                          <name>sid</name>
                          <value>
                            <int>8872</int>
                          </value>
                        </member>
                        <member>
                          <name>short_disable</name>
                          <value>
                            <string/>
                          </value>
                        </member>
                        <member>
                          <name>must_rooms</name>
                          <value>
                            <string>,</string>
                          </value>
                        </member>
                        <member>
                          <name>max_advance</name>
                          <value>
                            <int>7</int>
                          </value>
                        </member>
                        <member>
                          <name>max_stay</name>
                          <value>
                            <int>7</int>
                          </value>
                        </member>
                        <member>
                          <name>must_opps</name>
                          <value>
                            <string>,</string>
                          </value>
                        </member>
                        <member>
                          <name>dto</name>
                          <value>
                            <string>20/09/2017</string>
                          </value>
                        </member>
                        <member>
                          <name>name</name>
                          <value>
                            <string>New Dummy Special Offer</string>
                          </value>
                        </member>
                        <member>
                          <name>must_type</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>dfrom</name>
                          <value>
                            <string>10/09/2017</string>
                          </value>
                        </member>
                        <member>
                          <name>nations</name>
                          <value>
                            <array>
                              <data>
                              </data>
                            </array>
                          </value>
                        </member>
                        <member>
                          <name>must_advance</name>
                          <value>
                            <int>3</int>
                          </value>
                        </member>
                        <member>
                          <name>deposit</name>
                          <value>
                            <double>5.0</double>
                          </value>
                        </member>
                      </struct>
                    </value>
                    <value>
                      <struct>
                        <member>
                          <name>id_policy</name>
                          <value>
                            <string/>
                          </value>
                        </member>
                        <member>
                          <name>wdays</name>
                          <value>
                            <array>
                              <data>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>1</int>
                                </value>
                                <value>
                                  <int>0</int>
                                </value>
                                <value>
                                  <int>0</int>
                                </value>
                              </data>
                            </array>
                          </value>
                        </member>
                        <member>
                          <name>wdays_type</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>dtype</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>periods</name>
                          <value>
                            <array>
                              <data>
                              </data>
                            </array>
                          </value>
                        </member>
                        <member>
                          <name>apply_to</name>
                          <value>
                            <string>*</string>
                          </value>
                        </member>
                        <member>
                          <name>rplan</name>
                          <value>
                            <int>8882</int>
                          </value>
                        </member>
                        <member>
                          <name>guarantee</name>
                          <value>
                            <int>0</int>
                          </value>
                        </member>
                        <member>
                          <name>dvalue</name>
                          <value>
                            <double>10.0</double>
                          </value>
                        </member>
                        <member>
                          <name>must_stay</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>ddp</name>
                          <value>
                            <int>0</int>
                          </value>
                        </member>
                        <member>
                          <name>sid</name>
                          <value>
                            <int>8871</int>
                          </value>
                        </member>
                        <member>
                          <name>short_disable</name>
                          <value>
                            <string/>
                          </value>
                        </member>
                        <member>
                          <name>must_rooms</name>
                          <value>
                            <string>,</string>
                          </value>
                        </member>
                        <member>
                          <name>max_advance</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>max_stay</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>must_opps</name>
                          <value>
                            <string>,</string>
                          </value>
                        </member>
                        <member>
                          <name>dto</name>
                          <value>
                            <string>20/09/2017</string>
                          </value>
                        </member>
                        <member>
                          <name>name</name>
                          <value>
                            <string>Edited Special Offer</string>
                          </value>
                        </member>
                        <member>
                          <name>must_type</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>dfrom</name>
                          <value>
                            <string>10/09/2017</string>
                          </value>
                        </member>
                        <member>
                          <name>nations</name>
                          <value>
                            <array>
                              <data>
                              </data>
                            </array>
                          </value>
                        </member>
                        <member>
                          <name>must_advance</name>
                          <value>
                            <int>2</int>
                          </value>
                        </member>
                        <member>
                          <name>deposit</name>
                          <value>
                            <double>5.0</double>
                          </value>
                        </member>
                      </struct>
                    </value>
                  </data>
                </array>
              </value>
            </data>
          </array>
        </value>
      </param>
    </params>
  </methodResponse>


Adding a new Special Offer
------------------------------


The function for adding a new Special Offer is:

.. function:: new_soffer(token, lcode, name, ddp, id_policy, dtype, dvalue, apply_to, guarantee, deposit, dfrom, dto, wdays, wdays_type, must_advance, max_advance, must_stay, max_stay, must_rooms, must_opps, must_type[, nations= [], periods= [], names= {}, descrs= {}, rplan= ''])

The parameters are explained in `Special Offers characteristics`_. 'names' and 'descrs' are structures of K→V values, each key representing a language ('name_XX', 'descr_XX').

The function returns, in case of success, the assigned ID for the new Special Offer.

Let's see it with an example of request and response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>new_soffer</methodName>
    <params>
      <param>
        <value>
          <string>9589155238.6682</string>
        </value>
      </param>
      <param>
        <value>
          <string>1213394817</string>
        </value>
      </param>
      <param>
        <value>
          <string>New Dummy Special Offer</string>
        </value>
      </param>
      <param>
        <value>
          <int>0</int>
        </value>
      </param>
      <param>
        <value>
          <int>0</int>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>10</int>
        </value>
      </param>
      <param>
        <value>
          <string>*</string>
        </value>
      </param>
      <param>
        <value>
          <int>0</int>
        </value>
      </param>
      <param>
        <value>
          <int>5</int>
        </value>
      </param>
      <param>
        <value>
          <string>10/09/2017</string>
        </value>
      </param>
      <param>
        <value>
          <string>20/09/2017</string>
        </value>
      </param>
      <param>
        <value>
          <array>
            <data>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>0</int>
              </value>
              <value>
                <int>0</int>
              </value>
            </data>
          </array>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>3</int>
        </value>
      </param>
      <param>
        <value>
          <int>7</int>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>7</int>
        </value>
      </param>
      <param>
        <value>
          <string/>
        </value>
      </param>
      <param>
        <value>
          <string/>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <array>
            <data>
            </data>
          </array>
        </value>
      </param>
      <param>
        <value>
          <array>
            <data>
            </data>
          </array>
        </value>
      </param>
      <param>
        <value>
          <struct>
          </struct>
        </value>
      </param>
      <param>
        <value>
          <struct>
          </struct>
        </value>
      </param>
      <param>
        <value>
          <int>8880</int>
        </value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value>
          <array>
            <data>
              <value>
                <int>0</int>
              </value>
              <value>
                <int>8871</int>
              </value>
            </data>
          </array>
        </value>
      </param>
    </params>
  </methodResponse>


Modifying an existing Special Offer
-----------------------------------

To modify an existing Special Offer, the function is:

.. function:: mod_soffer(token, lcode, sid[, name, ddp, id_policy, dtype, dvalue, apply_to, guarantee, deposit, dfrom, dto, wdays, wdays_type, must_advance, max_advance, must_stay, max_stay, must_rooms, must_opps, must_type, nations, periods, names, descrs, rplan])

The parameters are explained in `Special Offers characteristics`_. 'names' and
'descrs' are structures of K→V values, each key representing a language ('name_XX', 'descr_XX'). If you want to delete a name or a description for a specific language, you should specify an empty string for this language.

The function returns, in case of success, 0; the error code otherwise.

Let's see it with an example of request and response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>mod_soffer</methodName>
    <params>
      <param>
        <value>
          <string>9589155238.6682</string>
        </value>
      </param>
      <param>
        <value>
          <string>1213394817</string>
        </value>
      </param>
      <param>
        <value>
          <int>8871</int>
        </value>
      </param>
      <param>
        <value>
          <string>Edited Special Offer</string>
        </value>
      </param>
      <param>
        <value>
          <int>0</int>
        </value>
      </param>
      <param>
        <value>
          <int>0</int>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>10</int>
        </value>
      </param>
      <param>
        <value>
          <string>*</string>
        </value>
      </param>
      <param>
        <value>
          <int>0</int>
        </value>
      </param>
      <param>
        <value>
          <int>5</int>
        </value>
      </param>
      <param>
        <value>
          <string>10/09/2017</string>
        </value>
      </param>
      <param>
        <value>
          <string>20/09/2017</string>
        </value>
      </param>
      <param>
        <value>
          <array>
            <data>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>1</int>
              </value>
              <value>
                <int>0</int>
              </value>
              <value>
                <int>0</int>
              </value>
            </data>
          </array>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <string/>
        </value>
      </param>
      <param>
        <value>
          <string/>
        </value>
      </param>
      <param>
        <value>
          <int>2</int>
        </value>
      </param>
      <param>
        <value>
          <array>
            <data>
            </data>
          </array>
        </value>
      </param>
      <param>
        <value>
          <array>
            <data>
            </data>
          </array>
        </value>
      </param>
      <param>
        <value>
          <struct>
          </struct>
        </value>
      </param>
      <param>
        <value>
          <struct>
          </struct>
        </value>
      </param>
      <param>
        <value>
          <int>8882</int>
        </value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value>
          <array>
            <data>
              <value>
                <int>0</int>
              </value>
              <value>
                <string>Ok</string>
              </value>
            </data>
          </array>
        </value>
      </param>
    </params>
  </methodResponse>


Deleting an existing Special Offer
----------------------------------

To delete an existing Special Offer, the function is:

.. function:: del_soffer(token, lcode, sid)

Where 'sid' is the Special Offer ID, as explained in `Special Offers characteristics`_. It
returns, in case of success, 0; the error code otherwise.

Let's see an example of request and response:

.. hidden-code-block:: xml
  :starthidden: True

  <methodCall>
    <methodName>del_soffer</methodName>
    <params>
      <param>
        <value><string>1234567890.1234</string></value>
      </param>
      <param>
        <value><int>1234567890</int></value>
      </param>
      <param>
        <value><int>3333</int></value>
      </param>
    </params>
  </methodCall>

  <---------------response--------------->

  <methodResponse>
    <params>
      <param>
        <value><int>0</int></value>
      </param>
      <param>
        <value><string>Ok</string></value>
      </param>
    </params>
  </methodResponse>




Promo Codes
**************

Adding a new Promo Code
------------------------------

.. function:: new_promo(token, lcode, name, promo_code, dtype, dvalue, max_usage, [policy_id=0, active=1, cc_disabled=0])

Deleting an existing Promo Code
----------------------------------

.. function:: del_promo(token, lcode, promo_id)