Certificado HTTPS (TLS)¶

O servidor REST do Protheus roda em HTTPS (o PWA exige HTTPS ou localhost). O certificado é autoassinado, gerado pela ferramenta da TOTVS totvs_certificates, com o IP/host do servidor gravado no certificado (SAN).

Uso exclusivo do TOTVS | Application Server

Este recurso de geração de certificado é destinado exclusivamente ao TOTVS Application Server. Outros produtos/servidores não são suportados. Referência oficial: TDN — Geração de Certificado.

1. Gerar o certificado¶

A ferramenta acompanha o Application Server (fica na pasta bin\appserver\). Sintaxe:

totvs_certificates [-cert file] [-key file] [-passwd password] [-issuer name] [[-host HostName] ...] [-h|-help]

Parâmetro	Função	Padrão
`-cert`	Arquivo do certificado	`totvs_certificate.crt`
`-key`	Arquivo da chave privada	`totvs_certificate_key.pem`
`-passwd`	Senha do certificado	—
`-issuer`	Nome do emissor (¹)	1º host / 1º IP
`-host`	Registra N nomes ou IPs no certificado (SAN) (²)	—
`-h` / `-help`	Ajuda	—

Notas da TOTVS

(¹) Se o emissor não for definido, usa o primeiro nome de máquina; senão, o primeiro IP.
(²) Se nenhum -host for informado, inclui automaticamente o nome da máquina, os sufixos de domínio (DNS), localhost e 127.0.0.1.

Exemplo — servidor por IP (caso típico em LAN)¶

totvs_certificates.exe -host 192.168.1.3

Gera um certificado válido para https://192.168.1.3 (o IP do servidor Protheus da planta).

Exemplo — múltiplos nomes/IPs¶

totvs_certificates.exe -host 192.168.1.3 -host cliente.local -host www.cliente.com.br

Inclua todos os endereços de acesso

Coloque em -host todos os nomes/IPs pelos quais o terminal acessará o REST. Se o terminal usa o IP, o certificado precisa ter esse IP no SAN; se usa um nome, inclua o nome também.

Arquivos gerados¶

Arquivo	O que é	Onde usar
`totvs_certificate.crt`	Certificado folha (do servidor)	`appserver.ini` → `SslCertificate`
`totvs_certificate_key.pem`	Chave privada	`appserver.ini` → `SslCertificateKey`
`totvs_certificate_CA.crt`	Certificado raiz (CA) da TOTVS — valida a folha	`appserver.ini` → `SSLCertificateCA` e instalado nas estações

2. Configurar no `appserver.ini`¶

Aponte os três arquivos no bloco do servidor HTTPS (ver Autenticação e appserver.ini):

[HTTP_SSL_SERVER]
hostname=192.168.1.3
port=30019
SslCertificate=<...>\bin\appserver\totvs_certificate.crt
SslCertificateKey=<...>\bin\appserver\totvs_certificate_key.pem
SSLCertificateCA=<...>\bin\appserver\totvs_certificate_CA.crt

Reinicie o Application Server após trocar os arquivos.

3. Confiar o certificado nas estações (essencial no kiosk)¶

Cada terminal/estação que acessa o REST precisa confiar na raiz (CA) da TOTVS — instale o totvs_certificate_CA.crt (a raiz, não a folha):

Windows 11Android (tablet)

Importe totvs_certificate_CA.crt em Autoridades de Certificação Raiz Confiáveis (certmgr.msc → Autoridades de Certificação Raiz Confiáveis → Certificados → Importar).

Configurações → Segurança → Criptografia e credenciais → Instalar um certificado → Certificado CA, e selecione o totvs_certificate_CA.crt.

Por que a raiz é obrigatória no modo direto

Um fetch() para um endpoint com certificado não confiável falha de forma dura, sem tela de "avançar mesmo assim" (isso só existe para a página principal, não para sub-requisições). Sem a raiz instalada, o PWA até abre, mas as chamadas ao ERP falham. Com a raiz confiável, o PWA instala e as chamadas cross-origin funcionam sem aviso.

Modo LOCAL/proxy dispensa

Quando o front roda via proxy local (proxy.php com verificação SSL desligada), o certificado não precisa ser confiável no browser. Só o modo direto (browser → ERP na LAN) exige a raiz no aparelho.

4. Trocar o IP do servidor — checklist¶

O certificado folha é IP-bound (SAN = IP). Se o IP do Protheus mudar (ex.: demo em outra rede):

Regerar a folha para o novo IP (totvs_certificates.exe -host <novoIP>) → substituir totvs_certificate.crt + totvs_certificate_key.pem. A raiz continua a mesma.
appserver.ini → hostname=<novoIP>.
config.json (front) → API_BASE/API_TOKEN = https://<novoIP>:30019/rest.
Reiniciar o Application Server.
Nos aparelhos: nada — a raiz já instalada valida a folha nova. ✅

Verificação rápida no dia

Abra https://<novoIP>:30019/rest/ no navegador: cadeado limpo + 404 = certificado e bind OK. Não altere [CORS_UPD] AllowOrigins (essa é a origem do front, não o IP do ERP).

5. Produção séria: raiz dedicada¶

A raiz "TOTVS certificate CA" é compartilhada entre instalações TOTVS. Confiar nela significa que qualquer um com a ferramenta poderia emitir um certificado aceito pela estação (risco de MITM). Para uma operação de produção mais rígida, gere uma raiz dedicada (emissor próprio via -issuer) e instale apenas essa raiz nas estações.

Aviso de rede local (PNA) — modo hospedado

Quando o front está hospedado (origem pública, ex.: Hostinger) e chama um IP privado da LAN, o Chrome exibe um aviso de Private Network Access no painel de Problemas — hoje não bloqueia. O Chrome caminha para um prompt de permissão (1 clique por aparelho). Se um dia bloquear de vez, a saída é servir o front na própria LAN (same-origin).