Tempo de leitura: 9 minutos
No ecossistema Protheus, o controle sobre quem, quando e onde pode incluir uma nota fiscal é fundamental para a conformidade fiscal e operacional. Muitas vezes, as permissões de acesso padrão não são suficientes para barrar operações em cenários específicos, como feriados locais ou grupos de usuários restritos. O Ponto de Entrada MT103PN é a ferramenta técnica ideal para atuar como um filtro lógico logo no início da rotina de Documento de Entrada (MATA103). Este é um tema essencial para quem busca especialização em Pontos de Entrada.
Neste guia técnico, você aprenderá como implementar o MT103PN para decidir se a inclusão de um documento deve prosseguir ou ser abortada no módulo de Compras (SIGACOM).
💡 O que é o MT103PN?
O MT103PN é um Ponto de Entrada de controle lógico (booleano) que é executado no momento da inclusão de um Documento de Entrada (Nota Fiscal de Entrada), dentro da rotina MATA103 (ou em algumas funções chamadas por ela, como a A103NFISCAL).
-
Rotina: MATA103 – Documento de Entrada
-
Módulo: Compras (SIGACOM) / Fiscal (SIGAFIS)
-
Momento de Execução: Logo no início do processo de inclusão do documento de entrada.
🎯 Qual é a sua principal finalidade?
A principal função do MT103PN é decidir se a rotina de inclusão deve prosseguir ou ser abortada antes mesmo da abertura da tela principal da nota fiscal.
Ele retorna um valor lógico que determina o fluxo do programa:
-
Retorno .T. (True/Verdadeiro): A inclusão do Documento de Entrada continua.
-
Retorno .F. (False/Falso): A inclusão do Documento de Entrada é cancelada/bloqueada.
💻 Sintaxe do Ponto de Entrada
A estrutura básica do Ponto de Entrada é simples, retornando um valor lógico (lRet):
Código ADVPL:
#INCLUDE "PROTHEUS.CH"
/*/{Protheus.doc} MT103PN
Inclusão de documento de entrada. Continua ou não.
@type function
@version 1.0
@author Adilio Costa
@since 03/11/2025
*/
User Function MT103PN()
Local lRet := .T. // Valor padrão: continuar a inclusão
// ----------------------------------------------------------------------
// SEU CÓDIGO DE VALIDAÇÃO AQUI
// Exemplo: Bloquear a entrada se o usuário for o "ADM"
If AllTrim(cUsuario) == "ADM"
lRet := .F. // Bloqueia a inclusão
// FWAlertInfo("Usuário ADM não pode incluir Documentos de Entrada!")
EndIf
// ----------------------------------------------------------------------
Return(lRet)
🛠️ Casos de Uso Comuns
Este Ponto de Entrada é ideal para implementar regras de negócio que bloqueiam a entrada de documentos com base em condições de alto nível, como:
- Bloqueio por Usuário/Grupo de Usuários: Impedir que determinados usuários ou grupos incluam notas fiscais.
- Validação de Parâmetros/Configurações: Checar se parâmetros obrigatórios para a entrada de documentos estão configurados (Ex: Módulo Fiscal ativo, ambiente configurado, etc.).
- Restrição por Filial: Bloquear a entrada para filiais específicas.
- Integração com Ferramentas Externas: Algumas ferramentas externas de recebimento (como Centrais XML ou Portais de Fornecedores) podem utilizá-lo para realizar checagens iniciais.
- Perguntar ao Usuário: Pode ser usado para exibir uma mensagem de confirmação inicial antes de carregar toda a tela (embora não seja o uso mais comum, é tecnicamente possível).
⚠️ Observações Importantes
-
Momento: O MT103PN é executado antes da criação do cabeçalho e dos itens da nota fiscal na tela. Se você precisa validar dados já digitados ou inseridos (como TES, Fornecedor, etc.), procure por pontos de entrada que rodem após a digitação ou durante a gravação (Ex: MT103INC, MT103FIM, etc.).
-
Variáveis de Ambiente: No ponto de execução, você ainda não terá acesso aos dados da nota fiscal (campos F1_*). Se precisar de informações de contexto (como Filial, Data Atual, Usuário), utilize variáveis de ambiente ou tabelas do Protheus.
📝Exemplo Prático com MT103PN: Bloqueio em Feriados
Vamos criar uma customização usando o Ponto de Entrada MT103PN para bloquear a inclusão de um Documento de Entrada se a data atual do sistema for um feriado nacional.
Para isso, usaremos o array de feriados e algumas funções padrão do AdvPL.
#INCLUDE "PROTHEUS.CH"
/*/{Protheus.doc} MT103PN - Bloqueio em Feriados
Bloqueia a inclusão de Documento de Entrada (MATA103)
se a data do sistema for um feriado nacional.
@type function
@version 1.0
@author Adilio Costa
@since 03/11/2025
@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!!|
*/
User Function MT103PN()
Local lRet := .T. // Valor Padrão: .T. (Continua a inclusão)
Local dDataAtual := dDataBase // Pega a data atual do sistema (Base de Dados)
Local aFeriados := {} // Array para armazenar as datas dos feriados (Formato: AAAA/MM/DD)
Local cFeriadoNome := "" // Variável para armazenar o nome do feriado, se encontrado
// ----------------------------------------------------------------------
// 1. Definição dos Feriados Nacionais (Exemplo para 2025)
// NOTE: Em um ambiente real, você deve buscar essa lista em uma tabela
// própria (por exemplo, SXG, que é a tabela de dias não úteis)
// ou em um parâmetro customizado.
Aadd(aFeriados, {'20250101', 'Confraternização Universal'}) // 01/Jan
// O Carnaval (Março) e Corpus Christi (Junho) são pontos facultativos na maioria
// das vezes, mas incluímos como exemplo:
Aadd(aFeriados, {'20250303', 'Carnaval'}) // 03/Mar
Aadd(aFeriados, {'20250304', 'Carnaval'}) // 04/Mar
Aadd(aFeriados, {'20250418', 'Paixão de Cristo'}) // 18/Abr
Aadd(aFeriados, {'20250421', 'Tiradentes'}) // 21/Abr
Aadd(aFeriados, {'20250501', 'Dia do Trabalho'}) // 01/Mai
Aadd(aFeriados, {'20250619', 'Corpus Christi'}) // 19/Jun
Aadd(aFeriados, {'20250907', 'Independência do Brasil'}) // 07/Set
Aadd(aFeriados, {'20251012', 'Nossa Sra. Aparecida'}) // 12/Out
Aadd(aFeriados, {'20251102', 'Finados'}) // 02/Nov
Aadd(aFeriados, {'20251115', 'Proclamação da República'}) // 15/Nov
Aadd(aFeriados, {'20251120', 'Consciência Negra'}) // 20/Nov (Feriado Nacional a partir de 2024)
Aadd(aFeriados, {'20251225', 'Natal'}) // 25/Dez
// ----------------------------------------------------------------------
// 2. Lógica de Validação: Verifica se a data atual é um feriado
// Converte a data atual para o formato de string (AAAAMMDD) para comparação
Local cDataAtual := DToS(dDataAtual)
// Procura a data na lista de feriados
cFeriadoNome := AScan(aFeriados, {|aElement| aElement[1] == cDataAtual})
If cFeriadoNome > 0
// Se cFeriadoNome for maior que 0, significa que a data foi encontrada no array.
lRet := .F. // BLOQUEIA a inclusão!
cFeriadoNome := aFeriados[cFeriadoNome][2] // Pega o nome do feriado.
// Mensagem de alerta para o usuário
MsgStop("Bloqueio de Inclusão! " +;
"Não é permitida a inclusão de Documento de Entrada " +;
"na data de hoje (" + DToC(dDataAtual) + "), pois é **" + cFeriadoNome + "**.", ;
"Documento de Entrada Bloqueado")
EndIf
Return(lRet)
📋 Detalhamento da Implementação
Variáveis Locais:
- lRet: Define o retorno lógico do P.E. (inicia como .T. para permitir).
-
dDataAtual: Captura a data atual do sistema (dDataBase).
-
aFeriados: Um array de arrays onde cada elemento é {‘AAAAMMDD’, ‘Nome do Feriado’}.
-
cFeriadoNome: Usado para armazenar o nome do feriado, se a data for encontrada.
-
-
Lista de Feriados: A lista de datas é definida no array aFeriados.
-
Melhor Prática: Em um projeto real, evite “hard-codar” (escrever diretamente no código) datas fixas. É muito mais robusto e fácil de manter buscar essa informação em uma tabela de configuração no Protheus (como a SXG – Dias Não Úteis) ou em um Parâmetro Customizado (SX1).
-
-
Validação (AScan):
-
A função DToS(dDataAtual) converte a data atual para o formato AAAAMMDD (ex: 20251103).
-
A função AScan() percorre o array aFeriados, verificando se o primeiro elemento (aElement[1]) de cada sub-array é igual à data atual formatada (cDataAtual).
-
Se AScan retornar um número maior que 0, a data foi encontrada.
-
-
Bloqueio:
-
Se a data for encontrada (If cFeriadoNome > 0), a variável de retorno é alterada para lRet := .F., o que imediatamente aborta a inclusão do Documento de Entrada antes que o usuário possa interagir com a tela.
-
Uma mensagem (MsgStop) é exibida para informar claramente o motivo do bloqueio.
-
Com isso, você garante que nenhum documento será incluído em dias não úteis definidos, forçando o processo para o próximo dia útil.
Domine os Pontos de Entrada e o Backoffice
Para dominar este conceito em cenários de alta complexidade, como a integração com workflows de aprovação externa ou validações de períodos contábeis fechados, conheça o Portal ProtheusAdvpl. Lá, exploramos a fundo a arquitetura do Protheus e as melhores práticas para desenvolvedores seniores.
Cursos Recomendados para Programação e Backoffice:
Casos de Uso Comuns
- Restrição por Filial: Impedir a entrada de notas em filiais que estão em processo de inventário.
- Segurança de Período: Bloquear a inclusão se a data do sistema estiver fora do mês contábil aberto.
- Validação de Ambiente: Checar se parâmetros críticos (como o módulo fiscal ativo) estão configurados antes de permitir a operação.
Conclusão
O Ponto de Entrada MT103PN é uma ferramenta estratégica para elevar o nível de controle no módulo de Compras (SIGACOM). Ao atuar na “porta de entrada” da rotina, você evita que processos indevidos sejam sequer iniciados, economizando tempo e garantindo a integridade do Backoffice. Dominar ADVPL Avançado é o diferencial que transforma um programador em um consultor estratégico.
Links de referência(s):
