.. 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
fetch_opportunities
1234567890.1234
1234567890
01/04/2015
30/04/2015
1
<---------------response--------------->
0
oid
123
name
Bicycle City Tour
active
1
perday
1
extra
1
price
12.5
how
5
dfrom
01/01/2016
dto
31/12/2016
rooms
wdays
1
1
1
1
1
0
0
name_en
City Bike Tour
descr_en
Discover the city riding a bike!
oid
124
name
Additional Cradle
active
1
perday
1
extra
1
price
5
how
1
dfrom
01/01/2016
dto
31/12/2016
rooms
1001
1002
1005
wdays
1
1
1
1
1
1
1
name_en
Extra Cradle
descr_en
Add a cradle to your reserved room
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
new_opportunity
1234567890.1234
1234567890
Early Check-Out
1
0
0
3.5
1
01/07/2016
31/08/2016
1
1
1
1
1
1
1
name_en
Early Check-Out discount
descr_en
Check-Out before than 9AM and enjoy this discount
<---------------response--------------->
0
125
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
mod_opportunity
1234567890.1234
1234567890
125
Early Check-in / Check-Out
1
0
0
5
1
01/07/2016
31/08/2016
1
1
1
1
1
1
1
name_en
Early Check-In and Check-Out discount
descr_en
Check-In and Check-Out before than 9AM and enjoy this discount
<---------------response--------------->
0
Ok
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
del_opportunity
1234567890.1234
1234567890
125
<---------------response--------------->
0
Ok
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
fetch_soffers
9330239232.1623
1213394817
<---------------response--------------->
0
id_policy
wdays
1
1
1
1
1
0
0
wdays_type
2
dtype
2
periods
apply_to
*
rplan
8880
guarantee
0
dvalue
10.0
must_stay
2
ddp
0
sid
8872
short_disable
must_rooms
,
max_advance
7
max_stay
7
must_opps
,
dto
20/09/2017
name
New Dummy Special Offer
must_type
2
dfrom
10/09/2017
nations
must_advance
3
deposit
5.0
id_policy
wdays
1
1
1
1
1
0
0
wdays_type
2
dtype
2
periods
apply_to
*
rplan
8882
guarantee
0
dvalue
10.0
must_stay
2
ddp
0
sid
8871
short_disable
must_rooms
,
max_advance
2
max_stay
2
must_opps
,
dto
20/09/2017
name
Edited Special Offer
must_type
2
dfrom
10/09/2017
nations
must_advance
2
deposit
5.0
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
new_soffer
9589155238.6682
1213394817
New Dummy Special Offer
0
0
2
10
*
0
5
10/09/2017
20/09/2017
1
1
1
1
1
0
0
2
3
7
2
7
2
8880
<---------------response--------------->
0
8871
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
mod_soffer
9589155238.6682
1213394817
8871
Edited Special Offer
0
0
2
10
*
0
5
10/09/2017
20/09/2017
1
1
1
1
1
0
0
2
2
2
2
2
2
8882
<---------------response--------------->
0
Ok
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
del_soffer
1234567890.1234
1234567890
3333
<---------------response--------------->
0
Ok
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)