Auxiliary Requests API

Content

This guide provides information on how to interact with the REST API of Bloom Enterprise, some auxiliar requests to QM operations.

How to use

HTTP fundamentals

It is required a universal syntax to identify each service in the RESTful API, which is redirected by its URI (Uniform Resource Identifier). All API requests are made through HTTP requests to the URI, referring in the URI the service it must consume. Depending on the service’s action, the request’s header must have the operation which represents the aimed resource’s manipulation.

Operation	Description
DELETE	Responsible for a specific resource.
GET	Responsible for reading a specific resource.
POST	Responsible for transferring the status of a specific resource.
PUT	Responsible for creating or updating a resource set by the URI.

The basic URI for auxiliary requests is:

http://SERVER_IP:HTTP_PORT/restapi/requested_operation?format=xml

Where:

Item	Value
SERVER_IP	Bloom Enterprise server’s IP address.
HTTP_PORT	HTTP communication port (optional).
requested_operation	Requested system operation.
format=xml	To get a response in XML format (optional).

List of last called tickets

This request allows listing the last called tickets of a specific service.

Item	Value
Requested operation	ticket/lastTickets
HTTP method	GET
Parameters	location (string) ID of the location.
	number (integer) Number of last called tickets (optional) – default is 10.

Response structure

{
  "success" : Boolean,
  "lastTickets" : [
    service_id : {
      "ticket_id": String,
      "ticketService": String,
      "ticketServiceTag": String,
      "ticketNumber": Int,
      "ticketDeskTag": String,
      "ticketDeskName": String,
      "callDate": String (format: aaaa-mm-dd hh:mm:ss)
    },
  ]
}

Initial state

This request allows getting the initial state of the queue management.

Item	Value
Requested operation	v2/queuemanagement/initialstate
HTTP method	POST
Parameters	location_id (string) ID of the location.
	quantity_by_service (integer) Number of tickets by service (optional) – default is 10.
	quantity_by_desk (integer) Number of tickets by counter (optional) – default is 10.
	last_tickets_by_service (bool) Adds ‘lastTickets’ to response, with array ‘byservice’ (optional) – default is false.
	last_tickets_by_desk (bool) Adds ‘lastTickets’ to response, with array ‘bydesk’ (optional) – default is false.
	all_services (bool) Adds ‘player_info’ to response, with array ‘byService’ (optional) – default is false.
	all_desks (bool) Adds ‘player_info’ to response, with array ‘byDesk’ (optional) – default is false.

Response structure (with required parameters only)

{
  "success": true,
  "player_info": {
    "database": {
      "services": [
        {
          "id": String,
          "description": String,
          "tag": String,
          "desk_id": String,
          "state": String,               // possible values: "open" / "close"
          "answer_date": String,         // format: yyyy-mm-dd hh:mm:ss
          "arrival_date": String,        // format: yyyy-mm-dd hh:mm:ss
          "last_call_number": Integer,
          "dst_service_id": String,
          "last_print_ticket": Integer,
          "use_app_tag": Boolean,
          "app_tag": String,
          "max_ticket_number": Integer,
          "ticket_flags": Integer
        }
        // ... more services
      ],
      "desks": [
        {
          "id": String,
          "description": String,
          "tag": String
        }
        // ... more counters
      ]
    }
  }
}

List of locations

This request allows listing the locations. It accepts query filters to limit the results (optional).

Item	Value
Requested operation	locations
HTTP method	GET
Headers	Accept-Language (Optional)
Query Parameters	filter[code] (string) Code of the location.
	filter[locations][] (string) ID of the location.
	filter[services][] (string) ID of the server service.
	filter[city][] (string) Name of the city.
	filter[region][] (string) Name of the region.
	filter[country][] (string) Name of the country.
	filter[text] (string) Searches on email, phone, address, website, or name.

Response struture

{
  "success": Boolean,
  "locations": [
    {
      "id": String,
      "name": String,
      "state": Integer,
      "location_group": String,
      "phone": String,
      "email": String,
      "website": String,
      "coordinates": String,
      "address": String,
      "cloud": Boolean,
      "country": String,
      "region": String,
      "city": String,
      "timezone": String,
      "timeformat": String,
      "schedule": String,
      "social_links": Array,
      "t_checkin_before": Integer,
      "t_checkin_after": Integer,
      "t_attendance_before": Integer,
      "t_attendance_after": Integer,
      "t_delete": Integer,
      "t_profile_edit": Integer,
      "obs": String,
      "resource_id": String,
    }
  ]
}

List of services

This request allows listing the services. It accepts query filters to limit the results (optional).

Item	Value
Requested operation	services
HTTP method	GET
Headers	Accept-Language (Optional)
Roles required	acl_services_access Access services
Query Parameters	filter[ids][] (string) Id of service
	filter[locations][] (string) ID of the location.
	filter[services][] (string) ID of the server service.
	filter[text] (string) Searches on email, phone, address, website, or name.

Response struture

{
  "success": Boolean,
  "services": [
    {
      "id": String,
      "name": String,
      "state": Integer,
      "server_service": String,
      "service_group": {
        "id": String,
        "name": String,
        "description": String,
      },
      "service_code": String,
      "description": String,
      "capacity": Integer,
      "slot_time": Integer,
      "allow_multi_slot_appointments": Boolean,
      "allow_automatic_confirmation": Boolean,
      "location": String,
      "schedule": String,
      "app_schedule": String,
      "question_group": String,
      "tag": String,
      "rgbColour": String,
      "maxTicketNumber": Integer,
      "currentTicketNumber": Integer,
      "qm_enabled": Boolean,
      "virtual_ticket_enabled": Boolean,
      "metadata": {
                ":key1": String,
                ":key2": String
            }
    },
  …
  ]
}

List of server services

This request allows listing the server services. It accepts query filters to limit the results (optional).
Server services are the services created globally and that are available for all locations.

Item	Value
Requested operation	serverservices
HTTP method	GET
Roles required	acl_services_access Access services
Query Parameters	filter[ids][] (string) Id of service
	filter[locations][] (string) ID of the location.
	filter[services][] (string) ID of the server service.
	filter[text] (string) Searches on email, phone, address, website, or name.

Response structure

{
  "success": Boolean,
  "services": [
    {
      "id": String,
      "name": String,
      "state": Integer,
      "server_service": String,
      "description": String,
      "capacity": Integer,
      "slot_time": Integer,
      "allow_multi_slot_appointments": Boolean,
      "allow_automatic_confirmation": Boolean,
      "location": String,
      "schedule": String,
      "app_schedule": String,
      "question_group": String,
      "tag": String,
      "rgbColour": String,
      "maxTicketNumber": Integer,
      "currentTicketNumber": Integer,
      "qm_enabled": Boolean,
      "virtual_ticket_enabled": Boolean
    },
  …
  ]
}

List of users

This request allows listing the users. It accepts query filters to limit the results (optional).

Item	Value
Requested operation	users
HTTP method	GET
Roles required	essentials_staff_access_staff Access users
Query Parameters	filter[users][] (string) Id of user
	filter[desks][] (string) ID of the counter.
	filter[locations][] (string) ID of the location.
	filter[services][] (string) ID of the server service.
	filter[text] (string) Searches on email, phone, address, website, or name.

Response structure

{
  "success": Boolean,
  "users": [
    {
      "id": String,
      "username": String,
      "name": String,
      "phone": String,
      "email": String,
      "schedule": String,
    },
    …
  ]
}

Get Service by Metadata

This request allows the user to get services which match the metadata keys/values. It needs query filters to limit the results (optional).

Item	Value
Requested operation	services/metadata
HTTP method	GET
Roles required	acl_qmpad_access Access qmpad
Query Parameters	key=value (string) Key/value to search for

Response struture

{
  "success": Boolean,
  "services": [
    {
      "id": String,
      "name": String,
      "state": Integer,
      "server_service": String,
      "service_group": {
        "id": String,
        "name": String,
        "description": String,
      },
      "service_code": String,
      "description": String,
      "capacity": Integer,
      "slot_time": Integer,
      "allow_multi_slot_appointments": Boolean,
      "allow_automatic_confirmation": Boolean,
      "location": String,
      "schedule": String,
      "app_schedule": String,
      "question_group": String,
      "tag": String,
      "rgbColour": String,
      "maxTicketNumber": Integer,
      "currentTicketNumber": Integer,
      "qm_enabled": Boolean,
      "virtual_ticket_enabled": Boolean,
      "metadata": {
                ":key1": String,
                ":key2": String
            }
    },
  …
  ]
}

Ticket Detail

This request allows the user to get detailed information about a ticket.

Item	Value
Requested operation	ticket/details/:id
HTTP method	GET
Roles required	acl_qmpad_access Access qmpad

Response struture

{
    "success": Boolean,
    "ticket": {
        "id": String,
        "number": Integer,
        "date": String,
        "cancelled": Boolean,
        "transferred": Boolean,
        "state": Integer,
        "note": String,
        "lang": String,
        "custom_field": String,
        "client_name": String,
        "flags": Integer,
        "app_displayname": String,
        "app_id": String,
        "scheduled_to": String,
        "ticket_service": {
            "id": String,
            "name": String,
            "tag": String
        },
        "dst_service": {
            "id": String,
            "name": String,
            "tag": String
        },
        "dst_desk": String,
        "dst_user": String,
        "device": {
            "id": String,
            "name": String,
            "type": Integer
        },
        "location": String,
        "dst_location": {
            "id": String,
            "name": String
        },
        "extra_info": [String],
        "tickets_to_print": Integer
    }
}

Content​

How to use​

HTTP fundamentals​

List of last called tickets​

Initial state​

List of locations​

List of services​

List of server services​

List of users​

Get Service by Metadata​

Ticket Detail​

Content

How to use

HTTP fundamentals

List of last called tickets

Initial state

List of locations

List of services

List of server services

List of users

Get Service by Metadata

Ticket Detail