Se você ainda grava dados em tabelas padrão do Protheus de forma direta, vale a pena parar e revisar essa estratégia. Quando o assunto é automação com segurança, integridade de dados e respeito às regras do ERP, o caminho mais sólido é a rotina automática, também conhecida como ExecAuto.
O grande ponto aqui é simples: automatizar não é apenas fazer o dado chegar ao banco. Automatizar bem é garantir que esse dado passe pelas mesmas validações que passaria em uma rotina padrão do sistema. E é exatamente isso que o ExecAuto entrega.
Neste artigo, você vai entender:
- o que é o ExecAuto no Protheus;
- como ele funciona na prática;
- quais são as vantagens em relação à gravação direta;
- como localizar a documentação oficial;
- qual a diferença entre RecLock e ExecAuto;
- como aplicar isso em uma integração via API REST.
O que é o ExecAuto no Protheus
O ExecAuto, ou execução automática de rotinas, é uma funcionalidade nativa do Protheus que permite executar funções do sistema sem interação humana com telas, botões ou formulários visuais.
Na prática, ele funciona como um atalho para o motor da rotina original. Em vez de simular clique por clique de uma operação, você envia as informações para a rotina automática e o sistema processa aquilo internamente, seguindo as mesmas regras da operação padrão.
Isso significa que você pode, por exemplo, incluir ou alterar dados em tabelas nativas do Protheus sem violar as regras de negócio do módulo.
Esse detalhe é o que diferencia o ExecAuto de uma gravação direta no banco. Ao usar o ExecAuto, o sistema:
- valida campos obrigatórios;
- respeita regras do módulo;
- executa gatilhos e validações da rotina original;
- impede gravações inconsistentes.
Um exemplo simples ajuda a visualizar isso. Imagine a inclusão de um cliente. Se você tentar gravar apenas o código do cliente, o sistema deve recusar essa inclusão porque existem outros campos obrigatórios. Com o ExecAuto, essa recusa acontece naturalmente, exatamente como aconteceria na rotina padrão do cadastro.
O mesmo vale para operações mais complexas, como um pedido de venda ou faturamento. Se faltarem dados essenciais, como os itens da venda, a rotina automática não deixa a gravação acontecer.
Como o ExecAuto funciona na prática
A lógica do ExecAuto é direta: você monta uma estrutura com os dados que deseja enviar, chama a rotina correspondente e informa qual operação será executada, como inclusão, alteração ou exclusão, conforme a documentação da rotina.
De forma conceitual, o fluxo é este:
- você prepara um array com as informações da operação;
- esse array é enviado para o MSExecAuto;
- o Protheus analisa os dados;
- se tudo estiver correto, o registro é salvo;
- se houver erro, a rotina retorna o motivo da rejeição.
Além da chamada principal, existe um ponto obrigatório: o tratamento de erro com a estrutura de MSErroAuto. Isso é essencial para capturar as mensagens de rejeição e devolver um retorno útil para quem está consumindo a integração.
Na estrutura apresentada, os elementos centrais são:
- a rotina informada conforme a documentação oficial;
- o array preenchido com os campos necessários;
- a operação desejada, como a opção de inclusão;
- o tratamento de erro para saber por que a gravação falhou.
Quando tudo está preenchido corretamente, o retorno indica que o registro foi incluído com sucesso. Quando algo está faltando ou inválido, a rotina devolve o erro correspondente.
Por que usar ExecAuto em vez de gravar diretamente no banco
Essa é a pergunta mais importante de todas. E a resposta passa por quatro pilares: integridade, escalabilidade, padronização e prevenção de inconsistências.
1. Integridade de dados
Com o ExecAuto, os dados passam pelas mesmas validações e gatilhos que um usuário enfrentaria ao preencher a tela padrão do Protheus. Isso garante consistência no banco de dados e reduz muito o risco de registros incompletos ou fora do padrão.
2. Escalabilidade e adaptação
O ExecAuto permite processar grandes volumes em poucos segundos. Além disso, ele oferece uma proteção importante contra mudanças estruturais no sistema.
Se após uma atualização do Protheus surgir um novo campo obrigatório, por exemplo, a rotina automática interrompe o processo e avisa. Isso é muito melhor do que continuar gravando registros incompletos sem perceber.
3. Integração padronizada
Ao integrar o Protheus com APIs, aplicações internas, e-commerce e outros sistemas, o ExecAuto se encaixa muito bem porque trabalha sobre as tabelas nativas respeitando o comportamento do ERP.
Ou seja, a integração não vira um atalho perigoso. Ela continua alinhada às regras do ambiente padrão.
4. Bloqueio de inconsistências
O ExecAuto funciona como um filtro rigoroso. Se a informação não estiver de acordo com as regras de negócio, a gravação é impedida. Isso evita o famoso “lixo no banco”, que normalmente gera dor de cabeça mais adiante, em relatórios, processos fiscais, faturamento ou outras rotinas dependentes.
Como encontrar a documentação do ExecAuto
Um ponto fundamental para trabalhar com rotina automática no Protheus é saber localizar a documentação correta. Como cada rotina tem sua própria estrutura, parâmetros e comportamento, consultar a fonte oficial é indispensável.
Uma forma prática de pesquisar é procurar por termos como:
- rotina automática TOTVS Protheus;
- ExecAuto ADVPL;
- rotina automática + nome da rotina.
Ao fazer isso, você encontra resultados da central oficial da TOTVS e do TDN com exemplos de uso, descrição dos parâmetros e observações importantes sobre cada rotina.
Também é possível pesquisar diretamente pelo nome técnico da rotina. Um exemplo rotina automática CRMA980, referente ao cadastro de clientes.
Esse tipo de busca costuma trazer a documentação específica da rotina automática, com os campos esperados, exemplos de preenchimento e a forma correta de chamar o processo.
Outra alternativa é usar a barra de pesquisa do próprio TDN e procurar por termos como:
- ExecAuto;
- rotina automática.
O cuidado mais importante aqui é este: priorize sempre a documentação oficial da TOTVS. Isso evita seguir exemplos desatualizados ou interpretações incompletas publicadas em fontes paralelas.
ExecAuto x RecLock/HackLock: qual é a diferença real?
Na prática, essa comparação deixa tudo muito claro.
Ao usar um comando como RecLock, ou abordagens semelhantes de gravação direta, você informa em qual tabela deseja salvar os dados e faz a inclusão praticamente no nível da base. O sistema grava, mas sem necessariamente passar pelas validações da rotina padrão.
Já com o ExecAuto, a gravação ocorre dentro da lógica oficial da rotina. Isso muda completamente o nível de segurança da operação.
O que acontece com uma gravação direta
No primeiro cenário, foi feita uma inclusão no cadastro de clientes enviando apenas o código do cliente.
Resultado: a API retornou sucesso e o registro foi criado.
Mas ao abrir a rotina de clientes no sistema, ficou evidente o problema. O cliente havia sido incluído sem os demais campos obrigatórios. Ou seja, foi possível inserir um dado que a própria tela padrão do Protheus não aceitaria.
Se alguém tentasse fazer a mesma operação manualmente pela rotina padrão, preenchendo somente o código e clicando em salvar, receberia uma mensagem de erro. Isso mostra por que a gravação direta pode ser perigosa: o fato de o dado entrar no banco não significa que ele está válido para o sistema.
O que acontece com o ExecAuto
No segundo cenário, a inclusão foi feita usando o MSExecAuto dentro de uma API REST.
Foi enviado um formulário com os dados necessários do cliente, incluindo código, nome e outros campos obrigatórios. Alguns campos, como estado, cidade e tipo, precisavam conter valores válidos conforme as regras do sistema.
Com isso, a inclusão foi realizada com sucesso e o cadastro apareceu corretamente na rotina de clientes.
Aqui está a grande diferença:
- gravação direta salva mesmo quando o registro está inconsistente;
- ExecAuto só grava se o registro estiver conforme as regras da rotina.
Demonstração prática com API REST e Thunder Client
A aplicação prática mostrada usa uma API REST no Protheus testada via Thunder Client no VS Code. Esse modelo é excelente para integrações modernas, porque permite receber os dados em formato estruturado, tratar erros e devolver respostas claras.
O processo seguiu duas linhas de teste: sucesso e falha.
Teste 1: inclusão correta
No primeiro teste com ExecAuto, foi enviado um conjunto válido de informações para inclusão de um novo cliente.
O retorno da API indicou sucesso, e o cadastro foi confirmado no sistema. O formulário contemplava os campos obrigatórios do cadastro de clientes, respeitando aquilo que a rotina exige.
Esse é o cenário ideal para integrações: a API envia, o Protheus valida, e apenas dados consistentes são persistidos.
Teste 2: formulário com informação faltando
Depois, foi feito um teste removendo uma das informações do formulário antes do envio.
Nesse caso, a API retornou erro. A falha ocorreu porque havia um campo ausente, e a rotina automática barrou a gravação. Em vez de inserir um registro incompleto, o sistema sinalizou o problema imediatamente.
Esse comportamento é exatamente o que se espera de uma integração segura.
Teste 3: programação sem os parâmetros obrigatórios no array
Houve ainda um terceiro cenário importante: não bastava o formulário estar correto se a própria programação do array enviada ao ExecAuto não estivesse completa.
Ao comentar uma das linhas do array responsável por um campo obrigatório, a nova tentativa de envio também gerou erro. A resposta indicou que o campo obrigatório não estava presente na estrutura enviada à rotina.
Ou seja, o ExecAuto protege em duas frentes:
- na entrada da API;
- na montagem interna da rotina automática.
Isso ajuda muito no desenvolvimento, porque os erros ficam mais visíveis e o comportamento da integração permanece alinhado ao funcionamento real do sistema.
Boas práticas ao usar ExecAuto no Protheus
Com base nos exemplos apresentados, algumas boas práticas ficam bem claras:
- sempre consulte a documentação oficial da rotina antes de programar;
- monte o array com atenção, incluindo os campos obrigatórios;
- trate os erros com MSErroAuto para obter retorno claro da falha;
- não confie em gravações diretas quando estiver lidando com tabelas padrão;
- valide os dados da integração antes do envio, principalmente campos com conteúdo controlado pelo sistema;
- teste cenários de sucesso e erro usando ferramentas como Thunder Client.
Quando faz sentido usar ExecAuto
O ExecAuto faz especialmente sentido quando você precisa automatizar processos padrão do Protheus como:
- cadastros do sistema TOTVS Protheus;
- integrações entre sistemas internos e as rotinas do ERP Protheus;
- APIs REST para inclusão e alteração de dados nas rotinas do sistema;
- processamentos em lote com segurança;
- operações que precisam respeitar regras de negócio do módulo.
Se a sua automação mexe com dados nativos do Protheus, a pergunta não costuma ser “posso gravar direto?”. A pergunta mais madura é: como faço isso respeitando a lógica do sistema?
E, na maioria desses casos, a resposta passa pelo ExecAuto.
Conclusão
Automatizar processos no Protheus com ExecAuto e API REST é uma abordagem muito mais segura do que simplesmente gravar dados diretamente nas tabelas. Você ganha consistência, previsibilidade e aderência total às regras do ERP.
Enquanto uma gravação direta pode até parecer mais rápida num primeiro momento, ela abre espaço para registros inválidos, erros silenciosos e problemas futuros no ambiente. Já o ExecAuto atua como a camada de proteção que garante que a automação siga o mesmo padrão operacional do sistema.
Se você trabalha com desenvolvimento no TOTVS Protheus, entender e dominar rotina automática não é mais um diferencial. É parte do caminho para construir integrações realmente profissionais.
Em resumo:
- ExecAuto automatiza sem ignorar regras de negócio;
- API REST moderniza a integração;
- Thunder Client facilita os testes;
- documentação oficial é indispensável;
- gravação direta em tabela padrão deve ser tratada com muito cuidado.
Se a ideia é evoluir o nível das suas integrações no Protheus, esse é um dos fundamentos mais importantes para dominar.
Este este artigo foi uma breve explicação sobre o ExecAuto no TOTVS Protheus, para conferir o processo completo de forma prática sugerimos que assista o vídeo no início da página.
Cursos
Se você está buscando se tornar um desenvolvedor completo no Protheus, dominar REST, PO-UI e as demais tecnologias relacionadas ao Protheus, não fique de fora da nossa turma de alunos, clique aqui para mais detalhes.
Sobre nós:
A RFB Sistemas é uma consultoria e escola há mais de 15 anos no mercado e já atuamos em diferentes setores e portes de empresas ajudando a implantar a melhor solução para gerenciar os seus negócios, o que possibilita que sua empresa consiga tomar decisões mais rápidas, assertivas e claro otimizando resultados. Além disso já capacitamos mais de 1.600 profissionais a utilizarem as ferramentas, como: TOTVS Protheus e RM, Microsoft Power BI e Excel.
