pbb RESTful API V1
DOCUMENTATION (BETA Build 2022-02-24 -001-)
Deutsches Wiki (in Arbeit) zur RESTful API finden Sie künftig hier
If you find any errors or have any suggestions please feel free to send them to development (at) pbbsoftware.de
Changelog:
2022-02-24 - timeslots now return an additional \'numAvailable'\ data field.
HTTP REQUESTS
Main Types
Returns all main types with JSon. Since all types are fixed, this request is interesting only because of the label of the types, but not necessary.
Fixed types are:
02 - Spa treatments
10 - Accommodations
20 - Articles
25 - Gastronomy items
30 - Package arrangements
35 - Vouchers.
Best practice: Use them as constants.
Categories / Groups / Subgroups
Service items are sorted into three layers. Categories => groups => subgroups.
Returns all categories with JSon. Categories are not connected to any type. This request delivers all top level categories. Each category consists of groups, which in turn contain subgroups (optional) and only then do the service items emerge which are linked to a special type of service.Returns all categories for TYPE {type} with JSon. (Obsolte, since Types and Categories aren't necessarily connected to each other anymore)Service items
Returns all service items at once with JSon.Most data fields are self explaining. Here a list of the most important:
svValidForSale : If TRUE this service item is meant to be sold with mobile apps or in an online shop. There are some service items which are not. For example: breakfast without an accommodation (this is treated as an addon).
svValidForVoucher : Information if this service item may be sold on a spa voucher.
svReservationRequest : The customer can make a manual appointment request.
svReservationNeeded : An online reservation OR a manual appointment (if allowed) request is needed.
svStockLockUp : Reserved. Intended in future versions.
svIsAddon : This service item is an addon and must not be sold as a stand alone service item.
Returns a service with ID {id} with JSon. The response includes available media, addons, single items and vats in case of an arrangement (package).Example for an accommodation with addons. For example breakfast or cleaning services. Those are returned in an extra array: GET /v1/services/{id}. Details on an addon then can be requested with GET /v1/services/{addonId}.
Example for a package arrangement. The single items are returned in an extra array: GET /v1/services/{id}.
'package': {
'items': [ ... ]}
Please note: A package sometimes contains service items with different VAT rates. Those are delivered in an extra array [vats] with fixed amounts and associated rates. The point is that they can not be or are not allowed to be calucalted by the mobile app or the online shop.
Return all services of TYPE {type} with JSon.Returns all services filtered with TYPE and optional category (cat), group (group) and/or subgroup (sub) with JSon. {subgropup} are optional. Mainly we do have three levels into which service items can be sorted. Future versions allow service items to be sorted in to more than one category / group / subgroup. Example for the Category K (Wellness & Beauty) and the group K2 (single treatments): GET /v1/services/K/K2/ How categories, groups and subgroups are named is in the hand of the customer.Media represents all resources like pictures, videos or text for a specific service.
Note that media are not necessesarily needed to be requested as they are returned with the response of a single service item.Returns ALL media with JSon.Returns all media for the Service with ID {serviceId} with JSon.Timeslots
If you have to make a reservation the following steps have to be done:
1. Step: Ask for open timeslots for the desired service item (via GET timeslots). Important: In some cases there is a special price for a timeslot which you should sell the customer. Those special prices are sent within the response for the open timeslots.
2. Step: Remember the timeslotIds.
3. Step: When the customer has choosen his timeslot, block this timeslot with the associated (and remembered) timeslotId (via PUT timeslots and the action block).
This slot will be automatically released after a certain amount of time when no final booking has been done. You may want to refresh or release (cancel ) this timeslotId.
4. Step: the already blocked timeslotId must be sent with the final booking.First option:
GET free timeslots for the specfic Date (YYYY/MM/DD) and Service Id (svId) between timeFrom and timeTo. If there is a special price at a free time, this is given in the specialPrice field (otherwise -1).Second option (new):
GET free timeslots for the specfic service Id (svId) between given dateFrom and given dateTo, timeFrom and timeTo. The parameters timeFrom and timeTo apply to every single day that is requested. If you leave them empty, the request assumes 00:00 until 23:59:59. If there is a special price at a free time, this is given in the specialPrice field (otherwise -1).Params:
svId => service Id for which you want to receive free timeslotstimeFrom (hh:mm) & timeTo (hh:mm)- Second option only:
datefrom (YYYY/mm/dd) & dateTo (YYYY/mm/dd)
. Only the second option allowes the request for more than one day and will be limited to approx. seven days.Block, Cancel or Refresh a timeslot for a service Id with the timeslotId {timeslotId} which you received before. The response now contains validUntilDate & validUntilTime. After this the timeslot will be automatically released.Please use POSTMAN or a similiar client software for testing this.
Slots
This request concerns only accommodations. or GET free slosts with JSon from dateFrom to dateTo or(!) plus x nights and optional a specfic category. Maximum days for a request is 60.Params:
dateFrom: Starting date for the request. For example the desired check-in date.
dateTo or nights: The last day for which the room occupancy is needed or the number of total nights for which you take the request. A maximum of 60 days/nights is allowed.
category: Optional you can take the request for a specific category of the accommodations. This option may change in future versions.
With the response you receive the status for each requested day/night. 1 means the room/appartment with the objectId is free, 0 it isn`t.Block, Cancel or Refresh the range of slots between dateFrom and dateTo for the object [objectId].
(We will implement this between November, 09 and 12, 2020)Orders
Send a finished and paid order to our system. The body must contain the required data. {orderId} is the new resource, this id you may freely assign.
Structure of the data to be transferred:
[customer] with blowfish encrypted: custId, custTitle, custSalutation, custLastName, custFirstName, custStreet, custPostalCode, custCity, custCountry, custPhone, custMobile, custFax, custEMail, custBirthday, custNewsletter (true/false), custProspectus (true/false)
[accompagnions] (coming soon)
[items] : Every item is an array for itself containing: orderItemId (same as svId), orderQuantity, orderUnitPrice, orderDiscount, offerId (if this item is part of an offer). If there are one ore more confirmed (see timeslosts) reservations there must be an extra array named [reservations] containing every reservationId
[vouchers] : Every spa voucher contains an array [items] with a sub array for every [item] which belongs to the voucher.
Example for a spa voucher for two treatments, one treatment with the quantitiy of two.{
"vouchers": [
{
"voucherSvId": "300001 / 300005",
"voucherId": "01-BST00M0J0W",
"voucherRecipient": "William Gates",
"voucherValue": "105.00",
"voucherItems":
[
{
"voucherItemId": "4400002",
"voucherItemQuantity": "2",
"voucherItemValue": "60.00"
},
{
"voucherItemId": "4400004",
"voucherItemQuantity": "1",
"voucherItemValue": "45.00"
}
]
}
]
}
Offers
Offers will be implemented after the release of the beta of our API.VATS
VATS represents Value Added Taxes and rates for a specific service Id. This is an important resource for the package arrangements. Mostly this is an array which is delivered with the request for a single service item in case that the services item is a package arrangement or when more than one tax rates are included in one price. Check if the response of your request has this included. Single requests to this resource are rarely needed. But possible.Returns ALL Vat rates included for the requested service item with the id {id}.Vouchers
Mostly there are two types of vouchers, monetary vouchers (which are easy to implement) and spa vouchers. Spa vouchers can contain at least one but also more single service items. Service items which you are allowed to offer for a spa voucher do have the flag >svValidForVoucher (service item response).Every voucher has an unique Id which should be requested before (!) the payment has be done.
Please use POSTMAN or a similiar client software for testing this. For the moment you will receive a random id for testing purposes until the API goes live.
Logins (Authentification-Authorization)