@treeunfe/mdfe

Biblioteca MDF-e 3.00b (modelo 58) para Treeunfe DFe — modal rodoviário, autorizador SVRS.

Funcionalidades

| Operação | Método adapter | Status | |----------|----------------|--------| | Status do serviço | ConsultaStatusServico() | Implementado | | Autorização síncrona | Autorizacao(mdfe, options?) | Implementado | | Contingência offline (tpEmis=2) | Autorizacao(mdfe, { transmitir: false }) | Implementado | | Consulta situação | Consulta(chMDFe) | Implementado | | Cancelamento (110111) | Cancelamento(data) | Implementado | | Encerramento (110112) | Encerramento(data) | Implementado | | Inclusão condutor (110114) | InclusaoCondutor(data) | Implementado | | MDF-e não encerrados | ConsultaNaoEncerrados() | Implementado | | DAMDFE PDF | GerarDAMDFe(props) | Implementado (Anexo II) | | Distribuição DFe (NSU) | DistribuicaoDFePorUltNSU / PorNSU | Implementado |

Consulta por chave: use Consulta(chMDFe) (consSitMDFe). A distribuição DFe nacional (distDFeInt) não aceita chave — apenas ultNSU / NSU (MOC + XSD distDFeInt_v1.00.xsd).

Escopo v1 (produto Treeunfe)

• MDF-e modelo 58, modal rodoviário (01)
• tpEmit 1 (prestador) e 2 (carga própria PJ)
• Vinculação NF-e / CT-e por município de descarga
• Eventos emitente: cancelamento, encerramento (obrigatório), inclusão condutor
• Contingência offline (tpEmis=2) com QR sign= (MOC §9/§11)
• DAMDFE retrato conforme Anexo II

Contingência offline (tpEmis=2)

Fluxo em duas etapas quando a SEFAZ está indisponível:

1. Emitir localmente — XML assinado + QR com sign=, sem protocolo:

const doc = { infMDFe: { ide: { tpEmis: '2', /* ... */ }, /* ... */ } };
const local = await client.Autorizacao(doc, { transmitir: false });
await client.GerarDAMDFe({ procMDFe: local.procMDFe, outputPath: 'damdfe-contingencia.pdf' });

2. Regularizar na SEFAZ — reutilize o mesmo documento (mesma chave e cMDF) com transmissão padrão:

const autorizado = await client.Autorizacao(doc); // transmitir=true (default)

Regras MOC: mesma chave na retransmissão; prazo recomendado 168h; contingência tem valor fiscal para trânsito (aviso no DAMDFE, não “sem valor fiscal” diagonal).

Eventos pós-autorização

// Encerramento — obrigatório após transporte (MOC §3.7)
await client.Encerramento({
  chMDFe,
  nProt: protocoloAutorizacao,
  dtEnc: '2026-09-04',
  cUF: '41',
  cMun: '4106902',
});

// Cancelamento — até 24h, sem início de transporte
await client.Cancelamento({ chMDFe, nProt, xJust: 'Justificativa com no minimo 15 caracteres.' });

// Inclusão condutor
await client.InclusaoCondutor({
  chMDFe,
  condutor: { xNome: 'NOME', CPF: '12345678909' },
});

Retorno inclui procEventoMDFe (XML completo) para persistência no backend. CNPJ/CPF do emitente é obtido do certificado quando omitido no payload.

Integração backend (produção)

• Configure ambiente: 1 — URLs _P em MDFeServicosUrl.json
• Persista procMDFe e procEventoMDFe retornados pelos adapters
• PDF DAMDFE é auxiliar; validade fiscal está no XML
• Marca d'água homologação no PDF somente quando tpAmb=2

Fora do escopo (fases futuras)

• NFF / Autônomo (tpEmis=3), emitente PF (série 920–969)
• Modais aéreo, aquaviário, ferroviário
• Carregamento posterior (110115), pagamento transporte (110116/110118)
• Confirmação contratante (110117), eventos fisco
• Integração treeunfe-backend (após lib estável)

Documentação de referência

XSDs em runtime: packages/shared/resources/schemas/mdfe/

Consulte MOC MDF-e 3.00 (Visão Geral, Anexo I leiaute, Anexo II DAMDFe) nos portais SEFAZ.

Exemplo / testes

pnpm test:mdfe                              # autorizar → encerrar (ciclo feliz)
MDFE_EMITIR=1 pnpm test:mdfe                # só autorizar (pendente para eventos)
MDFE_CANCEL=1 pnpm test:mdfe                # cancelamento no pendente
MDFE_CONDUTOR=1 pnpm test:mdfe              # inclusão condutor
MDFE_CONTINGENCIA=1 pnpm test:mdfe          # tpEmis=2 local + DAMDFE
MDFE_REGULARIZAR=1 pnpm test:mdfe           # retransmitir contingência
MDFE_DIST=1 pnpm test:mdfe                  # distribuição DFe ultNSU

Fixtures: examples/MDFe/ — emitente fictício (EMITENTE_HOMOLOG).

Notas

• Autorização usa MDFeRecepcaoSinc (gzip+base64)
• Eventos usam XML sem compactação
• MDF-e não possui CC-e — alterações = cancelar/reemitir ou encerrar + novo manifesto
• Ciclo de vida: Autorizar → Transporte → Encerrar (110112)