Api - Smart Ticket REST

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 Smart Ticket feature 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.

You can read more about Smart Ticket feature here.

General Informations

At every API request it is neccessary to give an identifier for security reasons which provides the query to be insured by the Q-net server.
At requests that happens before ticket calls a ‘KEY’ hash parameter is needed at the URL as a variable. In order to generate a new ticket you will need a ‘KEY’ hash which is generated by the server. This hash contains a timestamp so the server only accepts those hash keys which were generated in the given timestamp.
This way the server can guarantee that one hash key can only be used once. This has is included in the Smart Ticket QR code.

Example

GET http://qnet-server:3000/qnet6/rest/smart/init?key=plTwVw86PjZ

When a ticket is requested or printed, then you can use the ticket parameter from the ticket indetifier insted of the key paramater. The ticket parameter must used as an URL variable.

GET http://qnet-server:3000/qnet6/rest/smart/init?ticket=6gTpJQ67Zmn

API test with Postman

You can try the below listed REST APIs with Postman Collection.

Postman collection
Right click “copy link” then at Postman “Import” and paste link.

Generate key hash (from >=6.7.15)

In some cases you might need to generate key hash in a different way. In case of QR code scanning on the ticket dispenser this API request is not neccessary because the QR code already includes this hash.

Request

GET /qnet6/rest/smart/generateHash/{branch}
Parameters
Name Type Description
branch Number Branch ID

Example

http://localhost:3000/qnet6/rest/smart/generateHash/1

Response: 200 OK

The returning values contains the generated key hash.

Fields
Name Type Description
key String Generated hash

 

Example
{
    "key": "plTwVw86PjZ"
}

Response: 400 Bad request

The branch indentifier does not exists or the Smart Ticket function is not enabled/configurated in this branch.

Get Smart Ticket settings

Query settings of the Smart Ticket.

Request

GET /qnet6/rest/smart/init?key={key}

or

GET /qnet6/rest/smart/init?ticket={ticket}

Parameters

The key or ticket hash is needed as an URL variable.

Example

http://localhost:3000/qnet6/rest/smart/init?key=plTwVw86PjZ

Response: 200 OK

The answer includes the configuration of the Smart Ticket settings stored in the server connected to the given branch. The branch ID is included in the submitted hash.

Fields
Name Type Description
cfProfile Number Feedback profile ID
cfTime Number Value in minutes which gives the timestamp when feedback operations can be made after the transaction.
publicUrl String Public URL address. In case of Smart Ticket proxy, the proxy’s address should be used.
dispProfile Number Ticket dispenser profile ID.
validTime Number Value in minutes which gives the timestamp of the generated key hash’s validity.
missingPutBackMins Number Value in minutes, which gives the timestamp when a ‘missing’ ticket is returned to the waiting list.
lngTexts Object Notification languages.
lngTexts{}.call String Call signal’s text language.
lngTexts{}.feedback String Customer feedback notification language.
Example
{
    "cfProfile": 1,
    "cfTime": 10,
    "publicUrl": "https://smart-ticket.awesome-company.com/qnet6",
    "dispProfile": 1,
    "validTime": 10,
    "missingPutBackMins": 10,
    "lngTexts": {
        "hu": {
            "call": "Az Ön ${ticketNumber} jegyét épp most hívják a ${counterNumber} pulthoz.",
            "feedback": "Kérjük értékelje a ${ticketNumber} számú jegy ügyintézését. Köszönjük!"
        },
        "en-gb": {
            "call": "Calling your number #{ticketNumber} at counter #{counterNumber}.",
            "feedback": "Please send your feedback about the administration for ticket #{ticketNumber}."
        }
    }
}

Response: 400 Bad request

Invalid key hash.

Response: 403 Forbidden

The given key hash is expired.

Response: 500 Server Error

The Smart Ticket function is not configured properly.

Get locale messages

This request gives the Smart Ticket’s texts in the given language.

Request

GET /qnet6/rest/smart/locales/{lang}?key={key}
Parameters

The key or ticket hash is needed as an URL variable.

Name Type Description
lang Number Nyelv ID.

Example

http://localhost:3000/qnet6/rest/smart/locales/1?key=plTwVw86PjZ

Response: 200 OK

The answer contains the given language’s text.

Fields
Name Type Description
messages Object Language texts

 

Example
{
    "messages": {
        "8332": "Total waiting time",
        "8333": "Current transaction time",
        "8330": "at counter",
        "8331": "under transaction at counter",
        "8336": "Put back to queue",
        "8337": "Are you sure to cancel your ticket?",
        "8334": "Missed call",
        "8335": "You missed your call and will be called again in {0} minute(s).",
        "8329": "Calling your number",
        "8327": "Current waiting time",
        "8328": "Cancel ticket",
        "8343": "Welcome in our office!",
        "8300": "Wrong URL"

    }
}

Response: 400 Bad request

Invalid language ID.

Get Dispenser profile

This requests the dispProfile‘s ticket dispenser profile got from the init.

Request

GET /qnet6/rest/smart/profile?key={key}
Parameters

The key hash is needed as an URL variable.

Example

http://localhost:3000/qnet6/rest/smart/profile?key=plTwVw86PjZ

Response: 200 OK

The answer contains the whole ticket dispenser profile structure, which offers the the available services listed hierarchically.

Fields
Name Type Description
profile Object Profile structure. Languages, service groups, services and language texts.
taskInfo Object Service ID’s waiting informations. The first value is the waiting number the second is the estimated waiting time in minute.
hiddenTasks Array<Number> Hidden service IDs.
disabledTasks Array<Number> Disabled service IDs.
Example
{
    "profile": {
        "prfID": 1,
        "standby": "30",
        "langID": 1,
        "lang": "en-gb",
        "content": [
            {
                "smartTicketTitle": "Smart Ticket",
                "description": "English",
                "back": "Back",
                "backToMain": "Back to main menu",
                "appointment": "Appointment",
                "title": "Main Menu",
                "successCard": "Card read successfully!",
                "cardReadFail": "Card read unsuccessfully. Please try again",
                "pushCard": "Push the card until it stops and pull it back out",
                "id": "en-gb",
                "langID": 1,
                "smartTicketDesc": "Please scan the QR code with your smartphone. After the successful scanning, a website will appear, where you can select a service and follow the status of your ticket. After the transaction don't forget to rate the administration",
                "authentication": "Authentication",
                "content": [
                    {
                        "number": "1",
                        "description": "Explanation 1",
                        "id": 1,
                        "title": "Service 1"
                    },
                    {
                        "number": "2",
                        "description": "Explanation 2",
                        "id": 2,
                        "title": "Service 2"
                    },
                    {
                        "number": "3",
                        "description": "Explanation 3",
                        "id": 3,
                        "title": "Service 3"
                    },
                    {
                        "number": "4",
                        "description": "Explanation 4",
                        "id": 4,
                        "title": "Service 4"
                    },
                    {
                        "number": "5",
                        "description": "Explanation 5",
                        "id": 5,
                        "title": "Service 5"
                    },
                    {
                        "number": "6",
                        "description": "Explanation 6",
                        "id": 6,
                        "title": "Service 6"
                    }
                ]
            }
        ]
    },
    "taskInfo": {
        "1": [
            0,
            ">60"
        ],
        "2": [
            0,
            ">60"
        ],
        "3": [
            0,
            ">60"
        ],
        "4": [
            0,
            ">60"
        ],
        "5": [
            0,
            ">60"
        ],
        "6": [
            0,
            ">60"
        ],
        "7": [
            0,
            ">60"
        ],
        "8": [
            0,
            ">60"
        ]
    },
    "hiddenTasks": [],
    "disabledTasks": []
}

Response: 400 Bad request

Profile ID does not exists.

Generate a ticket

To generate a ticket in the given language for the given service.

Request

POST /qnet6/rest/smart/generateTicket?key={key}
Parameters

The key hash parameter is needed as an URL variable.

Name Type Description
lang Number Language ID. The ticket dispenser profile’s langID field.
task Number Service ID. The ticket dispenser profile’s id field.

Example

POST http://localhost:3000/qnet6/rest/smart/generateTicket?key=plTwVw86PjZ
{
    "lang": 1,
    "task": 1
}

Response: 200 OK

The answer contains the generated ticket’s identifier hash. Later this will be needed at the URL as ticket instead of the key hash.

Fields
Name Type Description
ticket String Ticket ID’s hash.
Example
{
    "ticket": "aGdAT6exKj"
}

Response: 400 Bad request

Invalid key hash or missing data at the request’s body.

Response: 403 Forbidden

The given key hash has expired.

Generate a ticket from booking code

With this request you can generate a ticket from a booking code.

Request

POST /qnet6/rest/smart/bookingCode?key={key}
Parameters

The key hash is needed as an URL variable.

Name Type Description
lang Number Language ID. The ticket dispenser profile’s langID field.
task Number Service ID. The ticket dispenser profile’s id field.

Example

POST http://localhost:3000/qnet6/rest/smart/generateTicket?key=plTwVw86PjZ
{
    "lang": 1,
    "code": "12345"
}

Response: 200 OK

The answer contains the generated ticket’s indentifier hash. Later this will be needed at the URL as ticket instead of the key hash.

Fields
Name Type Description
ticket String Ticket ID’s hash.
Example
{
    "ticket": "aGdAT6exKj"
}

Response: 400 Bad request

Invalid key hash or missing data at the request’s body.

Response: 403 Forbidden

The given key hash has expired.

Get ticket status

With this request you can get the ticket’s status.

Request

GET /qnet6/rest/smart/ticket/{ticket}
Parameters

The ticket hash is needed as an URL variable.

Example

GET http://localhost:3000/qnet6/rest/smart/ticket/aGdAT6exKj

Response: 200 OK

The answer contains the ticket’s status and it’s important data.

Fields
Name Type Description
id Number Ticket ID.
number String Ticket number.
lang Number Language ID.
priority Number Ticket’s priority (1-9).
status Number Status of ticket
statusTime Number Last time of the ticket’s status change.
currentTime Number Current branch (time zone) time.
estimatedQueueSize Number Currently estimated queue length.
estimatedWaitingTime Number Currently estimated waiting time.
totalWaitingTime Number Total waiting time so far (not including the currently waiting data).
branch Object Branch data.
tasks Array<Object> Service data on the ticket.
tasks[].id Number Ticket’s service ID.
tasks[].name String Ticket’s service name.
tasks[].priority Number Ticket’s service priority (1-9).
tasks[].status Number Status of ticket service
Example
{
    "id": 10025,
    "number": "105",
    "lang": 1,
    "priority": 5,
    "status": 20,
    "statusTime": 20200518123918,
    "currentTime": 20200518130604,
    "estimatedQueueSize": 0,
    "estimatedWaitingTime": 0,
    "totalWaitingTime": 0,
    "branch": {
        "name": "Default branch",
        "id": 1
    },
    "tasks": [
        {
            "name": "Service 1",
            "id": 10025,
            "priority": 5,
            "status": 20
        }
    ],
}

Response: 400 Bad request

Invalid ticket hash.

Delete ticket

Deleting a ticket. In case of a ticket which is in a waiting status the customer can delete his/her ticket if he/she leaves the branch before he/she would have been called. In this way the calling of the missing tickets can be avoidable. At the delete the customer can give a note about why he/she deleted his/her ticket.

Request

DELETE /qnet6/rest/smart/ticket/{ticket}
Parameters

The ticket hash is needed as an URL variable.

Fields
Name Type Description
comment String Note for the delete.

Example

GET http://localhost:3000/qnet6/rest/smart/ticket/aGdAT6exKj
{
    "comment": "The waiting time was too long!!!"
}

Response: 200 OK

Ticket deleted succsessfuly.

Response: 400 Bad request

Invalid ticket hash.

Put back missing ticket

In case of missing ticket the customer can request to put his/her ticket back to the waiting list.

Request

PUT /qnet6/rest/smart/missingPutBack?ticket={ticket}
Parameters

The ticket hash is needed as an URL variable.

Example

PUT http://localhost:3000/qnet6/rest/smart/missingPutBack?ticket=aGdAT6exKj

Response: 200 OK

The ticket was returned to the queue successfuly.

Response: 400 Bad request

Invalid ticket hash.

Get Feedback profile

This requests the cfProfile‘s feedback profile got from the init.

Request

GET /qnet6/rest/smart/feedbackProfile?key={key}
Parameters

The key hash is needed as an URL variable.

Example

http://localhost:3000/qnet6/rest/smart/feedbackProfile?key=plTwVw86PjZ

Response: 200 OK

The answer contains the feedback profil structure including it’s questions and answers.

Fields
Name Type Description
id String Profile ID.
name String Profile name.
langs Array<Object> Languages list.
langs[].id String Language ID.
langs[].code String Language code.
langs[].name String Language name.
langs[].questions Array<Object> Questions.
langs[].questions[].id Number Question ID.
langs[].questions[].text Number Question text.
langs[].questions[].order Number Qestion sequence.
langs[].questions[].answers Array<Object> Answer possibilities.
langs[].questions[].answers[].id Number Answer ID.
langs[].questions[].answers[].text Number Answer text.
langs[].questions[].answers[].value Number Answer value.
Example
{
    "id": 1,
    "name": "Default profile",
    "langs": [
        {
            "id": 1,
            "code": "en-gb",
            "name": "English",
            "questions": [
                {
                    "id": 1,
                    "text": "How would you rate our service level?",
                    "order": 1,
                    "answers": [
                        {
                            "value": 1,
                            "id": 1,
                            "text": "Poor"
                        },
                        {
                            "value": 2,
                            "id": 2,
                            "text": "Acceptable"
                        },
                        {
                            "value": 3,
                            "id": 3,
                            "text": "Fair"
                        },
                        {
                            "value": 4,
                            "id": 4,
                            "text": "Good"
                        },
                        {
                            "value": 5,
                            "id": 5,
                            "text": "Excellent"
                        }
                    ]
                }
            ]
        }
    ]
}

Response: 400 Bad request

Profile ID does not exists.

Give feedback

Customer feedback connected to a ticket.

Request

POST /qnet6/rest/smart/feedback?ticket={ticket}
Parameters

The ticket hash is needed as an URL variable.

Fields
Name Type Description
lang Number The answer’s language (one language).
profile Number Feedback profile ID.
question Number Question ID.
answer Number Answer ID.
comment String Optional rating(text).

Example

POST http://localhost:3000/qnet6/rest/smart/feedback?ticket=aGdAT6exKj
{
    "lang": 1,
    "profile": 1,
    "question": 1,
    "answer": 5,
    "comment": "Very fast administration, great!"
}

Response: 200 OK

The operation was successful

Response: 400 Bad request

Missing parameter at the request body or a feedback has already been recorded.

Response: 404 Not found

Ticket not found.

Enums

Ticket statuses

Value Description
10 Booked.
20 Can be called.
30 Under calling.
40 Missing.
50 Definitive missing.
60 Under transaction.
70 On waiting list.
80 Deleted.
90 Closed.
100 Under afterwork.
Ticket Advertisement REST
Last updated: Mon Aug 15 2022