Customização no Protheus com Segurança: Guia Prático

Aprenda a planejar customizações no Protheus com ADVPL, pontos de entrada, versionamento, testes, homologação e governança para reduzir riscos.

O que é customização no Protheus com segurança?

Customização no Protheus com segurança é a adaptação controlada do ERP a uma regra de negócio que não pode ser atendida de forma sustentável pelo produto padrão, por parametrização ou por uma integração existente. O trabalho pode envolver ADVPL ou TLPP, pontos de entrada, rotinas, relatórios, APIs e outros artefatos, mas precisa preservar rastreabilidade, capacidade de atualização e operação.

O código é apenas uma parte. Uma customização segura possui justificativa de negócio, responsável, escopo, documentação, controle de versão, testes, aprovação, plano de implantação e estratégia de reversão. Sem esse ciclo, o ganho imediato pode se transformar em dependência de uma pessoa, falha silenciosa ou custo recorrente a cada release.

O objetivo não é eliminar toda personalização. É desenvolver apenas o que gera valor ou atende uma obrigação real e manter cada extensão separada, compreensível e verificável.

Quando customizar o Protheus?

Uma customização pode fazer sentido quando existe uma regra específica, relevante e estável que o padrão não cobre. Alguns exemplos são validações próprias de crédito, relatórios operacionais com lógica particular, automação entre módulos ou integração com uma aplicação que participa do processo da empresa.

Antes de aprovar o desenvolvimento, compare alternativas nesta ordem:

recurso padrão já disponível no release utilizado;
parâmetro, cadastro, fórmula, gatilho ou configuração suportada;
ajuste do processo sem perda do requisito essencial;
integração por API ou mecanismo documentado;
extensão por ponto de entrada;
rotina customizada quando as opções anteriores não atendem.

Essa sequência não é absoluta. Uma configuração excessivamente complexa também pode ser difícil de manter, enquanto uma extensão pequena e bem isolada pode ser mais clara. A decisão precisa considerar aderência, risco, suporte, desempenho, atualização e custo total.

A consultoria em Protheus pode ajudar a diagnosticar a necessidade, verificar recursos nativos e desenhar a alternativa mais sustentável antes de iniciar o código.

Transforme a solicitação em requisito verificável

Pedidos como “criar um botão”, “bloquear a rotina” ou “fazer um relatório” descrevem uma solução, não o problema. O levantamento deve registrar:

processo e módulos envolvidos;
usuários e perfis afetados;
regra atual e resultado esperado;
exceções, volumes e horários críticos;
dados de entrada e saída;
obrigações fiscais, contábeis ou de auditoria;
comportamento quando uma dependência falha;
indicador que demonstrará o benefício;
critérios objetivos de aceite.

Considere também a consequência de não desenvolver. Se a solicitação resolve uma preferência de tela com baixo impacto, talvez não justifique a manutenção futura. Se reduz um erro fiscal recorrente ou elimina uma atividade crítica sem rastreabilidade, a prioridade muda.

O responsável de negócio deve validar a regra e suas exceções. O time técnico não deveria decidir sozinho como compras, faturamento, estoque ou finanças precisam funcionar.

Escolha o mecanismo de extensão adequado

Pontos de entrada convencionais e MVC

Pontos de entrada permitem executar lógica customizada em momentos previstos de uma rotina, sem alterar diretamente o fonte padrão. A documentação oficial da TOTVS explica que pontos convencionais recebem parâmetros e retornam valores conforme o contrato de cada função. Em rotinas MVC, uma única função associada ao identificador do modelo pode ser chamada em diferentes momentos do ciclo.

A página do TDN sobre pontos de entrada em fontes ADVPL MVC ressalta que parâmetros chegam por PARAMIXB e que um retorno diferente do especificado pode abortar a rotina. Portanto, não reutilize uma assinatura encontrada em outro ponto por semelhança de nome. Confirme evento, parâmetros, retorno e release aplicável na documentação específica.

Mantenha o código executado dentro do ponto pequeno. Regras complexas podem ser delegadas a funções próprias, o que facilita testes e reduz acoplamento ao evento do produto.

Rotinas, relatórios e serviços próprios

Uma rotina própria pode ser adequada quando a capacidade é independente e possui jornada, permissões e dados bem definidos. Relatórios customizados também precisam de proprietário, critérios de filtro, fonte oficial e regras de acesso; um relatório aparentemente simples pode expor dados pessoais ou produzir números divergentes dos demonstrativos oficiais.

Integrações devem preferir contratos documentados e autenticação apropriada. Evite chamar um serviço externo lento dentro de uma transação do ERP. Uma indisponibilidade de terceiros não deveria manter registros bloqueados ou produzir um estado parcial difícil de reconciliar. Filas, processamento assíncrono e idempotência podem ser necessários conforme a criticidade.

A página de software sob medida apresenta princípios aplicáveis a APIs, integrações, segurança e evolução contínua além do código do ERP.

Alteração direta do padrão e banco de dados

Modificar o fonte padrão ou escrever diretamente em tabelas para contornar regras aumenta o risco de incompatibilidade, inconsistência e perda de suporte. Uma alteração pode ignorar validações, gatilhos, transações e relacionamentos que não estão visíveis no requisito inicial.

Se uma intervenção excepcional for inevitável para corrigir um incidente, trate-a como ação controlada: autorização explícita, backup, validação, registro completo e plano para substituir o desvio por uma solução suportável. A exceção não deve virar arquitetura permanente.

Faça um inventário das customizações existentes

Antes de governar novas demandas, descubra o que já está em produção. Para cada artefato, registre:

nome, tipo e repositório;
módulo, rotina e ponto de entrada relacionado;
responsável técnico e de negócio;
justificativa e processo atendido;
release e dependências conhecidas;
tabelas, campos, parâmetros e integrações utilizados;
evidências de testes;
data da última alteração e do último uso;
criticidade e procedimento de reversão;
situação: manter, revisar, substituir ou desativar.

O inventário precisa relacionar código e operação. Um fonte pode compilar sem que alguém saiba quem usa o resultado. Entrevistas com usuários e análise de logs ajudam a evitar tanto a remoção precipitada quanto a manutenção indefinida de artefatos sem utilidade.

Versionamento e documentação de ADVPL

Fontes não deveriam existir apenas no ambiente de um desenvolvedor, em anexos de chamados ou dentro do RPO. Use um repositório Git como fonte oficial, com histórico, revisão e acesso controlado. A documentação de personalização do SmartERP Protheus explicita a responsabilidade do cliente sobre guarda, manutenção e qualidade dos artefatos customizados e descreve um fluxo com repositório Git para personalizações.

Defina convenções mínimas:

estrutura por domínio ou módulo;
identificação da demanda e do responsável;
estratégia de branches compatível com o volume da equipe;
revisão por outra pessoa antes da promoção;
tags ou versões ligadas aos pacotes implantados;
proibição de credenciais e dados reais no código;
registro do artefato efetivamente compilado.

O guia de boas práticas ADVPL da TOTVS reúne convenções, estruturação, desempenho e técnicas para melhorar manutenção. Já o ProtheusDOC define uma forma estruturada de documentar funções, classes e métodos. Comentários devem explicar intenção, contrato, premissas e efeitos; repetir o código em português não facilita a manutenção.

Separe desenvolvimento, homologação e produção

Mudanças precisam ser compiladas e verificadas fora da produção. O ambiente de homologação deve representar o suficiente do cenário real: release, LIB, dicionário, parâmetros, módulos, integrações e dados anonimizados ou controlados.

A promoção deve identificar:

commit e fontes incluídos;
pacote ou artefato gerado;
dependências de dicionário e configuração;
ordem das etapas;
janela e responsáveis;
testes pós-implantação;
critérios para continuar ou reverter;
comunicação aos usuários e suporte.

Não recompile “a versão mais recente” sem fixar o conteúdo aprovado. O que chega ao RPO precisa corresponder ao que foi revisado e homologado.

Testes para customizações Protheus

Monte os testes a partir do risco do processo, não apenas da linha alterada.

Teste funcional

Valide cenário principal, exceções, cancelamento, estorno, permissões, filiais, moedas, impostos e arredondamentos aplicáveis. Compare o resultado ao critério de aceite aprovado pelo negócio.

Teste de integração

Confirme contratos, timeouts, repetição, indisponibilidade, mensagens fora de ordem e reconciliação. Ambientes devem usar credenciais separadas e dados controlados.

Teste de regressão

Verifique rotinas padrão e customizadas que compartilham tabelas, eventos ou regras. Uma validação em pedido de venda pode afetar liberação, faturamento e integrações posteriores.

Teste de desempenho e concorrência

Avalie volumes representativos, locks, transações e tempo adicionado à rotina. Consultas sem filtros adequados ou chamadas externas síncronas podem degradar o processo inteiro.

Teste de segurança

Valide autorização no servidor, menor privilégio, tratamento de entrada, proteção de segredos e ausência de dados sensíveis em logs. O NIST SP 800-218 organiza práticas de desenvolvimento seguro em preparação da organização, proteção do software, produção segura e resposta a vulnerabilidades; esses princípios podem ser adaptados ao ciclo ADVPL.

Prepare cada customização para o próximo release

Pontos de entrada e comportamentos padrão podem mudar. A TOTVS publicou, por exemplo, uma comunicação sobre pontos de entrada descontinuados no release 12.1.2410, recomendando avaliar alternativas mais recentes. Isso demonstra por que “não alterar o fonte padrão” é necessário, mas não suficiente para garantir compatibilidade futura.

Antes de uma atualização:

compare o inventário ao release de destino;
revise pontos de entrada, funções e dependências;
recompile com componentes compatíveis;
trate avisos e erros de análise;
execute testes funcionais e regressivos;
valide desempenho e integrações;
registre adaptações e itens desativados.

O guia de atualização do Protheus detalha inventário, homologação, compatibilidade, rollback e entrada em produção. Customizações devem participar desse planejamento desde o início, não aparecer apenas durante a virada.

Segurança, acessos e segregação de funções

Quem desenvolve não precisa ter privilégio irrestrito em produção. Separe responsabilidades de desenvolvimento, revisão, compilação, aprovação e implantação conforme o tamanho da equipe. Quando uma pessoa acumula funções, adicione evidências e aprovação independente para mudanças de maior risco.

Proteja repositórios, artefatos, credenciais e ambientes. Remova acessos quando o vínculo termina e revise permissões periodicamente. A gestão mais ampla de autenticação, privilégios e ciclo de vida é abordada no artigo de gestão de identidade e acesso.

Logs precisam ajudar no diagnóstico sem expor senhas, tokens, documentos ou conteúdo desnecessário. Para operações sensíveis, preserve quem executou, qual ação ocorreu, quando, em qual contexto e qual foi o resultado.

Como reduzir o legado customizado

Não reescreva tudo de uma vez. Classifique cada item:

manter: ainda é necessário, está documentado e funciona;
corrigir: tem valor, mas precisa de testes, desempenho ou segurança;
substituir: o padrão atual ou uma integração suportada atende melhor;
redesenhar: a regra continua válida, mas o acoplamento é excessivo;
desativar: não possui uso ou justificativa atual.

Comece pelos artefatos críticos sem proprietário, código fora de versão, pontos obsoletos e rotinas que escrevem diretamente em dados sensíveis. Monitore antes de remover quando o uso não estiver claro.

A redução de dívida técnica deve produzir benefícios verificáveis: menos falhas após atualização, menor tempo de diagnóstico, menos customizações sem dono e maior cobertura de testes críticos.

Checklist de customização no Protheus com segurança

A necessidade e o responsável de negócio estão definidos?
O recurso padrão e a parametrização foram avaliados?
O mecanismo de extensão é documentado para o release?
O contrato do ponto de entrada foi confirmado?
O fonte está em Git e passa por revisão?
Documentação explica regra, entradas, saídas e efeitos?
Desenvolvimento, homologação e produção estão separados?
O artefato implantado corresponde ao commit aprovado?
Há testes funcionais, regressivos, de integração e segurança?
O impacto em desempenho e transações foi avaliado?
Credenciais e dados sensíveis estão protegidos?
Existe rollback e validação pós-implantação?
A customização participa dos testes de atualização?
Proprietário, criticidade e última utilização são revisados?

Conclusão

A customização no Protheus com segurança começa pela decisão de desenvolver somente quando a extensão é justificável. Ela continua com mecanismo suportável, código isolado, versionamento, documentação, ambientes separados, testes e governança de mudanças.

Esse cuidado reduz retrabalho e torna atualizações mais previsíveis sem impedir que o ERP acompanhe particularidades importantes do negócio. Se sua empresa precisa revisar o legado ou desenvolver uma extensão controlada, fale com a Mattos Tech Solutions.