The vOffice-API is devided into three main sections:

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. Depending on the implementation type (direct or CM+), you will either get a api-key for each customer or one for all customer which have activated your connection on our side.

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

This api is charged by the number of api calls. Please refer to the vOffice prices for detailed information.

Implementation

Please reach out to us, so that we can discuss the implementation process (info@v-office.com or partner@v-office.com if previously in contact).

At first, things may need to be clarified on the business side, before starting with the technical parts.

If beneficial, we can set up meetings, to get things started. There we can clarify any questions, which occured after reading the api, the test process and everything else.

Onboarding

The onboarding process will be done by our support team, depending on the connection type, the new units will then be available under the existing api key (if CM+ / bul connection) or you will need to add a new api key (if direct connection) which will contain the new units.

The details of the process may differ from partner to partner, so make sure to clarify it with us in advance, to avoid misunderstandings later on.

Offboarding

If not agreed on otherwise, units that are no longer being exposed over the api, should be removed / set offline (or marked as unavailable till no open booking is present anymore) automatically.

Issues & Questions

Make sure to elaborate the thematic and add all the available information.

For example: member id, unit id, detailed description of the issue (not "price is wrong" but rather "we have noticed that the calculated vtax value we are getting from the QuotePrices action is to low, 200 instead of 300, when we book for 2 persons a 7 nights"), timestamps etc.

If you have general issues/questions: please contact  info@v-office.com

If you have api related issues/questions: please contact  partner@v-office.com

If there is any important news regarding the api, it will be mentioned here.

For example: planned changes which would require action on the implementation side in the future.

- No important notice at the moment - 

Sample result:

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

Member

The member ID which is returned for every unit, is the internal customer ID.

If you use a direct connection, every api key should only feature on member.

If you use the CM+ (bulk) connection, a key will feature all available aka multiple members, so you can use the member ID to identify which units belong to which member if necesssary.

UnitGroups

In our system, the customer has the possiblity to create unit groups. These groups have a unique ID and the customer may assign multiple units to it.

Groups will be included in the response (as groups, which will be a array), if the request parameter group (see above) is set to true.

You can filter for all units of a specific unit group by using the unitgroupid parameter and set the ID of the unit group you want to select with the filter.

Which units may be included in the specific unit groups and what these groups mean, should be clarified with the customer / agency, if you need to know it / want to use this feature.

Info

Properties

NOTE: In addition to these fields, all descriptions and properties can be exported (need to be activated in the api-key by our support).

You can get a list of all possible properties here: https://api2.v-office.com/export/properties

This will show a list of all properties that are valid for all customers

You can get a list of all properties that are possible for customers, exposed via the specified api key here (replace [key] with the api key): https://api2.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

You can also fetch properties, using the getProperties action, which will enable you to fetch properties on a customer aka member level (if CM+ is in use, you may want to specify the member ID, if it is a direct connection, this is not needed, since the api key will only contain one member):

Images

A list of the units images.

Example (of one image entry):

{
id: 123456,
width: 1440,
height: 961
tag: "fireside",
titles: {
        de: "Kamin-/Ofen",
        en: "Fireplace"
        }
},

Image download:

You can find and download the images under the following url:

https://dyn.v-office.com/image/[size]/[imageId].jpg

Possible sizes: tn, tnfx, tnx, tnxfx, s,sfx, m, mx, xl, xxl (sizes ending with fx will scale/stretch to fit exactly the size)

For example - medium size (600x400): m

roomDetails

A list of rooms with additional details, including beds. 

Example:

{
type: "BEDROOM",
hasPrivateBathroom: false,
roomDarkeningOption: true,
wardrobe: true,
maxGuests: 2,
beds: [{
       kind: "KINGSIZE",
       type: "ORDINARY",
       raisedBeds: false,
       openFootsection: true,
       extraLongBeds: false,
       childrenOnly: false,
       amount: 1
      }]
},
 

Address

Contains Address related information all in the STRING data type.

Example:

address: {
         street: "Straßenname",
         housenumber: "7",
         postalcode: "28217",
         city: "Stadt",
         country: "DE"
},
 

loc

Contains longitude and latitude values

Example:

{
type: "Point",
coordinates: [
             15.96399973376475,
             28.14786475479639
             ]
},
 

Prices

NOTE: Prices with the calculation PERC, will not be included in the response but will be returned in the QuotePrices request, where the percentage value is already calculated into an total value

NOTE: FINALCLEANING should only every be applied once, if multiple are returned, the first applicable FINALCLEANING in the order should be applied, other types usually add up if multiple apply

Example:

"prices": [
        {
          "service": 123332,
          "value": 15788,
          "ask": 32.0,
          "sourceId": 2331221,
          "calculation": "NIGHT",
          "type": "RENT",
          "fromdate": "2022-01-01",
          "tilldate": "2026-06-08",
          "nightRange": {
            "min": 1,
            "max": 2
          },
          "condition": {
            "minDays": 1,
            "maxDays": 2,
            "minPersons": 0,
            "maxPersons": 999999
            "sourceId": true
          }
        },
...]
 

Offers

Note: EarlyBird and Lastminute offers will only be applied, if the validfrom and validtill dates are within the stay period, the offer will not be applied if only the arrival day is within the valid dates.

Example:

      "offers": [
        {
          "id": 123,
          "minStay": 2,
          "type": "PERCENT",
          "timeSpan": 180,
          "discountType": "XY",
          "value": 3400,
          "visible4interfaces": true,
          "name": {},
          "services": [123, 1456]
        },
        ...]

Restrictions

Example:

restrictions: [{
               rid: 12345,
               minimumStay: 5,
               minimumGap: 5,
               fillGapsMinDays: 5,
               fillGaps: true,
               lastMinuteLead: 7,
               ignoreArrivalDaysOnLastMinute: false,
               ignoreDepartureDaysOnLastMinute: false,
               ignoreArrivalDaysOnFillGap: false,
               ignoreDepartureDaysOnFillGap: false,
               minimumStayLastMinute: 4,
               minimumGapLastMinute: 0,
               fixWrongDay: false,
               arrivalDays: {7 items},
               departureDays: {7 items},
               fromdate: "2023-05-13T00:00:00Z",
               tilldate: "2023-06-24T00:00:00Z"
              },...]
 

CancellationPolicy

Example:

           "cancellationPolicy": {
                "gracePeriod": 3,
                "gracePeriodArrivalInMaxDays": 180,
                "defaultPenalty": 3000,
                "cancellationFlatFee": 5000,
                "byDaysTillArrival": [
                    {
                        "daysBeforeArrival": 14,
                        "penaltyInPercent": 9500
                    },
                    {
                        "daysBeforeArrival": 30,
                        "penaltyInPercent": 9000
                    },
                    {
                        "daysBeforeArrival": 90,
                        "penaltyInPercent": 4000
                    }
                ]
            }

Feedbacks

fb_ +  a specific number are the internal rating categories, please ignore these and use the avg value instead.

Example:

{ ...

arrival: "2024-09-08T00:00:00Z",

departure: "2024-09-15T00:00:00Z",

onDate: "2024-09-30T00:00:00Z",

forename: "Max",

surname: "M.",

lang: "de",

fb_28: 5,

comment: "Dies ist ein Beispiel Text einer Bewertung.",

avgRating: 4.5

... },

Ratings

fb_ +  a specific number are the internal rating categories, please ignore these and use the avg value instead.

Example:

ratings: {...

fb_count: 124,

fb_28: 4.702479362487793,

fb_avg: 4.514904975891113,

...}

List / search for units. Useful for homepages, NOT intended for interfaces to OTAs / channelmanager.

Action name: searchUnits

Fields in the json-encoded "data" parameter:

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).
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.

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:

Get the availability, possible arrival/departure days and minimum stays for one unit. Intended for a single unit view.
Useful for homepages, NOT intended for interfaces to OTAs / channelmanager.

Action name: getCal

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

Search for a contact history by phonenumber.

Action name: searchPhoneNumber

Sample result:

{
    "trackingId": "i-0dd64dd37218bccef|c34e17f4-f384-45ec-864b-3d96385dfdbb",
    "intNr": "+49 40 99999XXX",
    "nr": "040 99999XXX",
    "description": "Hamburg",
    "id": 462723,
    "label": "Mustermann, Max",
    "image": "https://....",
    "unitcount": 1,
    "units": [
        {
            "id": 2133,
            "code": "Grüntal I App.05"
        }
    ],
    "bookingcount": 16,
    "bookings": [
        {
            "id": 3528776,
            "label": "Grüntal I App.05: 20.11.20 - 22.11.20"
        },
        {
            "id": 3198718,
            "label": "Grüntal I App.05: 04.11.20 - 06.11.20"
        },
        {
            "id": 3244487,
            "label": "Grüntal I App.05: 31.10.20 - 02.11.20"
        }
    ],
    "ok": true
}

Response

Check the VoucherCode via API-Action "validateVoucher"

You can use the validateVoucher action to check if the vouchers are valid, you should do that, before using the voucher codes in other actions.

Request example (Json payload):

{ 
"code": "[VOUCHER-CODE]" 
}

Response example (for an valid voucher):

{
  ... 
  "voucher": { 
    "name": "Name des Vouchers, wie im Backend angegeben" 
  }, 
  ...
}

Our suggested approach would be to store the voucherCode (temporarily) once it was successfully validated and submit it with all the following requests if it is needed (like price and booking requests).

Voucher process:

1. Check the VoucherCode via API-Action "validateVoucher".

2. Using the voucher on quotePrices

Because the voucherCodes can be restricted to certain Units/UnitGroups you should try to get the reduced price first by calling quotePrices with the code added on the root of the JSON Payload

{
  ... 
  "voucherCode": "[VoucherCode]", 
  ... 
}

3. Using the code again while executing the book request

While executing the final book request, the voucherCode has also to be submitted:

{
  ... 
  "voucherCode": "[VoucherCode]", 
  ... 
}

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

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"
        "discountName": "Name of the discount", // only present if a special offer applies to this service
        "specialOffer": 1234, // only present if a special offer applies to this service
        "oPrice": 6000, // only present if a special offer applies to this service
        "oTotal": 30000 // only present if a special offer applies to this service
    }, {
        "service": {
            "mandatory": true,
            "type": "FINALCLEANING",
            "id": 449,
            "name": "Endreinigung"
        },
        "price": 4500,
        "calculation": "FLAT",
        "charge": "CUSTOMER",
        "total": 4500
    }....
},
omandatory": [{ 
..... 
}],
"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,
"travelInsuranceIsSetup": false,
"deposit": {
        "amount": 25000,
        "location": "WITH_FINALPAYMENT"
},
"serviceLimits": [{ 
    "449": { 
        "maxPerBooking": null, 
        "maxDaysAfterBooking": null, 
        "minDaysBeforeArrival": 7, 
        "blockedByDate": true  
    }
}],
 "currency": "EUR"
}

Response sections

Sample result:

{
  "trackingId": "i-0dd64dd37218bccef|eba14461-5e6a-463c-8fe0-c19736f21e71",
  "bookings": [
    {
      "id": 3198434,
      "fromdate": "2021-02-13",
      "status": "CONFIRMED",
      "tilldate": "2021-02-21",
      "lines": [
        {
          "type": "RENT",
          "total": 44000,
          "fromdate": "2021-02-13",
          "price": 5500,
          "tilldate": "2021-02-21"
        }
      ]
    },

[...]

  ],
  "ok": true


}

List one specific Booking made by the supplied key.

Sample result:

{
  "trackingId": "i-0dd64dd37218bccef|eba14461-5e6a-463c-8fe0-c19736f21e71",
  "booking": 
    {
      "id": 3198434,
      "fromdate": "2021-02-13",
      "status": "CONFIRMED",
      "tilldate": "2021-02-21",
      "lines": [
        {
          "type": "RENT",
          "total": 44000,
          "fromdate": "2021-02-13",
          "price": 5500,
          "tilldate": "2021-02-21"
        }
      ],
    },
  "ok": true
}

Get a booking or option. It is intended to offer guests a possibility to update their booking. Please use "getUpdatedBookings" to look for changes in your bookings. 

Action name: getBooking

This action is only usable for direct connections, CM+ connections do not support this action at the moment.

Fields in the json-encoded "data" parameter:

DEPRICATED! Do not use any more. Get a specified document (for example 'terms and conditions'). 

Action Name: getDoc

Fields in the json-encoded "data" parameter:

Subscribe to newsletter via double opt-in

Action name: subscribe

Fields in the json-encoded "data" parameter:

Sample request data:

{
   "setup":{
      listId: 23324,
   },
   "form":{
       email: 'test@test.de',    
   }, 
}

Guest App Actions

Common values for all GuestApp-Requests:

reservationData

Get all information about the given reservation and bookings. The reservation is set by the key/token

Sample Request:

{}

Sample Response:

{
   "trackingId":"...",
   "bookings":[
      {
         "id":22554865,
         "availableLanguages":[
            "de",
            "en"
         ],
         "currency":{
            "code":"CHF",
            "symbol":"CHF",
            "symbolPosition":"TRAILING_SPACE"
         },
         "preferredLanguage":"de",
         "reservationNumber":"00001",
         "reservationDate":"2022-01-20",
         "bookingId":9319655,
         "customer":{
            "id":6351986,
            "title":"Herr",
            "forename":"Christian",
            "surname":"Mustermann",
            "street":"Dünenweg",
            "housenumber":"1h",
            "city":"Neustadt in Holstein",
            "postalcode":"23730",
            "country":"DE",
            "email":"cm@gmail.de",
            "mobile":null
         },
         "status":"CONFIRMED",
         "arrivalStatus":null,
         "from":"2022-03-30",
         "till":"2022-04-08",
         "arrivalTime":null,
         "departureTime":null,
         "totalDays":9,
         "totalPersons":2,
         "personCountDetails":{
            "adults":2,
            "children":0,
            "babys":0
         },
         "unit":{
            "id":12345,
            "title":"App. 01",
            "image":{
               "urlThumb":"//www.v-office.com/dyn/image/p.tnx/2721181.jpg",
               "url":"//www.v-office.com/dyn/image/p.m/2721181.jpg"
            },
            "city":"Westerland",
            "url":"http://hp.v-office-cms.com/de/Schleswig.Holstein/Nordsee/Sylt/Deich.01"
         },
         "bookedServices":[
            {
               "id":null,
               "serviceId":null,
               "name":"Inklusivpreis",
               "info":"Miete",
               "price":108000,
               "total":108000,
               "amount":null,
               "timespan":null,
               "from":null,
               "till":null,
               "calculation":null,
               "perAdult":null,
               "perBaby":null,
               "perChild":null
            },
            ...
         ],
         "availableExtras":[
            {
               "id":22571,
               "name":"Handtücher",
               "price":1000,
               "calculation":"DAY",
               "limits":{
                  "maxPerBooking":1,
                  "maxDaysAfterBooking":null,
                  "minDaysBeforeArrival":null
               }
            },
            ...
         ],
         "guests":[
            
         ],
         "guestSuggestions":[
            {
               "GuestId":null,
               "Tilldate":null,
               "Fromdate":null,
               "ContactId":123456,
               "Birthdate":null,
               "RegistrationPersonGroup":null,
               "City":"Neustadt in Holstein",
               "Country":"DE",
               "Forename":"Christian",
               "Gender":null,
               "Housenumber":"1h",
               "IdExpiry":null,
               "Iddate":null,
               "KnownIdType":null,
               "Nationality":null,
               "Personalid":null,
               "Postalcode":"23730",
               "Street":"Dünenweg",
               "Surname":"Mustermann",
               "Surname2":null,
               "Title":"Herr"
            }
         ],
         "payments":[
            
         ],
         "paymentSchedule":{
            "prepayment":{
               "date":"2022-02-03",
               "amount":21100,
               "includesDeposit":false
            },
            "rest":{
               "date":"2022-03-16",
               "amount":84400,
               "includesDeposit":false
            }
         },
         "registrationForm":[
            {
               "id":364,
               "provider":"DEMO",
               "useGuestNationality":"VISIBLE",
               "useGuestGender":"VISIBLE",
               "useGuestRegistrationPersonGroup":"VISIBLE",
               "useGuestForename":"REQUIRED",
               "useGuestSurname":"REQUIRED",
               "useGuestSurname2":"REQUIRED",
               "useGuestBirthdate":"REQUIRED",
               "useGuestStreet":"VISIBLE",
               "useGuestHousenumber":"VISIBLE",
               "useGuestPostalcode":"VISIBLE",
               "useGuestCity":"VISIBLE",
               "useGuestCountry":"VISIBLE",
               "useGuestKnownIdType":"VISIBLE",
               "useGuestPersonalid":"VISIBLE",
               "useGuestIddate":"VISIBLE",
               "useGuestFromdate":"VISIBLE",
               "useGuestTilldate":"VISIBLE",
               "personGroups":[
                  {
                     "code":"Erwachsener",
                     "label":"Erwachsener"
                  },
                  {
                     "code":"Kind",
                     "label":"Kind"
                  },
                  ...
               ]
            }
         ],
         "options":{
            "countries":[
               ...
               {
                  "id":"DE",
                  "text":"Deutschland",
                  "used":true
               },
               ...
            ],
            "titles":[
               "Frau",
               "Herr",
               "Familie",
               "Eheleute"
            ]
         },
         "setup":{
            "askForEstimatedArrival":true,
            "askForEstimatedDeparture":true,
            "checkinFrom":"08:00:00.000",
            "checkinTill":"20:00:00.000",
            "checkoutFrom":"08:00:00.000",
            "checkoutTill":"20:00:00.000",
            "colorBackground":null,
            "colorForeground":null,
            "colorPrimary":null,
            "colorSecondary":null,
            "fontFamily":null,
            "logoImageId":null,
            "showCheckin":true,
            "showCheckout":true,
            "showFeedback":true,
            "showGuides":true,
            "showLocations":true,
            "showTravelinfo":true
            "showPayments":true
            "showAddServicelines":true
         }
      }
   ],
   "ok":true
}

reservationContent

Providing the editorial content managed inside of vOffice.

Sample Request:

{}

Sample Response:

{
   "locations":[
      {
         "id":2861,
         "section":"locations",
         "vellcomeCategory":15,
         "title":"Zur goldenen Möwe",
         "filetype":"LOC",
         "latitude":null,
         "longitude":null,
         "highlight":false,
         "changed":"2021-01-14T10:39:05Z",
         "locationType":null,
         "fileUploaded":false,
         "previewImageUrl":"//www.v-office.com/dyn/image/p.m/3957684.jpg",
         "contacts":[
            {
               "id":1422,
               "type":"WEB",
               "value":"http://www.location-domain.de",
               "number":"http://www.location-domain.de"
            }
         ]
      },
      ...
   ],
   "guides":[
      {
         "id":2695,
         "section":"guides",
         "vellcomeCategory":null,
         "title":"Bedienunsanleitung Waschmaschine",
         "filetype":"HTML",
         "latitude":null,
         "longitude":null,
         "highlight":false,
         "changed":"2021-03-08T14:55:29Z",
         "locationType":null,
         "fileUploaded":false,
         "previewImageUrl":"//tim.v-office.com/dyn/image/p.m/4225544.jpg",
         "contacts":[
            
         ],
         "contentId":3906,
         "content":""
      },
      {
         "id":2528,
         "section":"guides",
         "vellcomeCategory":null,
         "title":"WLAN Zugang",
         "filetype":"LOC",
         "latitude":null,
         "longitude":null,
         "highlight":false,
         "changed":"2020-12-18T16:44:30Z",
         "locationType":null,
         "fileUploaded":false,
         "contacts":[
            
         ]
      }
   ],
   "locationCategories":[
      {
         "id":15,
         "label":"Bars & Restaurants"
      },
      {
         "id":16,
         "label":"Sehenswürdigkeiten"
      },
      {
         "id":17,
         "label":"Einkaufstipps"
      }
   ],
   "ok":true
}

submitFeedbackForm

Just submitting the customer feedback based on the feedback form.

Please note: for the type:"TEXT", the value may not contain characters that require 4 bytes unicode sequences (i.e. emojis). vOffice will remove any invalid characters without further notice.

Sample Request:

{
   "bookingId":9319654,
   "formData":[
      {
         "id":603,
         "name":"Sauberkeit",
         "type":"STARS",
         "value":3
      },
      {
         "id":604,
         "name":"W-Lan+Geschwindigkeit",
         "type":"STARS",
         "value":2
      },
      {
         "id":605,
         "name":"Essen",
         "type":"STARS",
         "value":4
      },
      {
         "id":606,
         "name":"Personal+Freundlichkeit",
         "type":"TEXT",
         "value":"Super+Toll"
      }
   ]
}

Sample Response:

{
    "ok":true
}

checkIn

The gust can tell vOffice when he has arrived at the location.

Sample Request:

{
	"bookingId":9319654
}

Sample Response:

{
    "ok":true,
    "arrivalStatus":"CHECKED_IN"
}

setReservationStatus

Changing the status of the given reservation. Valid status are:

• confirmed

Sample Request:

{
   "status":"CONFIRMED",
   "bookingId":9319656
}

Sample Response:

{
    "ok":true,
    "newStatus":"CONFIRMED"
}

setDepartureTime

Tell vOffice the estimated departure time.

Sample Request:

{
   "departureTime":"12:00",
   "bookingId":9319654
}

Sample Response:

{
    "ok":true,
    "departureTime":"12:00:00.000"
}

getPaymentMethods

Getting the configured Payments Methods

Sample Request:

{
    "bookingId":9319654
}

Sample Response:

{
   "BANKACCOUNT":{
      "id":12344,
      "type":"BANKACCOUNT",
      "paymentTest":false,
      "creditCardAccepted":false,
      "sofortAccepted":false,
      "giropayAccepted":false,
      "bankaccount":{
         "iban":"DE02200505501015871393",
         "swift":"HASPDEHH",
         "institution":"Sparkasse"
      }
   },
   "PAYPAL":{
      "id":12346,
      "type":"PAYPAL",
      "email":"paypal.mail@address.com",
      "paymentTest":true,
      "creditCardAccepted":false,
      "sofortAccepted":false,
      "giropayAccepted":false,
      "fields":{
         "cmd":"_xclick",
         "business":"paypal.mail@address.com",
         "item_name":"Reservierung: 00093",
         "cancel_return":"payment?result=canceled",
         "no_shipping":1,
         "return":"payment?result=accepted",
         "currency_code":"EUR",
         "notify_url":"https://api2.v-office.com/api/paypalcallback?ref_id=eyJhbGciOiJIUzI1NiJ9.eyJwYXltZW50TWV0aG9kSWQiOjEyMzQ2LCJyZXNlcnZhdGlvbklkIjoyMjU1NDg2NH0.pQTooGgDRK-7Tz9pY1RJmuG2HucY8zHTxbRrmx2XUPI",
         "lc":"de"
      },
      "url":"https://www.paypal.com/cgi-bin/webscr"
   },
   "STRIPE":{
      "id":12345,
      "type":"STRIPE",
      "paymentTest":false,
      "creditCardAccepted":true,
      "sofortAccepted":true,
      "giropayAccepted":true
   },
   "ok":true
}

submitCoupon

Submitting coupons, not vouchers. Coupons do represent a fixed amount of money (e.g. as a present) instead of vouchers that mostly represent a percentual discount for e.g. marketing purposes. Returning Coupon types are “VALUE” and “DISCOUNT”

Sample Request:

{
	"couponCode":"XXXX-XXXX-XXXX-XXXX",
	"bookingId":9111522,
	"amount":75000
}

Sample Response:

{
   "ok":true,
   "coupon":{
      "amount":10000,
      "type":"VALUE"
   }
}

The analytics api helps you understand your data. It provides a condensed view. Results should be cached at least 24 hours.

It uses a different API key, which can be setup in vOffice: Einstellungen->Team-Zugang->Analytics (Setup->Team-Access -> Analytics).

https://api2.v-office.com/api/analytics?parameters

Sample result schema:

{
    "data": {
        "fromdate": {
            "type": "DIMENSION",
            "datatype": "YEAR_MONTH_DAY",
            "label": "Von"
        },
        "tilldate": {
            "type": "DIMENSION",
            "datatype": "YEAR_MONTH_DAY",
            "label": "Bis"
        },
        "status": {
            "type": "DIMENSION",
            "datatype": "TEXT",
            "label": "Status"
        },
        "booking_total": {
            "type": "METRIC",
            "datatype": "CENT",
            "currency": "EUR",
            "label": "Gesamt VK"
        },
....
}

Response fields

{
    "data": [
        {
            "fromdate": "2021-01-21",
            "tilldate": "2021-01-24",
            "status": "CONFIRMED",
            "booking_total": 54000,
            "purchase_total": 26068,
            "days": 3,
            "adults": 2,
            "children": 0,
            "babys": 0,
            "booked": "2020-10-01",
            "channel": "Booking.com",
            "client": null,
            "unit": "Deich Hs. 37",
            "rooms": 3,
            "beds": 4,
            "margin": 8142,
            "sale_PET": 9000,
            "sale_RENT": 32100,
            "sale_LINEN": 3000,
            "sale_offer": null,
            "purchase_PET": 9000,
            "purchase_RENT": 32100,
            "purchase_offer": null,
            "sale_ownerTotal": 41100,
            "sale_BOOKING_FEE": 1900,
            "sale_FINALCLEANING": 8000,
            "purchase_COMMISSION": -8142,
            "purchase_COMM_THIRD": -6890,
            "purchase_ownerTotal": 41100
        },
        {
            "fromdate": "2021-03-08",
            "tilldate": "2021-03-10",
            "status": "CONFIRMED",
            "booking_total": 31300,
            "purchase_total": 19206,
            "days": 2,
            "adults": 2,
            "children": 0,
            "babys": 0,
            "booked": "2020-05-12",
            "channel": "Homepage",
            "client": null,
            "unit": "Königsstr. 04",
            "rooms": 3,
            "beds": 4,
            "margin": 2594,
            "sale_RENT": 21800,
            "sale_LINEN": 2000,
            "sale_offer": null,
            "purchase_RENT": 21800,
            "purchase_offer": null,
            "sale_ownerTotal": 21800,
            "sale_FINALCLEANING": 7500,
            "purchase_COMMISSION": -2594,
            "purchase_ownerTotal": 21800
        },
     ...
}

Response fields

Projection:

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

Coupons

Coupons are pre paid, the guest can pay money for a coupon, which will then contain the credit according to the paid amount. If the coupon code is added to a payment process, the credited value will be substracted from the amount (does not go past 0) the guest would have to pay otherwise. The coupon will be gone, as soon as the credit is used up.

You can check for valid coupon codes using checkCoupon action

You can apply a coupon code by adding it to the booking request

You can submit coupons using the submitCoupon action

Vouchers

Vouchers are for restricted special offers, these restricted special offers may function like normal special offers, except for the application condition, since the restricted special offers require the specific voucher code to be sent in the request, otherwise they will not be applied.

The customer can add the voucher code requirement to any regular special offer and therefore turn it into a restricted one, these special offers will be returned in the regular offers list and will contain the voucherCode field, with the value being the voucher code itself.

You can check for valid voucher codes using validateVoucher action

You can apply a voucher code by adding it to the qoutePrices and booking requests

Note: Only the special offer, which will lead to the lowest price will be applied. Since these voucher restricted special offers, follow the same logic, they may not be applied if another special offer would result in a lower price.

Die Buchungsstrecke kann um eine optionale Reiserücktrittskostenversicherung erweitert werden: 

Abfrage, ob travelInsurance unterstützt wird

Zunächst wird über einen zusätzlichen Parameter in der API Funktion quotePrices abgefragt, ob die Agentur eine Versicherungsleistung anbieten will/kann.

Abfrage der Pläne

Ist die Unterstützung der Reiserücktrittversicherung konfiguriert, kann unmittelbar ein zweiter API Request mit der  Funktion getTravelInsurancePlans abgesetzt werden. Dieser Request baut eine Verbindung von vOffice zu dem Server der Versicherung auf, um die möglichen Versicherungspläne abzufragen.

Achtung: dieser Request kann etwas dauern. Daher ist zu überlegen, ob der Request asynchron erfolgt.

Das Rückgabeergebnis von getTravelInsurancePlans enthält verschiedene Pläne (in der Regel zwei), die jeweils einen Tarifcode und weitere Angaben enthalten. 

Der Gast kann nur einen Plan aus der Auswahl buchen- oder eben auch gar keinen Plan.

Auf der Buchungsseite

Wir empfehlen eine separate Box mit folgenden Optionen: 

• Kein Versicherungsschutz (voreingestellt)

• Reiserücktrittsversicherung

• Reiserücktrittsversicherung inkl. Reise-Abbruch-Versicherung

Die Angebote müssen folgende Angaben enthalten: 

• Anzeige des ausgewählten Plans: Bezeichnung, Tarifcode (optional), Preis
• Anzeige der Links zu den folgenden Unterlagen: 
  •  Versicherungsbedingungen
  •  Informationsblatte zu Versicherungsprodukten gemäß §7 VVG (Variante exkl. Reiseabbruch)
  •  Informationsblatte zu Versicherungsprodukten gemäß §7 VVG (Variante inkl. Reiseabbruch)
  •  Widerrufsbelehrung und Datenschutzinformationen (BDSG, Code of Conduct)

Wenn eine der Versicherungen ausgewählt wird, müssen vor Bestätigung der Buchung durch den Gast die rechtlich vorgegebenen Dokumente abgerufen worden sein, d.h. erst danach darf die Schaltfläche “Buchen” nutzbar sein. Dies kann beispielsweise durch das Öffnen des Dokuments in einem separaten Tab geschehen oder die Option, das Dokument herunterzuladen. Die Umsetzung sollte so erfolgen, dass die Conversion möglichst wenig beeinträchtigt wird. 

Vor Anfrage der Versicherung unbedingt prüfen, ob sich die Reisesumme durch Ergänzung oder Reduktion optionaler Leistungen verändert hat, sonst kann es zu Fehlern kommen, weil der angefragte Tarif nicht mehr zur Buchungssumme passt.

Wir empfehlen, sich von vOffice ein paar aktuelle Referenz-Seiten nennen zu lassen um sich einen Eindruck von der Umsetzung machen zu können. 

Nach der Buchung 

Um den Abschluss der eigentlichen Buchung nicht zu gefährden, wird im Anschluss an den API Aufruf book die Versicherung gebucht. Dieser Buchungsvorgang ist mehrstufig.

Im ersten Schritt wird die Buchung der Versicherung "angekündigt". Die Versicherung antwortet mit einer PolicyId und einer URL, die der Gast zum Bezahlen aufrufen muss. Bezahlt werden kann per Kreditkarte und Lastschrift. Die Versicherung wird erst gültig, wenn die Bezahlung erfolgt ist.

Auf der Buchungsbestätigungseite

Nach erfolgter Buchung der Reise sollte dem Gast eine Buchungsbestätigung angezeigt werden. Darüber hinaus sollte darauf verwiesen werden, dass der Versicherungsschutz erst mit Bezahlung der Prämie gesichert ist. Hierzu wird in x Sekunden auf die Bezahlseite der URV weitergeleitet. 

Sollte die Bezahlung scheitern, kann sie unter Wahrung gewisser Fristen unter demselben Link nachgeholt werden.

Die URL, die zur Bezahlseite der Versicherung führt, kann nicht in einem iframe aufgerufen werden!

Erst wenn der Gast die Versicherung bezahlt hat, ist sie gültig. Nach der Bezahlung der Versicherung erhält der Gast von der URV eine Bestätigungsmail, in der nochmal alle Details aufgeführt sind, im Anhang sind u.a. die Versicherungsbedingungen.

Einschränkungen

Keine Versicherung bei “Anfrage” oder  “Option” 

Es hat keinen Sinn, bei einer Anfrage oder der unverbindlichen Reservierung einer Option eine Versicherung zu buchen. Denn dann hätte der Gast schon eine Versicherung gebucht, ohne überhaupt eine Reise gebucht zu haben.
Daher sollte bei Anfragen oder Optionen keine Versicherung in der Buchungsstrecke mit angeboten werden. Die Versicherung kann immer noch im Nachgang bei fester Buchung dazugebucht werden (z.B. über die Gäste-App).

Ausnahme: Wenn für Buchungen innerhalb einer bestimmten Frist vor Anreise die Zahlung per Online-Payment vorgesehen ist, werden solche Buchungen zunächst als Belegung mit Status “Angebot” in vOffice angelegt. Erst nach Bestätigung des Zahlungseingangs durch Stripe kann der Status in “Bestätigt” gewandelt werden. (Dies kann automatisiert oder manuell erfolgen). In diesen Fällen darf eine Versicherung mit angeboten werden, da ja eine unmittelbare Buchungsabsicht besteht.

Ausschluss von Gästen mit Haupt-Wohnsitz im Ausland

Gemäß § 2 Abs. 1 der Allgemeinen Bedingungen kann nur Versicherungsnehmer “sein, wer seinen ständigen Wohnsitz in der Bundesrepublik Deutschland hat.”
Daher darf die Versicherung nur angeboten werden, wenn in der Maske der Adressdaten des Gastes kein anderes Land als Deutschland eingetragen wurde.

Die Reiserücktritts-Versicherung kann auch im Anschluss an die eigentliche Buchung oder später gebucht werden, z.B. im Rahmen einer Gästeapp.

Bedingungen

Die Versicherung kann bis 30 Tage vor Anreise gebucht werden, oder wenn die Reise weniger als 30 Tage vor der Anreise gebucht wird, innerhalb von zwei Werktagen nach Buchung der Reise. Diese Bedingungen werden von der Versicherungsagentur (URV) vorgegeben.

Die Buchung der Versicherung wird erst mit der Bezahlung der Versicherung gültig. Bezahlt werden kann die Versicherung über den Link, der in paymentUrl zurückgegeben wird, oder über die vOffice Gästeapp.

bookTravelInsurancePlan

Action name: bookTravelInsurancePlan

Fields in the json-encoded "data" parameter:

Das Feld forceTravelInsuranceTarget kann auf 'test' gesetzt werden, auch wenn die Agentur schon im Live Betrieb ist. In diesem Falle wird gegen das Testsystem der URV gebucht.

Das Feld forceTravelInsuranceBookingMode kann auf 'test' gesetzt werden, auch wenn die Agentur schon im Live Betrieb ist. In diesem Falle wird gegen das Produktiv System der URV gebucht, die Buchung aber als Textbuchung markiert.

Sample request

{
    "debug": 1,
    "bookingId": {{bookingId}},
    "plan": {
        "planid": "{{planId}}",   // muss zum Reisepreis passen
        "amount": {{planAmount}}
    },
    "forceTravelInsuranceTarget": "{{forceTravelInsuranceTarget}}",      // force test or production
    "forceTravelInsuranceBookingMode": "{{forceTravelInsuranceBookingMode}}"

}

Response sections

Sample result (success)

{
    "trackingId": "i-0703ff64e73c6165a|3adab145-db39-437f-9cf9-fc0d5aab18ca",
    "ok": true,
    "travelInsurance": {
        "id": 299,
        "policyid": "109003990",
        "target": "test",
        "mode": "test",
        "paymentUrl": "https://urvibetest.it-auf-abruf.de/public/paymentLink.do?token=pPudIDsHLx5iTkEBHOt3p8oDzMWk2kDXenLu62b0fxorIa6ElKQmKjKOURLHQrlp",
        "planid": "RR03",
        "amount": 2700,
        "booked": "2022-08-27T15:07:13Z",
        "changed": "2022-08-27T15:07:14Z",
        "status": "BOOKED",
        "status_payment": "UNKNOWN",
        "errortext": "OK",
        "bookingTotal": 49400,
        "tarifLimit": 50000
    },
    "status": 200,
    "transactionIdentifier": "voffice-2515-11024329-2022-08-27 15:07:13.818"
}

Sample result (error)

{
    "trackingId": "i-0703ff64e73c6165a|13f8c6d3-6b66-4a58-970e-65f932c91702",
    "ok": false,
    "travelInsurance": {
        "id": 291,
        "target": "test",
        "mode": "test",
        "planid": "RR03",
        "amount": 2700,
        "booked": "2022-08-27T11:52:25Z",
        "status": "BOOKEDERROR",
        "status_payment": "UNKNOWN",
        "errortext": "[0:[code:1, type:1, text:Das gewählte Produkt passt nicht zu den von Ihnen angegebenen Reiseinformationen!]]"
    },
    "status": 200,
    "text": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<OTA_InsuranceBookRS Version=\"1.0\" TransactionIdentifier=\"voffice-2515-9470258-2022-08-27 11:52:25.019\" TimeStamp=\"2022-08-27T13:52:25.287+02:00\" Target=\"Test\">\n    <Warnings>\n        <Warning Type=\"1\" ShortText=\"Das gewählte Produkt passt nicht zu den von Ihnen angegebenen Reiseinformationen!\" Code=\"1\"/>\n    </Warnings>\n</OTA_InsuranceBookRS>\n<!-- 200 [0:[code:1, type:1, text:Das gewählte Produkt passt nicht zu den von Ihnen angegebenen Reiseinformationen!]] -->",
    "rq": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<OTA_InsuranceBookRQ PrimaryLangID=\"de\" Target=\"Test\" TimeStamp=\"2022-08-27T11:52:25\" TransactionIdentifier=\"voffice-2515-9470258-2022-08-27 11:52:25.019\" Version=\"1.0\">\n  <POS>\n    <Source AgentDutyCode=\"464\" ISOCountry=\"DE\" ISOCurrency=\"EUR\">\n      <RequestorID ID=\"50000082\" ID_Context=\"KID\" MessagePassword=\"2-gh5jHABSpf\" Type=\"13\" URL=\"\">\n        <CompanyName CompanyShortName=\"vOffice\" TravelSector=\"6\">vOffice GmbH</CompanyName>\n      </RequestorID>\n    </Source>\n  </POS>\n  <PlanForBookRQ Name=\"\" PlanID=\"RR03\">\n    <CoveredTravelers>\n      <CoveredTraveler>\n        <CoveredPerson Age=\"42\" BirthDate=\"1900-01-01\">\n          <NamePrefix>Herr</NamePrefix>\n          <GivenName>Test</GivenName>\n          <Surname>vOffice</Surname>\n        </CoveredPerson>\n        <IndCoverageReqs>\n          <IndTripCost Amount=\"0\" CurrencyCode=\"EUR\" />\n        </IndCoverageReqs>\n      </CoveredTraveler>\n      <CoveredTraveler>\n        <CoveredPerson Age=\"42\" BirthDate=\"1900-01-01\">\n          <NamePrefix>Familie</NamePrefix>\n          <GivenName>2.</GivenName>\n          <Surname>Reiseteilnehmer</Surname>\n        </CoveredPerson>\n        <IndCoverageReqs>\n          <IndTripCost Amount=\"0\" CurrencyCode=\"EUR\" />\n        </IndCoverageReqs>\n      </CoveredTraveler>\n      <CoveredTraveler>\n        <CoveredPerson Age=\"12\" BirthDate=\"1900-01-01\">\n          <NamePrefix>Familie</NamePrefix>\n          <GivenName>3.</GivenName>\n          <Surname>Reiseteilnehmer</Surname>\n        </CoveredPerson>\n        <IndCoverageReqs>\n          <IndTripCost Amount=\"0\" CurrencyCode=\"EUR\" />\n        </IndCoverageReqs>\n      </CoveredTraveler>\n    </CoveredTravelers>\n    <InsCoverageDetail EffectiveDate=\"2023-01-30\" ExpireDate=\"2023-02-04\">\n      <CoverageRequirements>\n        <CoverageRequirement CoverageType=\"4\" EffectiveDate=\"2023-01-30\" ExpireDate=\"2023-02-04\" />\n      </CoverageRequirements>\n      <TotalTripQuantity Quantity=\"1\" />\n      <TotalTripCost Amount=\"0\" CurrencyCode=\"EUR\" />\n      <CoveredTrips>\n        <CoveredTrip End=\"2023-02-04\" Start=\"2023-01-30\">\n          <Destinations>\n            <Destination ArrivalDate=\"2023-01-30\" DepartureDate=\"2023-02-04\" Type=\"4\">\n              <CountryName Code=\"DE\">Germany</CountryName>\n            </Destination>\n          </Destinations>\n          <Operators>\n            <Operator CompanyShortName=\"ABC\" TravelSector=\"6\">ABC GmbH</Operator>\n          </Operators>\n        </CoveredTrip>\n      </CoveredTrips>\n    </InsCoverageDetail>\n    <InsuranceCustomer Gender=\"\" ID=\"5259900\">\n      <PersonName>\n        <NamePrefix>Herr</NamePrefix>\n        <GivenName>Test</GivenName>\n        <Surname>vOffice</Surname>\n      </PersonName>\n      <Telephone CountryAccessCode=\"49\" PhoneLocationType=\"6\" PhoneNumber=\"+49192277363535356\" />\n      <Email>info@v-office.com</Email>\n      <Address>\n        <StreetNmbr PO_Box=\"\">Am Holm 25</StreetNmbr>\n        <BldgRoom />\n        <CityName>Neustadt in Holstein</CityName>\n        <PostalCode>23730</PostalCode>\n        <CountryName Code=\"DE\">DE</CountryName>\n      </Address>\n      <PaymentForm>\n        <PaymentLink>\n          <NotifyUrl>https://juergen.v-office.com/if/travelInsurancePaymentCallback?id=291&amp;bid=9470258</NotifyUrl>\n        </PaymentLink>\n      </PaymentForm>\n    </InsuranceCustomer>\n    <PlanCost Amount=\"32\" CurrencyCode=\"\" />\n  </PlanForBookRQ>\n</OTA_InsuranceBookRQ>",
    "rs": {},
    "transactionIdentifier": "voffice-2515-9470258-2022-08-27 11:52:25.019"
}

Eine Versicherung kann im Rahmen des 14 tägigen Widerrufsrechtes storniert werden, wenn die Buchung der Versicherung nicht länger als 14 Tage zurückliegt.

Action name: cancelTravelInsurance

cancelReasonId

    1 - Reise vom Veranstalter abgesagt
    2 - Reiseumbuchung - deshalb neuer Vertrag bei URV
    3 - Reise bereits vorher anderweitig versichert
    4 - Storno Reiserücktritt wg. Umwandlung in Paket inkl. Reiserücktritt (neuer Vertrag)
    5 - Kunde widerruft innerhalb Frist von 14 Tagen
 

Sample request

{
    "debug": 0,
    "bookingId": 12456789,
    "cancelReasonId": 5,            // 5: cancellation within 14 days after booking  
    "forceTravelInsuranceTarget": "test"    
 
}