Integrated appointment booking project

Use our appointment booking module !

In most cases, it is not necessary to use the API directly seeing as you already have a complete appointment booking module iframe or widget integration into your website. This module is fully customisable (colours, logo, appointment booking process) to match the identity of your website.

Specific need : where to start ?

If for any reason your need for integration is more specific and you can't use our integrated appointment booking module, you can familiarise yourself with the concepts of the section API REST and use the API described in this document to build your own appointment booking process.

Identify your process

Once you have mastered the principles of our API, build your own appointment booking workflow.

Important : the appointment booking process is customised for each group. The interfaces which allow the appointment booking of the group must comply with the specific settings of the appointment bookings of the group, in particular the attributes inactive, open, openData, calendarChoice, anyCalendar, validateEmail, display_intervention_length, display_intervention_price et max_multirdvs (see resource Group).

It is worth noting that your client will be authenticated with the profile Account, therefore you will have to consult the description of each resource, paying careful attention to the accessible read and written profile fields

A detailed example

Example remarks :

• the process applies in the context of a particular group (see resource Group), for example, we take the group with the id which is equal to 4.
• according to the value of the attribute calendarChoice of the group, we need to start by choosing a service or by choosing a calendar. Here, we choose for example calendarChoice == 2, the first step lets you select a service
• the services can be grouped or not grouped. Here, for example, we are selecting grouped services, we therefore need to start by listing the service categories, then list the services based on the chosen category

1 List the service categories

GET /api/v1/groups/4/interventionsets?apikey=xxxxxx

(see resource Interventionset)

Example : the customer chooses the category id = 9.

2 List the services in the chosen category

GET /api/v1/groups/4/interventions?apikey=xxxxxx&interventionset_id=9

(see resource Intervention)

Example : the client chooses the service id = 21.

3 List the calendars associated with the selected service

GET /api/v1/groups/4/calendars?apikey=xxxxxx&intervention_ids[]=21

(see resource Calendar)

Example : the client chooses the calendar id = 15.

4 List the availabilities

Example : we list the availabilities based on the chosen service and calendar, from 17th March 2014.

GET /api/v1/groups/4/availabletimeslots?apikey=xxxxxx&\
                intervention_ids[]=21&\
                calendar_id=15&\
                start=2014-03-17%2000:00:00

(see resource AvailableTimeSlots)

Example : the API shows an available time slot for March 17th, 2014 at 10:30am, which the customer chooses

5 Use an existing ClicRDV account / create a new ClicRDV account

The following steps need to be authenticated with the help of a ClicRDV account. The interface will then propose: to either create a ClicRDV account, or to login with an existing account. The resource to use to connect a client is Account (see also the basic principle of Authentication).

Example : the client is logged in with an existing ClicRDV account.

6 List the details associated with the client account

The account (Account) allows the user to login (with email/password) onto the appointment booking interface, but does not include other personal information such as their name,telephone number, address etc. The user (represented by their Account) must therefore have a Fiche, associated with the group, containing their details. A user (Account) can have multiple "fiches" for the same group if he books an appointment for different people. Common examples :

• Typical scenario : a person books a doctor’s appointment for herself
• A person can also book an appointment at their garage, this garage would require more information : vehicle registration, mileage, etc.
• A parent can book an appointment with a paediatrician for their children. The parent only has one ClicRDV account but has multiple "fiches" at the paediatrician.
• A secretary can take an appointment with access to all clients in the group

Retrieve existing records about the group for the authenticated account:

GET /api/v1/groups/4/fiches?apikey=xxxxxx

(see resource Fiche)

Example : the client already has a fiche with id = 48.

7 Create a new appointment

Example : the client books an appointment for the 17th March 2014 at 10:30am, and modifies his telephone number in doing so

The corresponding query is, assuming that the data is sent in JSON format (see Formats) :

POST /api/v1/groups/4/appointments.json?apikey=xxxxxx
{
  "appointment": {
    "date": "2016-01-18 10:30:00",
    "calendar_id": 15,
    "intervention_ids": [21],
    "comments": "",
    "fiche": {
      "id": 48,
      "group_id": 4,
      "firstphone": "06 12 34 56 78"
    }
  }
}

(see resource Appointment)

Please note : a typical alternative would be to create a new "fiche" with the new appointment (because the client does not have any records about this group, the request step 6 will have returned a blank reply). In this case, the major difference with regards to the query above is to not specify the "id" in the "fiche" object. A new "fiche" will be created with all the specified attributes (see resource Fiche for the list of attributes).

Other cases

There are numerous variants with regards to the example scenario proposed above, including : ungrouped services, process beginning with the selection of a calendar, a.s.o. See the workflow description of booking appointments to understand how these steps can be articulated, then the documentation for each resource to have more information.