advpl-matxfis — Família fiscal Protheus

MATXFIS é a família de rotinas/funções fiscais do Protheus. Domina geração de NF-e (Nota Fiscal Eletrônica), NFC-e, CT-e, e integração com obrigações fiscais brasileiras: SPED Fiscal, SPED Contribuições, ECF, EFD-REINF, GIA, DAPI.

Nota de escopo: MATXFIS é um dos módulos mais densos do Protheus (milhares de regras tributárias por UF/operação). Esta skill dá panorama + entry-points. Para deep-dive em regras específicas (cálculo de ICMS-ST, partilha de DIFAL, ajuste fiscal SPED registro C100/E110), invoque o agent advpl-specialist ou consulte a documentação oficial TDN.

Quando usar

• Usuário menciona "nota fiscal", "NF-e", "SPED", "ECF", "REINF", "tributação", "ICMS", "IPI", "PIS/COFINS", "fiscal", "obrigação acessória".
• Edit em fontes com prefixo MATA9*, MTA710*, SPED*, MATFXX*, MATXFIS*.
• Tabelas envolvidas: SF2 (NF de saída), SF1 (NF de entrada), SD1/SD2 (itens), SF3 (livro fiscal), SF6 (acumulado fiscal), SFB, CDA/CDF (apuração SPED).
• Workflow de "rejeição da SEFAZ", "carta de correção", "inutilização".

Panorama

Diagrama de fluxo simplificado de uma nota de saída:

Pedido de Venda (SC5/SC6)
       ↓ MATA460 — Documento de Saída
Nota Fiscal de Saída (SF2/SD2)
       ↓ MATA951/MATA952 — Transmissão NF-e
SEFAZ ← XML assinado → resposta (autorizada/rejeitada)
       ↓ MATA920 — Encerramento
Livro Fiscal (SF3) + Acumulados (SF6/CDA/CDF)
       ↓ SPED* — Obrigações acessórias
Arquivos SPED Fiscal / Contribuições / ECF / REINF

Tabelas-chave

Pontos de Entrada (PE) comuns

NF Saída

NF-e (transmissão)

SPED

Use /plugadvpl:find function <PE> para localizar implementações no projeto. O lookup pontos_entrada_padrao cataloga os mais comuns.

TES — Tipo de Entrada/Saída

A TES (cadastrada em SF4) é o coração do cálculo tributário. Define:

• Se gera duplicata (F4_DUPLIC).
• Se atualiza estoque (F4_ESTOQUE).
• CFOP padrão.
• Bases e alíquotas de IPI, ICMS, PIS, COFINS.
• Tratamento de Substituição Tributária.

Funções utilitárias:

• MaFisRef("operacao_fiscal", "tag", aDados) — leitura/gravação de campos fiscais.
• MaFisGet("tag") — lê valor fiscal corrente do contexto.
• MaFisEnd() — encerra contexto fiscal.
• MaFisIni() — inicia contexto.

Cálculo de impostos — quem é responsável

Para customizar cálculo: PE M460FIM, PE MA440PGN, ou override via MaFisRef. Mexer direto em SD2 sem MaFisRef quebra a integridade fiscal.

Anti-padrões

• Atualizar SF2/SD2 direto com RecLock sem chamar MaFisRef → bases ficam zeradas, gera multa.
• Customizar SPED via WriteFile fora da rotina SPEDFIS → registros fora de ordem.
• Mudar CFOP na PE pós-gravação → não recalcula impostos.
• Ler SF3 direto para apuração → use MaFisCalc/MaFisRef para garantir consistência.
• Hardcode de alíquota ICMS → use SF7 (alíquotas por UF) ou SFB (TES) — alíquotas mudam por legislação.
• Não tratar carta de correção (SFC) ao recalcular nota — pode revogar correção sem querer.

Referência rápida

Quando escalar para advpl-specialist

Esta skill cobre o panorama. Acione o agente especialista quando o usuário pedir:

• Regra detalhada de DIFAL/FCP por par origem-destino.
• Diferenças entre regimes (Lucro Real × Presumido × Simples) em rotinas fiscais.
• Reconciliação fina SPED Fiscal × ECF × SF3.
• Diagnóstico de rejeição NF-e por código (rejeição 539, 627, etc.).
• Histórico de uma legislação específica (NT 2024.xxx).

Comandos plugadvpl relacionados

• /plugadvpl:tables SF2 (e SD2, SF3, SF6, CDA, CDF) — quem usa o quê.
• /plugadvpl:find function MaFisCalc — usos no projeto.
• /plugadvpl:arch <fonte> antes de tocar em qualquer rotina fiscal.
• /plugadvpl:callers <PE_fiscal> — onde a PE está implementada.

Referência profunda

Para detalhes completos (~1.3k linhas), consulte reference.md ao lado deste arquivo:

• Estrutura completa do contexto fiscal (MaFisIni/MaFisEnd/MaFisRef/MaFisGet/MaFisCalc).
• Tabela exaustiva de tags fiscais (IT_VALMERC, IT_VALICM, IT_BASEIPI, etc.) e quando atualizar cada uma.
• Regras de DIFAL/FCP/Partilha por UF e ajustes para emendas constitucionais (EC 87/2015).
• Mapeamento dos registros SPED Fiscal (C100/C170/C190/E110) ↔ tabelas Protheus (SF2/SD2/SF3/CDA).
• Cenários de NF complementar, NF de ajuste, denegação, inutilização, carta de correção.

Exemplos práticos

Veja a pasta exemplos/ ao lado deste SKILL.md para fonte real ADVPL de produção:

• DAMDFE.prw — impressão do Documento Auxiliar do Manifesto Eletrônico (MDF-e) com tratamento de contingência, layout estruturado em oDamdfe:SetPaperSize/SetMargin e parsing do XML MDF-e via XMLXFUN.CH.