Use Case Description
The “Service combinations” feature needs to be enabled for the possibility of booking an appointment with several services inside via API. (Accounts & Systems - System Settings - Service combinations toggle). Otherwise, the system will not accept appointments with more than one service selected.
Service combinations need to be configured before using the endpoints, otherwise endpoints will return an error. Please follow the User Guide for the details.
To book an appointment with multiple services the API client needs to perform multiple interactions with the API. Most of the interactions are similar to “Book an appointment“, but /external/v1/serviceCombination/ API calls should be used. In general, the flow consists of the following steps:
Retrieve the list of combinable, uncombinable, and combined services for each branch.
Please, note! Service combinations are configured on the branch level so there is no possibility of retrieving the list of combinations without specifying the Branch ID.
Retrieve the list of available service combinations (combinable, uncombinable, combined) for the specific branch ID
Get time slots for the combined services and branch ID
Reserve a time slot for the appointment with more than 1 service included
Confirm a booking with multiple services
API endpoints
Service Combinations
GET /external/v1/serviceCombination/branch
Allows to retrieve the list of combinable, uncombinable services and combined services grouped by service type for each branch.
Combinable services - the services that can theoretically be combined but were not configured so an attempt to book an appointment with these services will return an error. Configurations should be changed to enable making appointments with these services combined.
Uncombinable services - the services that cannot be combined within one single appointment.
Combined Services - the services are configured as combined so can be selected and booked in one single appointment.
Attributes
Name | Type | Required | Description |
|---|---|---|---|
X-TENANT-ID | string | yes | The tenant id to use for this operation. The tenant id must be the same as an existing system Id. |
Response schema
[
{
"branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"serviceCombinations": [
{
"resourceTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"combinableServices": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"unCombinableServices": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"combinedServices": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
]
}
]
Service combinations per Branch ID
Allows to retrieve the list of combinable, uncombinable and combined services for the specific Branch.
Listing
GET /external/v1/serviceCombination/branch/{branchId}
Response schema
Note! It is impossible to get the list of combinable services without the Branch ID specified since combinations can differ depending on the branch.
Attributes
Name | Type | Required | Description |
|---|---|---|---|
Branch ID | string | yes | The Branch id (GUID), ex. |
X-TENANT-ID | string | yes | The tenant id to use for this operation. The tenant id must be the same as an existing system Id. |
Listing
GET /external/v1/serviceCombination/branch/{branchId}
Response schema
[
{
"resourceTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
],
"combinedServices": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
]
where
"combinedServices" the service IDs that are marked as “combinable“ in Configurations, so can be combined within one appointment.
Timeslots
GET /external/v1/serviceCombination/branch/{serviceId}/timeslots
Allows retrieving the timeslots for service combinations (combined services) according to service combination configurations in the case when the feature is enabled.
Attributes
Name | Type | Required | Description |
|---|---|---|---|
Service IDs | strings | yes | The service ID to get the list of timeslots. Several “combined” service IDs can be specified |
Branch ID | string | yes | The Branch id, ex. |
requestedResourceID | string | no | The resource ID for the services selected |
numberofReservations | integer | no | The total number of reservations for all services included in the appointment (for instance, if the number for service 1 is 1 but for service 2 is specified as 2 then the value that should be specified is 3) The default value is 1. |
X-TENANT-ID | string | yes | The tenant id to use for this operation. The tenant id must be the same as an existing system Id. |
Only services related to one branch can be combined within one appointment. In case the service combination is invalid - the error will be returned.
Number of reservations (Number of people) for each service should be specified separately.
Listing
GET /external/v1/serviceCombination/branch/{serviceId}/timeslots
Response schema
Note! The service ID with the longest duration will be returned in the response but all the services selected by the customer for the appointment will be taken into account for the list of available timeslots exposure.
{
"serviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timeSlots": [
{
"startTime": "2022-03-03T09:00:00+01:00",
"endTime": "2022-03-03T09:00:00+01:00"
}
]
}
Create an appointment reservation
POST /external/v1/serviceCombination/reservations
Allows to create a new reservation with several combined services in one appointment.
The timeslot must be in the future to create a reservation.
Attributes
Name | Type | Required | Description |
|---|---|---|---|
Accept - Language | string | yes | Requested language for service names. The system will support languages depending on Tenant Localization settings (possible values are: en_US, en_UK, fr_FR, nl_NL, de_DE, it_IT, ES_es ) |
X-TENANT-ID | string | yes | The tenant id to use for this operation. The tenant id must be the same as an existing system Id. |
When two services are passed, the reservation “number of reservations“ should be specified for each service separately. The value corresponds to the number of people for each service/amount of services.
Request Body
{
"serviceWithNrOfReservationsValues": [
{
"serviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nrOfReservations": 0
}
],
"branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestedResource": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timeSlot": {
"startTime": "2022-03-03T09:00:00+01:00",
"endTime": "2022-03-03T09:00:00+01:00"
}
}
Several service IDs can be passed, but the services should be “combined“. “Requested resource“ parameter is optional.
“nrOfReservations” number of people/services selected for the appointment. Should be specified for each service included in the appointment. The value should be valid for the service specified according to configurations.
Listing
POST /external/v1/serviceCombination/reservations
Response
{
"appointmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"serviceWithNrOfReservationsValues": [
{
"serviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nrOfReservations": 0
}
],
"branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestedResource": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timeSlot": {
"startTime": "2022-03-03T09:00:00+01:00",
"endTime": "2022-03-03T09:00:00+01:00"
},
"expiration": "2024-07-05T16:08:17.748Z",
"reservationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Confirm Appointment with multiple services
PUT /external/v1/serviceCombination/reservations/{reservationId}
Allows to confirm a reservation created with several combined services.
Note! The following additional things should be taken into account for getting a successful response:
The timeslot should not be in the future (a reservation cannot be confirmed for the timeslot in the past).
The timeslot should not expire, no more than 15 minutes can pass from the time the reservation was created. The reservation will be automatically canceled/removed in case if the confirmation is not received within 15 minutes.
Attributes
Name | Type | Required | Description |
|---|---|---|---|
Accept - Language | string | yes | Requested language for service names. The system will support languages depending on Tenant Localization settings (possible values are: en_US, en_UK, fr_FR, nl_NL, de_DE, it_IT, ES_es ) |
X-TENANT-ID | string | yes | The tenant id to use for this operation. The tenant id must be the same as an existing system Id. |
reservationID | string | yes | Reservation ID to be confirmed by customer’s data |
Request Body
{
"customerInfo": {
"personalIdentifier": "Ptv35MQYuQIfKulVi8oEAQjv0MvJ7QBLYCbS0Ot",
"firstName": "al{w.",
"lastName": "ll-",
"phoneNumber": "}DD{{ti }+-igp{}p{i}ptg{gt+ tpitg{g-tD{+t+D++pt{",
"email": "string",
"dateOfBirth": "2000-01-01"
},
"informationQuestions": [
{
"question": "string",
"answer": "string"
}
],
"supportNotes": "string"
}“
where
“PersonalIdentifier“ is the external customer’s identifier.
Must contain 10-48 char and must match A-Za-z0-9
Response Body
{
"appointmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timeSlot": {
"startTime": "2022-03-03T09:00:00+01:00",
"endTime": "2022-03-03T09:00:00+01:00"
},
"customer": {
"firstName": "LttnbygDy{tbryt{It-Dc}'n'pwlnel{ni.nlae.}a'",
"lastName": "lrI} Dcbw'gC-H}sDIeH H arD{sc'{yCCia {}tpDs}'ppprwyiL Ilgepe anL-IHs}ppwycLi",
"phoneNumber": "{t",
"email": "string",
"dateOfBirth": "2000-01-01"
},
"service": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"config": {
"maxNumberOfReservations": 0
}
},
"branch": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"address": {
"streetName": "string",
"zipCode": "string",
"city": "string",
"country": "string"
},
"location": {
"longitude": 180,
"latitude": 180
}
},
"numberOfReservations": 0,
"supportNotes": "string"
}
0 Comments