MDF-e Sem Caos Logístico: Gere e Encerre Manifestos em Tempo Real com Código Pronto da API MagelNet

MDF-e precisa ser emitido e encerrado no momento certo para evitar frota parada, rejeições e multas que podem passar de R$ 1.000 por viagem. A forma mais segura de escalar isso é integrar uma API que valide documentos, acompanhe eventos da SEFAZ e automatize o encerramento com webhooks ou polling. Com a API MagelNet, isso pode começar com poucas linhas de código.

Imagine sua frota parada porque o MDF-e não encerrou a tempo, o próximo carregamento não pode sair e o time operacional começa a caçar erro em chave de acesso, protocolo e retorno da SEFAZ. Esse cenário é comum em transportadoras, TMS e ERPs logísticos que ainda dependem de rotinas frágeis ou integrações incompletas.

O MDF-e (Manifesto Eletrônico de Documentos Fiscais) consolida os documentos fiscais transportados em uma operação, normalmente CT-e e/ou NF-e, vinculando carga, veículo, percurso e responsável pelo transporte. Na prática, ele funciona como a camada de controle da viagem.

A ideia é simples: seu sistema continua dono da regra de negócio logística, enquanto a API MagelNet assume a parte mais sensível do documento fiscal eletrônico: validações, comunicação com a SEFAZ, contingências, eventos e armazenamento histórico. Isso reduz complexidade no seu código e aumenta previsibilidade operacional.

Abaixo está um blueprint de integração para times de desenvolvimento. Os nomes de campos podem variar conforme a versão da API, mas o fluxo arquitetural é este: autenticar, montar payload do manifesto, incluir documentos, enviar, acompanhar autorização e encerrar automaticamente.

Use credenciais da sandbox para obter o token e injete-o no seu client HTTP. Boas práticas: timeout curto, retry com backoff, correlation-id e logs estruturados por viagem/MDF-e.

Exemplo em Node.js para autenticação e envio inicial do manifesto:

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://sandbox.magelnet.com/api',
  timeout: 15000,
  headers: { 'Content-Type': 'application/json' }
});

async function autenticar() {
  const { data } = await api.post('/auth/token', {
    client_id: process.env.MAGELNET_CLIENT_ID,
    client_secret: process.env.MAGELNET_CLIENT_SECRET
  });

  api.defaults.headers.Authorization = `Bearer ${data.access_token}`;
  return data.access_token;
}

Monte o payload com foco em consistência. Antes de enviar, valide localmente: UF de carregamento/descarga, placa, condutor, RNTRC, ambiente, tipo de emitente e lista de chaves de CT-e/NF-e.

async function emitirMdfe() {
  const payload = {
    ambiente: 'homologacao',
    carga: {
      municipio_carregamento: '3550308',
      uf_carregamento: 'SP'
    },
    veiculo: {
      placa: 'ABC1D23',
      rntrc: '12345678'
    },
    condutor: {
      cpf: '12345678901',
      nome: 'Motorista Exemplo'
    },
    documentos: [
      { tipo: 'CTE', chave: '35240112345678000123570010000012341000012345' },
      { tipo: 'NFE', chave: '35240112345678000123550010000098761000098765' }
    ],
    percurso: ['SP', 'MG']
  };

  const { data } = await api.post('/mdfe', payload, {
    headers: {
      'Idempotency-Key': 'viagem-8471-mdfe-emissao'
    }
  });

  return data;
}

Configure um endpoint para receber eventos da API MagelNet. Assim, seu sistema deixa de depender apenas de consulta ativa e reage em tempo real a mudanças como autorizado, rejeitado, encerrado ou contingência ativada.

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/magelnet/mdfe', async (req, res) => {
  const evento = req.body;

  // valide assinatura/hmac se disponível
  // persista evento bruto para auditoria

  switch (evento.tipo) {
    case 'MDFE_AUTORIZADO':
      await atualizarViagem(evento.mdfe_id, 'autorizado', evento.protocolo);
      break;
    case 'MDFE_REJEITADO':
      await registrarErro(evento.mdfe_id, evento.codigo, evento.mensagem);
      break;
    case 'MDFE_ENCERRADO':
      await atualizarViagem(evento.mdfe_id, 'encerrado', evento.protocolo);
      break;
  }

  res.status(200).send({ ok: true });
});

Webhook é o caminho ideal, mas times experientes sempre mantêm fallback por polling para cobrir atraso de eventos, indisponibilidade temporária ou inconsistência de rede. O segredo é usar janela de consulta, backoff e trava idempotente.

async function acompanharEEncerrar(mdfeId, municipioEncerramento) {
  for (let tentativa = 1; tentativa <= 12; tentativa++) {
    const { data: status } = await api.get(`/mdfe/${mdfeId}/status`);

    if (status.situacao === 'AUTORIZADO') {
      const { data: encerramento } = await api.post(`/mdfe/${mdfeId}/encerrar`, {
        municipio_encerramento: municipioEncerramento
      }, {
        headers: {
          'Idempotency-Key': `mdfe-${mdfeId}-encerramento`
        }
      });

      return encerramento;
    }

    if (status.situacao === 'REJEITADO') {
      throw new Error(`MDF-e rejeitado: ${status.codigo} - ${status.mensagem}`);
    }

    await new Promise(r => setTimeout(r, tentativa * 5000));
  }

  throw new Error('Timeout aguardando autorização do MDF-e');
}

Em um cenário típico de integração logística, o ganho aparece quando a equipe para de tratar MDF-e como uma chamada isolada e passa a operar um pipeline observável. Com pré-validação de chaves, idempotência, webhook e fallback por polling, a emissão fica previsível e o encerramento deixa de depender de ação humana.

No exemplo acima, uma operação sai de 9,8% para 2,1% de rejeições, aumenta o encerramento no prazo de 61% para 96% e reduz o tempo médio de tratamento de 18 para 6 minutos. Não é mágica: é arquitetura correta, validação antecipada e automação de eventos.

Além da emissão e do encerramento, existe outra dor silenciosa: guardar e recuperar MDF-e, XMLs, protocolos e eventos antigos. Quando isso fica espalhado em banco local, storage improvisado ou dependente de janelas curtas de consulta, o suporte vira arqueologia.

Com o repositório central da MagelNet, sua operação mantém histórico documental com muito mais previsibilidade. Isso ajuda em auditoria, suporte, reconciliação, disputas operacionais e reprocessamento sem ficar preso às limitações comuns de consulta e download.

Se o seu sistema gerencia frota, expedição ou documentos de transporte, MDF-e não pode ser um ponto frágil da arquitetura. Emitir e encerrar em tempo real exige validação, observabilidade, fallback e trilha documental. Quando essa complexidade fica abstraída por uma API especializada, seu time ganha velocidade sem comprometer conformidade.

A API da MagelNet abstrai a complexidade do MDF-e — incluindo validações, contingências, eventos e repositório central — para que sua engenharia foque no core do negócio logístico. Teste grátis a integração MDF-e na sandbox da MagelNet e veja seu pipeline rodar sem interrupções: acesse a documentação da API e integre agora.