← Voltar ao Guia

🚚 Guia de Integração - MDF-e

Passo a passo completo para emitir MDF-e

✓ 4 MDF-e Autorizados

🔄 Fluxo de Operação MDF-e

1️⃣

Emitir

Autorização SEFAZ

→

2️⃣

Transporte

Em andamento

→

3️⃣

Encerrar

No destino

Opcional: Incluir condutor durante o transporte ou cancelar (até 24h)

🚚 Passo 1: Emitir MDF-e

Crie o MDF-e com os dados do veículo, condutores, carga e documentos fiscais:

POST /api/mdfe/emitir.php

{
    "emitente": {
        "nome": "PRINT JET DIGITAL",
        "nome_fantasia": "Print Jet",
        "cnpj": "21497109000156",
        "inscricao_estadual": "093218028",
        "estado": "PE",
        "cidade": "Recife",
        "endereco": "Rua Frei Cassimiro",
        "numero": "644",
        "bairro": "Santo Amaro",
        "cep": "50100260",
        "telefone": "(81) 99999-9999",
        "email": "atendimento@printjetdigital.com.br"
    },
    "mdfe": {
        "numero": "1",
        "serie": "001"
    },
    "tipo_emitente": 2,
    "modal": 1,
    "uf_inicio": "PE",
    "uf_fim": "SP",
    "veiculo": {
        "codigo_interno": "VEI001",
        "placa": "ABC1234",
        "renavam": "12345678901",
        "tara": 8000,
        "capacidade_kg": 25000,
        "capacidade_m3": 80,
        "tipo_rodado": "02",
        "tipo_carroceria": "00",
        "uf": "PE"
    },
    "condutores": [
        {
            "nome": "João da Silva",
            "cpf": "05138670409"
        }
    ],
    "municipios_carregamento": [
        {
            "codigo_municipio": 2611606,
            "nome": "Recife",
            "nfes": [
                {
                    "chave_acesso": "35251012345678000195550010000000011234567890"
                }
            ]
        }
    ],
    "municipios_descarregamento": [
        {
            "codigo_municipio": 3550308,
            "nome": "São Paulo",
            "nfes": [
                {
                    "chave_acesso": "35251012345678000195550010000000011234567890"
                }
            ]
        }
    ],
    "totalizadores": {
        "quantidade_nfe": 1,
        "quantidade_cte": 0,
        "quantidade_mdfe": 0,
        "valor_carga": 5000.00,
        "codigo_unidade": "01",
        "peso_carga": 2500.0000
    },
    "informacoes_complementares": "Transporte de mercadorias"
}

✅ Resposta de Sucesso:

Response

{
    "success": true,
    "numero": "1",
    "serie": "001",
    "chave_acesso": "26251021497109000156580010000000011735126513",
    "protocolo": "926250000006524",
    "cStat": "100",
    "xml_path": "/pontti_nfe/arquivos/.../mdfe/xml/...",
    "message": "MDF-e emitido com sucesso"
}

✅ Importante

Guarde a chave_acesso e protocolo - serão necessários para encerramento/cancelamento

👤 Passo 2 (Opcional): Incluir Condutor

Durante o transporte, você pode incluir condutores adicionais:

POST /api/mdfe/incluir_condutor.php

{
    "chave_acesso": "26251021497109000156580010000000011735126513",
    "cnpj": "21497109000156",
    "condutor": {
        "nome": "Maria Santos Silva",
        "cpf": "12345678909"
    }
}

🏁 Passo 3: Encerrar MDF-e

Ao chegar no destino, encerre o MDF-e informando o município:

POST /api/mdfe/encerrar.php

{
    "chave_acesso": "26251021497109000156580010000000011735126513",
    "protocolo": "926250000006524",
    "cnpj": "21497109000156",
    "uf_encerramento": "SP",
    "municipio_encerramento": {
        "codigo": "3550308",
        "nome": "São Paulo"
    }
}

✅ MDF-e Encerrado

Após o encerramento, você pode emitir novo MDF-e para a mesma placa e destino.

❌ Alternativa: Cancelar MDF-e

Se houver erro ou necessidade de cancelamento (até 24 horas e antes do encerramento):

POST /api/mdfe/cancelar.php

{
    "chave_acesso": "26251021497109000156580010000000011735126513",
    "protocolo": "926250000006524",
    "cnpj": "21497109000156",
    "justificativa": "Erro no preenchimento dos dados do MDF-e, necessário cancelamento"
}

⚠️ Atenção

• Justificativa mínima: 15 caracteres

• Não pode cancelar MDF-e já encerrado

• Prazo: até 24 horas após autorização

📊 Tabelas de Referência

Tipo de Emitente

Código	Descrição
`1`	Prestador de serviço de transporte
`2`	Transportador de Carga Própria ✅ Recomendado
`3`	Prestador que emitirá CT-e Globalizado

Tipo de Rodado

Código	Descrição	Reboque
`01`	Truck	Não
`02`	Toco ✅ Recomendado	Não
`03`	Cavalo Mecânico	Sim (obrigatório)
`04`	VAN	Não
`05`	Utilitário	Não
`06`	Outros	Não

Principais Municípios (Código IBGE)

Cidade	UF	Código
Recife	PE	`2611606`
São Paulo	SP	`3550308`
Rio de Janeiro	RJ	`3304557`
Belo Horizonte	MG	`3106200`
Salvador	BA	`2927408`
Brasília	DF	`5300108`

⚠️ Erros Comuns e Soluções

Código	Erro	Solução
`539`	Duplicidade de MDF-e	MDF-e já autorizado - use outro número
`604`	Chave NF-e inválida	Verifique o DV da chave de acesso das NF-es
`611`	MDF-e não encerrado	Encerre o MDF-e anterior para a mesma placa
`631`	Duplicidade de evento	Evento já registrado anteriormente
`663`	Percurso inválido	Sistema adiciona percurso automaticamente (BA, MG)
`740`	Proprietário igual emitente	Não informe proprietário se for o próprio emitente
`745`	Tipo transportador sem proprietário	Não informe tipo_transportador se não houver proprietário

💡 Dicas Importantes

🔑

Chaves NF-e

Use chaves REAIS de NF-es autorizadas que estão sendo transportadas

🚗

Uma Placa por Vez

Só pode haver 1 MDF-e aberto por placa e UF de destino

🗺️

Percurso Automático

Sistema adiciona BA e MG automaticamente entre PE e SP

⚖️

Peso e Capacidade

Tara + Carga não pode exceder capacidade do veículo

🔢

Numeração

Controle sequencial rigoroso por série

📍

Município Correto

Use códigos IBGE corretos para carga e descarga

📝 Cenários Práticos

Cenário 1: Transporte Simples (PE → SP)

Situação: 1 caminhão toco, 1 motorista, 1 NF-e

JSON: exemplos_json/mdfe_emissao_completa.json

Tipo rodado: 02 (Toco)

Tipo emitente: 2 (Carga própria)

Cenário 2: Múltiplos Documentos

Situação: Transporte de 5 NF-es diferentes

Solução: Adicione todas as chaves no array "nfes"

Totalizadores: quantidade_nfe = 5

Cenário 3: Troca de Motorista

Situação: Motorista substituto durante viagem

Solução: Use o endpoint /api/mdfe/incluir_condutor.php

Quando: Durante o transporte (MDF-e não encerrado)

✅ Checklist Antes de Emitir

Certificado digital (.pfx) instalado na pasta correta
Senha do certificado configurada em config_certificado.php
Chaves de acesso das NF-es são VÁLIDAS
Códigos IBGE dos municípios estão corretos
Dados do veículo (placa, renavam, tara) estão corretos
CPF do(s) condutor(es) é válido
Não há MDF-e aberto para mesma placa e destino
Ambiente configurado (2=Homologação, 1=Produção)