Data de publicação: 25/06/2026
Produto: TOTVS Backoffice — Linha Protheus
Módulo: Framework / AppServer
Release relacionada: 12.1.2510
Tema: Padronização de nomes de ambientes no Protheus

📌 Objetivo

Orientar sobre a nova regra de validação de nomes de ambientes no TOTVS Protheus, aplicada a partir da Release 12.1.2510, que passa a restringir o uso de caracteres especiais nos nomes dos ambientes configurados no AppServer.

Essa mudança tem como objetivo aumentar a estabilidade, segurança e compatibilidade técnica do ambiente Protheus, principalmente em processos de acesso, execução de rotinas, integrações, migrações e chamadas realizadas por meio de comandos como RpcSetEnv.

✅ O que muda a partir da Release 12.1.2510

A partir da Release 12.1.2510, o Protheus passa a impedir o uso de ambientes com nomes que contenham caracteres especiais.

Na prática, se um ambiente estiver configurado com nome inválido, o acesso pela interface poderá ser bloqueado. Além disso, processos executados em segundo plano que utilizem o comando RpcSetEnv poderão apresentar geração de error log.

Essa alteração exige uma revisão prévia dos nomes dos ambientes existentes antes da atualização para a nova release.

🧩 Padrão permitido para nomes de ambientes

O nome do ambiente deverá seguir um padrão simples, sem acentos, espaços ou caracteres especiais.

Serão permitidos apenas:

• Letras maiúsculas de A a Z;

• Letras minúsculas de a a z;

• Números de 0 a 9;

• Underline _.

✅ Exemplos de nomes válidos

Abaixo estão exemplos de nomes de ambientes aceitos pelo novo padrão:

Esses nomes não possuem acentos, espaços, cedilha ou símbolos especiais, estando aderentes ao padrão esperado para a Release 12.1.2510.

🚫 Exemplos de nomes inválidos

Abaixo estão exemplos de nomes que não devem ser utilizados:

⚠️ Impacto em ambientes existentes

Ambientes já existentes que estejam com nomes fora do padrão poderão deixar de ser acessíveis após a atualização para a Release 12.1.2510.

Por esse motivo, é obrigatório revisar e, se necessário, renomear os ambientes antes da atualização.

Essa análise deve considerar todos os ambientes configurados no AppServer, como:

• Produção;

• Homologação;

• Desenvolvimento;

• Testes;

• Ambientes auxiliares;

• Ambientes utilizados por integrações;

• Ambientes utilizados por rotinas automáticas;

• Ambientes utilizados em jobs ou serviços agendados.

🔎 Pontos de atenção técnica

A restrição não se limita apenas ao acesso manual dos usuários ao ambiente.

Também devem ser avaliadas rotinas automáticas, integrações e customizações que utilizem o nome do ambiente internamente.

Entre os principais pontos de atenção estão:

• Chamadas com RpcSetEnv;

• Jobs configurados no AppServer;

• Serviços REST;

• Rotinas automáticas;

• Integrações com sistemas externos;

• Schedule;

• WebServices;

• APIs;

• Customizações ADVPL, TL++ ou integrações que informem o nome do ambiente;

• Scripts de inicialização ou monitoramento;

• Documentações internas que contenham referência ao nome antigo do ambiente.

🧭 Procedimento recomendado antes da atualização

Antes de atualizar o ambiente Protheus para a Release 12.1.2510, recomenda-se executar uma revisão técnica preventiva.

1. Levantar os ambientes existentes

Verifique todos os ambientes configurados nos arquivos de configuração do AppServer.

Exemplos comuns:

• appserver.ini;

• arquivos auxiliares de configuração;

• serviços adicionais do Protheus;

• configurações utilizadas por integrações.

2. Identificar nomes inválidos

Avalie se os nomes dos ambientes possuem:

• Acentos;

• Cedilha;

• Espaços;

• Hífen;

• Ponto;

• Barra;

• Caracteres especiais;

• Símbolos como @, #, $, %, &, *, entre outros.

Caso exista qualquer um desses caracteres, o ambiente deverá ser ajustado.

3. Definir novo padrão de nomenclatura

Defina nomes simples e padronizados.

Exemplos recomendados:

4. Ajustar configurações do AppServer

Após definir os novos nomes, realize os ajustes necessários nas seções de ambiente do AppServer.

É importante garantir que todas as referências estejam consistentes com o novo nome.

5. Revisar integrações e customizações

Verifique se existem fontes, integrações, agendas ou serviços utilizando o nome antigo do ambiente.

Essa etapa é fundamental para evitar falhas após a atualização.

6. Testar em homologação

Antes de aplicar a alteração em produção, recomenda-se validar o comportamento em ambiente de homologação.

Os testes devem contemplar:

• Login no Protheus;

• Acesso via SmartClient;

• Acesso via WebApp, quando aplicável;

• Serviços REST;

• Execução de jobs;

• Execução de rotinas automáticas;

• Integrações;

• Chamadas com RpcSetEnv;

• Processos críticos do cliente.

7. Atualizar documentação interna

Após a alteração, atualize todos os documentos técnicos que mencionem o nome dos ambientes.

Isso inclui:

• Manuais internos;

• Documentação de suporte;

• Procedimentos operacionais;

• Scripts;

• Monitoramentos;

• Documentos de infraestrutura;

• Cadastros em ferramentas de chamados;

• Materiais de apoio utilizados pela equipe técnica.

🛠️ Exemplo prático de adequação

Imagine que o ambiente esteja configurado com o nome abaixo:

Produção

Esse nome passa a ser inadequado por conter caracteres especiais, como cedilha e acentuação.

O recomendado é alterar para:

PRODUCAO

Outro exemplo:

Homologação@2024

Esse nome possui acentuação, cedilha e o caractere especial @.

Uma sugestão adequada seria:

HOMOLOGACAO_2024

🚨 Riscos de não adequar os nomes dos ambientes

Caso a adequação não seja realizada antes da atualização para a Release 12.1.2510, podem ocorrer impactos como:

• Bloqueio de acesso ao ambiente;

• Falha na abertura do sistema;

• Geração de error log;

• Falha em rotinas automáticas;

• Erro em integrações;

• Falha em jobs;

• Interrupção de processos dependentes de RpcSetEnv;

• Aumento de chamados após atualização;

• Necessidade de ajuste emergencial em produção.

✅ Boas práticas de nomenclatura

Para evitar problemas futuros, recomenda-se adotar um padrão único de nomenclatura para ambientes Protheus.

Boas práticas recomendadas:

• Utilizar nomes curtos e objetivos;

• Não utilizar acentos;

• Não utilizar cedilha;

• Não utilizar espaços;

• Não utilizar caracteres especiais;

• Preferir letras maiúsculas;

• Utilizar underline apenas quando necessário;

• Padronizar nomes entre produção, homologação e desenvolvimento;

• Registrar o padrão em documentação técnica interna.

Exemplos de padrão recomendado:

📋 Checklist de validação

Antes da atualização para a Release 12.1.2510, utilize o checklist abaixo:

•  Levantar todos os ambientes configurados no AppServer;

•  Verificar se existem nomes com acentos;

•  Verificar se existem nomes com cedilha;

•  Verificar se existem nomes com espaços;

•  Verificar se existem caracteres especiais;

•  Definir novo padrão de nomenclatura;

•  Ajustar os nomes inválidos;

•  Revisar chamadas RpcSetEnv;

•  Revisar jobs;

•  Revisar integrações;

•  Revisar serviços REST e WebServices;

•  Testar acesso em homologação;

•  Validar rotinas críticas;

•  Atualizar documentação técnica;

•  Planejar janela de aplicação em produção.

❓ FAQ

1. A restrição vale para qual release?

A restrição passa a ser aplicada a partir da Release 12.1.2510 do Protheus.

2. Posso utilizar acentos no nome do ambiente?

Não. A partir dessa release, nomes de ambientes com acentos não devem ser utilizados.

3. Posso utilizar cedilha?

Não. A cedilha também é considerada caractere inválido para nomes de ambientes.

4. Posso utilizar espaço em branco?

Não. Espaços em branco não são permitidos.

5. Posso utilizar underline?

Sim. O underline _ é permitido.

6. Posso utilizar hífen?

Não é recomendado, pois o padrão permitido considera letras, números e underline.

7. O que acontece se o ambiente estiver com nome inválido?

O ambiente poderá ter o acesso bloqueado, e processos em segundo plano que utilizem o nome do ambiente poderão gerar error log.

8. Essa alteração pode afetar customizações?

Sim. Customizações que utilizem o nome do ambiente, principalmente por meio de chamadas como RpcSetEnv, devem ser revisadas.

9. Preciso revisar apenas o appserver.ini?

Não. Além do arquivo de configuração do AppServer, é necessário revisar integrações, jobs, rotinas automáticas, scripts, documentação e qualquer referência ao nome antigo do ambiente.

10. É recomendado ajustar antes da atualização?

Sim. A recomendação é revisar e regularizar todos os ambientes antes da atualização para evitar indisponibilidade ou erros após a mudança de release.

🏁 Conclusão

A restrição de caracteres especiais em nomes de ambientes na Release 12.1.2510 representa uma mudança importante no padrão técnico do Protheus.

Para evitar impactos operacionais, é fundamental revisar previamente os nomes dos ambientes, remover caracteres especiais e padronizar a nomenclatura antes da atualização.

A adoção de nomes simples, sem acentos, sem espaços e sem caracteres especiais contribui para maior estabilidade, compatibilidade e segurança no ambiente Protheus.

👤 Autor

Mastersiga Consultoria
“Conectamos tecnologia, processos e pessoas para acelerar resultados com excelência em sistemas TOTVS.”