API - Appointment REST

Short descriptions

Representational State Transfer (REST) is a software architecture style consisting of guidelines and best practices for creating scalable web services. REST is a coordinated set of constraints applied to the design of components in a distributed hypermedia system that can lead to a more performant and maintainable architecture.

Thanks to this API – if you embed it – your system is going to be able to handle appointment from any mobile device and other desktop application (OS independent). This documentation will guide you through the APIs structure and will help you understand the background info.

Appointment REST methods

Get languages

The system handled languages in alphabetical order. The method hasn’t got parameter.

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/getLanguages

Answer sample:

[
    {
        "id": "1",
        "name": "English",
        "code": "en-GB"
    },
    {
        "id": "2",
        "name": "Magyar",
        "code": "hu"
    }
]

Get services

Query the list of services in alphabetical order.

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/getTasks/<languageID>

Necessary parameters:

languageID: Code of the language, which we can get with the previous method.
Sample query:

http://localhost:3000/qnet6/rest/getTasks/1

Answer sample:

[
    {
        "id": "1",
        "name": "Service 1"
    }
]

Get branches

Query the list of branches where the task (service) can be served. The list of branches can be refined with the “search” field where you can predefine by name of address.

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/getBranches/<taskID>/<languageID>/<longitude>/<latitude>/<search>/<sort>

Necessary parameters:

taskID: Task ID.
longitude: geographic longitude (or “-1” if not identifiable ).
latitude: geographic latitude (or “-1” if not identifiable).
search: search field (or “-1” if no refine ).
sort: View mode of the list. Options can be:
0 – By the name of the branch in alphanumeric order
1 – By the number of the waiting clients in ascending order
2 – By GPS Location (nearest id the first)
3 – By waiting time in ascending order

Query sample:

http://localhost:3000/qnet6/rest/appointment/getBranches/1/1/-1/-1/-1/0

Answer sample:

[
    {
        "short": "DEFAULT",
        "id": "1",
        "zip": "",
        "distance": "157",
        "seconds": "0",
        "name": "Default branch",
        "address1": "",
        "address2": "",
        "address3": "",
        "tickets": "0"
    }
]

Where “distance” is the distance of the branch to the client’s actual position, “seconds” is the actual waiting time in the branch, “tickets” is the number of currently waiting clients – for the selected service,

Get available timeslots

Returns with a list of available timeslots in the „ScheduleEvent” block between two given time points. TaskID is the selected service ID and it is mandatory. Branch ID is also mandatory.
URL sample:
http://yourserverhost:[http-port]/qnet6/rest/appointment/getEmptyTimes/<begin>/<end>/<branchID>/<taskID>
Necessary parameters:

begin: start of the query province (14 character long timestamp) *
stop: end of the query province (14 character long timestamp) *
branchID: ID of the branch
taskID: ID of the service

The timestamp needs to be given in a 14 character long format: year-month-day-hour-minute-second. I.e.: “20150203145300”

Query sample:

http://localhost:3000/qnet6/rest/appointment/getEmptyTimes/20150101010000/20150108010000/1/1

Answer sample:

[
    {
        "available": "0",
        "end": "20150105003000",
        "begin": "20150105000000"
    },
    {
        "available": "0",
        "end": "20150105010000",
        "begin": "20150105003000"
    },
    {
        "available": "0",
        "end": "20150105013000",
        "begin": "20150105010000"
    },
    {
        "available": "0",
        "end": "20150105020000",
        "begin": "20150105013000"
    },
    {
        "available": "0",
        "end": "20150105023000",
        "begin": "20150105020000"
    }
]

Get time intervals between two given time points

Returns with the list of time intervals between two given time points.

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/getReservedTimes/<begin>/<end>/<branchID>/<taskID>

Necessary parameters:

begin: start of the query province (14 character long timestamp) *
stop: end of the query province (14 character long timestamp) *
branchID: ID of the branch
taskID: ID of the task

The timestamp needs to be given in a 14 character long format: year-month-day-hour-minute-second. I.e.: “20150203145300”

Query sample:

http://localhost:3000/qnet6/rest/appointment/getReservedTimes/201506020010000/20150625010000/1/1

Answer sample:

[
    {
        "available": "77",
        "end": "20150623113000",
        "begin": "20150623110000"
    },
    {
        "available": "39",
        "end": "20150623170000",
        "begin": "20150623163000"
    },
    {
        "available": "31",
        "end": "20150623200000",
        "begin": "20150623193000"
    }
]

Save customer details

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/saveCustomerData/<name>/<email>/<phone>

Necessary parameters:

name: name of customer.
email: e-mai of customer.
phone: phone number of customer.
The functions returning value is the “customerID”.

Query sample:

http://localhost:3000/qnet6/rest/appointment/saveCustomerData/tester+bill/[email protected]/+513652363422

Answer sample:

4
(customerID)

Reserving a time slot

Reserve a given time slot. The system can modify the time of reservation or the length of it. The functions returning value is the reservation code.

URL sample with confirmation:
http://yourserverhost:[http-port]/qnet6/rest/appointment/addReservation/<begin>/<end>/<languageID>/<branchID>/<taskID>/<customerID>

Query sample with confirmation. Customer will get a confirmation email in order to finalize his/her reservation:

http://localhost:3000/qnet6/rest/appointment/addReservation/20150105000000/20150105003000/1/1/1/4

URL sample without confirmation:
http://yourserverhost:[http-port]/qnet6/rest/appointment/addReservation/<begin>/<end>/<languageID>/<branchID>/<taskID>/<customerID>?noConfirm=1

Query sample without confirmation. The status automatically turns into ‘Confirmed’, no email sent:

http://localhost:3000/qnet6/rest/appointment/addReservation/20150105000000/20150105003000/1/1/1/4?noConfirm=1

Necessary parameters:

begin: Start of the reservation (14 character long timestamp). *
end: end of the reservation (14 character long timestamp). *
languageID: customers selected language
branchID: ID of the branch
taskID: ID of the service
customerID: customers unique ID
The “customerID” parameter can be created with the “saveCustomerData” function – see point 7.

The timestamp needs to be given in a 14 character long format: year-month-day-hour-minute-second. I.e.: “20150203145300”

Answer sample:

5167

The system sends e-mail with booking code and confirmation link

Get Confirmation code

Get the confirmation code connected to a booking code. It is needed for finalizing a reservation and for deleting a reservation.

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/getConfirmationCode/<bookingCode>

Necessary parameters:

bookingCode: reservation ID

Query sample:

http://localhost:3000/qnet6/rest/appointment/getConfirmationCode/9212

Answer sample:

0000000k57wpn5k-k5dnfzpx-1tfq5jpphh-2z2z

Finalizing a reservation

Finalizes the reservation in the system. The functions returning value is true or false depending on the existing „bookingCode” .

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/confirmReservation/<bookingCode>/<confirmation>

Necessary parameters:

bookingCode: reservation ID.
confirmation: mailed verification code.
The returning value of the function is true or false. The answer is depending on the „bookingCode” if it exists or not. The return value is false if the code does not exist.

Query sample:

http://localhost:3000/qnet6/rest/appointment/confirmReservation/8634/0000000ib7x5avz-ib7xjvud-m1bqwbyek-1wf0r

Answer sample:

true

Deleting a reservation

Deletes the given „bookingCode” reservation.

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/deleteReservation/<bookingCode>/<confirmation>

Necessary parameters:

bookingCode: reservation ID.
confirmation: mailed verification code.

The returning value of the function is true or false. The answer is depending on the „bookingCode” if it exists or not. The return value is false if the code does not exist.

Query sample:

http://localhost:3000/qnet6/rest/appointment/deleteReservation/8634/0000000ib7x5avz-ib7xjvud-m1bqwbyek-1wf0r

Answer sample:

true

Getting task length

A given tasks available length. Queries the maximum time length of a given task. The functions returning value is the available time length of the given task in minutes.

URL sample:

http://yourserverhost:[http-port]/qnet6/rest/appointment/getTaskLength/<taskID>

Necessary parameters:

taskID: ID of the task.

Query sample:

http://localhost:3000/qnet6/rest/appointment/getTaskLength/1

Answer sample:

30

Flow chart

Using the Java REST API

Two independent workflow. One is preparing the appointment status while the other is saving the customer details. These two are necessary for a valid appointment.

Preparing the reservation:

Create Appserver

import com.qnet.appointment.*;
// Connection to the AppointmentServer
AppServer appServer = new AppServer("http://192.168.51.54:3000");

Select language

Get all languages

AppLanguage[] languages = appServer.getLanguages();

Select one language

AppLanguage selectedLanguage = languages[0];

Select task

Get all tasks/services of the specified language

AppTask[] tasks = appServer.getTasks(selectedLanguage);

Select one task/service

AppTask selectedTask = tasks[0];

Select branch

Get all branches of the specified language and task/service

AppBranch[] branches = appServer.getBranches(selectedTask, selectedLanguage);

Select one branch

AppBranch selectedBranch = branches[0];

Getting empty times

We will download all timeframes of the next 7 days

long oneWeek = 1000L * 60 * 60 * 24 * 7

Calculate begin and end times

Date begin = new Date();
Date end = new Date(begin.getTime() + oneWeek);

Download all timeframes

AppTimeFrame[] timeFrames = appServer.getEmptyTimes(begin, end, selectedBranch, selectedTask);

Select a timeframe

Select one timeframe

AppTimeFrame selectedTimeFrame = timeFrames[3];

Get the begin and end times of this timeframe

Date selectedBegin = selectedTimeFrame.getBegin();
Date selectedEnd = selectedTimeFrame.getEnd();

Save customer

Save personal data of the customer/client

long customerID = appServer.saveCustomer("Tom Smith", "[email protected]", "+55 555 5555");

Add reservation

IMPORTANT: At this point a CustomerID should have been created!!

Save appointment

String bookingCode = appServer.addReservation(selectedBegin, selectedEnd,
selectedLanguage, selectedBranch,selectedTask, customerID);

When bookingCode is not empty, your reservation is successful!

The system sends e-mail with booking code and confirmation link.

The template of the e-mail can be configured on the System Administration page:

Appointment v2 REST Ticket Advertisement REST

Getting Started

Architectures

Administration

Statistics (SH41)

Appointment (SH42)

Further modules

Devices

Maintenance

API

API - Appointment REST

Short descriptions

Appointment REST methods

Get languages

Get services

Get branches

Get available timeslots

Get time intervals between two given time points

Save customer details

Reserving a time slot

Get Confirmation code

Finalizing a reservation

Deleting a reservation

Getting task length

Flow chart

Using the Java REST API

Create Appserver

Select language

Select task

Select branch

Getting empty times

Select a timeframe

Save customer

Add reservation