API CT-e e MDF-e: Guia Definitivo de Integração REST JSON para ERPs e TMS

A gestão fiscal de transporte rodoviário de cargas no Brasil sempre foi considerada uma das disciplinas mais complexas da engenharia tributária. Desenvolvedores de ERPs, softwares de gestão de transporte (TMS) e plataformas de e-commerce frequentemente enfrentam uma barreira técnica intimidadora: webservices SOAP heterogêneos das Secretarias de Fazenda estaduais (SEFAZ), schemas XSD imensos e a manutenção custosa de bibliotecas legadas (como componentes ACBr e DLLs atreladas a ambientes Windows).

Com a disponibilização dos endpoints de CT-e (Conhecimento de Transporte Eletrônico - Modelo 57) e MDF-e (Manifesto Eletrônico de Documentos Fiscais - Modelo 58) na API da Notaas, essa fricção foi eliminada.

Agora, a sua aplicação pode gerenciar o ciclo fiscal completo da logística nacional — da nota de venda do produto ao documento de transporte e manifesto de carga na estrada — utilizando requisições REST limpas em JSON, webhooks com assinatura criptográfica e geração local ultrarrápida de DACTE e DAMDFE em PDF.

Neste guia técnico, você entenderá as diferenças regulatórias entre o CT-e e o MDF-e, o fluxo operacional de despacho de carga, os payloads de envio, o tratamento de eventos essenciais (como inclusão de condutor e encerramento automatizado) e como implementar a integração em TypeScript e cURL.

🧭 CT-e vs MDF-e: Entendendo os Papéis Fiscais

Antes de escrever a primeira linha de código, é fundamental compreender a finalidade de cada documento fiscal exigido pelo Fisco brasileiro:

⚡ O Ciclo Operacional de Transporte e Despacho de Cargas

Na prática, uma operação logística de distribuição interestadual obedece a uma esteira rigorosa de emissão fiscal. A Notaas simplifica esse fluxo em 4 etapas assíncronas:

🚚 Fluxo Completo de Expedição e Transporte:

• 1. Faturamento da Venda: O ERP emite as Notas Fiscais de Produto (NF-e Modelo 55) via POST /api/v1/nfe/emitir.
• 2. Contratação do Frete (se houver transportadora): A transportadora emite o CT-e Modelo 57 via POST /api/v1/cte/emitir, referenciando as chaves de acesso das NF-es transportadas.
• 3. Criação do Manifesto: Antes de o caminhão sair para a rodovia, a expedição dispara POST /api/v1/mdfe/emitir, agrupando todas as chaves de NF-e e CT-e, vinculando a placa do veículo, RNTRC e condutor.
• 4. Encerramento no Destino: Quando a carga é descarregada no destino final, a aplicação chama POST /api/v1/mdfe/encerrar, liberando o veículo para novas viagens e evitando multas na barreira fiscal.

📦 1. Como Emitir o CT-e (Modelo 57) via API REST

Para emitir um CT-e Rodoviário na Notaas, o sistema envia um objeto JSON contendo os dados do tomador do serviço, remetente, destinatário, valores da prestação, componentes do frete, informações de seguro e as NF-es transportadas.

Exemplo de Payload JSON para Emissão de CT-e

{
  "modelo": "57",
  "naturezaOperacao": "TRANSPORTE RODOVIARIO DE CARGAS",
  "cfop": "6353",
  "tipoServico": "NORMAL",
  "formaPagamento": "PAGO",
  "municipioEnvio": "3550308",
  "municipioInicio": "3550308",
  "municipioFim": "3106200",
  "tomador": {
    "tipo": "REMETENTE"
  },
  "remetente": {
    "cnpj": "12345678000195",
    "razaoSocial": "DISTRIBUIDORA DE ALIMENTOS PAULISTA LTDA",
    "inscricaoEstadual": "123456789110",
    "endereco": {
      "logradouro": "Avenida dos Bandeirantes",
      "numero": "2500",
      "bairro": "Vila Olimpia",
      "codigoMunicipio": "3550308",
      "uf": "SP",
      "cep": "04553000"
    }
  },
  "destinatario": {
    "cnpj": "98765432000100",
    "razaoSocial": "SUPERMERCADOS BH COMERCIO S/A",
    "inscricaoEstadual": "0621234560088",
    "endereco": {
      "logradouro": "Avenida Amazonas",
      "numero": "1800",
      "bairro": "Centro",
      "codigoMunicipio": "3106200",
      "uf": "MG",
      "cep": "30180001"
    }
  },
  "valores": {
    "valorTotalServico": 1850.00,
    "valorReceber": 1850.00,
    "componentes": [
      { "nome": "FRETE VALOR", "valor": 1600.00 },
      { "nome": "GRIS (GERENCIAMENTO DE RISCO)", "valor": 150.00 },
      { "nome": "PEDAGIO", "valor": 100.00 }
    ]
  },
  "impostos": {
    "icms": {
      "cst": "00",
      "aliquota": 12.00,
      "baseCalculo": 1850.00,
      "valor": 222.00
    }
  },
  "carga": {
    "valorTotalCarga": 85400.00,
    "produtoPredominante": "MERCADORIAS MANUFATURADAS",
    "quantidadeCarga": [
      {
        "codigoUnidade": "01",
        "tipoMedida": "PESO BRUTO",
        "quantidade": 14250.500
      }
    ]
  },
  "seguro": {
    "responsavel": "EMITENTE",
    "seguradora": "PORTO SEGURO CIA DE SEGUROS",
    "numeroApolice": "987654321",
    "numeroAverbacao": "AVG20261002998811"
  },
  "documentosTransportados": [
    {
      "tipo": "NFE",
      "chaveAcesso": "35261012345678000195550010000045611000045610"
    }
  ]
}

A engine da Notaas valida a consistência de municípios IBGE, assina o documento com o Certificado Digital A1 cadastrado na organização e submete o lote à SEFAZ autorizadora.

🚛 2. Como Emitir o MDF-e (Modelo 58) e Vincular Documentos

O MDF-e é o documento de fiscalização rodoviária por excelência. Quando o caminhão é abordado no posto fiscal da Polícia Rodoviária Federal ou Receita Estadual, o agente fiscal escaneia apenas o QR Code do DAMDFE.

Caso 1: MDF-e de Carga Própria (E-commerce / Frotas Próprias)

Muitos fundadores e desenvolvedores de e-commerce desconhecem que toda empresa que realiza entregas interestaduais com veículos próprios ou locados é obrigada por lei a emitir o MDF-e, mesmo que não seja uma transportadora contratada.

Nesse caso:

• O tipo de emitente é configurado como CARGA_PROPRIA (ou tpEmit = 2).
• As notas fiscais vinculadas são diretamente as NF-es de venda (Modelo 55).
• Não há necessidade de emissão prévia de CT-e.

Caso 2: MDF-e de Prestador de Serviço de Frete (Transportadora)

• O tipo de emitente é configurado como TRANSPORTADOR (ou tpEmit = 1).
• Os documentos vinculados são os CT-es (Modelo 57) emitidos para cada tomador de frete.

Exemplo de Payload JSON para Emissão de MDF-e

{
  "modelo": "58",
  "tipoEmitente": "CARGA_PROPRIA",
  "ufInicio": "SP",
  "ufFim": "MG",
  "municipioCarregamento": "3550308",
  "veiculoTracao": {
    "placa": "BRA2E19",
    "renavam": "00123456789",
    "tara": 8500,
    "capacidadeKg": 16000,
    "uf": "SP",
    "tipoRodado": "02",
    "tipoCarroceria": "01",
    "condutor": {
      "nome": "Carlos Eduardo da Silva",
      "cpf": "12345678901"
    }
  },
  "totais": {
    "quantidadeNFe": 1,
    "valorTotalCarga": 85400.00,
    "codigoUnidadePeso": "01",
    "pesoBruto": 14250.50
  },
  "municipiosDescarregamento": [
    {
      "codigoMunicipio": "3106200",
      "documentos": [
        {
          "tipo": "NFE",
          "chaveAcesso": "35261012345678000195550010000045611000045610"
        }
      ]
    }
  ]
}

🛑 3. Como Resolver a Rejeição 611/612 (Existe MDF-e Não Encerrado)

O erro mais comum que paralisa veículos em estradas e trava a expedição de mercadorias é a Rejeição 611 da SEFAZ ("Existe MDF-e não encerrado para esta placa há mais de 30 dias") ou a Rejeição 612 ("Existe MDF-e não encerrado para esta UF de início e fim").

A legislação impede a emissão de um novo MDF-e para um veículo que ainda consta com viagem em aberto para a mesma rota.

A. Consultando Manifestos Não Encerrados

Na Notaas, você pode consultar via API os manifestos pendentes antes de iniciar o processo de emissão:

curl -X GET "https://api.notaas.com.br/api/v1/mdfe/nao-encerrados?placa=BRA2E19" \
  -H "Authorization: Bearer seu_api_key_notaas" \
  -H "X-Project-Id: proj_9988aabb"

A resposta retornará a lista com o número do protocolo, a chave de acesso do manifesto pendente e a UF em aberto.

B. Encerrando o MDF-e Automaticamente

Assim que o veículo chega ao destino ou seu sistema recebe a confirmação de entrega via comprovante eletrônico (POD), basta chamar o endpoint de encerramento:

curl -X POST "https://api.notaas.com.br/api/v1/mdfe/encerrar" \
  -H "Authorization: Bearer seu_api_key_notaas" \
  -H "Content-Type: application/json" \
  -d '{
    "chaveAcesso": "35261012345678000195580010000012341000012349",
    "protocoloAutorizacao": "135260001234567",
    "ufEncerramento": "MG",
    "codigoMunicipioEncerramento": "3106200"
  }'

⚡ Dica de Engenharia e Resiliência:
Implemente uma rotina automatizada no seu backend: quando seu sistema registrar o evento de entrega finalizada pelo motorista no app mobile, dispare o encerramento do MDF-e imediatamente via API. Isso garante que, no dia seguinte, a placa do veículo estará 100% liberada na SEFAZ para carregar uma nova viagem.

💻 4. Exemplo Prático de Integração em TypeScript (Node.js / Next.js)

Abaixo está um módulo de serviço em TypeScript pronto para produção, demonstrando a emissão assíncrona com tratamento de idempotência e tipagem segura:

// services/fiscalTransporteService.ts
import axios from 'axios';

const NOTAAS_API_BASE = 'https://api.notaas.com.br/api/v1';
const API_KEY = process.env.NOTAAS_API_KEY!;
const PROJECT_ID = process.env.NOTAAS_PROJECT_ID!; // Multi-tenant / Multi-CNPJ

const client = axios.create({
  baseURL: NOTAAS_API_BASE,
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'X-Project-Id': PROJECT_ID,
    'Content-Type': 'application/json',
  },
  timeout: 10000,
});

export interface EmissaoMdfeResponse {
  id: string;
  status: 'PROCESSANDO' | 'AUTORIZADO' | 'REJEITADO';
  chaveAcesso?: string;
  protocolo?: string;
  urlDamdfePdf?: string;
  urlXml?: string;
  motivoRejeicao?: string;
}

/**
 * Emite um MDF-e de Carga Própria para entregas interestaduais
 */
export async function emitirMdfeCargaPropria(
  payload: Record<string, unknown>,
  idempotencyKey: string
): Promise<EmissaoMdfeResponse> {
  try {
    const response = await client.post<EmissaoMdfeResponse>(
      '/mdfe/emitir',
      payload,
      {
        headers: {
          'Idempotency-Key': idempotencyKey, // Evita emissão duplicada em caso de timeout
        },
      }
    );

    return response.data;
  } catch (error: any) {
    if (error.response) {
      console.error('[Notaas API] Erro na emissão de MDF-e:', error.response.data);
      throw new Error(error.response.data.message || 'Falha ao submeter MDF-e à SEFAZ');
    }
    throw error;
  }
}

/**
 * Encerra um MDF-e liberando o veículo para a próxima viagem
 */
export async function encerrarMdfe(
  chaveAcesso: string,
  protocoloAutorizacao: string,
  ufEncerramento: string,
  codigoMunicipioEncerramento: string
) {
  const response = await client.post('/mdfe/encerrar', {
    chaveAcesso,
    protocoloAutorizacao,
    ufEncerramento,
    codigoMunicipioEncerramento,
  });

  return response.data;
}

🛡️ 5. Vantagens Competitivas da Notaas para Transporte & ERPs

Se a sua empresa avalia provedores de API fiscal (como Nuvem Fiscal, Focus NFe ou TecnoSpeed), avalie estes diferenciais técnicos exclusivos da Notaas:

1. 50 Emissões Gratuitas por Mês por CNPJ em Produção:
   Você não precisa desembolsar mensalidades de centenas de reais apenas para homologar ou atender frotas com baixa volumetria. O free tier da Notaas roda em ambiente de produção real, permitindo lançar seu MVP sem risco financeiro.

2. Org API Nativa para Multi-Tenancy:
   Se você é uma software house atendendo 50 transportadoras ou indústrias, utilize o endpoint POST /api/v1/org/projects para criar ambientes isolados para cada cliente, gerenciando certificados A1 e webhooks de forma programática.

3. DACTE e DAMDFE em PDF Instantâneos:
   Geração server-side com layout pixel-perfect regulamentado pela SEFAZ e Código de Barras 128 / QR Code v2 de altíssima legibilidade para leitores ópticos de postos fiscais.

4. Webhooks Assinados e Tolerantes a Quedas:
   Receba eventos como cte.autorizado, cte.rejeitado, mdfe.autorizado e mdfe.encerrado em tempo real com garantia de entrega (at-least-once delivery) e validação criptográfica via HMAC SHA-256.

🚀 Comece a Integrar CT-e e MDF-e Hoje

A infraestrutura fiscal da sua aplicação não precisa ser um gargalo para a sua operação logística. Una notas de produto, conhecimentos de transporte e manifestos em uma stack moderna, unificada e escalável.

• Acesse a Documentação Completa da API Notaas
• Crie sua Conta Gratuita e Obtenha sua API Key