Emitir MDFe

POST/v1/mdfe/emit

POST /v1/mdfe/emit emite um MDF-e (mod: "58") — o Manifesto Eletrônico de Documentos Fiscais que agrupa os DF-e (NF-e, CT-e) transportados em uma viagem.

Endpoint assíncrono

Esta chamada retorna 202 Accepted assim que o documento entra na fila de processamento — não espera pela SEFAZ. Uma rejeição da SEFAZ (schema inválido, duplicidade, regra de negócio, etc.) não vira erro HTTP nesta chamada: ela só aparece depois, consultando GET /v1/mdfe/{id} com o invoiceId retornado aqui. Use esse endpoint para fazer polling até o status deixar de ser PENDENTE.

Numeração automática

Os campos serie e numero podem ficar em branco — nesse caso a API se responsabiliza pela numeração automática do MDF-e, o que é o comportamento recomendado.

Parâmetros do corpo

Campos principais

modstringobrigatório

Valores aceitos: 58

Modelo do documento: 58 para MDF-e.

tipo_transportestring | number

Valores aceitos: 1 | 2 | 3

Tipo do Transportador. 1: ETC · 2: TAC · 3: CTC.

uf_iniciostring

Sigla da UF de carregamento. Informar EX para operações com o exterior.

uf_fimstring

Sigla da UF de descarregamento. Informar EX para operações com o exterior.

cnpj_emitentestring

CNPJ do emitente.

inscricao_estadual_emitentestring | number

Inscrição Estadual da empresa emitente.

nome_emitentestring

Razão Social ou nome da empresa emitente.

municipios_carregamentoarray

Municípios de carregamento da carga.

codigostring | number

Código IBGE do município de carregamento.

nomestring

Nome do município de carregamento.

municipios_descarregamentoarray

Municípios de descarregamento, com os documentos fiscais vinculados.

codigostring | number

Código IBGE do município de descarregamento.

nomestring

Nome do município de descarregamento.

notas_fiscaisarray

NF-e transportadas até este município.

chave_nfestring

Chave de acesso de 44 dígitos da NF-e.

valor_total_cargastring | number

Valor total da carga/mercadorias transportadas.

peso_brutostring | number

Peso Bruto Total da carga/mercadorias transportadas.

Só o campo mod é estritamente obrigatório no schema, mas uma emissão real de MDF-e normalmente precisa de pelo menos os campos de identificação do emitente, UF de início/fim e os municípios de carregamento/descarregamento acima. Veja a listagem completa de campos de MDF-e para todos os grupos opcionais (seguro de carga, lacres, produtos perigosos, pessoas autorizadas, responsável técnico, etc).

Resposta

202 Accepted

messagestring

Confirmação de que o documento entrou na fila de processamento.

invoiceIdstring

UUID interno do documento — use nas chamadas de consulta e nos eventos de MDF-e (encerramento, inclusão de condutor, inclusão de DF-e).

accessKeystring

Chave de acesso de 44 dígitos do documento fiscal, quando já pode ser calculada no momento do enfileiramento.

cURL

curl -X POST https://app.nfe.tenzanlabs.com/v1/mdfe/emit \
  -H "X-Access-Key: nfe_access_SUA_CHAVE_DE_ACESSO_AQUI" \
  -H "Authorization: Bearer nfe_test_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "mod": "58",
    "tipo_transporte": "1",
    "uf_inicio": "SP",
    "uf_fim": "RJ",
    "municipios_carregamento": [
      { "codigo": "3550308", "nome": "São Paulo" }
    ],
    "cnpj_emitente": "12345678000199",
    "inscricao_estadual_emitente": "123456789",
    "nome_emitente": "Transportadora Exemplo LTDA",
    "municipios_descarregamento": [
      {
        "codigo": "3304557",
        "nome": "Rio de Janeiro",
        "notas_fiscais": [
          { "chave_nfe": "35260812345678000199550010000000011000000018" }
        ]
      }
    ],
    "valor_total_carga": 15000.00,
    "peso_bruto": 1200.5,
    "codigo_unidade_medida_peso_bruto": "01"
  }'

Node.js

import { NFeClient } from '@tenzanlabs/nfe-node-sdk';

const client = new NFeClient('nfe_access_SUA_CHAVE_DE_ACESSO_AQUI', 'nfe_test_SUA_CHAVE_AQUI');

const resposta = await client.emit({
  mod: '58',
  tipo_transporte: '1',
  uf_inicio: 'SP',
  uf_fim: 'RJ',
  municipios_carregamento: [
    { codigo: '3550308', nome: 'São Paulo' },
  ],
  cnpj_emitente: '12345678000199',
  inscricao_estadual_emitente: '123456789',
  nome_emitente: 'Transportadora Exemplo LTDA',
  municipios_descarregamento: [
    {
      codigo: '3304557',
      nome: 'Rio de Janeiro',
      notas_fiscais: [
        { chave_nfe: '35260812345678000199550010000000011000000018' },
      ],
    },
  ],
  valor_total_carga: 15000.0,
  peso_bruto: 1200.5,
  codigo_unidade_medida_peso_bruto: '01',
});
console.log(resposta.invoiceId);

Python

from nfe_sdk import NFeClient

client = NFeClient(access_key='nfe_access_SUA_CHAVE_DE_ACESSO_AQUI', api_key='nfe_test_SUA_CHAVE_AQUI')

resposta = client.emit({
    "mod": "58",
    "tipo_transporte": "1",
    "uf_inicio": "SP",
    "uf_fim": "RJ",
    "municipios_carregamento": [
        {"codigo": "3550308", "nome": "São Paulo"},
    ],
    "cnpj_emitente": "12345678000199",
    "inscricao_estadual_emitente": "123456789",
    "nome_emitente": "Transportadora Exemplo LTDA",
    "municipios_descarregamento": [
        {
            "codigo": "3304557",
            "nome": "Rio de Janeiro",
            "notas_fiscais": [
                {"chave_nfe": "35260812345678000199550010000000011000000018"},
            ],
        },
    ],
    "valor_total_carga": 15000.00,
    "peso_bruto": 1200.5,
    "codigo_unidade_medida_peso_bruto": "01",
})
print(resposta["invoiceId"])

Java

import br.com.saascore.nfe.NFeClient;
import br.com.saascore.nfe.model.MdfeData;
import java.util.*;

NFeClient client = new NFeClient("nfe_access_SUA_CHAVE_DE_ACESSO_AQUI", "nfe_test_SUA_CHAVE_AQUI");

MdfeData manifesto = new MdfeData();
manifesto.mod = "58";
manifesto.tipo_transporte = "1";
manifesto.uf_inicio = "SP";
manifesto.uf_fim = "RJ";
manifesto.cnpj_emitente = "12345678000199";
manifesto.inscricao_estadual_emitente = "123456789";
manifesto.nome_emitente = "Transportadora Exemplo LTDA";
manifesto.valor_total_carga = 15000.00;
manifesto.peso_bruto = 1200.5;
manifesto.codigo_unidade_medida_peso_bruto = "01";

MdfeData.MdfeDataMunicipiosCarregamento carregamento = new MdfeData.MdfeDataMunicipiosCarregamento();
carregamento.codigo = "3550308";
carregamento.nome = "São Paulo";
manifesto.municipios_carregamento = List.of(carregamento);

MdfeData.MdfeDataMunicipiosDescarregamentoNotasFiscais nota = new MdfeData.MdfeDataMunicipiosDescarregamentoNotasFiscais();
nota.chave_nfe = "35260812345678000199550010000000011000000018";

MdfeData.MdfeDataMunicipiosDescarregamento descarregamento = new MdfeData.MdfeDataMunicipiosDescarregamento();
descarregamento.codigo = "3304557";
descarregamento.nome = "Rio de Janeiro";
descarregamento.notas_fiscais = List.of(nota);
manifesto.municipios_descarregamento = List.of(descarregamento);

var resposta = client.emit(manifesto);
System.out.println(resposta.invoiceId);

Exemplo de resposta

{
  "message": "Documento enfileirado para processamento",
  "invoiceId": "35f0a1b2-...",
  "accessKey": "35260812345678000199580010000000011000000018"
}