N|Solid

Introdução

Esse documento visa fornecer o padrão de uso das APIs do Q-Manager disponibilizadas a partir da versão 1.0.7. As APIs fornecidas são:

  • Listagem de Operadores
  • Listagem de Filas
  • Relatórios do Operador
  • Relatório da fila

Access Token

Para utilizar as APIs é necessário fornecer o access_token do usuário do Q-Manager para validação e permissionamento dos dados. Para visualizar o access_token basta acessar Usuários -> Editar

Acess_token

IMPORTANTE: Para evitar o alto consumo do servidor, as APIs de dados dos relatórios do Q-manager tem controle de consultas por tempo. Ao receber a primeira requisição o Q-Manager estipula um prazo de 1(um) minuto de controle, sendo que se ocorrer uma nova consulta em menos de 1(um) minuto a mesma terá um delay de 3 segundos acumulativos. Estas APIs fornecerão dados em no máximo 5(cinco) requisições dentro do prazo de 1(um) minuto, caso ocorra a sexta consulta a API fornecerá um status code 403(não permitido).


Listagem de Operadores - (GET)

API para listagem dos operadores.

URL

ip_server:8080/operators/api/v1/getOperators?access_token=VALOR_DO_ACCESS_TOKEN

Response:

{
    "_id": "584fda8f96891a001256743c",
    "agent": "1017",
    "secret": "1017",
    "endpoint": "SIP/8017",
    "peer_fixed": false,
    "name": "Pedro Silva",
    "queues": {
        "Suporte": {
            "pause": "0",
            "state": "off",
            "penalty": "0"
        }
    },
    "created": "2016-12-13 09:25:03",
    "updated": "2017-02-21 17:56:18",
    "worktime": {
        "start": "08:00",
        "end": "18:00"
    },
    "email": "[email protected]"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

_id: Identificação do operador.

agent: Código do operador.

secret: Senha de login do operador.

endpoint: Ramal do operador.

peer_fixed: É true quando o operador possui o mesmo número do ramal. Exemplo: Operador 2000 e Ramal SIP/2000.

name: Nome do operador.

queues: Nome da fila padrão do operador. Os parâmetros pausa, state e penalty é referente ao status do operador na fila informada.

created: Data de criação do pausa.

updated: Data de atualização da pausa.

email: Email do operador.


Listagem de Filas - (GET)

API para listagem das filas.

URL

ip_server:8080/queues/api/v1/getQueues?access_token=VALOR_DO_ACCESS_TOKEN

Response:

{
  "queue": "Suporte",
  "loggedin": "9",
  "available": "9",
  "callers": "0",
  "holdtime": "0",
  "talktime": "0",
  "longestholdtime": "0"
}
1
2
3
4
5
6
7
8
9

queue: Nome da fila.

loggedin: Quantidade de membros na fila.

available: Quantidade de membros disponíveis.

callers: Quantidade de chamadas aguardando na fila no momento.

holdtime: Tempo de espera na fila(média).

talktime: Tempo de chamada na fila(média).

longestholdtime: Tempo de espera da chamada na fila(média).


Relatório do operador - (GET)

API para gerar dados dos operadores.

URL

ip_server:8080/report-operators/api/v1/generate?access_token=VALOR_DO_ACCESS_TOKEN&type=TIPO_DE_RELATORIO&from=DATA_INICIAL&to=DATA_FINAL&operator=OPERADORES

Valores Permitidos:

access_token: Token de acesso. *Dado obrigatório.

type: Tipo do relatório. Poderá ser analytic ou synthetic. *Dado obrigatório.

from: Data inicial da consulta no formato yyyy-mm-dd. Exemplo: 2017-04-18. *Dado obrigatório.

to: Data final da consulta no formato yyyy-mm-dd. Exemplo: 2017-04-19. *Dado obrigatório.

operator: Código dos operadores. Quando for mais de um operador separar por vírgula. Exemplo: 1018,1025. *Dado obrigatório.

discard: Valor em segundos de descarte de chamada "menor que". Valor deve ser inteiro.

Exemplo Tipo Sintético

URL

ip_server:8080/report-operators/api/v1/generate?access_token=frmCREB8vXrA9jZI&type=synthetic&from=2017-04-18&to=2017-04-19&operator=1018,1025&discard=10

Response:

[
  {"1025": [{
    "name": "",
    "partials": {
      "02/02/2018": {
        "incoming": {
          "date": "02/02/2018",
          "total": 14,
          "answer": 3,
          "noanswer": 11,
          "talktime": "00:10:04",
          "ringtime": "00:01:19",
          "duration": "00:03:28",
          "perc_answer": 21,
          "perc_noanswer": 79
        },
        "outgoing": {
          "date": "02/02/2018",
          "total": 10,
          "answer": 6,
          "noanswer": 4,
          "talktime": "00:15:04",
          "ringtime": "00:02:19",
          "duration": "00:17:23",
          "perc_answer": 60,
          "perc_noanswer": 40
        }
      },
    },
    "availability": {
      "cont_pauses": 10,
      "time_pauses": "09:42:16",
      "online": "94:26:48",
      "available": "84:44:32",
      "in_call": "03:04:42",
      "data_pauses": {
        "Almoço": {
          "cont": 4,
          "time": "06:07:35"
        },
        "Café": {
          "cont": 6,
          "time": "03:34:41"
        }
      },
      "availability_date": {
        "02/02/2018": {
          "cont_pauses": 2,
          "time_pauses": "04:12:56",
          "online": "27:59:04",
          "available": "23:46:08",
          "in_call": "00:30:13",
          "data_pauses": {
            "Almoço": {
              "cont": 1,
              "time": "02:31:20",
              "limit": true
            },
            "Café": {
              "cont": 1,
              "time": "01:41:36",
              "limit": true
            }
          }
        }
      },
      {"total": {
        "incoming": {
          "total": 37,
          "answer": 19,
          "noanswer": 18,
          "talktime": "00:08:23",
          "ringtime": "00:00:43",
          "duration": "00:05:02",
          "perc_answer": 51,
          "perc_noanswer": 49
        },
        "outgoing": {
          "total": 25,
          "answer": 15,
          "noanswer": 10,
          "talktime": "00:01:29",
          "ringtime": "00:00:07",
          "duration": "00:01:01",
          "perc_answer": 60,
          "perc_noanswer": 40
        }
      }
    }
  ]
},
{"1025": [{"message": "No data Found"}]}
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

Nomenclatura dos dados do resultado.

partials: Dados parciais do operador por dia a dia dentro do período escolhido.

total: Soma total dos dados do período.

incoming: Chamadas de entrada.

outgoing: Chamadas de saída.

total: Quantidade total de chamadas.

answer: Quantidade de chamadas atendidas.

noanswer: Quantidade de chamadas não atendida.

talktime: Tempo médio de atendimento(TMA).

ringtime: Tempo médio de espera(TME).

duration: Tempo médio de chamada(TMC).

perc_answer: Porcentagem de chamadas atendidas.

perc_noanswer: Porcentagem de chamadas não atendidas.

availability: Disponibilidade do operador total no período(Soma dos dias)

cont_pauses: Quantidade de pausas.

time_pauses: Tempo total em pausas.

online: Tempo online. Desde último login.

in_call: Tempo em ligação.

data_pauses: Pausas geradas no período com quantidade, tempo e se extrapolou o tempo limite diário configurado da pausa.

message: Apresentado quando não há dados do operador.

Exemplo Tipo Analítico

URL

ip_server:8080/report-operators/api/v1/generate?access_token=frmCREB8vXrA9jZI&type=analytic&from=2017-05-02&to=2017-05-02&operator=1025

Response:

[{
 "1025": [{
  "analytic": [
   {
    "eventdate": "02/05/2017 08:10:55",
    "status": "answer",
    "type": "outgoing",
    "class": "badge badge-success",
    "queue": null,
    "talktime": "00:00:02",
    "duration": "00:00:05",
    "to": "8018",
    "from": "8025"
   },
   {
    "eventdate": "02/05/2017 08:09:51",
    "status": "answer",
    "type": "incoming",
    "class": "badge badge-success",
    "queue": "Suporte",
    "talktime": "00:01:03",
    "duration": "00:01:09",
    "to": "suporte",
    "from": "(47)99707-6158"
   }
  ],
  "feature": [
   {
    "date": "02/05/2017",
    "hour": "08:02:25",
    "event": "login",
    "queue": ["Suporte","Portaria"],
    "class": "badge badge-success",
    "event_name": "login"
   },
   {"date": "02/05/2017",
    "hour": "08:34:51",
    "event": "pause",
    "queue": ["Portaria","Suporte"],
    "class": "badge badge-warning",
    "event_name": "Default Pause"
   }
  ]
 }]
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Nomenclatura dos dados do resultado.

analytic: Dados das chamadas de entrada e saída do operador.

eventdate: Data e horário da chamada.

status: Status da chamada. Poderá ser answer(atendida) e noanswer(não atendida)

type: Incoming - ligação de entrada. Outgoing - ligação de saída.

queue: Nome da fila caso a ligação esteja sendo recebida na fila.

talktime: Tempo de atendimento.

duration: Tempo de chamada.

to: Destino da chamada.

from: Origem da chamada.

feature: Dados de disponibilidade do operador.

date: Data do evento.

hour: Hora do evento.

event: Tipo de evento. Poderá ser login, pause, unpause e logoff.

queue: Fila que foi efetuado o evento.

event_name: Nome do evento. Caso o evento seja pause o nome da pausa é fornecido nesse campo.


Relatório de Fila - (GET)

API para gerar dados das filas.

URL

ip_server:8080/report-queues/api/v1/generate?access_token=VALOR_DO_ACCESS_TOKEN&type=TIPO_DE_RELATORIO&from=DATA_INICIAL&to=DATA_FINAL&queues=FILAS&status=STATUS

Valores Permitidos:

access_token: Token de acesso. *Dado obrigatório.

type: Tipo do relatório. Poderá ser analytic ou synthetic. *Dado obrigatório.

from: Data inicial da consulta no formato yyyy-mm-dd. Exemplo: 2017-04-18. *Dado obrigatório.

to: Data final da consulta no formato yyyy-mm-dd. Exemplo: 2017-04-19. *Dado obrigatório.

queues: Nome das Filas. Quando for mais de uma fila separar por vírgula. Exemplo: Suporte,Comercial. *Dado obrigatório.

status: Status da chamada. Valor poderá ser all(todas), queueabandon(somente abandonadas), queuetimeout(somente tempo limite), queuehangup(somente atendidas), caller(somente desligada pelo cliente), agent(somente desligada pelo operador) ou transfer(somente transferidas). *Dado obrigatório.

Exemplo Tipo Sintético

URL

ip_server:8080/report-queues/api/v1/generate?access_token=frmCREB8vXrA9jZI&type=synthetic&from=2017-05-02&to=2017-05-05&queues=Suporte&status=all

Response:

[{
 "Suporte": [{
  "total":
   {
    "total": 7,
    "abandon": 0,
    "answer": 7,
    "timeout": 0,
    "transfer": 3,
    "agent": 3,
    "caller": 1,
    "talktime": 2219,
    "holdtime": 33,
    "duration": 5104,
    "div_total": 7,
    "div_answer": 7,
    "perc_answer": 100,
    "perc_abandon": 0,
    "perc_timeout": 0,
    "perc_transfer": 43,
    "perc_agent": 43,
    "perc_caller": 14,
    "tme": "00:00:05",
    "tma": "00:05:17",
    "tmc": "00:12:09"
   },
   "partials":{
    "02/05/2017": {
     "08": {
      "total": 4,
      "abandon": 0,
      "answer": 4,
      "timeout": 0,
      "transfer": 3,
      "agent": 0,
      "caller": 1,
      "talktime": 705,
      "holdtime": 18,
      "duration": 3575,
      "div_total": 4,
      "div_answer": 4,
      "perc_answer": 100,
      "perc_abandon": 0,
      "perc_timeout": 0,
      "perc_transfer": 0,
      "perc_agent": 0,
      "perc_caller": 0,
      "tme": "00:00:05",
      "tma": "00:02:56",
      "tmc": "00:14:54"
     },
     "max": {
      "max_call": 4
     }
    }
   },
  "graphic": {}
 }]
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

Nomenclatura dos dados do resultado.

partials: Dados parciais da fila por dia a dia e hora em hora dentro do período escolhido.

total: Soma total dos dados do período.

total: Quantidade total de chamadas.

abandon: Quantidade de chamadas abandonadas.

answer: Quantidade de chamadas atendidas.

timeout: Quantidade de chamadas tempo limite.

transfer: Quantidade de chamadas transferidas.

agent: Quantidade de chamadas desligadas pelo operador.

caller: Quantidade de chamadas desligadas pelo cliente.

talktime: Tempo de atendimento(em segundos).

holdtime: Tempo de espera(em segundos).

duration: Tempo de chamada(em segundos).

perc_answer: Porcentagem de chamadas atendidas.

perc_abandon: Porcentagem de chamadas abandonadas.

perc_timeout: Porcentagem de chamadas tempo limite.

perc_transfer: Porcentagem de chamadas transferidas.

perc_agent: Porcentagem de chamadas desligadas pelo operador.

perc_caller: Porcentagem de chamadas desligadas pelo cliente.

tme: Tempo médio de espera(TME).

tma: Tempo médio de atendimento(TMA).

tmc: Tempo médio de chamada(TMC).

max: Quantidade máxima de chamadas em um hora no dia.

message: Apresentado quando não há dados da fila.

Exemplo Tipo Analítico

URL

ip_server:8080/report-queues/api/v1/generate?access_token=frmCREB8vXrA9jZI&type=analytic&from=2017-05-02&to=2017-05-05&queues=Suporte&status=all

Response:

[{
 "Suporte": [{
  "header": {
   "calldate": "02/05/2017 08:01:55",
   "queue": "Suporte",
   "from": "(47)99707-6158",
   "holdtime": "00:00:00",
   "firstevent": "Enterqueue"
  },
  "footer": {
   "callid": "2017050211015547997076158",
   "lastevent": "queuehangup",
   "hangupdate": "02/05/2017 08:09:16",
   "duration": "00:07:21",
   "talktime": "00:07:17",
   "timewaiting": "00:00:04",
   "record": "192.168.10.252/snep/arquivos/2017-05-02/1493722896_20170502_0801_47997076158_4839548001.wav"
  },
  "callf": [{
   "event": "answered",
   "holdtime": "00:00:04",
   "queue": "Suporte",
   "eventdate": "02/05/2017 08:01:59",
   "ringtime": "00:00:03",
   "endpoint": "SIP/8018",
   "name": "Marine Mafra",
   "classe": "badge badge-success"
  },
  {
   "event": "Off by the client",
   "holdtime": "00:07:17",
   "queue": "Suporte",
   "eventdate": "02/05/2017 08:09:16",
   "ringtime": "-",
   "endpoint": "SIP/8018",
   "name": "Marine Mafra",
   "classe": "badge badge-success"
  }
 ]}
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

Nomenclatura dos dados do resultado.

header: primeiro evento da chamada na fila.

calldate: Data e horário da chamada.

queue: Nome da fila.

from: Origem da chamada.

holdtime: Tempo do evento.

firstevent: Nome do primeiro evento. Sempre será Enterqueue(Entrou na Fila).

footer: Dados da chamada após o término da mesma.

callid: Código identificador da chamada.

lastevent: Último evento da chamada. Poderá ser queuehangup(ligação atendida), queueabandon(ligação abandonada) ou queuetimeout(ligação com tempo limite da fila).

hangupdate: Data e hora do fim da chamada.

duration: Tempo de chamada.

talktime: Tempo de atendimento.

timewaiting: Tempo de espera.

record: Localização da gravação da chamada, caso tenha.

callf: Fluxo da chamada dentro da fila.

event: Nome do evento. Poderá ser answered(atendida), transfer(transferida), Off by the client(desligada pelo cliente) ou Off by the operator(desligada pelo operador).

holdtime: Tempo de evento.

ringtime: Tempo de ring no operador.

endpoint: Ramal do operador.

name: Nome do operador.

feature: Dados de disponibilidade do operador.

date: Data do evento.

hour: Hora do evento.

event: Tipo de evento. Poderá ser login, pause, unpause e logoff.

queue: Fila que foi efetuado o evento.

event_name: Nome do evento. Caso o evento seja pause o nome da pausa é fornecido nesse campo.