Índice da Documentação Técnica — API GTI

Lista das documentações disponíveis para consulta.

Documentações

• 01 — Agent
  Consulta de indicadores operacionais agrupados por data, fila e agente.
• 02 — Extrato
  Consulta detalhada dos atendimentos, incluindo dados da chamada, cliente, serviço, gravação, tabulação e indicadores.
• 03 — Pesquisa Simples
  Consulta de pesquisas simples de satisfação vinculadas aos atendimentos.
• 04 — Login
  Consulta de logs operacionais dos atendentes, incluindo login, logout, filas, pausas e status.

Documentação Técnica — API GTI

Aplicação: agent — Consulta de Indicadores por Agente

1. Objetivo

Esta documentação descreve como consumir a aplicação agent da API GTI.

A aplicação agent permite consultar indicadores operacionais de atendimento agrupados por data, fila e agente.

Os dados retornados podem ser utilizados para relatórios, dashboards, integrações externas, auditorias operacionais e análises de performance de atendimento.

2. Endpoint

3. URL da Requisição

{{url}}/agi/app.php?user={{user}}&pwd={{pass}}&end_date={{dt_init}}&app=agent&intervalo=1&key_agents=&key_queues=suporte&teste=0

4. Proteção de Dados Sensíveis

A documentação deve utilizar variáveis no lugar de dados reais.

5. Variáveis Utilizadas

6. Autenticação

A API utiliza autenticação por parâmetros na URL e também por headers HTTP.

6.1 Autenticação pela URL

6.2 Autenticação via Headers

6.3 Headers Recomendados

7. Parâmetros da Query String

8. Parâmetro app

Para consultar os indicadores por agente, o parâmetro app deve receber o valor:

app=agent

9. Parâmetro end_date

O parâmetro end_date representa a data final da consulta.

Formato esperado:

YYYY-MM-DD

Exemplo:

end_date=2025-04-01

A API considera a data final até o último segundo do dia.

2025-04-01 23:59:59

10. Parâmetro intervalo

O parâmetro intervalo define a quantidade de dias anteriores que serão incluídos na consulta, usando end_date como referência.

11. Exemplos de Intervalo

11.1 Exemplo com intervalo igual a 0

Período calculado:

Neste caso, a consulta considera somente o dia 2025-04-01.

11.2 Exemplo com intervalo igual a 1

Período calculado:

Neste caso, a consulta considera o período de 2025-03-31 00:00:00 até 2025-04-01 23:59:59.

12. Limite do Intervalo

O intervalo aceito pela API é de 0 a 91 dias.

13. Filtro por Agente

O parâmetro key_agents permite filtrar os resultados por agente.

Quando vazio:

key_agents=

A API não restringe a consulta a um agente específico.

Quando informado, deve conter a identificação do agente desejado.

key_agents=NOME_DO_AGENTE

14. Filtro por Fila

O parâmetro key_queues permite filtrar os resultados por fila.

key_queues=suporte

No retorno, a fila pode aparecer normalizada em caixa alta.

SUPORTE

15. Exemplo de Requisição cURL

curl --location '{{url}}/agi/app.php?user={{user}}&pwd={{pass}}&end_date={{dt_init}}&app=agent&intervalo=1&key_agents=&key_queues=suporte&teste=0' \
--header 'Accept: application/json' \
--header 'user: {{header_user}}' \
--header 'pwd: {{header_pass}}'

16. Exemplo de Retorno Geral

{
  "status": 0,
  "msg": [
    "Login bem sucedido!",
    "A data informada é valida!",
    "O intervalo informado é valido entre 0 e 91 dias",
    "A aplicação exite!",
    "A soma de catacteres em keywords é menor ou igual a 100"
  ],
  "dt": {
    "start": "2025-03-31 00:00:00",
    "end": "2025-04-01 23:59:59",
    "intervalo": 1
  },
  "key_agents": null,
  "key_queues": [
    "suporte"
  ],
  "dados": {},
  "csv": {},
  "filas": []
}

17. Estrutura Principal do Retorno

18. Campo status

O campo status indica o resultado geral da execução.

{
  "status": 0
}

19. Campo msg

O campo msg retorna uma lista de mensagens referentes às validações realizadas pela API.

20. Campo dt

O campo dt informa o período efetivamente usado na consulta.

{
  "dt": {
    "start": "2025-03-31 00:00:00",
    "end": "2025-04-01 23:59:59",
    "intervalo": 1
  }
}

21. Campo key_agents

Quando nenhum agente é informado, o retorno pode vir como:

{
  "key_agents": null
}

Isso indica que a consulta não foi limitada a um agente específico.

22. Campo key_queues

Quando uma fila é informada, o retorno contém a lista de filas filtradas.

{
  "key_queues": [
    "suporte"
  ]
}

23. Campo dados

O campo dados contém os indicadores agrupados por data, fila e agente.

data -> fila -> agente -> indicadores

{
  "dados": {
    "2025-04-01": {
      "SUPORTE": {
        "NOME_DO_AGENTE": {
          "date": "2025-04-01",
          "queue_id": "130",
          "queue": "SUPORTE",
          "agent_id": "4188",
          "agent": "NOME_DO_AGENTE",
          "RINGNOANSWER": "0",
          "COMPLETEAGENT": "2",
          "COMPLETECALLER": "1",
          "TRANSFER": "0",
          "CONNECT": 3,
          "TME": "00:00:04",
          "TMA": "00:08:46",
          "SLA": "3",
          "SLA-P": "100,00%",
          "all_call": "00:26:20",
          "all_esp": "00:00:14",
          "max_esp": "00:00:05"
        }
      }
    }
  }
}

24. Indicadores Retornados por Agente

25. Campo csv

O campo csv contém os mesmos indicadores em uma estrutura achatada, usando uma chave composta.

{data}-{fila}-{agente}

{
  "2025-04-01-SUPORTE-NOME_DO_AGENTE": {
    "date": "2025-04-01",
    "queue_id": "130",
    "queue": "SUPORTE",
    "agent_id": "4188",
    "agent": "NOME_DO_AGENTE",
    "RINGNOANSWER": "0",
    "COMPLETEAGENT": "2",
    "COMPLETECALLER": "1",
    "TRANSFER": "0",
    "CONNECT": 3,
    "TME": "00:00:04",
    "TMA": "00:08:46",
    "SLA": "3",
    "SLA-P": "100,00%",
    "all_call": "00:26:20",
    "all_esp": "00:00:14",
    "max_esp": "00:00:05"
  }
}

Essa estrutura é recomendada para:

• exportação CSV;
• geração de relatórios;
• importação em ferramentas de BI;
• criação de dashboards;
• leitura tabular dos dados.

26. Campo filas

O campo filas retorna a lista de filas disponíveis na base da aplicação.

{
  "filas": [
    {
      "queue_id": "130",
      "queue": "SUPORTE"
    }
  ]
}

27. Exemplo de Consumo em PHP

<?php

$urlBase = '{{url}}/agi/app.php';

$params = [
    'user'       => '{{user}}',
    'pwd'        => '{{pass}}',
    'end_date'   => '{{dt_init}}',
    'app'        => 'agent',
    'intervalo'  => 1,
    'key_agents' => '',
    'key_queues' => 'suporte',
    'teste'      => 0,
];

$url = $urlBase . '?' . http_build_query($params);

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Accept: application/json',
        'user: {{header_user}}',
        'pwd: {{header_pass}}',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception('Erro na requisição: ' . curl_error($ch));
}

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

$data = json_decode($response, true);

if ($httpCode !== 200) {
    throw new Exception('Erro HTTP: ' . $httpCode);
}

if (!isset($data['status']) || $data['status'] !== 0) {
    throw new Exception('Erro retornado pela API.');
}

print_r($data);

28. Exemplo de Consumo em JavaScript

const url = new URL('{{url}}/agi/app.php');

url.searchParams.set('user', '{{user}}');
url.searchParams.set('pwd', '{{pass}}');
url.searchParams.set('end_date', '{{dt_init}}');
url.searchParams.set('app', 'agent');
url.searchParams.set('intervalo', '1');
url.searchParams.set('key_agents', '');
url.searchParams.set('key_queues', 'suporte');
url.searchParams.set('teste', '0');

const response = await fetch(url, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    user: '{{header_user}}',
    pwd: '{{header_pass}}',
  },
});

if (!response.ok) {
  throw new Error(`Erro HTTP: ${response.status}`);
}

const data = await response.json();

if (data.status !== 0) {
  throw new Error('Erro retornado pela API.');
}

console.log(data);

29. Exemplo de Leitura do Campo dados em JavaScript

const dados = data.dados;

for (const dataRef in dados) {
  for (const fila in dados[dataRef]) {
    for (const agente in dados[dataRef][fila]) {
      const item = dados[dataRef][fila][agente];

      console.log({
        data: item.date,
        fila: item.queue,
        agente: item.agent,
        atendidas: item.CONNECT,
        tme: item.TME,
        tma: item.TMA,
        sla: item['SLA-P'],
      });
    }
  }
}

30. Exemplo de Leitura do Campo csv em JavaScript

const linhas = Object.values(data.csv);

linhas.forEach((item) => {
  console.log({
    data: item.date,
    fila: item.queue,
    agente: item.agent,
    chamadasConectadas: item.CONNECT,
    tempoMedioEspera: item.TME,
    tempoMedioAtendimento: item.TMA,
    percentualSla: item['SLA-P'],
  });
});

31. Tratamento de Retorno Vazio

A API pode retornar sucesso, mas sem dados no período consultado.

{
  "status": 0,
  "dados": {},
  "csv": {}
}

Nesse caso, a aplicação consumidora deve tratar como consulta válida sem registros.

32. Validações Recomendadas no Sistema Consumidor

33. Possíveis Erros

34. Boas Práticas de Segurança

• Não expor user, pwd, headers de autenticação ou IP real em frontend público.
• Não versionar credenciais em repositórios Git.
• Não enviar credenciais em prints, documentos públicos ou tickets externos.
• Utilizar variáveis de ambiente para armazenar credenciais.
• Utilizar HTTPS em ambiente de produção.
• Restringir acesso por IP quando possível.
• Rotacionar senhas periodicamente.
• Evitar registrar credenciais em logs.
• Não documentar cookies de sessão.
• Não compartilhar URLs reais contendo usuário e senha.

35. Boas Práticas de Performance

• Evitar consultas com intervalo=91 sem necessidade.
• Usar filtro por fila sempre que possível.
• Usar filtro por agente quando o relatório não precisar de todos os agentes.
• Armazenar cache local quando o dado não precisar ser atualizado em tempo real.
• Evitar chamadas repetidas em intervalos muito curtos.
• Para dashboards, definir uma frequência controlada de atualização.

36. Checklist de Homologação

37. Resumo Técnico

38. Observação Final

A aplicação agent deve ser utilizada para consultas consolidadas de atendimento por agente.

O retorno fornece duas formas principais de leitura: