Í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: login — Consulta de Logs de Login, Filas e Pausas dos Atendentes

1. Objetivo

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

A aplicação login permite consultar registros operacionais dos atendentes, incluindo eventos de login, logout, entrada em fila, saída de fila, entrada em pausa, saída de pausa e demais status operacionais registrados no período consultado.

Os dados retornados podem ser utilizados para auditoria operacional, controle de jornada, análise de disponibilidade, acompanhamento de pausas, relatórios de produtividade, dashboards gerenciais e integrações externas.

2. Endpoint

3. URL da Requisição

{{url}}/agi/app.php?user={{user}}&pwd={{pass}}&app=login&end_date={{dt_init}}&intervalo=0&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 registros de login, filas e pausas, o parâmetro app deve receber o valor:

app=login

9. Parâmetro end_date

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

Formato esperado:

YYYY-MM-DD

Exemplo:

end_date=2026-06-10

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

2026-06-10 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 2026-06-10.

11.2 Exemplo com intervalo igual a 1

Período calculado:

Neste caso, a consulta considera o período de 2026-06-09 00:00:00 até 2026-06-10 23:59:59.

12. Limite do Intervalo

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

13. Exemplo de Requisição cURL

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

14. 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": "2026-06-10 00:00:00",
    "end": "2026-06-10 23:59:59",
    "intervalo": 0
  },
  "key_agents": null,
  "key_queues": null,
  "csv": []
}

15. Estrutura Principal do Retorno

16. Campo status

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

{
  "status": 0
}

17. Campo msg

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

18. Campo dt

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

{
  "dt": {
    "start": "2026-06-10 00:00:00",
    "end": "2026-06-10 23:59:59",
    "intervalo": 0
  }
}

19. 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.

20. Campo key_queues

Quando nenhuma fila é informada, o retorno pode vir como:

{
  "key_queues": null
}

Isso indica que a consulta não foi limitada a uma fila específica.

21. Campo csv

O campo csv contém a lista de eventos operacionais dos atendentes.

Cada item representa um registro de movimentação ou status, podendo indicar login, logout, entrada em fila, saída de fila, entrada em pausa, saída de pausa ou outro status operacional.

Exemplo protegido:

{
  "pk_log": "11065791",
  "id_agent": "1261",
  "log_name": "NOME_DO_AGENTE",
  "dt_log": "2026-06-10 00:00:34",
  "event_log": "-1",
  "st_name": "LogIn",
  "ramal": null,
  "queue": null,
  "q_name": null,
  "dt_st": null,
  "tempo": null,
  "event_st": null,
  "ed_name": null,
  "est_min": null
}

22. Campos Retornados em csv

23. Campo pk_log

O campo pk_log identifica de forma única o registro de log retornado pela API.

11065791

Esse campo pode ser utilizado para controle de duplicidade, auditoria e rastreamento de eventos importados em sistemas externos.

24. Campo id_agent

O campo id_agent representa o ID interno do atendente/agente.

1261

Esse campo pode ser utilizado para cruzar dados com cadastros internos de agentes, relatórios de produtividade ou outros módulos da API.

25. Campo log_name

O campo log_name informa o nome ou identificação do atendente.

NOME_DO_AGENTE

Por conter identificação de colaborador, recomenda-se proteger ou anonimizar esse campo em ambientes públicos, relatórios externos ou bases de teste.

26. Campo dt_log

O campo dt_log informa a data e hora em que o evento foi registrado.

Formato observado:

YYYY-MM-DD HH:MM:SS

Exemplo:

2026-06-10 08:12:05

27. Campo event_log

O campo event_log informa o código interno do evento registrado.

28. Campo st_name

O campo st_name informa a descrição textual do evento ou status registrado.

29. Campo ramal

O campo ramal informa o ramal associado ao atendente no momento do evento.

1020

Em eventos como LogIn e LogOut, esse campo pode retornar null.

30. Campo queue

O campo queue representa o ID interno da fila associada ao evento.

Em eventos de login ou logout, esse campo pode retornar null.

31. Campo q_name

O campo q_name informa o nome da fila associada ao evento.

32. Campo dt_st

O campo dt_st informa a data e hora de início do status anterior relacionado ao evento atual.

Esse campo aparece principalmente em eventos de saída de pausa.

{
  "st_name": "Sair da Pausa",
  "dt_log": "2026-06-10 02:30:52",
  "dt_st": "2026-06-10 02:20:13"
}

Neste exemplo, o atendente saiu da pausa às 02:30:52, e a pausa havia iniciado às 02:20:13.

33. Campo tempo

O campo tempo informa o tempo decorrido do status anterior relacionado, em segundos.

{
  "tempo": "639"
}

Neste exemplo, o tempo decorrido foi de 639 segundos.

34. Campo event_st

O campo event_st informa o código do evento/status anterior relacionado.

Esse campo aparece principalmente em eventos de saída de pausa.

{
  "event_st": "3",
  "ed_name": "Pausa para Descanso"
}

Neste exemplo, o evento anterior foi uma pausa de descanso.

35. Campo ed_name

O campo ed_name informa o nome do evento/status anterior relacionado.

36. Campo est_min

O campo est_min informa o tempo estimado ou limite configurado, em minutos, para o status anterior.

37. Exemplos de Registros por Tipo de Evento

37.1 Registro de LogIn

{
  "pk_log": "11065791",
  "id_agent": "1261",
  "log_name": "NOME_DO_AGENTE",
  "dt_log": "2026-06-10 00:00:34",
  "event_log": "-1",
  "st_name": "LogIn",
  "ramal": null,
  "queue": null,
  "q_name": null,
  "dt_st": null,
  "tempo": null,
  "event_st": null,
  "ed_name": null,
  "est_min": null
}

37.2 Registro de Entrada em Fila

{
  "pk_log": "11065797",
  "id_agent": "1261",
  "log_name": "NOME_DO_AGENTE",
  "dt_log": "2026-06-10 00:00:35",
  "event_log": "-3",
  "st_name": "Atendente Entra na Fila",
  "ramal": "1020",
  "queue": "130",
  "q_name": "SUPORTE",
  "dt_st": null,
  "tempo": null,
  "event_st": null,
  "ed_name": null,
  "est_min": null
}

37.3 Registro de Entrada em Pausa

{
  "pk_log": "11065799",
  "id_agent": "1261",
  "log_name": "NOME_DO_AGENTE",
  "dt_log": "2026-06-10 02:20:13",
  "event_log": "3",
  "st_name": "Pausa para Descanso",
  "ramal": "1020",
  "queue": "135",
  "q_name": "DIGITAL",
  "dt_st": null,
  "tempo": null,
  "event_st": null,
  "ed_name": null,
  "est_min": null
}

37.4 Registro de Saída de Pausa

{
  "pk_log": "11065806",
  "id_agent": "1261",
  "log_name": "NOME_DO_AGENTE",
  "dt_log": "2026-06-10 02:30:52",
  "event_log": "-5",
  "st_name": "Sair da Pausa",
  "ramal": "1020",
  "queue": "135",
  "q_name": "DIGITAL",
  "dt_st": "2026-06-10 02:20:13",
  "tempo": "639",
  "event_st": "3",
  "ed_name": "Pausa para Descanso",
  "est_min": "10"
}

37.5 Registro de Saída de Fila

{
  "pk_log": "11065863",
  "id_agent": "1261",
  "log_name": "NOME_DO_AGENTE",
  "dt_log": "2026-06-10 05:59:01",
  "event_log": "-4",
  "st_name": "Atendente Sai da Fila",
  "ramal": "1020",
  "queue": "135",
  "q_name": "DIGITAL",
  "dt_st": null,
  "tempo": null,
  "event_st": null,
  "ed_name": null,
  "est_min": null
}

37.6 Registro de LogOut

{
  "pk_log": "11065870",
  "id_agent": "1261",
  "log_name": "NOME_DO_AGENTE",
  "dt_log": "2026-06-10 05:59:02",
  "event_log": "-2",
  "st_name": "LogOut",
  "ramal": null,
  "queue": null,
  "q_name": null,
  "dt_st": null,
  "tempo": null,
  "event_st": null,
  "ed_name": null,
  "est_min": null
}

38. Interpretação dos Eventos

A aplicação login pode retornar múltiplos registros para o mesmo atendente no mesmo horário quando o evento estiver relacionado a várias filas.

Exemplo: quando um atendente entra em pausa, o sistema pode registrar a pausa para cada fila em que o atendente estava associado.

Por isso, ao gerar relatórios, o sistema consumidor deve considerar:

39. Exemplo de Consumo em PHP

<?php

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

$params = [
    'user'      => '{{user}}',
    'pwd'       => '{{pass}}',
    'app'       => 'login',
    'end_date'  => '{{dt_init}}',
    'intervalo' => 0,
    '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);

40. 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('app', 'login');
url.searchParams.set('end_date', '{{dt_init}}');
url.searchParams.set('intervalo', '0');
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);

41. Exemplo de Leitura do Campo csv em JavaScript

const registros = data.csv;

registros.forEach((item) => {
  console.log({
    idLog: item.pk_log,
    idAgente: item.id_agent,
    agente: item.log_name,
    dataHora: item.dt_log,
    codigoEvento: item.event_log,
    status: item.st_name,
    ramal: item.ramal,
    idFila: item.queue,
    fila: item.q_name,
    inicioStatusAnterior: item.dt_st,
    tempoSegundos: item.tempo,
    codigoStatusAnterior: item.event_st,
    statusAnterior: item.ed_name,
    limiteMinutos: item.est_min,
  });
});

42. Exemplo de Agrupamento por Agente

const registros = data.csv;

const porAgente = registros.reduce((acc, item) => {
  const agente = item.id_agent;

  if (!acc[agente]) {
    acc[agente] = {
      id_agent: item.id_agent,
      log_name: item.log_name,
      registros: [],
    };
  }

  acc[agente].registros.push(item);

  return acc;
}, {});

console.log(porAgente);

43. Exemplo de Filtrar Somente Login e Logout

const registros = data.csv;

const loginLogout = registros.filter((item) => {
  return item.event_log === '-1' || item.event_log === '-2';
});

console.log(loginLogout);

44. Exemplo de Filtrar Entrada e Saída de Fila

const registros = data.csv;

const eventosFila = registros.filter((item) => {
  return item.event_log === '-3' || item.event_log === '-4';
});

console.log(eventosFila);

45. Exemplo de Filtrar Pausas

const registros = data.csv;

const pausas = registros.filter((item) => {
  return item.event_log !== null
    && !['-1', '-2', '-3', '-4'].includes(item.event_log);
});

console.log(pausas);

46. Exemplo de Conversão de Tempo

function segundosParaHora(segundos) {
  if (segundos === null || segundos === undefined || segundos === '') {
    return null;
  }

  const total = Number(segundos);

  if (Number.isNaN(total)) {
    return null;
  }

  const horas = Math.floor(total / 3600);
  const minutos = Math.floor((total % 3600) / 60);
  const seg = total % 60;

  return [
    String(horas).padStart(2, '0'),
    String(minutos).padStart(2, '0'),
    String(seg).padStart(2, '0'),
  ].join(':');
}

console.log(segundosParaHora('639'));

47. Tratamento de Retorno Vazio

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

{
  "status": 0,
  "csv": []
}

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

48. Validações Recomendadas no Sistema Consumidor

49. Possíveis Erros

50. 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.
• Proteger nomes de colaboradores em ambientes públicos.
• Mascarar ou anonimizar log_name quando o relatório for externo.
• Controlar permissões de acesso aos relatórios de jornada e pausas.

51. Boas Práticas de Performance

• Evitar consultas com intervalo=91 sem necessidade.
• Processar os dados de csv de forma paginada ou assíncrona quando o volume for alto.
• Agrupar registros por agente no sistema consumidor quando o objetivo for controle de jornada.
• Agrupar registros por fila quando o objetivo for análise operacional por fila.
• 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.

52. Checklist de Homologação

53. Resumo Técnico

54. Observação Final

A aplicação login deve ser utilizada para consultar a movimentação operacional dos atendentes no período informado.

O retorno fornece uma estrutura indicada para análise de login, logout, entrada em fila, saída de fila, entrada em pausa, saída de pausa e status operacionais.

Por retornar dados internos de operação e identificação de colaboradores, a integração deve aplicar cuidados de segurança, principalmente em relação a credenciais, nomes de atendentes, ramais e relatórios de jornada.