API Web Agent — Lorentz Server¶

1. Visão geral¶

A API Web Agent permite que operadores utilizem o sistema Lorentz diretamente pelo navegador, sem instalar o aplicativo desktop. A comunicação acontece via banco de dados (tabela de situação CTI), eliminando a necessidade de conexão TCP direta com o servidor.

Quando usar¶

Operadores remotos que não podem instalar software
Ambientes com restrições de rede (NAT, VPN)
Operações via interface web integrada ao Supervisor

Diferenças em relação ao agente desktop¶

Aspecto	Agente Desktop	Agente Web
Conexão	TCP direta com o servidor	Via banco de dados
Instalação	Necessária (aplicativo)	Não necessária (navegador)
Latência	Baixa (~milissegundos)	Moderada (~1 segundo)
Softphone	Integrado (SIP)	Externo (webphone ou telefone IP)
Funcionalidades	Completas	Completas (mesmos comandos)

2. Como funciona¶

Fluxo de comunicação¶

┌─────────────────┐       ┌──────────────┐       ┌──────────────┐
│   Navegador     │ SQL   │  Banco de    │  SQL  │   Lorentz    │
│   do Agente     ├──────►│  Dados       │◄──────┤   Server     │
│                 │◄──────┤  (SQL Server) │──────►│              │
└─────────────────┘       └──────────────┘       └──────────────┘
      Escreve                                        Lê a cada
      comando                                        1 segundo
      na tabela                                      e processa

Ciclo de operação¶

Registro: quando o agente acessa a interface web, um registro é criado na tabela de situação
Servidor detecta: o Lorentz Server verifica a tabela a cada segundo e cria uma sessão interna para o agente
Comandos: o agente escreve comandos na coluna "Cliente" da tabela
Processamento: o servidor lê o comando, processa (mesmo tratamento do agente desktop) e grava a resposta na coluna "Servidor"
Resposta: a interface web lê a resposta e atualiza a tela

3. Tabela de situação CTI¶

A tabela de situação é o canal de comunicação entre agentes web e o servidor.

Campos principais¶

Campo	Direção	Descrição
Apelido	Web → Servidor	Nome de login do agente
HashCode	Servidor → Web	Identificador único da sessão no servidor
Cliente	Web → Servidor	Comando enviado pelo agente (formato de pacote)
Servidor	Servidor → Web	Resposta do servidor (formato de pacote)
Estado do ramal	Servidor → Web	Código numérico do estado atual do ramal
Origem (A)	Servidor → Web	Ramal/número de origem da chamada
Destino (B)	Servidor → Web	Ramal/número de destino da chamada
Externo	Servidor → Web	Número externo do interlocutor
Número do serviço	Servidor → Web	Serviço em atendimento
Gravação automática	Servidor → Web	Se deve gravar automaticamente
Código do atendimento	Servidor → Web	Identificador do atendimento atual
Chamada receptiva	Servidor → Web	Código da chamada receptiva
Chamada ativa	Servidor → Web	Código da chamada ativa
Data/hora	Servidor → Web	Timestamp da última atualização
Ramal	Servidor → Web	Ramal associado à sessão
XML da URA	Servidor → Web	Dados de screen pop da URA

4. Comandos disponíveis¶

O agente web utiliza os mesmos comandos do agente desktop, escritos na coluna "Cliente" no formato de pacote padrão:

Operação	Descrição
Login	Autenticar no sistema com usuário, senha, grupo e ramal
Pausa eventual	Entrar/sair de pausa eventual
Pausa produtiva	Entrar/sair de pausa produtiva (com motivo)
Fazer chamada	Discar para número ou ramal
Atender	Atender chamada recebida
Desligar	Encerrar chamada atual
Reter	Colocar chamada em espera
Transferir	Transferir chamada para outro ramal
Consultar fila	Verificar status da fila de espera
Solicitar lista de agentes	Ver agentes logados
Chat	Enviar mensagem a outro agente
Alerta supervisor	Solicitar atenção do supervisor
Alterar senha	Mudar senha de acesso

5. Detecção de sessão¶

Início da sessão¶

Interface web insere registro com o Apelido preenchido e HashCode vazio
Servidor detecta registro sem HashCode e cria nova sessão interna
Servidor grava o HashCode da sessão na tabela
Interface web detecta o HashCode e passa a usá-lo nas operações

Fim da sessão¶

Interface web remove o registro da tabela (ou o HashCode é limpo)
Servidor detecta que o HashCode não existe mais na tabela
Servidor finaliza a sessão interna (registra logout)

Detecção de desconexão¶

O servidor verifica a cada ciclo se os HashCodes das sessões internas ainda existem na tabela. Se uma sessão não tem mais registro correspondente:

Se o agente tem apelido definido → finaliza com logout
Se não tem apelido → remove silenciosamente

6. Exemplo de integração¶

Para criar um agente web (lado da aplicação web)¶

Inserir registro na tabela de situação:

Apelido = "operador01"
HashCode = "" (vazio — servidor preencherá)

Aguardar o servidor preencher o HashCode (poll a cada 1-2 segundos)
Enviar comando de login na coluna Cliente:
```
CHR(3) + "1;0;operador01;senha123;Suporte;200;2;1.0" + CHR(7)
```
Campos: código (1=login), sequência, usuário, senha, grupo, ramal, tipo (2=agente), versão
Ler resposta na coluna Servidor (poll a cada 1 segundo)
Para cada operação, gravar comando na coluna Cliente e ler resposta na coluna Servidor

Para encerrar a sessão¶

Remover o registro da tabela ou limpar o HashCode.

7. Considerações¶

Latência¶

A comunicação via banco de dados tem latência de 1-2 segundos (ciclo do servidor + poll da interface). Para operações telefônicas críticas, o softphone SIP funciona independentemente — o delay afeta apenas comandos e notificações na tela.

Escalabilidade¶

Cada agente web gera consultas SQL a cada ciclo do servidor. Para grandes volumes de agentes web, considere:

Otimizar a tabela de situação com índices
Monitorar carga no SQL Server
Limitar o número de agentes web simultâneos

Segurança¶

Os comandos na coluna "Cliente" são processados com o mesmo nível de validação dos agentes TCP
A autenticação (login/senha) é validada no banco de dados
Os registros da tabela devem ser protegidos por permissões de banco de dados adequadas

Última atualização: Junho 2025