Tempo de leitura: 8 minutos
Se você trabalha com customização no TOTVS Protheus, entender o Ponto de Entrada MA020BUT é uma excelente forma de evoluir no desenvolvimento ADVPL e criar soluções mais práticas para o usuário final.
Esse ponto de entrada permite incluir botões personalizados na EnchoiceBar da rotina MATA020, que corresponde ao Cadastro de Fornecedores no Protheus. Na prática, isso abre espaço para criar atalhos, validações, integrações e rotinas auxiliares diretamente na tela do fornecedor.
Neste artigo, você vai entender o que é o MA020BUT, como ele funciona, quando usar, quais cuidados tomar e ainda verá um exemplo prático em ADVPL.
O que é o Ponto de Entrada MA020BUT no Protheus?
O MA020BUT é um ponto de entrada da rotina MATA020, utilizada no Cadastro de Fornecedores do Protheus. Sua principal finalidade é permitir que o desenvolvedor adicione botões customizados na barra de ações da rotina, normalmente logo abaixo ou ao lado dos botões padrão já exibidos pelo sistema.
Com isso, você pode ampliar a usabilidade da tela e entregar funções específicas da regra de negócio sem precisar alterar a lógica padrão da rotina principal.
Para que serve o MA020BUT?
O ponto de entrada MA020BUT é útil quando existe a necessidade de disponibilizar ações extras no cadastro de fornecedores, como por exemplo:
- abrir consultas complementares do fornecedor
- executar validações específicas
- disparar integrações com sistemas externos
- exibir históricos ou relatórios auxiliares
- chamar rotinas internas personalizadas em ADVPL
Esse tipo de recurso é muito útil em cenários onde o usuário precisa acessar informações adicionais sem sair da rotina principal.
Qual rotina utiliza o ponto de entrada MA020BUT?
O MA020BUT está ligado à rotina MATA020, responsável pelo Cadastro de Fornecedores, que trabalha diretamente com a tabela SA2 no Protheus.
Isso significa que a customização acontece em um dos cadastros mais importantes dos processos de compras, financeiro e integrações do ERP.
Como funciona o retorno do MA020BUT?
O funcionamento do MA020BUT é baseado no retorno de um array de arrays. Cada item desse array representa um botão novo que será adicionado à interface da rotina.
De forma geral, cada subarray define propriedades como:
- texto do botão
- função que será executada
- posição ou comportamento
- condição de exibição
- modo de uso na rotina
Essa abordagem dá bastante flexibilidade para o desenvolvedor criar botões fixos ou até ações condicionais, conforme a necessidade do negócio.
Sintaxe do Ponto de Entrada MA020BUT
User Function MA020BUT()
// código aqui
Return aBotoes
O retorno esperado é um array contendo os botões que deverão ser exibidos na rotina.
Exemplo prático do MA020BUT em ADVPL
Abaixo está um exemplo prático de implementação do ponto de entrada MA020BUT para adicionar botões customizados no cadastro de fornecedores:
#Include "protheus.ch"
/*
@Inscreva-se no Blog ProtheusAdvpl:
https://www.protheusadvpl.com.br
@Inscreva-se no Canal ProtheusAdvpl:
https://www.youtube.com/protheusadvpl
@Siga-nos no Instagram:
https://www.instagram.com/protheusadvpl
@Conheça os Cursos do ProtheusAdvpl:
https://cursos-e-formacoes-protheusadvpl.gr-site.com/
@Participe de nossas comunidades no WhatsApp:
-Comunidade Protheus-Backoffice:
https://chat.whatsapp.com/KMUIAjwZ6EZ6eAHsLkPTyb
-Comunidade Protheus-RH:
https://chat.whatsapp.com/L5dUyAna6xU4ylG5DUgfOW
-Comunidade Protheus-Programação:
https://chat.whatsapp.com/LsD6z0apdqKHlOz67bcaEn
-Comunidade Protheus-Framework:
https://chat.whatsapp.com/BzUFpjaSnTC3vtsfa77jmG
|Se esse conteúdo foi útil pra você nos ajude divulgando
ele e nossas redes sociais!!|
*/
/*/{Protheus.doc} MA020BUT
Inclusão de botão customizado na EnchoiceBar do Cadastro de Fornecedores.
@type User Function
@author Adilio Costa
@since 29/10/2025
/*/
User Function MA020BUT()
Local aBotoes := {}
Local cCodFor := ""
aAdd(aBotoes, { "Ver Saídas", "U_fFunc(cCodFor)", 0, .T., "VIEW" })
If AllTrim(cCodFor) == "000001"
aAdd(aBotoes, { "Val. Espec.", "U_FNCTST()", 0, .T., "VIEW" })
EndIf
Return aBotoes
Entendendo o exemplo na prática
Nesse exemplo, o ponto de entrada cria inicialmente um array chamado aBotoes, que será responsável por armazenar os botões personalizados da rotina.
Em seguida, é adicionado o botão Ver Saídas, que chama uma função customizada responsável por exibir uma mensagem com referência ao fornecedor.
Depois, existe uma validação condicional: se o código do fornecedor for 000001, o sistema adiciona um segundo botão chamado Val. Espec., executando outra função personalizada.
Esse tipo de lógica é interessante porque mostra que você não precisa exibir todos os botões para todos os cenários. É possível condicionar o comportamento conforme o registro, perfil de uso ou regra de negócio.
Quais são os benefícios de usar o MA020BUT?
O uso do ponto de entrada MA020BUT traz várias vantagens para quem desenvolve no Protheus:
- mais produtividade para o usuário, com atalhos diretos na tela
- mais flexibilidade, permitindo adaptar a rotina ao processo da empresa
- melhor experiência de uso, com funções importantes visíveis no cadastro
- mais integração, possibilitando chamadas para outras rotinas ou sistemas externos
- menor necessidade de alterar fluxo padrão, mantendo a customização em ponto apropriado
Quando vale a pena usar esse ponto de entrada?
O MA020BUT vale muito a pena quando a empresa precisa adicionar inteligência operacional no cadastro de fornecedores sem modificar diretamente a rotina padrão.
Alguns cenários comuns:
- consulta rápida de movimentações do fornecedor
- abertura de histórico financeiro ou compras
- integração com análise de crédito ou compliance
- execução de rotina específica por fornecedor
- validações ou bloqueios operacionais sob demanda
Boas práticas ao desenvolver com MA020BUT
Ao trabalhar com esse ponto de entrada, é importante seguir algumas boas práticas para manter a customização organizada e segura:
- use nomes claros para os botões
- evite excesso de ações na tela para não poluir a usabilidade
- garanta que a função chamada esteja bem validada
- trate cenários onde o fornecedor não esteja corretamente identificado
- documente a regra de negócio implementada
- teste o comportamento em visualização, inclusão e alteração
Cuidados importantes na implementação
Embora o exemplo seja simples, existe um ponto importante: a lógica do botão normalmente depende de informações do fornecedor corrente. Por isso, a obtenção correta do contexto do registro precisa ser bem tratada no seu desenvolvimento.
Além disso, toda customização em ponto de entrada deve ser testada com cuidado para evitar impactos na navegação da rotina, principalmente em ambientes com regras adicionais, segurança por usuário ou outras personalizações já existentes.
MA020BUT é útil apenas para fornecedores?
Sim, esse ponto de entrada é específico da rotina MATA020, portanto seu uso está diretamente ligado ao Cadastro de Fornecedores. Porém, o conceito de adicionar botões via ponto de entrada existe em outras rotinas do Protheus, e aprender esse padrão ajuda bastante quem deseja evoluir em customização ADVPL.
Por que esse post é importante para quem programa em ADVPL?
Porque ele mostra um tipo de customização muito valorizado no mercado Protheus: a capacidade de adaptar rotinas padrão com inteligência e baixo acoplamento.
Entender pontos de entrada como o MA020BUT ajuda você a:
- customizar telas com mais profissionalismo
- entender melhor o ecossistema de extensibilidade do Protheus
- criar soluções mais úteis para o usuário final
- evoluir no desenvolvimento ADVPL prático
Conclusão
O Ponto de Entrada MA020BUT é um excelente recurso para quem deseja adicionar botões customizados no Cadastro de Fornecedores do Protheus de forma prática e alinhada ao modelo de customização do ERP.
Com ele, você pode ampliar a rotina MATA020, melhorar a experiência do usuário e disponibilizar ações estratégicas diretamente na EnchoiceBar, sem descaracterizar o fluxo padrão da aplicação.
Se você trabalha com ADVPL e quer evoluir em customizações no Protheus, dominar esse tipo de ponto de entrada é um passo muito importante.
FAQ – Perguntas frequentes sobre o ponto de entrada MA020BUT
O que é o ponto de entrada MA020BUT?
É um ponto de entrada do Protheus que permite adicionar botões personalizados na rotina MATA020, usada no cadastro de fornecedores.
Qual rotina utiliza o MA020BUT?
O MA020BUT é utilizado na rotina MATA020, ligada ao cadastro de fornecedores.
Qual tabela está relacionada a essa rotina?
A rotina trabalha com a tabela SA2, referente aos fornecedores no Protheus.
O que o MA020BUT retorna?
Ele retorna um array de botões que serão exibidos na barra de ações da rotina.
Posso exibir botões condicionais com MA020BUT?
Sim. Você pode criar regras para exibir botões somente em situações específicas, como no caso de determinado fornecedor ou condição de negócio.
Esse ponto de entrada serve para customizações ADVPL?
Sim. Ele é um recurso típico de customização ADVPL no Protheus, muito útil para ampliar funcionalidades sem alterar a lógica padrão da rotina principal.