vOffice Dokumentation

Intro

Introduction

The vOffice-API is devided into three main sections:

 
section description
Data-Export Export data from vOffice. It is typically used to import all relavant data to an external database. It is NOT intended for a live query / high frequency calls
Live-Query Query search-results, quotes etc. This section is especially usefull, if you are devoloping a custom homepage (not using the vOffice CMS).
Booking Save an online-booking / option and query existing bookings

 

To access the interface, you need to have an api-key. If you do not have one yet, please create it in the options of vOffice / request it from our customer.

If you set up an interface to vOffice, please tell us about it, so we can inform our customers about the possibilities: info@v-labs.eu

 

Access

An API request via HTTP GET must be of the following form:

https://api.v-office.com/api/json?parameters

Parameters that are always required:

parameter name value
key your vOffice api key
actionName action to perform

Parameters that are always required for live-queries and bookings:

parameter name value
data json encoded data (see corresponding actions for details)
lang ISO 639-1 language code

Depending on the action there might be more required parameters.

All parameters need to be URL-encoded.

All responses are UTF-8 json files.

 

Costs

Please refer to the vOffice prices for detailed information.

Data-Export

Units

Get all unit data (= holiday homes) except availabilities (including names, addresses, descriptions, images, prices and booking-restrictions).
 
Action name: getUnits
 
Optional parameters:
 
parameter description value
prices include prices true
offers include offers true
restrictions include booking-restrictions true
facilities include facilities or list only facilities true = include OR exclusive
ratings average ratings (1-5) true
feedbacks list of text feedbacks true
updatedSince show only entries, that have been updated since this date e.g. 2015-06-05T09:53:43Z
 
NOTE: The maximum number of results is currently 128 (may vary). If there are more units, the result will contain a field called "lastid". You will need to include it as parameter for subsequent calls to get the next chunk of results.
 
NOTE: There is another representation of the booking-restrictions: changeOver and minStay for action 'getAvailabilities'. Please request either this one OR the other.
 

Sample result:

{units: [
{
    _id: 23423, 
    info: {...},
    prices: {...},
    offers: {...},
    restrictions: {...},
    currency: 'EUR'
},
{
   _id: 23424,
   ....,  
}
]}

 

Info

 
field description type
facility facility id (Facilities combine units located in one house or at one site.
For example a holiday apartment house is one facility.)
 
isfacility whether this entry is a facility or a unit  
code internal name of the unit  
type

one of HOUSE, FLAT, ROOM, PRIVAT, MOBILEHOME, YACHT in case of a unit
or HOUSE_FAC, FLAT_FAC, HOTEL, HOSTEL, FARM, CAMPGROUND in case of a facility

 
deposit   C
depositLocation one of ON_INVOICE, ON_SITE  
bookable one of DIRECTLY, REVERSED, REVERSED_OPT, INQUIRY_CAL, INQUIRY_NO_CAL  
region the id of the region and the index SET
regionName   ML
loc Location (longitude latitude) GeoJSON
fullName name including facility name (in the language of the customer) S
name   ML
facilityName   ML
address   SET
url direct link to unit on vOffice Homepage ML
picsOrder one of FAC_PICS_FIRST, FAC_PICS_LAST, NO_FAC_PICS  
images see below  
roomDetails list of rooms including list of beds  

NOTE: In addition to these fields, all descriptions and properties can be exported (need to be activated in the api-key). You can get a list of all possible properties:

https://api.v-office.com/export/properties
This will show a list of all properties that are valid for all customers.

https://api.v-office.com/export/properties?key=[key]
This will show a list of all properties (global and user-defined), that are actually beeing exported for the given api-key. If you want to see the complete list of possible properties add &all=true

Images

You can find the images under the following url:

Medium size (600x400): https://dyn.v-office.com/image/m/[imageId].jpg
XL (1440): https://dyn.v-office.com/image/xl/[imageId].jpg
XXL (2048): https://dyn.v-office.com/image/xxl/[imageId].jpg

 

Prices

Field

Description

service

service id

value

price in cents

ask

used to sort the price table

type

one of RENT, FINALCLEANING, LINEN, HANDTOWELS, PET, CRIB, HIGHCHAIR, BABYBED, TRANSFER, VTAX, HEATING, GAS, WATER, ELECTRICITY, INSURANCE, CANCELLATION

season

name of the season

condition

price is only valid if condition is met

fromdate

 

tilldate

 

 

Offers

Field

Description

name

 

validfrom

the arrival may not be before this day

validtill

the departure may not be after this day

minStay

special offer is only valid if the customer stays at least this long

type

'EARLYBIRD','LASTMINUTE'

timeSpan

if type=’EARLYBIRD’: the arrival has to be at least this far ahead

if type=’LASTMINUTE’: the arrival may not be more than this ahead

discountType

'XY','PERCENT'

value

if discountType=’XY’: the number of days that have to be paid for. So minStay-value days are free.

if discountType=’Percent’:discount in percent

services ids of the services this discount is applied to


Restrictions

Field

Description

fromdate

 

tilldate

 

minimumStay

during the specified period, a booking has to be at least this long

minimumGap

in order to prevent gaps that are too small to be booked, it is possible to specify a minimum gap between the arrival and the departure of the preceding guest. Applies only if the arrival is not on the same day as the preceding departure.

fillGaps

if specified, these restrictions are ignored if an existing gap can be closed.

days

if specified the arrival and departure has to be on these days

Exception: The arrival is on an existing departure or the departure is on an existing arrival respectively (may occur if there is a manually entered booking)

Availability

Get all availabilities and optionally booking-restrictions.
 
Action name: getAvailabilities
 
Optional parameters:
 
parameter description value
changeOver include possible changeover days true
minStay include minimum stay information true
updatedSince show only availabilities, that have been updated since this date e.g. 2015-06-05T09:53:43Z
 
NOTE: The maximum number of results is currently 128 (may vary). If there are more units, the result will contain a field called "lastid". You will need to include it as parameter for subsequent calls to get the next chunk of results.
 
NOTE: changeOver and minStay are another representation of the booking-restrictions (action 'getUnits'). Please request either these ones OR the booking-restrictions of getUnits.
 
ChangeOver and minStay can be empty, simply because no booking restrictions have been entered yet by the customer. Or they may not have been entered completely for the whole period. In that case any booking is valid, as long as the availability is checked.

Sample result:

{units: [
{
    _id: 23423, 
    availability: [NNNYYYYNNN...],
    changeOver: [XXXXIIIIOOOCCC....],
    minStay: [3333377777777333...],
    availabilityUpdate: "2015-06-05T09:53:43Z"
},
{
   _id: 23424,
   ....,  
}
]}

Each section consists of an array of days. The first day is the value of "availabilityUpdate". Max size is 1095.

Availabilities

N = not available
Y = available
Q = on request

The arrivalday is marked as not available, the departureday is marked as available.

The array will not be larger than the last booking, the last item in the array stands for the rest of the period. So if there are no bookings yet, you will only get [Y].

Change-Over

X=no action possible, C=check-in/out, O=check-out only, I=check-in only

Minimum Stay

A booking has to be at least this long.

Services

Get all services that customers can be charged for, including rental fees.
 
Action name: getServices
 
Sample result:
{
   "services": [
      {
         "_id": 446,
         "calculation": "NIGHT",
         "constrain": true,
         "mandatory": true,
         "type": "RENT",
         "charge": "CUSTOMER",
         "ask": 1000,
         "provider": "OWNER",
         "name": {
            "en": "Rent",
            "de": "Miete"
         }
      },
      {
         "_id": 449,
         "calculation": "FLAT",
         "mandatory": true,
         "type": "FINALCLEANING",
         "charge": "CUSTOMER",
         "ask": 2000,
         "provider": "SELF",
         "name": {
            "en": "Finalcleaning",
            "de": "Endreinigung"
         }
      },
...]}

 

Info

 
field description type
name   ML
calculation one of "FLAT","NIGHT","DAY","WEEK","MONTH","PERC","USAGE"  
constrain if true this service has to be charged the hole stay B
perAdult if true prices are multiplied by the number of adults B
perChild if true prices are multiplied by the number of children B
perBaby if true prices are multiplied by the number of babys B
minChildAge if perChild is true, prices are multiplied by the number of children that are at least this old  
maxChildAge if perChild is true, prices are multiplied by the number of children that are not older than this  
mandatory if true, customers have to pay for this service  
type Appendix B  
surcharge if true prices are multiplied by the number of persons exceeding the minimum number of persons specified in the price-condition (see unit-prices)  

 

 

Regions

Get all regions. vOffice Regions are setup as a tree.
 
Action name: getRegions
 
Optional parameters:
 
parameter description value
description include descriptions true

Sample result:

{"regions":[
      {
         _id:3,
         name:{
            "de":"Alle Orte"
            "en":"All regions"
         },
         path:{
            "de":"Alle-Orte",
            "en":"All-regions"
         }
      },
      {
         _id:608,
         leveltype:"REGION",
         name:{
            "de":"Ostsee"
         },
         path:{
            "de":"Ostsee",
            "en":"Ostsee"
         },
         descriptions:{
            "de":"Die Ostsee ist ...",
            "en":"The Baltic Sea is...."
         },
         parent:3
      },
      {
         _id: 23424,
         ....,  
      }
]}

 

Info

 
field description type
name   ML
description   ML
path path on the vOffice CMS homepage ML
leveltype one of: 'COUNTRY','REGION','AREA','CITY','DISTRICT' or empty if other  
parent id of the parent region  

 

 

Live-Query

Search

List / search for units.

Action name: searchUnits

Fields in the json-encoded "data" parameter:

name description format required
fields requested unit properties for the search result, see below Object true
filter filter for the search result List true
warnings wether to check for warnings, only aplicable when from and till is set in the filter B  
sorting can be a unit property or one of: 'price', 'random', 'rating', 'stars' S  
ids unit ids for subsequent calls (pagination) List  
max maximal number of results, default is 18, max is 64    
 

NOTE: Live search is for now restricted to 600 units max. If you've got more units in total, you may not use use this function but use your own database by exporting the units through the export.

NOTE: Live search is only allowed with pagination in place. If you've got more than 64 units, subsequent results may only be fetched on user interaction (e.g. pagination or infinite scroll).

 

Possible requested fields:

 

Requested fields can be all unit properties (global and custom ones). See unit export for possible values. In addition these special fields can be requested:

name description
calc.total total price for the selected period
calc.oTotal  
calc.discountName  
idxImage index image path

A field is specified as {'u.fieldname':{filter:projection}}, see projection for details.

 

Possible filter values:

You can filter for all unit properties (global and custom ones). See unit export for possible values.

Append '_min' or '_max' to the fieldname for integer values, like 'beds_min'.

In addition these special values can be used:

name description
from yyyy-MM-dd
till yyyy-MM-dd
region region path, like "France/Provence/Cote.d-Azur/Vence"
regionid  
unitgroupid unit group id
facilityid facility id
adults  
children  
babys  
name (first letters of) unit name OR unit id
price_min  
price_max  

 

Sample request data:

{
    "fields": {
        "u.name": {"filter": "vautolang"},
        "u.loc.coordinates": {},
        "u.path": {"filter": "vlang"},
        "u.idxImage": {},
        "u.calc.total": {"filter": "vcurrency"},
    },

    "filter": {
        "adults": "4",
        "children": "1",
        "babys": "0"
    },
    "sorting": "random"
}

 

NOTE: Sorting or filtering by price is more expensive and will cost more credits.

 

Sample result:

{
    ids: [2344,2342343,3423423,...],
    units: [
        {name: 'App. 04', type: 'Ferienwohnung'},
        {name: 'App. 05', type: 'Ferienwohnung'},
        ....
    ],
    ok: true
}

Note: On first call, you will get a list of all unit-ids in the result-set and the first page of data. To get other pages, you need to add a sublist of these ids to the request.

 

Get single Unit

Get unit data for a single view.

Action name: getUnit

Fields in the json-encoded "data" parameter:

name description format required
fields requested unit properties for the search result, see below Object true
id unit id I true unless code is give
code unit code S false
pricetable additionally request a pricetable (pricelist optimized for presentation) B false
 
 

Possible requested fields:

Requested fields can be all unit properties (global and custom ones). See unit export for possible values.

A field is specified as {'u.fieldname':{filter:projection}}, see projection for details and search for example.

Calendar

Get the availability, possible arrival/departure days and minimum stays for one unit. Intended for a single unit view.

Action name: getCal

Fields in the json-encoded "data" parameter:
 
name description format required
unit unit id   true
 
 
 

Sample result:

{
    "availability": ["N", "N", "Y",... ],
    "changeOver": ["X", "X", "X", "X",... ],
    "availabilityUpdate": "2015-07-18T01:00:03Z",
    "minStay": [7, 7, 7, 7, 5, 5, ....]
}

 

Response sections

 
name description
availability availability: N=not available, Y=available, Q=on request; Arrival = N; Departure = Y
minStay minimum stay in nights
changeOver X=no action possible, C=check-in/out, O=check-out only, I=check-in only
availabilityUpdate timestamp the calendar was updated, first entries of each section is this day

Quote prices

This query greatly reduces the complexity of building your own booking process on an external website. It calculates for a given time period the prices, taking into account things like special offers, booking restrictions, price conditions etc.

See Booking -> "quote prices" for details.

Booking

Quote prices

This query greatly reduces the complexity of building your own booking process on an external website. It calculates for a given time period the prices, taking into account things like special offers, booking restrictions, price conditions etc.

Action name: quotePrices

Fields in the json-encoded "data" parameter:
 
name description format required
fromdate   D true
tilldate   D true
adults      
children      
babys babys that do not require a full-sized bed    
 
NOTE: DO NOT use this action for lists of units. The response is very detailed and only intended for a unit / property page / booking process. Use the live query search to get prices for search results.
 

Sample result:

{"mandatory": [{
        "service": {
            "constrain": true,
            "mandatory": true,
            "type": "RENT",
            "id": 446,
            "name": "Miete"
        },
        "price": 5500,
        "calculation": "NIGHT",
        "charge": "CUSTOMER",
        "season": "Saison C",
        "fromdate": "2015-09-20",
        "tilldate": "2015-09-25",
        "timespan": 5,
        "total": 27500,
        "timeLabel": "Nächte"
    }, {
        "service": {
            "mandatory": true,
            "type": "FINALCLEANING",
            "id": 449,
            "name": "Endreinigung"
        },
        "price": 4500,
        "calculation": "FLAT",
        "charge": "CUSTOMER",
        "total": 4500
    }....
}
"optional": [{
.....
}]
"onsite": [],
"onsiteOptional": [],
"usage": [],
"errors": {},
"warnings": {},
"paymentSchedule": {
    "prepayment": {
        "date": "2015-07-31",
        "amount": 8300,
        "percent": 2500
    },
    "rest": {
        "date": "2015-08-30",
        "amount": 24950,
        "percent": 7500
    }
},
"optionValidFor": 3



}

 

Response sections

 
name description
mandatory services that need to be paid for, for example rent
optional services that can be booked optionally, for example bed linen
onsite services that need to be paid on site, they will not be invoiced by vOffice
onsiteOptional services that need to be paid on site, but can be booked optional
usage services that need to be paid by usage, for example electricity, gas etc.
errors errors that are blocking the booking process, for example the unit is already occupied in the selected period
warnings warnings that are not blocking the booking process
paymentSchedule payment schedule (prepayment, rest payment, full payment etc.)
optionValidFor if making an option is possible in addition to a booking, these are the days the option will be valid for
 
 

Error codes

 
name description
notavailable

 

nopetsallowed  
maxbedsblock too many persons, booking is not possible
maxbeds too many persons, should request bunkbeds
minpersons not enough persons
maybeavailable no prices found for the rental
badday not a arrival / departure day, allowed days in details
mingap if arrival is not on a previous departure, there needs to be a minimum gap
minstay  
minstayfill minimum stay unless a gap is filled

Online Booking

Make an online booking or option.

Action name: book

Fields in the json-encoded "data" parameter:

name description format required
reservation.customer customer information, see below Object true
bookings List of booking information, currently only one booking possible per request, see below List true
action 'option' or 'booking' S true
commission commission charged by partner in cents C false
extraCommission Info about additional third party commission Object false
 
 

Reservation.customer fields:

name description
title  
forename  
surname  
mainAddress.street  
mainAddress.housenumber  
mainAddress.postalcode  
mainAddress.city  
mainAddress.country  
email  
phone  
telcom office phone
fax  
mobile  
currency  
preferredLanguage SO 639-1
message additional message from guest, will be shown in the inbox
 
 

Booking fields:

name description
unit unit id
adults  
children  
babys  
from yyyy-MM-dd
till yyyy-MM-dd
servicelines list of servicelines, see below

 

Serviceline fields:

you can simply use the lines gotten from the "quote prices" response.
 
name description
service.id  
amount as Float
price in cents
discountName  
description  
season  
fromdate yyyy-MM-dd
tilldate yyyy-MM-dd

The total will be calculated as: PRICE * AMOUNT * TIME (e.g. nights). Amount should be empty if not aplicable, for example for rent.

 

extra Commission fields:

 
name description
amount in cents
description who is charging this commission

 

Sample request data:

{"reservation": {
        "customer": {
            "mainAddress": {
                "country": "DE",
                "street": "Karpendiek 23",
                "postalcode": "23730",
                "city": "Neustadt"
            },
            "title": "Herr",
            "forename": "Jens",
            "surname": "Hoff",
            "email": "knoffhoff@gmx.de",
            "mobile": "56465"
        }
    },
    "action": "booking",
    "bookings": [{
            "unit": 2351,
            "adults": "2",
            "children": "1",
            "babys": "0",
            "from": "2015-10-02",
            "till ":"2015-10-07",
            "servicelines ":[{
                "service ":{
                    "id": 4465 //rent
                },
                "price": 9000, 
                "season": "Saison C", 
                "fromdate": "2015-10-03", 
                "tilldate": "2015-10-08", 
            }, {
                "service":{
                    "id ":4495 //final cleaning
                },
                "price ":6500
            }]
    }]
}

 

Sample response:

As result you will get the reservation id and number, customer id and number and booking id.

{
  reservation: {
    "id": 612349,
    "nr": "19204",
    "token": "sdfksdfj...",
    "customer": {
        "id": 757456,
        "nr": "26243"
    },
    "bookings": [{
        "id": 596995
    }]
  },
  ok: true
}

 

 

Manage Bookings

In order to manage bookings (get, update, add payments etc.), you will need a second token.

vOffice will generate a link for each booking with a custom token that will look like:

yourdomain/[language-code/]manage?token=sdfk23sdf...

This token is needed to get or update a booking. The link can be placed in any document intended for the guest / customer.

The token is also part of the returned value of each new booking made.

Get booking

Get a booking or option.

Action name: getBooking

Fields in the json-encoded "data" parameter:

name description format required
token booking token generated by vOffice S true

Update Booking

Update a online booking or option.

Right now, you can only add services and update Guests. Once you update a booking or option, the status will automatically become "CONFIRMED".

Action name: updateBooking

Fields in the json-encoded "data" parameter:

name description format required
token booking token generated by vOffice S true
bookings updated bookings, this set consists of the booking ids as the keys and the updates as the value, see below SET true
noStatusChange leave the booking-status unchanged B  

 

Mapped bookings value:

name description format required
addedServicelines see online booking for details LIST false
addedGuests   LIST false
changedGuests you can only update the birthdate LIST false
removedGuests   LIST false

 

Sample request data:

{"bookings":{
      "710560":{
         "addedServicelines":[
            {
               "service":{
                  "id":480
               },
               "price":1000,
               "amount":1,
               "total":1000
            }
         ]
      }
   },
   "token":"eyJhbGciOiJ..."
}

 

Sample response:

As result you will get the reservation status:

{
   "reservation":{
      "nr":"20599",
      "paid":0,
      "outstanding":49600,
      "total":50600,
      "id":726544,
      "paymentSchedule":{
         "total":{
            "date":"2015-11-14",
            "amount":37200
         }
      }
   },
   "ok":true
}

 

Sample request data for updating guests:

{"bookings":{
      "710560":{
        addedGuests:[
            { // enter a known contact as guest:
                id: 34343 
            },
            { // or create a new contact:
                surname: 'Doe',
                forename: 'John',
                birthdate: '1984-01-01'
            }
        ],
        removedGuests: [
            {
                guestId: 234234
            }
        ],
        changedGuests: [
            {
                guestId: 234235,
                birthdate: '1984-01-01'    
            }
        ]
      }
   },
   "token":"eyJhbGciOiJ..."
}

 

Add Payment

Add a payment to a reservation.

Action name: addPayment

Fields in the json-encoded "data" parameter:

name description format required
token booking token generated by vOffice S true
payment   SET true

 

payment fields:

name description format required
amount   C true
note   S false
valuedate default is day of method call D false
type

one of CASH, BANKACCOUNT, CREDITCARD, PAYPAL, DIBS, DISBURSEMENT

important: a corresponding payment method needs to be setup in vOffice prior to this call

S true unless pmid is specified
pmid payment method id L true unless type is specified

 

Sample request data:

{"payment":{
      amount: 1000,
      note: 'prepayment made online',
      valuedate: '2016-12-01',
      type: 'PAYPAL'
   },
   "token":"eyJhbGciOiJ..."
}

 

Sample response:

As result you will get the reservation status:

{
   "reservation":{
      "nr":"20599",
      "paid":1000, //paid in total
      "outstanding":49600,
      "total":50600
      
   },
   "ok":true
}

 

Get Document

Get a specified document (for example 'terms and conditions'). 

Action Name: getDoc

Fields in the json-encoded "data" parameter:

 
name description format required
lang   S true
type specifiy required document, currently only 'gtc' supported S true
 

Appendix

A: Data-Types

 
type description
S String
ML multilanguage set, the key describes the language code (ISO 639-1)
SET  
C Currency: long value stating the cents
D Date as String: yyyy-MM-dd

B: Service-Types

 

 

type description

RENT

 

FINALCLEANING

 

LINEN

 

HANDTOWELS

 

PET

 

CRIB

 

HIGHCHAIR

 

BABYBED

 

TRANSFER

e.g. Airport Transfer

VTAX

Visitor’s tax

GAS

 

WATER

 

ELECTRICITY

 

INSURANCE

 

CANCELLATION

cancellation fee

COMMISSION

own booking commission

COMM_THIRD

booking commission to third parties

AGIO

payment agio

BOOKING_FEE

 

C: Projection

Projection:

The result of searches and unit request can be projected for easier handling, performance and result size.

name description
vcurrency format as currency
vsoption translate an option value into the translated string
vlang select requested language only for a multilanguage text
vautolang select best available language for a multilanguage text (slower)