.. meta::
  :description: Wired API, handling restrictions
  :keywords: Wired, xml, api, channel manager, booking engine, restrictions

Handling Restrictions
*********************

Introduction
------------

As for :doc:`prices`, WuBook supports multiple **Restriction Plans**. This is generally
used to send different restrictions (like minStay) to the connected OTAs, 
depending for example on the OTAs rates. For example, you can define on
Booking.com a Weekly-Stay promotion (fo 7 days stays) and you need to 
configure the relative rate with appropriated restrictions.

WuBook supports two kind of Restriction Plans: **Daily** and **Compacts**.
A **Daily Restriction Plan** works like a Daily Pricing Plan, each room having
its own values for each day. **Compacts Restriction Plans** are used when you
need static restrictions (i.e., restrictions which do not change depending on
the dates).

For example, if you want to limit a rate, allowing only 7-days stay, you
just need a Compact Restriction Plan where MinStay= MaxStay= 7. There is
no need to define these values day by day. You do it once. 
Another example is a Closure Restriction Plan: you can define a
Compact Restriction Plan with Closed= 1, associating it to the rates you 
want to temporarily/definitively close.

Finally, let's list the possible restrictions supported by wubook:


========================= =====================================================================
Restriction               Meaning
========================= =====================================================================
min_stay                  Minimum Stay
min_stay_arrival          Minimum Stay Arrival depending on the arrival date
max_stay                  Maximum Stay
max_stay_arrival          Maximum Stay Arrival depending on the arrival date
closed                    To block sales
closed_departure          To block sales depending on the departure date
closed_arrival            To block sales depending on the arrival date
========================= =====================================================================

By setting the **min_stay**, **min_stay_arrival**, **max_stay**, **max_stay_arrival** restrictions 
equal to 0 (zero), you remove the restrictions.
So, when min_stay= 0, each stay will be allowed indipendently by its lenght.

The **closed** and **closed_departure** restrictions are integers: 0 (zero) and 1. If and
when they're equal to 1, the closure is activated.


Adding and removing Restriction Plans
-------------------------------------

To manage restriction plans, you have the following functions:

.. function:: rplan_add_rplan(token, lcode, name, compact)
.. function:: rplan_rplans(token, lcode)
.. function:: rplan_del_rplan(token, lcode, rpid)
.. function:: rplan_rename_rplan(token, lcode, rpid, name)

The  **rplan_add_rplan()** function is used to add a new Restriction Plan.
If **compact** is 1, the Plan will be Compact. It returns the assigned ID
of the new restriction plan.

The **rplan_rplans()** function returns the existing restriction plans.
The returned value is an Array of KV structures, each one representing
a restriction plan and having the following fields:

============================== ===================================
Field                          Meaning
============================== ===================================
id                             The rplan ID
name                           The rplan Name
rules (optional)               For compact rplans
============================== ===================================

When an rplan is Compact, the **rules** fields contains its static settings,
check that:

.. code-block:: python

  {
    'id': 1200, 
    'name': 'Weekly Stay'
    'rules': {'closed_arrival': 0, 'closed': 0, 'min_stay': 7, 'closed_departure': 0, 'max_stay': 0, 'min_stay_arrival': 7}, 
  },

  {
    'id': 1201, 
    'name': 'Closing Plan',
    'rules': {'closed_arrival': 0, 'closed': 1, 'min_stay': 0, 'closed_departure': 0, 'max_stay': 0, 'min_stay_arrival': 0}, 
  }, 

The **rplan_del_rplan()** and **rplan_rename_rplan()** functions are trivial: an
explanation would be probably excessive and just confusing.

Managing restrictions
---------------------

The following functions are used to manage restriction plans:

.. function:: rplan_update_rplan_rules(token, lcode, pid, rules)
.. function:: rplan_update_rplan_values(token, lcode, pid, dfrom, values)
.. function:: rplan_get_rplan_values(token, lcode, dfrom, dto[, rpids])

The first function, **rplan_update_rplan_rules()**, is used to modify the
restriction settings of a Compact Restriction Plan. The **rules** argument
is a simple KV structure. Notice you need to pass all the supported
restrictions:

.. code-block:: python

  'rules': {'closed_arrival': 0, 'closed': 1, 'min_stay': 0, 'closed_departure': 0, 'max_stay': 0, 'min_stay_arrival': 0}, 

The **rplan_get_rplan_values()** values is used to read current values of
your restriction plans (the daily ones, because for compact plans you just
need the :func:`rplan_rplans` call). If you don't need to read values
of all the restriction plans, you can use the **rpids** argument, which is
an array of Restriction Plan IDs. 
Notice that this function consider only non-standard restrictions. 
The values relative to the default restriction plan (**rpid** = 0) can be retrieved with the call :func:`fetch_rooms_values`.

Finally, let's analyze the **rplan_update_rplan_values()**, used to manage
a daily restriction plan, updating values for each room and for each date.
Its usage is very very similar to :func:`update_plan_prices`.
First thing first, you define a starting date using the **dfrom** argument (eu date, 21/12/2021). 
Then, the **values** argument is a KV structure, allowing you to update 
multiple rooms with a single message:

.. code-block:: python

  values= {
    '1': [ {'min_stay': 3}, {}, {'max_stay': 4}],
    '2': [ {'closed': 1}, {}, {'max_stay': 2}],
  }

  # If dfrom= 21/12/2012, the previous structure means:
  #  Room Id 1:
  #    21/12:  min_stay= 3
  #    22/12:  update nothing
  #    23/12:  max_stay= 4
  #
  #  Room Id 2:
  #    21/12:  close the room!
  #    22/12:  update nothing
  #    23/12:  put a max_stay= 2

As you can see:

 * You can pass an empty struct if you don't want to update a particular day (nothing to update).
 * For each day and for each room, you need to pass only the restrictions you want to update.

.. note:: 
  
  As for updating prices and availability, try to develop these functions in a smart way,
  compacting multiple rooms/ multiple dates update in a single message.

The following code is an XML example:

.. code-block:: xml

  <methodCall>
  <methodName>rplan_update_rplan_values</methodName>
  <params>
    <param>
      <value>
        <string>9560776837.2907</string>
      </value>
    </param>
    <param>
      <value>
        <int>LCODE</int>
      </value>
    </param>
    <param>
      <value>
        <int>1</int>
      </value>
    </param>
    <param>
      <value>
        <string>13/12/2016</string>
      </value>
    </param>
    <param>
      <value>
        <struct>
          <member>
            <name>43</name>
            <value>
              <array>
                <data>
                  <value>
                    <struct>
                      <member>
                        <name>min_stay</name>
                        <value>
                          <int>19</int>
                        </value>
                      </member>
                    </struct>
                  </value>
                  <value>
                    <struct>
                      <member>
                        <name>max_stay</name>
                        <value>
                          <int>3</int>
                        </value>
                      </member>
                    </struct>
                  </value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
 </methodCall>