Informações importantes
📢 Assista esse episódio do Explica aí pra Gente! para conhecer mais sobre a configuração e utilização do WebAgent.
O WebAgent é um serviço opcional necessário "apenas" nas estações de trabalho que precisem utilizar:
Para uso das rotinas padrão, como cadastros e relatórios, não existe impedimento no uso do ERP sem a utilização do WebAgent.
Os navegadores atuais possuem um ambiente de execução segura, chamado Sandbox, que impede o acesso à sua estação de trabalho.
O WebAgent permite esses acessos de forma segura, utilizando os seguintes mecanismos:
Baixe os instaladores do WebAgent a partir da Central de Downloads.
Para consultar todas as opções de configuração acesse aqui.
| Parâmetro | Descrição | Observações |
|---|---|---|
| VERSION | Define a versão dos instaladores do WebAgent disponíveis pra download |
|
| PORT(opcional) | Habilita uma porta específica para o WebAgent de todos os usuários |
|
Os parâmetros abaixo representam o Sistema Operacional e a Arquitetura(32/64 bits) do WebAgent:
| Parâmetro | Descrição |
|---|---|
| Windows_x86 | Windows 10/11 32 bits |
| Windows_x64 | Windows 10/11 64 bits |
| Darwin_universal | masOS 64 bits Universal Apps (mais informações aqui) |
| Linux_x64_deb | Linux 64 bits pacote DEB (Ubuntu) |
| Linux_x64_rpm | Linux 64 bits pacote RPM (Fedora, Oracle Linux e Red Hat) |
[WEBAGENT] VERSION=1.x.x "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>" Windows_x86=webagent/web-agent-1.x.x-windows-x86.setup.exe Windows_x64=webagent/web-agent-1.x.x-windows-x64.setup.exe Darwin_universal=webagent/web-agent-1.x.x-darwin-universal.dmg Linux_x64_deb=webagent/web-agent-1.x.x-linux-x64.deb Linux_x64_rpm=webagent/web-agent-1.x.x-linux-x64.rpm
[WEBAGENT] VERSION=1.x.x "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>" Windows_x86=C:\totvs\files\web-agent-1.x.x-windows-x86.setup.exe Windows_x64=C:\totvs\files\web-agent-1.x.x-windows-x64.setup.exe Darwin_universal=C:\totvs\files\web-agent-1.x.x-darwin-universal.dmg Linux_x64_deb=C:\totvs\files\web-agent-1.x.x-linux-x64.deb Linux_x64_rpm=C:\totvs\files\web-agent-1.x.x-linux-x64.rpm
Neste exemplo utilizaremos o arquivo de configuração com o nome webagent.json, na mesma pasta do AppServer, mas tanto o nome do arquivo quanto o diretório são de sua escolha, ajuste a configuração de acordo com sua necessidade, por exemplo:
agentJsonUpdate=/home/admin/file_config/installers.json
Para definir o caminho dos instaladores inclua o parâmetro agentJsonUpdate na seção [WebApp] em seu arquivo AppServer.INI.
[WEBAPP] Port=5002 ENABLE=1 agentJsonUpdate=webagent.json
Seguindo nosso exemplo, crie agora o arquivo webagent.json na mesma pasta do AppServer.
Os arquivos para download serão disponibilizados em uma subpasta do AppServer, exemplo: /home/admin/totvs/appserver/webagent/
| Parâmetro | Descrição | Observações |
|---|---|---|
| VERSION | Define a versão dos instaladores do WebAgent disponíveis pra download |
|
{
"version": "1.x.x","<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
"windows_x86": "webagent\\web-agent-1.x.x-windows-x86-release.setup.exe",
"windows_x64": "webagent\\web-agent-1.x.x-windows-x64-release.setup.exe",
"darwin_universal": "20-10-10-p12_smartclient_web-agent_1.x.x_mac-universal.dmg",
"linux_x64_deb": "webagent\\web-agent.deb",
"linux_x64_rpm": "webagent\\web-agent.rpm"
}
{
"version": "1.x.x", "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
"windows_x86": "webagent/web-agent-1.x.x-windows-x86-release.setup.exe",
"windows_x64": "webagent/web-agent-1.x.x-windows-x64-release.setup.exe",
"darwin_universal": "20-10-10-p12_smartclient_web-agent_1.x.x_mac-universal.dmg",
"linux_x64_deb": "webagent/web-agent.deb",
"linux_x64_rpm": "webagent/web-agent.rpm"
}
| Parâmetro | Descrição | Observações |
|---|---|---|
| PORT(opcional) | Habilita uma porta específica para o WebAgent de todos os usuários |
|
[WEBAGENT] Port=21021 ...
Ao habilitar essa chave, a opção "Habilita/Desabilita o Agente Local" não será mais exibida na tela de configuração para o usuário.
A partir do WebAgent 1.0.15 e WebApp 10.0.6 (apenas Onça Preta), é possivel definir a atualização automática de arquivos extras, como por exemplo, os arquivos do FrontLoja.
Importante
Esta implementação foi feita exclusivamente para Windows.
As chaves a seguir definem o caminho para um arquivo ZIP, que deverá conter a estrutura de diretórios e arquivos que o cliente deseja descompactar na pasta do WebAgent.
📢 Estas chaves estão disponiveis tanto no arquivo AppServer.INI quanto no arquivo JSON de configuração.
| Parâmetro | Descrição |
|---|---|
| Windows_x86_extras | Caminho para o arquivo ZIP que deverá conter a estrutura de diretórios e arquivos, na arquitetura 32 bits, que será descompactada na pasta do WebAgent. |
| Windows_x64_extras | Caminho para o arquivo ZIP que deverá conter a estrutura de diretórios e arquivos, na arquitetura 64 bits, que será descompactada na pasta do WebAgent. |
[WEBAGENT] Windows_x86_extras=C:\totvs\files\DLL_SIGALOJA_Win32.zip Windows_x64_extras=C:\totvs\files\DLL_SIGALOJA_Win64.zip
Acessando a Tela de Parâmetros do WebApp, agora será exibida a tela para download dos instaladores:
Importante
O popup para instalação deixará de ser exibido assim que a primeira conexão entre o WebAgent e o Navegador for bem sucedida, para que não induza o usuário a instalar mais de uma vez a ferramenta.
O checkbox "Não mostrar novamente" pode ser usado caso o usuário não precise instalar o WebAgent, e também não queira que esta opção continue sendo exibida.
🚨 A atualização automática do WebAgent foi implementada apenas para o Windows, e acontecerá sempre que o Administrador do ERP atualizar a versão do WebAgent nos arquivos de configuração.
Para Linux e macOS é necessário informar a senha do administrador do computador no momento da instalação/atualização, impossibilitando a atualização automática.
O instalador vai sugerir o Sistema Operacional e a Arquitetura(32/64 bits).
Caso utilize o Windows 64 bits, mas precise integrar o ERP com o Microsoft Office 32 bits, poderá baixar o WebAgent 32 bits, mais detalhes aqui.
Instalando no Windows (topo)Após o download do instalador, basta iniciar sua instalação, que irá seguir sem intervenção do usuário.
O programa ficará disponível no menu, como neste exemplo utilizando o Windows 11.
O WebApp irá iniciar o WebAgent sempre que necessário, mais detalhes consulte a seção Habilitar WebAgent na Tela de Parâmetros.
Apenas para testes, você pode iniciar o WebAgent manualmente, ele será exibido na bandeja de ícones:
Instalando no Linux (topo)Para mais detalhes sobre como baixar o WebAgent acesse aqui, escolha o download para o seu Linux, sendo o arquivo .deb para Ubuntu e o .rpm para o Fedora, Oracle Linux e Red Hat.
Video com detalhes do processo:
Ubuntusudo apt install ./web-agent<versao>.deb
chmod +x ./web-agent<versao>.deb
Fedora, 
Oracle Linuxsudo dnf install oracle-epel-release-el9 sudo dnf update
sudo dnf install libappindicator-gtk3
sudo dnf install gnome-extensions-app gnome-shell-extension-appindicator
🚨 Importante: Efetue o logout e se logue novamente no sistema operacional para efetivar a instalação da extensão acima.
Acesse o aplicativo Extensões
Habilite a extensão AppIndicator
sudo dnf install ./web-agent<versao>.rpm
chmod +x ./web-agent<versao>.deb
Instalando no macOS (topo)🚨 Importante
O WebAgent, como qualquer aplicação que não seja disponibilizada via Apple Store, precisa ser autorizado manualmente para execução.
Este é o link para documentação oficial para o macOS Sequoia 15: https://support.apple.com/pt-br/guide/mac-help/mh40616/mac
Para consultar outra versão do sistema operacional, selecione a versão correta:
Este exemplo de instalação/autorização se baseia no macOS Sequoia. (💡 Dica: Clique nas imagens para melhor visualização )
Após baixar o arquivo de instalação para macOS (Universal), com a extenção .dmg, execute o instalador e na sequencia arraste o web-agent para pasta Aplicações (Applications)
Caso esteja atualizando o web-agent, pressione o botão Atualizar (Replace)
Abra o web-agent na pasta Aplicações e pressione o botão Done
Acesse as configurações do seu Mac e na sequencia Privacidade e Segurança (Privacy & Security)
Role até localizar a seção Segurança (Security) e na sequencia clique em Abrir Mesmo Assim (Open Anyway)
Confirme, cliquando em Abrir Mesmo Assim (Open Anyway)
Clique em Use sua Senha (Use Password)
Digite o usuário e senha de um usuário com autorização de Administrador do equipamento
Clique no botão OK para autorizar a execução do WebAgent
Para utilizar o Websocket Secure (wss) é necessário registrar o TOTVS Certificate em seu sistema operacional.
Para usuários Windows (automático) (topo)O registro é automático para Windows 10/11, 32 ou 64 bits, e será efetivado na primeira execução do WebAgent.
🚨 Importante
Durante a primeira execução do WebAgent, caso seja apresentada a tela de confirmação para o registro do certificado, selecione a opção "SIM", "OK" ou "CONFIRMAR", essa opção que pode variar dependendo da versão do Windows em uso.
Dicas para configuração do Firefox
Na configuração do Firefox pode estar desabilitada a utilização de certificados do sistema, causando falha na conexão com o WebAgent, é necessário habilitar os certificados da seguinte maneira:
Para usuários Linux (automático a partir da versão 1.0.15) (topo) Ubuntu Acesse seu navegador e efetue o registro:
Para o Google Chrome
Para o Microsoft Edge
Na barra de navegação digite: edge://settings/privacy/manageCertificates
Acesse: Authorities (autoridades)
Na sequência: Import (importar)
Selecione todos os Trusts e Okay
Para o Firefox
Na barra de navegação digite: about:preferences#privacy
Acesse: View Certificates… (verificar certificados)
Acesse: Authorities (autoridades)
Na sequência: Import (importar)
Selecione todos os Trusts e OK
Fedora, Oracle Linux e 
Red HatPara Google Chrome e Firefox o registro do certificado segue os mesmos passos do Ubuntu.
Para usuários macOS (topo)🚨 Importante
Importante: O processo de registro do certificado deve ser feito uma unica vez, atualizações do WebAgent assumirão o certificado já registrado automaticamente.
O WebAgent, como qualquer aplicação que não seja disponibilizada via Apple Store, precisa ter seus certificados instalados manualmente para execução.
Este é o link para documentação oficial para o macOS Sequoia 15: https://support.apple.com/pt-br/guide/keychain-access/kyca2431/mac
Para consultar outra versão do sistema operacional, selecione a versão correta:
Este exemplo de registro do certificado se baseia no macOS Sequoia. (💡 Dica: Clique nas imagens para melhor visualização )
Após instalar o WebAgent, localize o arquivo totvs_certificate_CA.crt na pasta /Applications/web-agent.app/Contents/MacOS
No App Acesso às Chaves (Keychain Access) 
, selecione Sistema (System), e na sequência Certificados (Certificates).
Importante
🚨 No macOS Sequoia, o atalho pro Keychain mudou, sendo acessado pelo caminho: /System/Library/CoreServices/Applications/Keychain Access.app
Arraste o arquivo do certificado para o App Acesso às Chaves (Keychain Access).
Configure a confiança do certificado, clicando com o botão direito do mouse sobre o arquivo, e escolhendo a opção Obter Informações (Get Info).
Expanda a opção Confiança (Trust), e coloque Confiar Sempre (Always Trust) para todas as opções disponíveis.
Ao confirmar as informações, se for solicitado usuário e senha, utilize um usuário com acesso de administrador.
Para habilitar o uso do WebAgent pelo WebApp, na Tela de Parâmetros, selecione o botão de configuração.
Escolha a porta de inicialização do WebAgent (por padrão é a 21021).
Na sequencia feche essa janela clicando no X na parte superior da janela de configuração.
Ao confirmar os dados na Tela de Parâmetros será exibida a mensagem abaixo, solicitando autorização para abertura do WebAgent, basta clicar no botão Abrir.
Caso a conexão com o WebAgent falhe ou a solicitação de autorização seja ignorada, será exibida a mensagem de erro a seguir:
O WebAgent pode ser iniciado via linha de comando, os parâmetros podem ser usados em conjunto, as opções são:
| Parâmetro | Descrição |
|---|---|
| web-agent -h ou --help | Exibe help com essas opções |
| web-agent -c ou --console | Inicia o WebAgent em console(linha de comando) omitindo o systray(icone na bandeja), nesse exemplo iniciamos o WebAgent em console na porta 21023: web-agent -c --port 21023 |
| web-agent -v ou --version | Exibe a versão do WebAgent, exemplo: web-agent -v |
| web-agent -t ou --tray | Abre o WebAgent via systray (default) |
| web-agent --port | Define uma porta específica para o WebAgent (a porta padrão é a 21021) |
| web-agent --locallog <n> | 0 (default): Desabilita o log de execução; |
Vídeo com detalhes do processo:
Permite abrir uma janela destacada do navegador a partir do WebAgent.
Dicas importantes
Durante a primeira execução com comando launch, a janela pode não ser exibida de forma maximizada, impedindo uma melhor experiência, maximize a janela, e nas próximas execuções o navegador irá respeitar o estado em que foi encerrado.
Importante: O comando launch deve obrigatóriamente ser o primeiro da linha de comando, exemplo:
web-agent launch...
Quando utilizado o comando launch, o WebAgent iniciará em uma porta aleatória, permitindo multiplas execuções, cada uma em sua porta específica.
*Para execução de aplicações que não utilizam interface, como processamentos e execução de jobs, utilize a opção --headless, mais informações acesse aqui.
webagent launch "ip+porta+[parâmetros<opcional>]" --browser="caminho para o navegador"
Nos exemplos abaixo será aberto o SIGAFAT e preenchidos os parâmetros de abertura (&A=), artificio utilizado em produtos como SIGALOJA, e útil em algumas customizações.
C:\Users\Administrator\AppData\Local\Programs\web-agent\web-agent.exe launch "http://10.173.9.215:5011?E=padrao&P=SIGAFAT&A=param1&A=param2&A=param3" --browser="C:\Program Files\Google\Chrome\Application\chrome.exe"
/opt/web-agent/web-agent launch "http://10.173.9.215:5011?E=padrao&P=SIGAFAT&A=param1&A=param2&A=param3" --browser="/usr/bin/microsoft-edge"
| Parâmetro de linha para a URL | Descrição | Observações |
|---|---|---|
| &E= | Indica o nome do ambiente que será utilizado para definições gerais. | |
| &P= | Identifica o programa inicial que será executado. | |
| &A= | Identifica um parâmetro que será passado para o programa inicial. |
|
Vídeo com detalhes do processo:
A partir da versão 1.0.9 do WebAgent será possível executar programas sem interface gráfica, com o objetivo de dinamizar automações, testes e etc.
Nesse modo é recomendado o uso dos navegadores Google Chrome, Microsoft Edge ou Mozilla Firefox.
webagent launch "ip+porta+[parâmetros<opcional>]" --browser="caminho para o navegador" --headless
O exemplo abaixo executa a função de usuário u_headless em um navegador sem interface gráfica.
C:\Users\Administrator\AppData\Local\Programs\web-agent\web-agent.exe launch "http://10.173.9.215:5011?E=padrao&P=u_headless" --browser="C:\Program Files\Google\Chrome\Application\chrome.exe" --headless
/opt/web-agent/web-agent launch "http://10.173.9.215:5011?E=padrao&P=u_headless" --browser="/usr/bin/microsoft-edge" --headless
/Applications/web-agent.app/Contents/MacOS/web-agent launch "http://10.173.9.215:5011?E=padrao&P=u_headless" --browser="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless
Dica importante
O Mozilla Firefox, em Linux e modo headless, pode recusar os certificados de autoridade CA já registrados, impossibilitando o uso.
É possível utilizar policies.json do navegador para contornar esse problema:
O parâmetro de linha &A pode ser utilizado multiplas vezes.
O valor recebido pelo programa através do parâmetro é do tipo caractere, mesmo que seja preenchido um valor numérico.{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true,
"Install" [
"/opt/web-agent/totvs_certificate_CA.crt"
]
}
}
}
Video sobre o tema
O WebAgent para Linux e macOS será distribuido somente na versão 64 bits.
Para Windows ele será distribuido também na versão 32 bits, devido a dois cenários:
Cenário 2
Utilizar o Windows 64 bits, o Office 32 bits e uma integração com DLLs 64 bits (o inverso pode ocorrer).
Este cenário é mais complexo, faremos o mesmo processo que já era conhecido nessa situação para o SmartClient Desktop, manteremos duas instalações do WebAgent na estação do usuário, uma 32 e uma 64 bits.
Ao fim do processo abaixo, iremos executar cada WebAgent a partir do parâmetro launch:
web-agent.exe launch "ip:porta para o Servidor do WebApp" --browser="caminho completo para seu navegador"
Mais alguns detalhes sobre arquitetura clique aqui.
Importante
Para verificar a arquitetura de seu pacote Microsoft Office clique aqui ou acione o suporte da Microsoft.
Para verificar a arquitetura das DLLs de alguma ferramenta que utilize, acione o suporte do equipamento ou ferramenta em questão.
Integração com o Microsoft Excel, mais informações aqui. (💡 Dica: Clique nas imagens para melhor visualização )
Consumindo uma DLL através da função ExeDllRun3:
Executando uma aplicação nativa através da função ShellExecute:
Retornando as pastas e arquivos de um diretório através da função Directory:
Recuperando a configuração da estação de trabalho através do Shift+F6.
O WebAgent não é homologado para navegadores utilizados a partir de Metaframes, RDPs ou Web enablers, como:
Devido à simplificação na montagem do ambiente com o WebApp, nossa arquitetura não depende das ferramentas acima para operação dos ERPs Protheus/Logix.
O WebAgent não é homologado para sistemas operacionais :
Importante
A homologação de uma distro base Linux permite o uso se suas flavors e spins Oficiais, pois essas variantes mantém as mesmas bibliotecas que sua base, exemplo:
🚨Isso não significa que os spins são Homologados, eles serão mantidos como "Suportados", havendo diferenças de comportamentos nos flavors e spins, cada caso será avaliado, podendo impedir o suporte a essa determinada distro.
Window 32 e 64 bits Linux 64 bits Ubuntu 22.04 LTS (recomendamos o uso do Ubuntu 24.04 LTS) Ubuntu 24.04 LTS ou superior (a partir do WebAgent 1.0.15)Fedora 41 (a partir do WebAgent 1.0.15)
Oracle Linux 9.x (a partir do WebAgent 1.0.15)
Red Hat Enterprise Linux Desktop 8.x
🚨 Recomendamos o uso do Fedora ou do Oracle Linux, ambas distros gratuitas, e com a mesma base do Red Hat.
macOS x86_64 e Universal(ARM64) 🚨 A tentativa de utilizar a versão Universal em macOS anterior resultará no erro abaixo:
Esta seção manterá informações sobre os Sistemas Operacionais em processo de homologação para o WebAgent.
As datas de inicio e finalização da homologação poderão sofrer alterações dependendo do processo.