.. meta::
:description: Wired API, handling cancellation policies
:keywords: Wired, xml, api, channel manager, booking engine, cancellation policies
=====================
Cancellation Policies
=====================
Introduction
************
This chapter will describe how to manage property's cancellation policies.
.. warning:: Policies are only used within the WuBook extranet and shown on WuBook Booking Engine; they have no involvement with Channel Manager.
Policy Master
*************
Each property has a default Policy, which is called Policy Master. It exists since the
moment of the property creation, and it should be configured to accomplish
property's needs.
It is identify by flag 'master': as explained in `Policy characteristics`_,
for Policy Master, master=1 (there will be just one policy with this value set to 1). Also, its name is, literally, 'Policy Master' (and it can't be changed).
Policies Calendar
*****************
The Policy Calendar defines, day by day, which Cancellation Policy should be shown on WuBook Booking Engine.
That's it: you'll set, day by day (or for periods of time), just one Cancellation Policy. If none is set, Policy Master will be shown as the default one.
Handling Policies
*****************
Policy characteristics
----------------------
Each policy will be defined for this fields:
+------------+------------------------------------------------------------+
| Field | Meaning |
+============+============================================================+
| pid | The Id of the policy |
+------------+------------------------------------------------------------+
| name | The main name of the policy. For Policy Master, |
| | the name is always 'Policy Master' |
+------------+------------------------------------------------------------+
| master | 1 for the Policy Master, 0 for the others |
+------------+------------------------------------------------------------+
| pshow | How policy is shown: |
| | |
| | * 0: Clauses too |
| | * 1: Only Rule (deprecated, use 0 for new) |
| | * 2: Only clauses (deprecated, use 0 for new) |
+------------+------------------------------------------------------------+
| ptype | Type of penalty: |
| | |
| | * 1: First Night |
| | * 2: Amount Percentage |
| | * 3: First Night and Percentage |
| | * 4: No penalty |
| | * 5: Entire Amount |
| | * 6: Not Refundable (Soft) |
| | * 7: Not Refundable (Hard) |
+------------+------------------------------------------------------------+
| value | Applying value for the penalty (only if 'ptype' is 2 or 3) |
| | A value between 1 and 99 if ptype is 2 or 3, 0 otherwise |
+------------+------------------------------------------------------------+
| days | Minimum advance for avoiding the penalty (number of days) |
+------------+------------------------------------------------------------+
| descr_XX | Clauses of the Policy, where XX is each language code |
+------------+------------------------------------------------------------+
Fetching existing Policies
--------------------------
To retrieve the Policies of one property, the function is:
.. function:: fetch_policies(token, lcode [, ancillary= 0])
It returns a list of Policies, each one being represented by a Key->Value structure. Each structure having the keys explained in `Policy characteristics`_. The clauses (descr_XX),
will be returned just if 'ancillary=1'.
Here is an example of a fetch Policies request, followed by the response:
.. hidden-code-block:: xml
:starthidden: True
fetch_policies
1234567890.1234
1234567890
1
<---------------response--------------->
0
pid
123
name
Policy Master
master
1
pshow
0
ptype
4
value
0
days
2
descr_en
English description of the clauses
id
124
name
Weekend Policy
master
0
pshow
0
ptype
3
value
15
days
5
descr_en
English description of the clauses
Adding a new Policy
-------------------
The function for adding a new Policy is:
.. function:: new_policy(token, lcode, name, pshow, ptype, value, days [, descrs= {}])
The parameters are explained in `Policy characteristics`_. 'descrs' parameter is a
KV structure used to specify clauses in different languages. The function returns,
in case of success, the assigned Id for the new policy.
Let's see it with an example of request and response:
.. hidden-code-block:: xml
:starthidden: True
new_policy
1234567890.1234
1234567890
Summer Policy
0
2
10.5
3
descr_en
English clauses for the Summer Policy
<---------------response--------------->
0
125
Modifying an existing Policy
----------------------------
To modify an existing Policy, the function is:
.. function:: mod_policy(token, lcode, pid, [name, pshow, ptype, value, days, descrs= {}])
The parameters are explained in `Policy characteristics`_. 'descrs' parameter is a
KV structure used to specify clauses in different languages. If you want to delete a
clause 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
mod_policy
1234567890.1234
1234567890
125
Summer Policy Improved
0
2
10.5
4
descr_en
descr_es
Cláusulas para la pólitica
<---------------response--------------->
0
Ok
Deleting an existing Policy
---------------------------
To delete an existing Policy, the function is:
.. function:: del_policy(token, lcode, pid)
Where 'pid' is the Policy id, as explained in `Policy characteristics`_. It returns,
in case of success, 0; the error code otherwise.
.. note:: Policy Master cannot be deleted.
Let's see an example of request and response:
.. hidden-code-block:: xml
:starthidden: True
del_policy
1234567890.1234
1234567890
125
<---------------response--------------->
0
Ok
Handling Policies Calendar
**************************
Fetching Policies Calendar
--------------------------
To fetch the Policies Calendar, the function is:
.. function:: fetch_policy_calendar(token, lcode, dfrom, dto)
Where 'dfrom' and 'dto' determine the period of time. It'll return a list of values,
each one representing a day, with a K→V structure like:
.. code-block:: python
{'day': '01/05/2016', 'pid': 11}
If some of the period' days is not returned, it means that any Policy was set for
this day, so, Policy Master will be applied for it.
.. note:: Here applies the generic date restrictions of Wired: past dates are not allowed, and the maximum period you can fetch is for two years.
There it is an example of request and response:
.. hidden-code-block:: xml
:starthidden: True
fetch_policy_calendar
1234567890.1234
1234567890
01/05/2016
07/05/2016
<---------------response--------------->
0
pid
123
day
01/05/2016
pid
123
day
02/05/2016
pid
123
day
03/05/2016
pid
123
day
04/05/2016
pid
123
day
05/05/2016
pid
124
day
06/05/2016
pid
124
day
07/05/2016
Modifying Policies Calendar
---------------------------
To configure the Calendar, the function is:
.. function:: set_policy_calendar(token, lcode, pid, dfrom, dto)
Where 'dfrom' and 'dto' determine the period of time.
.. note:: Here applies the generic date restrictions of Wired: past dates are not allowed, and the maximum period you can fetch is for two years.
Here we have an example:
.. hidden-code-block:: xml
:starthidden: True
set_policy_calendar
1234567890.1234
1234567890
1
08/05/2016
12/05/2016
<---------------response--------------->
0
Ok