Í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: pesquisa_simples — Consulta de Pesquisa Simples de Satisfação

1. Objetivo

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

A aplicação pesquisa_simples permite consultar registros de pesquisas simples de satisfação vinculadas aos atendimentos realizados no sistema.

O retorno apresenta informações como identificador único da chamada, data e hora da pesquisa, agente responsável, nota registrada, telefone de origem, fila, identificadores internos e situação da pesquisa.

Os dados podem ser utilizados para relatórios de qualidade, acompanhamento de satisfação, dashboards gerenciais, análise por agente, análise por fila e integrações externas.

2. Endpoint

3. URL da Requisição

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

app=pesquisa_simples

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. Filtro por Fila

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

Quando vazio:

key_queues=

A API não restringe a consulta a uma fila específica.

Quando informado, deve conter a identificação da fila desejada.

key_queues=sac

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

SAC

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

15. Exemplo de Requisição cURL

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

23. Campo endpont

O campo endpont é retornado pela aplicação como uma estrutura complementar.

{
  "endpont": {
    "": null
  }
}

Este campo pode ser tratado como informação auxiliar da aplicação.

24. Campo csv

O campo csv contém os registros da pesquisa simples.

Cada item dentro de csv é identificado pelo uniqueid da chamada/pesquisa.

Formato observado da chave:

{uniqueid}

Exemplo protegido:

{
  "UNIQUEID_EXEMPLO": {
    "uniqueid": "UNIQUEID_EXEMPLO",
    "datetime": "2026-06-10 08:00:00",
    "nagent": "NOME_DO_AGENTE",
    "nota": "3",
    "callerid": "TELEFONE_MASCARADO",
    "queue": "SAC",
    "qname": "129",
    "qagent": "0000",
    "qevent": "12",
    "situacao": "Não Opinou."
  }
}

25. Campos Retornados em csv

26. Campo uniqueid

O campo uniqueid identifica de forma única a chamada ou o registro associado à pesquisa.

1781060857.1568334

Este campo pode ser usado para relacionar a pesquisa a outros registros de atendimento, gravações, extratos ou eventos internos, quando houver correspondência disponível em outros módulos.

27. Campo datetime

O campo datetime informa a data e hora do registro da pesquisa.

Formato observado:

YYYY-MM-DD HH:MM:SS

Exemplo:

2026-06-10 08:39:42

28. Campo nagent

O campo nagent informa o nome ou identificação do agente associado ao atendimento avaliado.

NOME_DO_AGENTE

29. Campo nota

O campo nota informa a nota registrada na pesquisa simples.

30. Campo callerid

O campo callerid informa o telefone de origem da chamada.

Exemplo protegido:

TELEFONE_MASCARADO

Por conter dado sensível, recomenda-se mascarar esse campo em ambientes públicos, relatórios externos ou dashboards compartilhados.

31. Campo queue

O campo queue informa o nome da fila associada à pesquisa.

Exemplos observados:

32. Campo qname

O campo qname representa o ID interno da fila.

33. Campo qagent

O campo qagent representa o ID interno do agente.

4690

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

34. Campo qevent

O campo qevent representa o ID interno do evento associado ao registro.

Exemplo observado:

12

35. Campo situacao

O campo situacao informa a situação da pesquisa.

Exemplo observado:

Não Opinou.

Esse campo deve ser tratado como texto.

36. Campo filas

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

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

37. Exemplo de Consumo em PHP

<?php

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

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

38. 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', 'pesquisa_simples');
url.searchParams.set('end_date', '{{dt_init}}');
url.searchParams.set('intervalo', '0');
url.searchParams.set('key_queues', '');
url.searchParams.set('key_agents', '');
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);

39. Exemplo de Leitura do Campo csv em JavaScript

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

registros.forEach((item) => {
  console.log({
    uniqueid: item.uniqueid,
    dataHora: item.datetime,
    agente: item.nagent,
    nota: item.nota,
    telefone: item.callerid,
    fila: item.queue,
    idFila: item.qname,
    idAgente: item.qagent,
    idEvento: item.qevent,
    situacao: item.situacao,
  });
});

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

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

const dadosProtegidos = registros.map((item) => ({
  uniqueid: item.uniqueid,
  dataHora: item.datetime,
  agente: item.nagent,
  nota: item.nota,
  telefone: item.callerid ? '***' : null,
  fila: item.queue,
  idFila: item.qname,
  idAgente: item.qagent,
  idEvento: item.qevent,
  situacao: item.situacao,
}));

console.log(dadosProtegidos);

41. Exemplo de Conversão Segura da Nota

function normalizarNota(nota) {
  if (nota === null || nota === undefined) {
    return null;
  }

  if (nota === 'None' || nota === '') {
    return null;
  }

  const numero = Number(nota);

  return Number.isNaN(numero) ? null : numero;
}

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

const pesquisas = registros.map((item) => ({
  uniqueid: item.uniqueid,
  agente: item.nagent,
  fila: item.queue,
  notaOriginal: item.nota,
  notaNormalizada: normalizarNota(item.nota),
}));

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

43. Validações Recomendadas no Sistema Consumidor

44. Possíveis Erros

45. 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 em ambientes públicos.
• Mascarar callerid antes de enviar para dashboards externos, BI público ou ambientes de teste.

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

47. Checklist de Homologação

48. Resumo Técnico

49. Observação Final

A aplicação pesquisa_simples deve ser utilizada para consultar registros de avaliação simples dos atendimentos.

O retorno fornece uma estrutura indicada para análise de satisfação por agente, fila e período, contendo identificador único, data e hora, agente, nota, telefone, fila, evento e situação da pesquisa.

Por retornar telefone de origem no campo callerid, a integração deve aplicar cuidados de segurança e mascaramento quando os dados forem exibidos fora de ambientes internos controlados.