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

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 (like coins, the list of properties, …).

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.

corporate_fetch_channels(token, lcode)
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

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 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 mark_bookings()

Create accounts and properties

corporate_new_property(token, lodg, woodoo_only, acode)
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.

+ show/hide code

Managing subaccounts and properties

corporate_set_password(token, subaccount_code, password)
corporate_destroy_subaccount(token, subaccount_code)
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. You can’t remove the last property, see corporate_cancel_destroy_subaccount() instead.

Renewing services

corporate_renew_booking(token, lcode, months[, pretend= 1])
corporate_renew_channels(token, lcode, channels[, pretend= 1])

Those functions are used to renew your services (with coins). They return the number of used coins. For both functions, you have an optional argument: pretend. When 1, you are just making a simulation.

For the corporate_renew_booking() function, the argument months is an integer representing the number of months you want to renew.

For the corporate_renew_channels() function, the channels argument is a KW structure, having Channel IDs as keys and, as values, a renewal quantity. A simple example will make these concepts clearier:

channels= {
  '111': '3d', # it means: renew the channel with ID= 111 for three days
  '112': '2m', # 2m= 2 Months
  '113': '2',  # 2= 2 Months (m is the default unity),
  '114': '1y', # 1y= 1 Year
}

As you can see, you can use an integer (in this case, it is considered a number of months) or you can specify a string with a final “d”, “y” or “m”, respectively for days, years and months.

corporate_set_autorenew_wb(token, lcode, set_autorenew)
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.

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:

corporate_balance_transactions(token)
corporate_balance_details(token, transaction_id)
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

Here you can find all the timezones available for corporate_new_property_ and corporate_new_account_and_property_ :