.. meta:: :description: Wired API, corporate functions :keywords: Wired, xml, api, channel manager, booking engine, corporate functions Corporate API ************* Introduction ------------ If you have a corporate account, these functions can be very useful to program the wubook services. .. note:: To launch these functions, you need to use a Token acquired with the credentials of your corporate account. Global Information ------------------ .. function:: corporate_fetch_accounts(token [, acode]) Returns a KV struct, each Key being the account code, and the Value being another KV struct with the information about the account (email, prepaid_amount, list of properties). .. function:: corporate_get_providers_info(token [, acodes=[]]) Returns a list of providers that accessed corporate's sub-accounts through Wired, each value of this list being a KV struct with the fields **pkey** (Provider Key), **emails** (of the provider) and **acode** (the accessed account code). The filter **acodes** is a list of account codes; an empty one will return information for every corporate's sub-account. .. function:: corporate_fetch_channels(token, lcode) .. function:: corporate_get_channels(token[, filters]) The **corporate_get_channels()**, called without the **filters** argument, returns all of the channels of all of your properties. If you want to filter results, you can pass them inside the KV structure **filters**, which supports the following (optional and not exclusive) filters: * **dfrom**: channels expiring not before this european date * **dto**: channels expiring before this european date * **lcodes**: a list of lcode, to return channels of a specific set of properties .. function:: corporate_fetchable_properties(token) This function is used to receive a list of properties having new reservations to be fetched. If you use the **Push Notification** feature, this function could be periodically called (let's say with a 4 hours frequence) to prevent problems arising from missing notifications. That's of course seriously better than periodically cycling all of your properties with a :func:`fetch_new_bookings` call. .. note:: This function could return False Positive cases: properties tagged as "fetchable" but having no new reservations/modifications/cancellations. If you want them to desappear from the list, please, call :func:`mark_bookings` Create accounts and properties ------------------------------ .. function:: corporate_new_property(token, lodg, woodoo_only, acode) .. function:: corporate_new_account_and_property(token, lodg, woodoo_only, account) Those functions are used to add new properties on your corporate account. The first one will be used when the new property has to be associated to an existing account. The second one will be used when you also need a new account owning the property. For both functions, the **lodg** parameter is a KV struct containing the following values: ======================= ================================ Field Meaning ======================= ================================ name The name of the property address The address of the property url The url of its site zip Zip code city City phone Phone contact_email Email booking_email Email country Two digits code (IT, ES, ..) timezone (optional) List of available Timezones_ ======================= ================================ While using **corporate_new_account_and_property()**, you need to pass a similar KV structure to define a new account, having the following values: ======================= ================================ Field Meaning ======================= ================================ first_name The name of the account owner last_name The last name of the account owner phone Phone lang Two digits code (IT, ES, ..) email Email currency Three digits code (EUR, USD, ..) ======================= ================================ Notice that both functions return information about the new property and, eventually, the new account. The return values is in fact a KV structure containing the **lcode** (property identifier), **acode** and **password** (username and password assigned to the new account) values. Click on the following link to have a corporate_new_account_and_property() xml example. .. hidden-code-block:: xml :starthidden: True corporate_new_account_and_property 9573126409.1799 phone phone name name zip zip city city url a country IT address s email foo@bar.com 1 lang it first_name a last_name b currency USD phone 999 email foo@bar.com Managing subaccounts and properties ----------------------------------- .. function:: corporate_set_password(token, subaccount_code, password) .. function:: corporate_recovery_link(token, subaccount_code) .. function:: corporate_destroy_subaccount(token, subaccount_code) .. function:: corporate_remove_property(token, subaccount_code, lcode) Function **corporate_set_password()** let you set the password for one of your subaccounts. Function **corporate_recovery_link()** let you generate a link to set a new password for one of your subaccounts. This function returns a link via API and sends an SMS with the secret code to the phone number of the subaccount owner. The secret code is meant to be used on the page linked via the API to set the new password. .. note:: For **corporate_recovery_link()** it is **mandatory** that the subaccount has a mobile phone number correctly set up on WuBook. Function **corporate_destroy_subaccount()** let you destroy a subaccount. .. note:: The procedure is irreversible, you will not be able to recover your subaccount's data. For **corporate_destroy_subaccount()** it is **mandatory** to not have confirmed reservations with furure checkout nor transactions waiting for payments in any property. Function **corporate_remove_property()** let you remove a property from a subaccount. .. note:: For **corporate_remove_property()** it is **mandatory** to not have confirmed reservations nor transactions waiting for payments. Renewing services ----------------- .. function:: corporate_set_autorenew_wb(token, lcode, set_autorenew) .. function:: corporate_set_autorenew_zak(token, lcode, set_autorenew) Those functions allows to setup the **autorenew** feature. They accept the argument **set_autorenew**, which is an integer. If 1, you are activating the autorenew feature, while 0 disables it. .. function:: corporate_set_channel_status(token, lcode, lchans, running) Since channels don't have autorenew but can only be either **running** or **paused**, the function for them is a bit different. **running** is a boolean integer: * If 0, it will change the status to **paused** for the channels in **lchans** * If 1, it will change the status to **running** for the channels in **lchans** **lchans** argument is an array of Channel IDs. Balance and transactions ------------------------ Corporates can programmatically read the additional costs that WuBook is registering for your users. It is possible to use the following functions: .. function:: corporate_balance_transactions(token) .. function:: corporate_balance_details(token, transaction_id) .. function:: dtype_mapping(token) The first function returns the list of your transactions. Notice that a transaction is a container of atomic costs. The result of such function is an array, each item having the following meaning: * **id**: guess what! the transaction id!! Surprise :) * **closed_at**: if frozen, this is the date of the transaction closure * **details**: the anatomy of the transaction * **paid**: is this transaction already paid? Few remarks: the **details** field does not contain atomic costs. It aggregates them. For example, if you have 2 costs of the same type, then you will receive the sum of such costs, tagged with their related type. The transaction having **id==0 (zero)** is the **current transaction**, where current costs are inserted. It's never closed, never paid. The function **corporate_balance_details** is used to retrieve all the atomic costs of a transaction. You obviously must specify the transaction ID and you can use **ID=0** to read the current costs (costs associated to the current transaction). Its return value is again an array, each item having the following meaning: * **descr**: description * **shortdescr**: short description * **embargo**: we will not require a payment until this date * **registered**: the registration time * **currency**: currency * **dtype**: the type of cost * **name**: the name of the type * **amount**: the cost * **lcode**: if not null, this cost has been generated for the related property * **account**: the user account code who generates the cost The function **dtype_mapping** returns an array of cost types. Each item consists on a KV structure with two keys: * **dtype**: the cost type * **name**: the cost name Compatible timezones for a new property --------------------------------------- .. _Timezones: Here you can find all the timezones available for `corporate_new_property` and `corporate_new_account_and_property`: __TIMEZONES__