Endpoints MDF-e (Modelo 58)

Referência técnica completa dos endpoints REST para emissão, consulta, geração do DAMDFE, encerramento de viagem e gestão de manifestos abertos. Autenticação via header x-api-key.

1. Emissão de MDF-e

Enfileira o manifesto de viagem para assinatura digital e autorização na SEFAZ. Bloqueia a placa contra concorrência e inicia o rastreio da rota.

POST/mdfe/emitir🔑 x-api-key

Envia os dados do manifesto de carga. Retorna 202 com status 'queued' e o invoiceId para acompanhamento.

Parâmetros da Requisição (Nível Raiz)

Campo	Tipo	Req?	Descrição
serie	number	não	Número de série do MDF-e (ex: 1). Se omitido, utiliza a série padrão do projeto.
dados	object	sim	Objeto contendo os dados operacionais, veículo, motoristas, descargas e rota da viagem.

Campos Amigáveis do Objeto 'dados'

Campo	Tipo	Req?	Descrição
tipoEmitente	string \| number	não	Aceita prestador_servico/prestador/transportador/1 (CT-e) ou carga_propria/embarcador/2 (NF-e); padrão 1. Nome canônico: tpEmit.
tipoTransportador	string \| number	não	"etc" (Empresa de Transporte), "tac" (Autônomo) ou "ctc" (Cooperativa).
ufInicio	string	sim	UF de início da rota (ex: "SP").
ufFim	string	sim	UF de encerramento da rota (ex: "RJ").
municipiosCarregamento	array	sim	Locais de carregamento: [{ codigoMunicipio: 3550308, municipio: "São Paulo" }].
ufsPercurso	array	não	UFs intermediárias cruzadas na rota rodoviária (ex: ["MG"]).
veiculoTracao	object	sim	Exige placa válida, tara inteira não negativa e de 1 a 10 condutores com nome e CPF. Aceita renavam, capacidadeKg/capacidadeM3, tipoRodado, tipoCarroceria e uf.
veiculoReboque	array	não	Reboques acoplados: [{ placa: "DEF4G56", renavam: "...", tara: 5000, capacidadeKg: 15000, tipoCarroceria: "bau", uf: "SP" }].
antt	object	não	Grupo ANTT em rodo; rntrc deve ter 8 dígitos. Também aceita CIOT, vale-pedágio, contratantes e pagamentos nos formatos técnicos definidos no contrato.
descargas	array	sim	De 1 a 1000 paradas com codigoMunicipio e municipio. Cada parada pode incluir chavesCte e/ou chavesNfe (listas de chaves de 44 dígitos).
produtoPredominante	object	não	Opcional: tipoCarga (código 01–12 ou nome amigável), descricao e, opcionalmente, ean/gtin, ncm e lotacao { cepCarrega, cepDescarrega }. Nome canônico: prodPred.
valorTotalCarga	number	sim	Valor total da carga; aliases aceitos: vCarga e valorCarga.
pesoBrutoTotal	number	sim	Quantidade da carga; aliases: qCarga, pesoBruto e quantidadeCarga. cUnid aceita "01" (KG) ou "02" (TON), com padrão "01".
dataHoraInicioViagem	string (ISO 8601 com fuso)	não	Data e hora de início da viagem; nome canônico dhIniViagem.
informacoesAdicionaisFisco / informacoesComplementares	string	não	Aliases de infAdFisco (até 2000 caracteres) e infCpl (até 5000 caracteres).
cUnid	string	não	Unidade da quantidade de carga: "01" (KG) ou "02" (TON); padrão "01".
seguros	array	não	Registros de seguro com respSeg (1 ou 2) e, conforme o caso, documentoResponsavel, seguradora { xSeg, CNPJ }, nApol e nAver.
lacres	string[]	não	Até 100 números/identificadores de lacre, com no máximo 60 caracteres cada.
autXML	string[]	não	Até 10 CPF/CNPJ autorizados a acessar o XML.
serie	number	não	No nível raiz do body, inteiro de 0 a 889; usa a série padrão do projeto quando omitido.

Percurso, múltiplas descargas e documentos

Informe em ufsPercurso cada UF intermediária na ordem em que a viagem a cruza; não inclua a UF de início nem a UF final. Para entregas em mais de um município, crie um item de descargas por parada e vincule em cada parada as chaves dos CT-e ou das NF-e descarregados ali. Em carga própria (emitente 2), normalmente são referenciadas NF-e; no transporte contratado (emitente 1), CT-e. O tipo de documento e a operação precisam ser consistentes com a viagem real e com as regras fiscais aplicáveis.

Para veículo arrendado/de terceiro, reboques, CIOT, vale-pedágio e contratantes, use os campos detalhados em rodo. O payload amigável reduz os códigos mais comuns, mas esses subgrupos ainda têm campos técnicos e regras próprias; consulte o schema/OpenAPI antes de integrá-los.

Exemplo Completo: MDF-e Rodoviário com Carga Interestadual (Payload Amigável)

{
  "serie": 1,
  "dados": {
    "tipoEmitente": "prestador_servico",
    "tipoTransportador": "etc",
    "ufInicio": "SP",
    "ufFim": "RJ",
    "municipiosCarregamento": [
      {
        "codigoMunicipio": 3550308,
        "municipio": "São Paulo"
      }
    ],
    "ufsPercurso": [
      "MG"
    ],
    "veiculoTracao": {
      "placa": "ABC1D23",
      "renavam": "12345678901",
      "tara": 8500,
      "capacidadeKg": 25000,
      "tipoRodado": "truck",
      "tipoCarroceria": "aberta",
      "uf": "SP",
      "motoristas": [
        {
          "nome": "João da Silva",
          "cpf": "529.982.247-25"
        }
      ]
    },
    "antt": {
      "rntrc": "12345678"
    },
    "descargas": [
      {
        "codigoMunicipio": 3304557,
        "municipio": "Rio de Janeiro",
        "chavesCte": [
          "35261011222333000181570010000001231123456781"
        ]
      }
    ],
    "produtoPredominante": {
      "tipoCarga": "granel_solido",
      "descricao": "CARGA GERAL FRACIONADA",
      "ncm": "94032000"
    },
    "valorTotalCarga": 85000,
    "pesoBrutoTotal": 4500,
    "cUnid": "01"
  }
}

2. Consulta, XML de Distribuição e DAMDFE

Obtenha o status em tempo real, faça download do XML assinado ou gere o DAMDFE em PDF para impressão.

GET/mdfe/invoices/{id}/status🔑 x-api-key

Retorna status atual (issued, closed, cancelled), protocolo SEFAZ, placa do caminhão e detalhes do encerramento se já finalizado.

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "issued",
  "numero": 850,
  "serie": 1,
  "chaveAcesso": "35261011222333000181580010000008501000008503",
  "protocoloAutorizacao": "135260000000002",
  "placaTracao": "ABC1D23",
  "dataAutorizacao": "2026-10-01T21:42:00.000Z",
  "cStat": 100,
  "xMotivo": "Autorizado o uso do MDF-e"
}

GET/mdfe/invoices/{id}/xml🔑 x-api-key

Retorna o XML completo do manifesto (mdfeProc com protMDFe assinado pela SEFAZ).

GET/mdfe/invoices/{id}/damdfe🔑 x-api-key

Retorna o documento auxiliar (DAMDFE) em PDF de alta qualidade com QR Code e marca d'água de encerramento quando aplicável.

Exemplo de Visualização e Download do DAMDFE

O endpoint retorna o arquivo com Content-Disposition: inline para abertura imediata no navegador. Você também pode testar a renderização visual em nossos links públicos:

Abrir Visualizador Web do DAMDFE →·Baixar PDF Binário (/api/examples/damdfe-pdf) →

3. Encerramento Auditado de MDF-e (Evento 110112)

Registra o encerramento da viagem na SEFAZ e libera a placa do caminhão para novas emissões.

POST/mdfe/encerrar🔑 x-api-key

Executa o evento 110112 com auditoria inteligente da rota. Desvios ou encerramentos intermediários exigem confirmação explícita no payload.

Body (JSON)

Campo	Tipo	Req?	Descrição
invoiceId	string (UUID)	sim	ID do manifesto a ser encerrado.
uf	string	sim	UF onde ocorreu a finalização efetiva da viagem (ex: "RJ").
codigoMunicipio / cMun	number	sim	Código IBGE de 7 dígitos do município onde o caminhão finalizou a rota (ex: 3304557).
dataEncerramento	string (YYYY-MM-DD)	não	Data do encerramento (se omitido, assume a data/hora atual).
confirmarEncerramentoIntermediario	boolean	não	Obrigatório enviar true se estiver encerrando antes do destino final planejado.
confirmarDesvioRota	boolean	não	Obrigatório enviar true se a viagem terminou em UF fora da rota declarada.

{
  "invoiceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "uf": "RJ",
  "codigoMunicipio": 3304557
}

4. Cancelamento de MDF-e (Evento 110111)

Permite cancelar um MDF-e autorizado dentro do prazo SEFAZ de 24 horas, desde que o caminhão ainda não tenha iniciado a viagem física.

POST/mdfe/cancelar🔑 x-api-key

Envia o pedido de cancelamento à SEFAZ. Se o MDF-e já tiver sido encerrado (closed), o cancelamento é rejeitado pela legislação.

Body (JSON)

Campo	Tipo	Req?	Descrição
invoiceId	string (UUID)	sim	ID do MDF-e a ser cancelado.
justificativa	string	sim	Justificativa (15 a 255 caracteres).

5. Monitoramento de Manifestos Abertos

Evite multas e placas bloqueadas consultando em tempo real quais veículos da sua frota estão com viagens pendentes de encerramento.

GET/mdfe/alertas/abertos🔑 x-api-key

Lista todos os MDF-e autorizados e não encerrados, calculando o total de horas em aberto e sinalizando criticidade (>48h).

Query Params (Opcionais)

Campo	Tipo	Req?	Descrição
placa	string	não	Filtra pelo veículo específico (ex: "ABC1D23").
olderThanHours	number	não	Filtra manifestos abertos há mais de N horas (ex: 48).

Diagnóstico de Rejeições Comuns do MDF-e

Rejeição 616 / 628 — Existe MDF-e não encerrado para esta placaSEFAZ

Causa: O caminhão realizou uma viagem anterior cujo MDF-e não foi encerrado na SEFAZ.
Solução: Chame o endpoint POST /api/v1/mdfe/encerrar informando a UF e município onde o veículo está para liberar a placa.

Rejeição 220 — Prazo de Cancelamento Superior a 24 HorasSEFAZ

Causa: Ao contrário da NF-e (24h) e do CT-e (168h), o prazo de cancelamento do MDF-e é de estritamente 24 horas.
Solução: Se a viagem foi abortada após 24 horas, deve-se realizar o Encerramento por Interrupção de Viagem.