Í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: extrato — Consulta de Extrato de Atendimentos

1. Objetivo

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

A aplicação extrato permite consultar registros detalhados de atendimentos realizados em uma ou mais filas, retornando informações operacionais da chamada, dados do cliente, dados do serviço, agente responsável, gravação, tabulação, avaliação, eventos da ligação e indicadores de tempo.

Os dados retornados podem ser utilizados para auditoria, relatórios analíticos, conferência de atendimento, integração com sistemas externos, dashboards e exportações operacionais.

2. Endpoint

3. URL da Requisição

{{url}}/agi/app.php?user={{user}}&pwd={{pass}}&app=extrato&end_date={{dt_init}}&intervalo=0&key_agents=&key_queues=sac&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 o extrato de atendimentos, o parâmetro app deve receber o valor:

app=extrato

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-10-08

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

2025-10-08 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-10-08.

11.2 Exemplo com intervalo igual a 1

Período calculado:

Neste caso, a consulta considera o período de 2025-10-07 00:00:00 até 2025-10-08 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=sac

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

SAC

15. Exemplo de Requisição cURL

curl --location '{{url}}/agi/app.php?user={{user}}&pwd={{pass}}&app=extrato&end_date={{dt_init}}&intervalo=0&key_agents=&key_queues=sac&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-10-08 00:00:00",
    "end": "2025-10-08 23:59:59",
    "intervalo": 0
  },
  "key_agents": null,
  "key_queues": [
    "sac"
  ],
  "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-10-08 00:00:00",
    "end": "2025-10-08 23:59:59",
    "intervalo": 0
  }
}

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": [
    "sac"
  ]
}

23. Campo csv

O campo csv contém os registros detalhados do extrato de atendimento.

Diferente da aplicação agent, que retorna dados consolidados por agente, a aplicação extrato retorna registros detalhados com informações da chamada, cliente, serviço, evento, gravação, tabulação, avaliação e indicadores de tempo.

Cada item dentro de csv é identificado por uma chave composta.

Formato observado da chave:

{protocolo}-{agent_id}-{queue_id}-{event_id}

Exemplo protegido:

{
  "PROTOCOLO_EXEMPLO-AGENT_ID-QUEUE_ID-EVENT_ID": {
    "Protocolo ": "PROTOCOLO_EXEMPLO",
    "callerid": "TELEFONE_MASCARADO",
    "telefone_primario": "TELEFONE_MASCARADO",
    "telefone_de_cadastro_igual": 1,
    "nome_razaosocial": "CLIENTE_EXEMPLO",
    "cpf_cnpj": "DOCUMENTO_MASCARADO",
    "date": "2025-10-08 08:06:35",
    "event": "COMPLETEAGENT",
    "queue_id": "129",
    "queue": "SAC",
    "agent_id": "0000",
    "agent": "NOME_DO_AGENTE",
    "filename": "{{url_gravacao}}/arquivo.mp3",
    "nota_avaliacao": "3",
    "situacao": "Não Opinou.",
    "tabulacao": "DESCRICAO_DA_TABULACAO",
    "TME": "00:00:02",
    "TMA": "00:03:03",
    "SLA": "1",
    "SLA-P": "100,00%",
    "all_call": "00:03:03",
    "all_esp": "00:00:02",
    "max_esp": "00:00:02"
  }
}

24. Grupos de Campos do Extrato

25. Campos de Identificação da Chamada

26. Campos de Cliente

27. Campos de Serviço

28. Campos de Atualização Cadastral

29. Campos de Fila e Agente

30. Campos de Eventos e Indicadores da Chamada

31. Eventos Observados

32. Campos de Gravação

O campo filename pode retornar uma URL de gravação em formato .mp3.

Por segurança, em documentações públicas ou exemplos externos, a URL real da gravação deve ser substituída por placeholder.

{{url_gravacao}}/gravacoes/2025-10-08/arquivo.mp3

33. Campos de Avaliação

Exemplo de situação observada:

Não Opinou.

34. Campos de Rechamada

35. Campos de Tabulação

Exemplos de tabulação podem representar motivos como informação, cancelamento, atualização cadastral, segunda via, suporte, indisponibilidade, transferência ou outros tipos definidos na operação.

36. Campos Complementares

37. Indicadores de Tempo

38. Campo filas

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

{
  "filas": [
    {
      "queue_id": "129",
      "queue": "SAC"
    }
  ]
}

39. Exemplo de Consumo em PHP

<?php

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

$params = [
    'user'       => '{{user}}',
    'pwd'        => '{{pass}}',
    'app'        => 'extrato',
    'end_date'   => '{{dt_init}}',
    'intervalo'  => 0,
    'key_agents' => '',
    'key_queues' => 'sac',
    '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', 'extrato');
url.searchParams.set('end_date', '{{dt_init}}');
url.searchParams.set('intervalo', '0');
url.searchParams.set('key_agents', '');
url.searchParams.set('key_queues', 'sac');
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 = Object.values(data.csv);

registros.forEach((item) => {
  console.log({
    protocolo: item['Protocolo '],
    data: item.date,
    evento: item.event,
    fila: item.queue,
    agente: item.agent,
    telefone: item.callerid,
    cliente: item.nome_razaosocial,
    documento: item.cpf_cnpj,
    servico: item.nome_servico,
    statusServico: item.status_servico,
    gravacao: item.filename,
    tabulacao: item.tabulacao,
    nota: item.nota_avaliacao,
    situacao: item.situacao,
    tme: item.TME,
    tma: item.TMA,
    sla: item['SLA-P'],
  });
});

42. Exemplo de Leitura com Proteção de Dados

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

const dadosProtegidos = registros.map((item) => ({
  protocolo: item['Protocolo '],
  data: item.date,
  evento: item.event,
  fila: item.queue,
  agente: item.agent,
  telefone: item.callerid ? '***' : null,
  cliente: item.nome_razaosocial ? 'CLIENTE_PROTEGIDO' : null,
  documento: item.cpf_cnpj ? 'DOCUMENTO_PROTEGIDO' : null,
  servico: item.nome_servico,
  statusServico: item.status_servico,
  tabulacao: item.tabulacao,
  nota: item.nota_avaliacao,
  situacao: item.situacao,
  tme: item.TME,
  tma: item.TMA,
  sla: item['SLA-P'],
}));

console.log(dadosProtegidos);

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

44. Validações Recomendadas no Sistema Consumidor

45. Possíveis Erros

46. 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.
• Não expor telefones, CPF/CNPJ, nomes de clientes ou URLs reais de gravações em ambientes públicos.
• Mascarar dados pessoais antes de enviar para dashboards externos, BI público ou ambientes de teste.
• Controlar permissões de acesso às gravações retornadas no campo filename.

47. 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.
• Em relatórios extensos, processar os dados de csv de forma paginada ou assíncrona no sistema consumidor.

48. Checklist de Homologação

49. Resumo Técnico

50. Observação Final

A aplicação extrato deve ser utilizada para consultas detalhadas de atendimentos.

O retorno fornece uma estrutura indicada para análise individual de chamadas, contendo protocolo, cliente, serviço, evento, fila, agente, gravação, avaliação, tabulação e indicadores operacionais.

Por retornar dados sensíveis, a integração deve aplicar cuidados adicionais de segurança, principalmente em relação a credenciais, dados pessoais de clientes e links de gravações.