IAEsta documentação também existe 100% adaptada para modelos de IA: /api-de-mdfe.md

Documentação

API de MDF-e

Emita o MDF-e na SEFAZ a partir do seu sistema pela API do Meu Rastreio: emissão assíncrona, consulta, encerramento, cancelamento, inclusão de condutor e de documentos, pagamento da operação, DAMDFE, XML e webhooks.

Base URLhttps://painel.meurastreio.app/api/v1
Requisitos e ativação
Nesta página

Visão geral

A API de MDF-e emite o Manifesto Eletrônico de Documentos Fiscais na SEFAZ a partir do seu sistema (ERP, TMS ou outro), em nome de uma filial, com o certificado digital configurado no Meu Rastreio. Ela também consulta o manifesto, registra os eventos da viagem e devolve o XML e o DAMDFE.

  • A emissão é assíncrona: o POST responde na hora dizendo que o MDF-e entrou na fila, e a autorização chega depois, pela consulta ou por webhook.
  • A external_reference é a chave do MDF-e para o seu sistema. Depois de autorizado, a chave de acesso (access_key) também serve para localizar o documento.
  • Veículos e condutores enviados no corpo são gravados no cadastro da filial: na próxima emissão, basta a placa e o CPF.
  • Os eventos (cancelamento, encerramento, inclusões, pagamento e confirmação do serviço) seguem o mesmo desenho: pedido enfileirado, resultado depois.
  • Série, numeração, ambiente e certificado vêm da configuração fiscal da filial.
métodocaminhoo que faz
POST/mdfesEmite um MDF-e, ou reenvia o da mesma external_reference.
GET/mdfes/{external_reference}Consulta um MDF-e.
GET/mdfes?external_reference= ou ?access_key=A mesma consulta, pela query string.
GET/mdfes?date_from=&date_to=Lista os MDF-e do período.
POST/mdfes/cancelCancelamento.
POST/mdfes/closeEncerramento.
POST/mdfes/include-driverInclusão de condutor.
POST/mdfes/include-documentsInclusão de documentos (NF-e).
POST/mdfes/paymentPagamento da operação de transporte.
POST/mdfes/payment-changeAlteração do pagamento do serviço.
POST/mdfes/confirm-serviceConfirmação do serviço de transporte.
GET/mdfes/pdfDAMDFE ou comprovante de um evento, em PDF.

Requisitos e ativação

Antes da primeira chamada, confira com o administrador da sua conta no Meu Rastreio:

  1. O plano da empresa inclui o módulo Documentos fiscais. Sem ele, a API responde 402.
  2. Existe uma integração com o canal API na filial que vai emitir. Ela é criada no painel, em Integrações → nova integração, por um usuário administrador.
  3. A integração está ativa e com a permissão MDF-e ligada. Sem a permissão, a API responde 401.
  4. A filial tem a configuração fiscal preenchida no painel, com certificado digital vinculado. Sem ela, a API responde 422 FISCAL_CONFIG_NOT_FOUND.
  5. Para tipo_emitente 1, o RNTRC do emitente está na configuração fiscal, ou será enviado no campo rntrc de cada MDF-e.
  6. Para informar ou gerar CIOT no MDF-e, o plano inclui o módulo CIOT e a integração tem a permissão CIOT. Para informar vale-pedágio, o plano inclui o módulo de vale-pedágio e a integração tem a permissão correspondente.
O ambiente (produção ou homologação), a série e a numeração vêm da configuração fiscal da filial: o corpo da requisição não escolhe ambiente nem número do MDF-e.

Autenticação

Envie o token da integração no cabeçalho x-api-token de todas as chamadas.

cabeçalho
x-api-token: 0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9
  • O token é um UUID e pertence a uma integração de uma filial: tudo o que você emite e consulta com ele é dessa filial. Empresa com várias filiais usa um token por filial.
  • Ele aparece na tela da integração, no painel, e não tem validade.
  • Para revogar, desative ou exclua a integração, ou substitua o token. O token antigo deixa de funcionar.
  • O mesmo token pode ter outras permissões. Esta API exige a permissão MDF-e.
  • Só HTTPS. Nunca envie o token na URL e guarde-o como senha, em cofre de segredos.
  • Token ausente ou desconhecido responde 401 com {"message":"Acesso negado"}.

Primeira chamada

Emita um MDF-e de um CT-e autorizado. Gere um UUID para a external_reference e guarde-o: é a sua chave para consultar, reenviar, encerrar e registrar eventos.

requisição
curl -s -X POST "https://painel.meurastreio.app/api/v1/mdfes" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "mdfe": {
    "tipo_emitente": 1,
    "uf_inicio": "SP",
    "uf_fim": "RJ",
    "percurso": [],
    "carregamentos": [
      {
        "ibge": "3550308",
        "cidade": "São Paulo"
      }
    ],
    "descarregamentos": [
      {
        "ibge": "3304557",
        "cidade": "Rio de Janeiro",
        "documentos": [
          {
            "tipo": "CTE",
            "chave": "35261100000000000191570010000012341000012345"
          }
        ]
      }
    ],
    "inicio_viagem": "2026-11-20T08:00:00-03:00",
    "veiculo": {
      "placa": "ABC1D23",
      "tara": 7500,
      "capacidade_kg": 14000,
      "tipo_rodado": "02",
      "tipo_carroceria": "02",
      "uf": "SP"
    },
    "condutores": [
      {
        "cpf": "00000000191",
        "nome": "Motorista Exemplo",
        "telefone": "+55 11 90000-0000"
      }
    ],
    "contratantes": [
      {
        "cpf_cnpj": "00000000000272",
        "nome": "Contratante Exemplo Ltda"
      }
    ],
    "seguros": [
      {
        "responsavel": 1,
        "seguradora": "Seguradora Exemplo",
        "cnpj_seguradora": "00000000000353",
        "apolice": "0000000001",
        "averbacoes": [
          "0000000000000001"
        ]
      }
    ],
    "produto_predominante": {
      "tipo_carga": "05",
      "descricao": "Eletrônicos",
      "ncm": "84713012"
    },
    "totais": {
      "valor_carga": 85000,
      "unidade": "01",
      "quantidade_carga": 1200
    },
    "cep_carregamento": "01001000",
    "cep_descarregamento": "20010000"
  }
}'
resposta 201
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "mdfe": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PENDING"
  }
}

O 201 quer dizer enfileirado, não autorizado. protocol identifica a chamada. Consulte o resultado alguns segundos depois:

requisição
curl -s "https://painel.meurastreio.app/api/v1/mdfes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"

Quando status for AUTHORIZED, a resposta traz chave de acesso, protocolo, xml_url e pdf_url. Ao fim da viagem, encerre o manifesto (ver Eventos).

Emissão

POST /mdfes recebe um JSON com a referência e o objeto mdfe. Valores monetários e quantidades são números (1500.5), nunca texto.

Corpo raiz
campotipoobrigatórioregras
external_referencestring (UUID)nãoA sua chave para o MDF-e. Sem ela, o Meu Rastreio gera uma e devolve na resposta. Enviar de novo a mesma referência reenvia o documento (ver Reenvio).
mdfeobjectsimOs dados do manifesto.
MDF-e mdfe
campotipoobrigatórioregras
tipo_emitenteintegersim1 prestador de serviço de transporte (manifesta CT-e), 2 transportador de carga própria (manifesta NF-e) ou 3 prestador de serviço de transporte que emitirá CT-e globalizado (manifesta NF-e).
tipo_transportadorintegernão1 ETC, 2 TAC ou 3 CTC. Não se aplica a tipo_emitente 2. O valor enviado à SEFAZ é derivado do proprietário do veículo de tração (ver Veículo e condutor); este campo só decide entre ETC e CTC.
forma_emissaostringnãoNORMAL (padrão) ou CONTINGENCY.
data_contingenciadatetimenãoEntrada em contingência, em ISO 8601 com fuso. Só é lida com CONTINGENCY; omitida, vale o momento da chamada.
uf_iniciostringsimUF de início da viagem, com 2 letras.
uf_fimstringsimUF de fim da viagem, com 2 letras.
percursoarraynãoUFs de passagem entre o início e o fim, cada uma com 2 letras.
carregamentosarraysimMunicípios de carregamento (ver tabela): de 1 a 50, sem IBGE repetido.
cep_carregamentostringnãoCEP do local de carregamento, com 8 dígitos.
descarregamentosarraysimMunicípios de descarregamento com os documentos de cada um (ver tabela). Ao menos um.
cep_descarregamentostringnãoCEP do local de descarregamento, com 8 dígitos.
inicio_viagemdatetimenãoPrevisão de início da viagem, em ISO 8601 com fuso (2026-11-20T08:00:00-03:00). Data sem fuso é recusada.
veiculoobjectsimVeículo de tração (ver tabela).
reboquesarraynãoAté 3 reboques, no mesmo formato de veiculo. Sem placa repetida entre tração e reboques.
condutoresarraysimAo menos um condutor (ver tabela), sem CPF repetido.
rntrcstringnãoRNTRC do emitente, com 8 dígitos. Omitido, vale o da configuração fiscal; com tipo_emitente 1 e sem nenhum dos dois: 422 RNTRC_REQUIRED.
ciotsarraynãoCIOTs já declarados da viagem: ciot (12 dígitos) e cpf_cnpj do responsável. Sem CIOT repetido. Exige a permissão CIOT.
gerar_ciotobjectnãoGera o CIOT junto com o MDF-e (ver CIOT gerado junto). Exige a permissão CIOT.
vale_pedagioarraynãoVales-pedágio da viagem (ver tabela). Exige a permissão de vale-pedágio.
categoria_combinacao_veicularstringnãoCategoria de combinação veicular do vale-pedágio (categCombVeic): 02, 04, 06, 07, 08, 10, 11, 12, 13 ou 14. O nome antigo categoria_combustivel ainda é aceito; os dois juntos precisam ter o mesmo valor.
lacresarraynãoNúmeros dos lacres, até 20 caracteres cada, sem repetição.
autorizadosarraynãoAté 10 CPFs/CNPJs autorizados a baixar o XML, sem repetição.
canal_verdebooleannãoPadrão false.
carregamento_posteriorbooleannãoPadrão false. Com true, o MDF-e não leva documentos e precisa de exatamente um carregamento e um descarregamento, no mesmo município, com uf_inicio igual a uf_fim. Sem ele, ao menos um documento é obrigatório.
segurosarraynãoSeguros da carga (ver tabela).
contratantesarraycom tipo_emitente 1Contratantes do transporte (ver tabela). Obrigatório, com ao menos um, para tipo_emitente 1. Quando o transportador é TAC (tipo_transportador 2 ou proprietário da tração com CPF), cada contratante precisa de pagamento (422 TAC_PAYMENT_REQUIRED).
produto_predominanteobjectnãoProduto predominante da carga (ver tabela).
totaisobjectsimTotais da carga (ver tabela).
observacaostringnãoObservações gerais, até 5000 caracteres.
observacao_fiscostringnãoInformações de interesse do fisco, até 2000 caracteres.
shipment_external_referencestring (UUID)nãoReferência de um romaneio da filial, para vincular o MDF-e a ele.
Carregamento mdfe.carregamentos[]
campotipoobrigatórioregras
ibgestringsimCódigo IBGE do município, com 7 dígitos.
cidadestringsimNome do município.
Descarregamento mdfe.descarregamentos[]
campotipoobrigatórioregras
ibgestringsimCódigo IBGE do município, com 7 dígitos.
cidadestringsimNome do município.
documentosarraynãoDocumentos descarregados neste município (ver tabela). Sem chave repetida no MDF-e inteiro.
Documento mdfe.descarregamentos[].documentos[]
campotipoobrigatórioregras
tipostringsimCTE com tipo_emitente 1; NFE com tipo_emitente 2 ou 3. Misturar responde 422 VALIDATION_ERROR.
chavestringsimChave de acesso, com 44 posições. CT-e que o Meu Rastreio conhece precisa estar autorizado nesta filial e neste ambiente (CTE_NOT_AUTHORIZED) e não pode ser de terceiro (CTE_IMPORTED_NOT_MANIFESTABLE); chave desconhecida é aceita como veio.
produtos_perigososarraynãoProdutos perigosos do documento: onu (até 4 dígitos, obrigatório), nome_embarque (até 150), classe_risco (até 40), grupo_embalagem (até 6), quantidade_total (até 20) e tipo_volume (até 20).
Veículo e reboque mdfe.veiculo, mdfe.reboques[]
campotipoobrigatórioregras
placastringsimPlaca do veículo. Sem cadastro na filial e sem nenhum outro dado: 422 VEHICLE_NOT_FOUND.
renavamstringnãoAté 11 caracteres.
taranumberpara completar o cadastroTara em kg, maior que zero.
capacidade_kgnumbernãoCapacidade em kg, zero ou mais.
capacidade_m3numbernãoCapacidade em m³, zero ou mais.
tipo_rodadostringna tração, para completar o cadastro01 truck, 02 toco, 03 cavalo mecânico, 04 VAN, 05 utilitário ou 06 outros. Só conta no veículo de tração. Cavalo mecânico exige ao menos um reboque (TRACTOR_WITHOUT_TRAILER).
tipo_carroceriastringpara completar o cadastro00 não aplicável, 01 aberta, 02 fechada/baú, 03 granelera, 04 porta container ou 05 sider.
ufstringpara completar o cadastroUF de licenciamento, com 2 letras.
tipo_veiculostringnãoTipo do veículo no cadastro do painel, por nome, até 60 caracteres. Nome novo vira uma opção da filial.
carroceriastringnãoCarroceria no cadastro do painel, por nome, até 60 caracteres. Não confundir com tipo_carroceria, que é o código da SEFAZ.
proprietarioobjectveículo de terceiroProprietário do veículo (ver tabela). Omitido em veículo novo, o veículo nasce próprio da filial.
Proprietário do veículo mdfe.veiculo.proprietario, mdfe.reboques[].proprietario
campotipoobrigatórioregras
tipointegersim0 agregado, 1 independente ou 2 outros.
cpf_cnpjstringsimCPF ou CNPJ do proprietário.
nomestringsimAté 60 caracteres.
iestringnãoInscrição estadual, até 14 caracteres.
ufstringsimUF do proprietário, com 2 letras.
rntrcstringsimRNTRC do proprietário, com 8 dígitos.
Condutor mdfe.condutores[]
campotipoobrigatórioregras
cpfstringsimCPF de um usuário da filial, ou de um condutor novo (com nome e telefone).
nomestringnãoAté 60 caracteres. Atualiza o nome do motorista já cadastrado.
telefonestringnãoCom nome, cadastra o motorista na filial quando o CPF ainda não existe. O telefone é o login do motorista no aplicativo.
Vale-pedágio mdfe.vale_pedagio[]
campotipoobrigatórioregras
cnpj_fornecedorstringsimCNPJ da fornecedora do vale-pedágio.
cnpj_pagadorstringnãoCNPJ de quem pagou.
numero_comprastringsimNúmero da compra, só dígitos, até 20.
valornumbersimMaior que zero.
tipostringnãoTipo do vale-pedágio, até 2 caracteres.
Seguro mdfe.seguros[]
campotipoobrigatórioregras
responsavelintegersim1 emitente ou 2 contratante.
cpf_cnpj_responsavelstringnãoCPF ou CNPJ do responsável pelo seguro.
seguradorastringcom tipo_emitente 1 e 3Nome da seguradora, até 30 caracteres.
cnpj_seguradorastringcom tipo_emitente 1 e 3CNPJ da seguradora.
apolicestringnãoNúmero da apólice, até 20 caracteres.
averbacoesarraynãoNúmeros de averbação, até 40 caracteres cada.
Cada seguro precisa de ao menos uma identificação: apolice, seguradora ou averbacoes.
Contratante mdfe.contratantes[]
campotipoobrigatórioregras
cpf_cnpjstringnãoCPF ou CNPJ do contratante.
id_estrangeirostringnãoIdentificação de contratante estrangeiro.
nomestringsimAté 60 caracteres.
pagamentoobjectcom TACPagamento do frete: valor_contrato (maior que zero), indicador (só 0, à vista), e onde o pagamento cai: chave_pix (até 60), cnpj_ipef, ou banco (de 3 a 5 dígitos) e agencia (até 10).
Produto predominante mdfe.produto_predominante
campotipoobrigatórioregras
tipo_cargastringsimCódigo com 2 dígitos: 01 granel sólido, 02 granel líquido, 03 frigorificada ou aquecida, 04 conteinerizada, 05 carga geral, 06 neogranel, 07 a 11 as versões perigosas dos anteriores (granel sólido, granel líquido, frigorificada, conteinerizada e carga geral) e 12 granel pressurizada.
descricaostringsimAté 120 caracteres.
ncmstringnãoNCM do produto.
eanstringnãoCódigo de barras (GTIN) do produto.
Totais mdfe.totais
campotipoobrigatórioregras
valor_carganumbersimValor total da carga, zero ou mais.
unidadestringsim01 kg ou 02 toneladas.
quantidade_carganumbersimPeso bruto total, maior que zero.
corpo de exemplo
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "mdfe": {
    "tipo_emitente": 1,
    "uf_inicio": "SP",
    "uf_fim": "RJ",
    "percurso": [],
    "carregamentos": [
      {
        "ibge": "3550308",
        "cidade": "São Paulo"
      }
    ],
    "descarregamentos": [
      {
        "ibge": "3304557",
        "cidade": "Rio de Janeiro",
        "documentos": [
          {
            "tipo": "CTE",
            "chave": "35261100000000000191570010000012341000012345"
          }
        ]
      }
    ],
    "inicio_viagem": "2026-11-20T08:00:00-03:00",
    "veiculo": {
      "placa": "ABC1D23",
      "tara": 7500,
      "capacidade_kg": 14000,
      "tipo_rodado": "02",
      "tipo_carroceria": "02",
      "uf": "SP"
    },
    "condutores": [
      {
        "cpf": "00000000191",
        "nome": "Motorista Exemplo",
        "telefone": "+55 11 90000-0000"
      }
    ],
    "contratantes": [
      {
        "cpf_cnpj": "00000000000272",
        "nome": "Contratante Exemplo Ltda"
      }
    ],
    "seguros": [
      {
        "responsavel": 1,
        "seguradora": "Seguradora Exemplo",
        "cnpj_seguradora": "00000000000353",
        "apolice": "0000000001",
        "averbacoes": [
          "0000000000000001"
        ]
      }
    ],
    "produto_predominante": {
      "tipo_carga": "05",
      "descricao": "Eletrônicos",
      "ncm": "84713012"
    },
    "totais": {
      "valor_carga": 85000,
      "unidade": "01",
      "quantidade_carga": 1200
    },
    "cep_carregamento": "01001000",
    "cep_descarregamento": "20010000"
  }
}
resposta 201
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "mdfe": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PENDING"
  }
}
A API valida o formato e as regras que conhece antes de enfileirar, mas quem autoriza é a SEFAZ. Um 201 seguido de REJECTED é esperado quando os dados fiscais não fecham; o motivo vem em c_stat e status_reason.

Regras que a API confere antes de enfileirar

  • tipo_emitente 1 manifesta só CT-e; 2 e 3, só NF-e.
  • Cavalo mecânico (tipo_rodado 03, do corpo ou do cadastro) sem reboque: 422 TRACTOR_WITHOUT_TRAILER.
  • Com proprietário informado no veículo de tração, todo contratante precisa ser o próprio emitente (CNPJ da filial): 422 CONTRACTOR_MUST_BE_EMITTER.
  • tipo_emitente 1 e 3 exigem seguradora e cnpj_seguradora em cada seguro.
  • Cada município de descarregamentos entra no manifesto uma vez, na ordem do corpo, com ou sem documento.

A SEFAZ ainda cobra regras que a API não confere. Na carga lotação (um carregamento, um descarregamento, produto_predominante e os dois CEPs), ela exige produto_predominante.ncm e ao menos um contratante com pagamento. E a mesma placa não pode ter dois MDF-e abertos com o mesmo tipo de emitente e a mesma UF de descarga: encerre o anterior antes de emitir outro.

Veículo e condutor

O MDF-e usa os veículos e condutores do cadastro da filial. O que vier no corpo é gravado no cadastro, depois de toda a validação:

o corpo trazo que acontece
só a placaUsa o veículo já cadastrado. Sem cadastro: 422 VEHICLE_NOT_FOUND.
a placa com outros dadosCria o veículo, ou atualiza só os campos enviados.
só o cpfUsa o usuário da filial com esse CPF. Sem cadastro: 422 DRIVER_NOT_FOUND.
o CPF com nomeAtualiza o nome do condutor já cadastrado.
o CPF com nome e telefone, sem cadastroCria o motorista e o vincula à filial. O telefone é o login do motorista no aplicativo e não é trocado pela API em quem já existe.
  • Depois de juntar cadastro e corpo, o veículo precisa ter tara, uf e tipo_carroceria, e a tração também tipo_rodado. Veículo de terceiro precisa ainda de cpf_cnpj, nome, rntrc e uf do proprietário. Faltando algo: 422 VEHICLE_INCOMPLETE, com plate e a lista fields com os nomes da API (tara, uf, tipo_rodado, tipo_carroceria, proprietario.cpf_cnpj, proprietario.nome, proprietario.rntrc, proprietario.uf).
  • Veículo novo sem proprietario nasce próprio da filial. O proprietário fica no cadastro: os MDF-e seguintes com a mesma placa herdam o dono. Para voltar à frota própria, envie proprietario com tipo 2 e o CNPJ da filial.
  • O tipo de transportador enviado à SEFAZ é derivado da tração: veículo próprio da filial, ou tipo_emitente 2, vai sem tipo; proprietário com CPF vira TAC (e os contratantes precisam de pagamento); com CNPJ, ETC, ou CTC se tipo_transportador for 3.
  • Veículo e condutor são gravados no cadastro depois de toda a validação do corpo, inclusive dos campos de gerar_ciot. As regras de negócio do CIOT gerado (transportador, RNTRC, pagamento, conflitos) leem esse cadastro: se elas recusarem, o cadastro fica com o que você enviou e nenhum MDF-e é criado.
  • Telefone que já pertence a outro usuário, ou a um motorista com outro CPF, responde 409 DRIVER_PHONE_IN_USE.

CIOT gerado junto

Com gerar_ciot, o Meu Rastreio declara o CIOT da viagem a partir do próprio manifesto e segura o MDF-e até o CIOT abrir: o número entra no MDF-e antes de ir à SEFAZ. A resposta 201 traz também ciot: { external_reference, status }, que você acompanha pela API de CIOT.

vem do MDF-evai em gerar_ciot
Veículo, reboques, primeiro condutor, primeiro carregamento (origem), último descarregamento (destino), UFs, CEPs, inicio_viagem, peso de totais, tipo_carga e NCM do produto predominante, contratantes que não são a filial e a soma de contratantes[].pagamento.valor_contrato (frete).tipo_operacao (LOTACAO, FRACIONADA ou TAC_AGREGADO), valor_frete e distancia_km (maiores que zero) e, no formato da API de CIOT, fim_viagem, destinatario, carga, pagamentos, indicadores e contratante.
  • O CIOT montado passa pelas mesmas regras da API de CIOT. Erro de formato responde 422 VALIDATION_ERROR com os itens de errors começando por gerar_ciot:; as demais recusas usam os códigos daquela API (por exemplo 409 CIOT_CONFLICT). Quando a recusa acontece depois de o MDF-e ser criado, o erro traz também mdfe: { external_reference, status: "REJECTED" }: reenvie com a mesma referência.
  • Se a ANTT recusar o CIOT, ou ele for cancelado, o MDF-e vai a REJECTED com status_reason começando por CIOT: e não é transmitido. Reenvie o MDF-e com a mesma referência para gerar outro CIOT.
  • No reenvio, um CIOT já aberto do mesmo MDF-e é reaproveitado; um em andamento continua sendo esperado.
  • Veículo com CIOT agregado aberto reaproveita esse CIOT. Agregado ainda em processamento: 409 CIOT_IN_PROGRESS. Agregado vigente que termina antes do inicio_viagem: 409 CIOT_AGGREGATE_PERIOD_OPEN; envie o MDF-e a partir do fim do período.
Enquanto espera o CIOT, o MDF-e fica em PENDING. Se a sua consulta em laço tiver prazo, conte com o tempo de abertura do CIOT.

Reenvio

O POST funciona como criar-ou-substituir pela external_reference: referência nova cria o MDF-e; referência que já existe substitui os dados e volta o documento para a fila, zerando protocolo, motivo e arquivos da tentativa anterior.

status do documentoo que o reenvio faz
PENDING, PROCESSING, REJECTED ou ERRORSubstitui os dados e enfileira de novo, mantendo série e número.
DENIEDSubstitui e enfileira com numeração nova: a denegação inutiliza o número anterior na SEFAZ.
AUTHORIZED, CANCELED ou CLOSED409 DOCUMENT_ALREADY_PROCESSED: documento aceito pela SEFAZ não se corrige; cancele e emita outro, com outra referência.
  • Referência que já pertence a outra filial responde 409 DOCUMENT_FROM_ANOTHER_SUBSIDIARY.
  • Se a filial trocou de ambiente (homologação/produção) depois da primeira emissão, o reenvio responde 409 DOCUMENT_ENVIRONMENT_CHANGED: emita um documento novo.

Consulta e listagem

chamadadevolve
GET /mdfes/{external_reference}O MDF-e dessa referência.
GET /mdfes?external_reference= ou ?access_key=O mesmo MDF-e, pela query string.
GET /mdfes?date_from=&date_to=A lista do período, paginada, do mais novo para o mais antigo.

A consulta só enxerga documentos da filial do token: referência de outra filial, ou que não existe, responde 404 DOCUMENT_NOT_FOUND. Na lista, cada item de data é o mesmo objeto da consulta individual.

parâmetro da listaobrigatóriocomo usar
date_fromsimInício do período, em ISO 8601 com fuso: 2026-11-01T00:00:00-03:00 ou 2026-11-01T03:00:00Z. Data sem fuso é recusada.
date_tosimFim do período, com fuso. Igual ou posterior a date_from.
statusnãoFiltra por um ou mais status: status=AUTHORIZED,CANCELED ou o parâmetro repetido. Valores aceitos: PENDING, PROCESSING, AUTHORIZED, DENIED, REJECTED, CANCELED, CLOSED, ERROR.
pagenãoPágina, a partir de 1. Padrão: 1.
per_pagenãoItens por página, de 1 a 100. Padrão: 10.
  • O período filtra por data de emissão do MDF-e; para o que ainda não foi emitido, pela data de criação.
  • Sem date_from e date_to, ou com um status que não existe, a resposta é 422 VALIDATION_ERROR.
  • O + do fuso precisa ir codificado como %2B na URL. Z e -03:00 não precisam.
  • A resposta da lista é { data, pagination: { page, per_page, total, total_pages } }.
consulta
curl -s "https://painel.meurastreio.app/api/v1/mdfes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
resposta 200
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "status": "AUTHORIZED",
  "emission_type": "NORMAL",
  "serie": 1,
  "number": 1234,
  "access_key": "35261100000000000191580010000012341000012345",
  "protocol": "135260000012345",
  "c_stat": 100,
  "status_reason": "Autorizado o uso do documento",
  "issued_at": "2026-11-19T14:01:58.000Z",
  "authorized_at": "2026-11-19T14:02:11.000Z",
  "canceled_at": null,
  "xml_url": "https://painel.meurastreio.app/api/files/3f6f0c2e-0000-4000-8000-000000000000",
  "pdf_url": "https://painel.meurastreio.app/api/v1/mdfes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "events": [],
  "closed_at": null
}
lista
curl -s "https://painel.meurastreio.app/api/v1/mdfes?date_from=2026-11-01T00:00:00-03:00&date_to=2026-11-30T23:59:59-03:00&status=AUTHORIZED,CLOSED&per_page=100" \
  -H "x-api-token: SEU_TOKEN"
MDF-e na resposta objeto devolvido
campotipoobrigatórioregras
external_referencestring—A sua referência.
statusstring—Ver a seção Status.
emission_typestring—Forma de emissão.
serie, numberinteger—Série e número. null até a numeração ser atribuída.
access_keystring—Chave de acesso, com 44 posições.
protocolstring—Protocolo de autorização na SEFAZ.
c_statinteger—Código de retorno da SEFAZ.
status_reasonstring—Motivo devolvido pela SEFAZ, ou a descrição do erro.
issued_atdatetime—Emissão.
authorized_atdatetime—Autorização.
canceled_atdatetime—Cancelamento.
closed_atdatetime—Encerramento.
xml_urlstring—Link do XML do documento. null enquanto não houver XML.
pdf_urlstring—Endereço do DAMDFE na rota /pdf. null enquanto o PDF não estiver disponível.
eventsarray—Eventos do documento (ver tabela).
Evento na resposta events[]
campotipoobrigatórioregras
typestring—Tipo do evento.
sequenceinteger—Sequência do evento dentro do tipo, a partir de 1.
statusstring—PENDING, PROCESSING, REGISTERED, REJECTED ou ERROR.
justificationstring—Justificativa enviada, quando o evento tem.
protocolstring—Protocolo de registro do evento na SEFAZ.
c_statinteger—Código de retorno da SEFAZ para o evento.
status_reasonstring—Motivo devolvido pela SEFAZ.
registered_atdatetime—Quando o evento foi registrado.
xml_urlstring—Link do XML do evento.
pdf_urlstring—Endereço do PDF do evento na rota /pdf. null enquanto o evento não estiver registrado.
Datas saem em ISO 8601, em UTC. Campo sem valor vem null. Novos campos podem aparecer com o tempo; ignore o que o seu sistema não conhece.

Eventos

Evento é o que se registra na SEFAZ depois que o MDF-e está autorizado. Cada evento tem a sua rota, sempre POST.

  • O documento é localizado por external_reference ou access_key, enviados no corpo junto com os campos do evento.
  • A resposta é 201 com { protocol, mdfe: { external_reference, event: { type, sequence, status } } }. Como na emissão, 201 quer dizer enfileirado: o registro na SEFAZ vem depois, em events da consulta ou pelos webhooks de evento.
  • Cancelamento, encerramento e as duas inclusões exigem o MDF-e em AUTHORIZED. Pagamento da operação, alteração do pagamento e confirmação do serviço aceitam AUTHORIZED ou CLOSED. Fora disso: 409 DOCUMENT_NOT_CANCELABLE no cancelamento, 409 DOCUMENT_NOT_CLOSABLE no encerramento e 409 DOCUMENT_NOT_CHANGEABLE nos demais.
  • Inclusão de documentos, pagamento da operação, alteração do pagamento e confirmação do serviço exigem o protocolo de autorização do MDF-e (409 DOCUMENT_WITHOUT_PROTOCOL).
  • Acontecem uma vez por documento: o cancelamento, o encerramento e a confirmação do serviço. Depois de registrados, um novo pedido responde 409. Podem se repetir: a inclusão de condutor, a inclusão de documentos, o pagamento da operação (um por viagem) e a alteração do pagamento; cada novo pedido ganha a próxima sequence.
  • Com um evento do mesmo tipo ainda em PENDING ou PROCESSING, um novo pedido responde 409 (EVENT_ALREADY_PENDING).
  • Evento que terminou em REJECTED ou ERROR pode ser pedido de novo: ele reaproveita a mesma sequence, com os dados novos.
  • Documento emitido por terceiro e importado é só leitura: 409 IMPORTED_DOCUMENT_READ_ONLY.
No encerramento, os códigos de conflito são próprios: 409 CLOSING_ALREADY_PENDING com um encerramento em andamento e 409 CLOSING_ALREADY_REGISTERED depois de encerrado.
Identificação do MDF-e em todo corpo de evento
campotipoobrigatórioregras
external_referencestring (UUID)um dos doisA referência do documento.
access_keystringum dos doisA chave de acesso, com 44 posições.
Cancelamento POST /mdfes/cancel
campotipoobrigatórioregras
justificativastringsimDe 15 a 255 caracteres.
Encerramento POST /mdfes/close
campotipoobrigatórioregras
ibge_encerramentostringsimCódigo IBGE do município onde a viagem terminou, com 7 dígitos.
Inclusão de condutor POST /mdfes/include-driver
campotipoobrigatórioregras
cpfstringsimCPF do condutor incluído: um usuário da filial, ou um novo (com nome e telefone), com as mesmas regras da emissão.
nomestringnãoAté 60 caracteres. Atualiza o nome do motorista já cadastrado.
telefonestringnãoCom nome, cadastra o motorista na filial quando o CPF ainda não existe. O telefone é o login do motorista no aplicativo.
Inclusão de documentos POST /mdfes/include-documents
campotipoobrigatórioregras
descarregamentosarraysimAo menos um município: ibge (7 dígitos), cidade e documentos (ao menos um). Sem chave repetida.
descarregamentos[].documentos[].tipostringsimSó NFE, qualquer que seja o tipo de emitente. Outro tipo: 422 DOCUMENT_TYPE_NOT_ALLOWED.
descarregamentos[].documentos[].chavestringsimChave de acesso da NF-e, com 44 posições. produtos_perigosos não é aceito aqui: o evento só leva tipo e chave.
Pagamento da operação POST /mdfes/payment
campotipoobrigatórioregras
quantidade_viagensintegersimQuantidade de viagens da operação, a partir de 1.
numero_viagemintegersimNúmero desta viagem, a partir de 1.
pagamentosarraysimAo menos um pagamento (ver tabela).
Alteração do pagamento POST /mdfes/payment-change
campotipoobrigatórioregras
pagamentosarraysimAo menos um pagamento (ver tabela).
Pagamento pagamentos[]
campotipoobrigatórioregras
nomestringnãoNome de quem recebe, até 60 caracteres.
cpf_cnpjstringum dos doisCPF ou CNPJ de quem recebe, até 14 caracteres.
id_estrangeirostringum dos doisIdentificação de estrangeiro, até 20 caracteres.
componentesarraysimAo menos um: tipo (01 vale-pedágio, 02 impostos, taxas e contribuições, 03 despesas, 04 frete ou 99 outros), valor (zero ou mais) e descricao (opcional, até 60).
valor_contratonumbersimValor total do contrato, zero ou mais.
indicador_pagamentointegersim0 à vista ou 1 a prazo.
valor_adiantamentonumbernãoZero ou mais.
permite_antecipacaointegernão0 ou 1.
parcelasarraya prazoObrigatório com indicador_pagamento 1 e proibido com 0. Cada parcela: numero (a partir de 1), vencimento (ISO 8601 com fuso) e valor (zero ou mais).
bancoobjectsimOnde o pagamento cai: pix (até 60), cnpj_ipef (até 14), ou codigo do banco (de 3 a 5 dígitos) e agencia (até 10). Ao menos uma das três formas.
Confirmação do serviço POST /mdfes/confirm-service
campotipoobrigatórioregras
———Só a identificação do MDF-e. Por enquanto, só MDF-e emitido pela própria filial do token.
encerrar
curl -s -X POST "https://painel.meurastreio.app/api/v1/mdfes/close" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "ibge_encerramento": "3304557"
}'
resposta 201
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "mdfe": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "event": {
      "type": "CLOSING",
      "sequence": 1,
      "status": "PENDING"
    }
  }
}
cancelar
curl -s -X POST "https://painel.meurastreio.app/api/v1/mdfes/cancel" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "justificativa": "Viagem cancelada antes da saída do veículo"
}'
pagamento da operação
curl -s -X POST "https://painel.meurastreio.app/api/v1/mdfes/payment" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "access_key": "35261100000000000191580010000012341000012345",
  "quantidade_viagens": 1,
  "numero_viagem": 1,
  "pagamentos": [
    {
      "nome": "Contratante Exemplo Ltda",
      "cpf_cnpj": "00000000000272",
      "componentes": [
        {
          "tipo": "04",
          "valor": 4800,
          "descricao": "Frete"
        }
      ],
      "valor_contrato": 4800,
      "indicador_pagamento": 0,
      "banco": {
        "pix": "[email protected]"
      }
    }
  ]
}'
Os tipos de evento que aparecem em events[].type são CANCELLATION, CLOSING, DRIVER_INCLUSION, DOCUMENT_INCLUSION, PAYMENT_OPERATION, PAYMENT_SERVICE_CHANGE e SERVICE_CONFIRMATION.

PDF e XML

XML

O XML autorizado é baixado pelo endereço em xml_url, devolvido na consulta do MDF-e. Cada evento registrado tem o próprio xml_url dentro de events.

PDF

O DAMDFE e os comprovantes dos eventos saem da rota de PDF, com o mesmo token:

parâmetroobrigatóriocomo usar
external_reference ou access_keyum dos doisIdentifica o MDF-e.
event_typenãoCom ele, a rota devolve o PDF do evento em vez do documento. É o type do evento em events.
event_sequencenãoSequência do evento. Padrão: 1.
requisição
curl -s "https://painel.meurastreio.app/api/v1/mdfes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN" \
  -o damdfe.pdf
  • Sucesso: 200 com Content-Type: application/pdf.
  • O PDF do documento existe quando o MDF-e tem XML e está AUTHORIZED, CANCELED ou CLOSED; o do evento, quando o evento está REGISTERED. Fora disso a resposta é 409 com {"message":"PDF_NOT_AVAILABLE"}.
  • Evento que não existe no documento: 404 EVENT_NOT_FOUND.
  • Falha ao gerar o arquivo: 502 com {"message":"FISCAL_PDF_NOT_GENERATED"}. Tente de novo.
  • O pdf_url da consulta já aponta para esta rota com os parâmetros certos; envie o cabeçalho x-api-token ao chamá-lo.

Status

statuso que quer dizer
PENDINGGravado e aguardando a fila.
PROCESSINGEm envio à SEFAZ, ou emitido em contingência aguardando a transmissão.
AUTHORIZEDAutorizado. Chave, protocolo, XML e PDF disponíveis.
REJECTEDRejeitado. O motivo fica em c_stat e status_reason. Corrija e reenvie com a mesma referência.
DENIEDDenegado pela SEFAZ. O número é perdido; o reenvio usa numeração nova.
CANCELEDCancelado: o evento de cancelamento foi registrado.
CLOSEDEncerrado: o evento de encerramento foi registrado.
ERRORFalha no processamento. O motivo fica em status_reason. Pode ser reenviado com a mesma referência.
Com gerar_ciot, o MDF-e fica em PENDING até o CIOT abrir. Recusa do CIOT leva o MDF-e a REJECTED com status_reason começando por CIOT:.

Status dos eventos

statuso que quer dizer
PENDINGPedido gravado, aguardando a fila.
PROCESSINGEm envio à SEFAZ.
REGISTEREDRegistrado na SEFAZ. protocol e registered_at preenchidos.
REJECTEDRecusado pela SEFAZ. O motivo fica em c_stat e status_reason.
ERRORFalha no processamento. Pode ser pedido de novo.

Webhooks

O Meu Rastreio tem webhooks para os eventos do MDF-e: em vez de consultar o status em laço, o seu sistema é avisado quando ele muda. Os webhooks são habilitados sob solicitação: escreva para [email protected] informando a filial, a URL que vai receber as chamadas e quais eventos você quer.

eventoquando é enviado
MDFE_CREATEDO POST da API criou o MDF-e. O reenvio da mesma referência não repete o evento.
MDFE_AUTHORIZEDA SEFAZ autorizou.
MDFE_REJECTEDTerminou sem autorização: REJECTED, DENIED ou ERROR.
MDFE_CANCELEDO cancelamento foi registrado.
MDFE_CLOSEDO encerramento foi registrado.
MDFE_EVENT_REGISTEREDQualquer evento foi registrado na SEFAZ, cancelamento inclusive.
MDFE_EVENT_REJECTEDUm evento foi recusado pela SEFAZ ou terminou em erro.
  • Cada evento habilitado gera uma chamada POST para a sua URL, com Content-Type: application/json.
  • O corpo é o próprio objeto do MDF-e, direto na raiz do JSON, com os campos da tabela abaixo. Os nomes aqui são em camelCase, diferentes dos da API.
  • Responda com status 2xx. Em caso de falha, o envio é tentado até 3 vezes, com espera crescente entre as tentativas.
  • Cancelar gera dois avisos: o de cancelamento do documento e o de evento registrado. Quem só precisa saber que o documento foi cancelado escuta o primeiro; quem precisa saber quando um cancelamento foi recusado escuta os de evento.
  • PENDING e PROCESSING não geram aviso.
  • Encerrar também gera dois avisos: MDFE_CLOSED e MDFE_EVENT_REGISTERED.
  • MDF-e recusado porque o CIOT gerado junto foi recusado também dispara MDFE_REJECTED.
MDF-e no webhook corpo do POST
campotipoobrigatórioregras
idinteger—Identificador do MDF-e no Meu Rastreio.
externalReferencestring—A sua referência.
companySubsidiaryIdinteger—Identificador da filial.
statusstring—Status do documento.
statusDescriptionstring—O status em português.
environmentstring—Ambiente em que o documento foi emitido (produção ou homologação).
emissionTypestring—Forma de emissão.
emitterCnpjstring—CNPJ do emitente.
serie, numberinteger—Série e número.
accessKeystring—Chave de acesso.
protocolstring—Protocolo de autorização.
cStatinteger—Código de retorno da SEFAZ.
statusReasonstring—Motivo devolvido pela SEFAZ.
issuedAt, authorizedAt, canceledAtdatetime—Emissão, autorização e cancelamento.
closedAtdatetime—Encerramento.
shipmentIdinteger—Identificador do romaneio vinculado, quando houver.
eventobject—null nos eventos do documento. Nos webhooks de evento traz type, typeDescription, status, statusDescription, protocol, statusReason e justification.
corpo recebido
{
  "id": 52144,
  "externalReference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "companySubsidiaryId": 12,
  "status": "CLOSED",
  "environment": "PRODUCTION",
  "emissionType": "NORMAL",
  "emitterCnpj": "00000000000191",
  "serie": 1,
  "number": 1234,
  "accessKey": "35261100000000000191580010000012341000012345",
  "protocol": "935260000012345",
  "cStat": 100,
  "statusReason": "Autorizado o uso do MDF-e",
  "issuedAt": "2026-11-19T14:01:58.000Z",
  "authorizedAt": "2026-11-19T14:02:11.000Z",
  "canceledAt": null,
  "closedAt": "2026-11-22T21:10:40.000Z",
  "shipmentId": null,
  "statusDescription": "Encerrado",
  "event": null
}
As chamadas não têm cabeçalho de assinatura. Para confirmar que a chamada veio do Meu Rastreio, peça ao suporte para configurar um cabeçalho personalizado com um segredo seu (por exemplo x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.
Trate o webhook como aviso: o mesmo evento pode chegar mais de uma vez. Use externalReference e status para decidir o que fazer e, na dúvida, consulte o documento pela API.

Limites de uso

limitevalorcomo funciona
Requisições por minuto120 por IPVale para todas as rotas da API somadas, contadas pelo IP de origem.
Itens por página10 (padrão), até 100Parâmetro per_page das listas.
Período da listaobrigatóriodate_from e date_to sempre informados: não existe listagem sem período.
Municípios de carregamentode 1 a 50Campo carregamentos, sem IBGE repetido.
Reboquesaté 3Por MDF-e.
Autorizados a baixar o XMLaté 10Campo autorizados.

Passou do limite de requisições, a resposta é 429 e o cabeçalho Retry-After diz quantos segundos esperar:

resposta 429
HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "message": "TOO_MANY_REQUESTS" }
  • Respeite o Retry-After antes de tentar de novo.
  • Para acompanhar o resultado de uma emissão, prefira os webhooks. Se for consultar, espere alguns segundos entre uma consulta e outra.
  • Na lista, use per_page=100 para fazer menos chamadas.

Erros

O corpo de erro traz code, para o seu código decidir o que fazer, e message, para leitura de pessoas. Alguns erros trazem campos extras, como errors na validação.

resposta 422
{
  "code": "VALIDATION_ERROR",
  "message": "2 errors occurred",
  "errors": [
    "external_reference must be a valid UUID",
    "deve ser uma data ISO 8601 com fuso, como 2026-10-10T09:00:00-03:00"
  ]
}
statuscodequando acontece
401—Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code.
401INTEGRATION_DISABLEDA integração do token foi desativada pelo administrador.
401MDFE_NOT_ALLOWEDA integração não tem a permissão MDF-e.
402PLAN_WITHOUT_FISCAL_DOCUMENTSO plano da empresa não inclui o módulo de documentos fiscais.
422FISCAL_CONFIG_NOT_FOUNDFilial sem configuração fiscal ou sem certificado digital vinculado.
404DOCUMENT_NOT_FOUNDDocumento não encontrado na filial do token.
405METHOD_NOT_ALLOWEDMétodo HTTP não aceito pela rota. Em algumas rotas o identificador vem só em message.
422VALIDATION_ERRORCorpo ou query fora do formato. errors lista cada problema encontrado.
429—Limite de requisições. O corpo é {"message":"TOO_MANY_REQUESTS"}, com o cabeçalho Retry-After.
500INTERNAL_ERRORFalha inesperada. Tente de novo; se persistir, fale com o suporte informando o protocol ou o horário da chamada.
409DOCUMENT_ALREADY_PROCESSEDDocumento autorizado, cancelado ou encerrado não aceita reenvio.
409DOCUMENT_FROM_ANOTHER_SUBSIDIARYA referência externa já pertence a um documento de outra filial.
409DOCUMENT_ENVIRONMENT_CHANGEDA filial mudou de ambiente desde a emissão; emita um documento novo.
401CIOT_NOT_ALLOWEDO corpo tem ciots ou gerar_ciot e o plano ou a integração não têm CIOT.
401VPO_NOT_ALLOWEDO corpo tem vale_pedagio e o plano ou a integração não têm vale-pedágio.
404SHIPMENT_NOT_FOUNDO romaneio de shipment_external_reference não existe na filial.
409CTE_NOT_AUTHORIZEDUm CT-e do manifesto existe no Meu Rastreio mas não está autorizado nesta filial e ambiente.
409CTE_IMPORTED_NOT_MANIFESTABLEUm CT-e do manifesto foi emitido por terceiro e importado.
409DRIVER_PHONE_IN_USEO telefone do condutor já pertence a outro usuário.
409CIOT_IN_PROGRESSCom gerar_ciot: o CIOT agregado do veículo ainda está em processamento.
409CIOT_AGGREGATE_PERIOD_OPENCom gerar_ciot: o inicio_viagem é depois do fim do CIOT agregado vigente.
422RNTRC_REQUIREDRNTRC ausente no MDF-e e na configuração fiscal da filial, com tipo_emitente 1.
422VEHICLE_NOT_FOUNDPlaca sem cadastro na filial e sem dados para cadastrar.
422VEHICLE_INCOMPLETECadastro do veículo incompleto para o MDF-e; fields diz o que falta.
422TAC_PAYMENT_REQUIREDO transportador é TAC e algum contratante está sem pagamento.
422TRACTOR_WITHOUT_TRAILERCavalo mecânico sem reboque.
422CONTRACTOR_MUST_BE_EMITTERCom proprietário na tração, o contratante precisa ser a própria filial.
422DRIVER_NOT_FOUNDCPF sem cadastro na filial. Envie nome e telefone para cadastrar.
422DRIVER_INVALID_PHONETelefone do condutor inválido.
404EVENT_NOT_FOUNDRota de PDF: o evento pedido não existe no documento.
409DOCUMENT_NOT_CANCELABLEO status do documento não permite cancelamento (só AUTHORIZED).
409DOCUMENT_NOT_CHANGEABLEO status do documento não aceita o evento pedido.
409DOCUMENT_WITHOUT_PROTOCOLO evento exige o protocolo de autorização e o documento não tem.
409IMPORTED_DOCUMENT_READ_ONLYDocumento emitido por terceiro e importado não aceita eventos.
409EVENT_ALREADY_PENDINGJá existe um evento do mesmo tipo aguardando processamento.
409EVENT_ALREADY_REGISTEREDO evento só acontece uma vez e já foi registrado.
409DOCUMENT_NOT_CLOSABLEO status do MDF-e não permite encerramento (só AUTHORIZED).
409CLOSING_ALREADY_PENDINGJá existe um encerramento aguardando processamento.
409CLOSING_ALREADY_REGISTEREDO MDF-e já foi encerrado.
422DOCUMENT_TYPE_NOT_ALLOWEDA inclusão de documentos só aceita NF-e.
409—Rota de PDF: {"message":"PDF_NOT_AVAILABLE"}, sem code.
502—Rota de PDF: {"message":"FISCAL_PDF_NOT_GENERATED"}, sem code.
  • 401 e 402: pare e avise uma pessoa. O problema é de token, permissão ou plano; insistir não resolve.
  • 404: confira a referência e se o token é da filial certa.
  • 422: corrija o corpo ou o cadastro apontado em message e envie de novo com a mesma external_reference.
  • 429: espere o Retry-After.
  • 409: leia o code. EVENT_ALREADY_PENDING pede espera; os demais dizem que o documento não está no status que a operação exige.
  • Rejeição da SEFAZ não é erro HTTP: a chamada responde 201 e a rejeição aparece depois, no status, c_stat e status_reason do documento ou do evento.

Exemplos completos

Emitir, acompanhar, baixar o DAMDFE e encerrar um MDF-e com curl:

1. emitir
curl -s -X POST "https://painel.meurastreio.app/api/v1/mdfes" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "mdfe": {
    "tipo_emitente": 1,
    "uf_inicio": "SP",
    "uf_fim": "RJ",
    "percurso": [],
    "carregamentos": [
      {
        "ibge": "3550308",
        "cidade": "São Paulo"
      }
    ],
    "descarregamentos": [
      {
        "ibge": "3304557",
        "cidade": "Rio de Janeiro",
        "documentos": [
          {
            "tipo": "CTE",
            "chave": "35261100000000000191570010000012341000012345"
          }
        ]
      }
    ],
    "inicio_viagem": "2026-11-20T08:00:00-03:00",
    "veiculo": {
      "placa": "ABC1D23",
      "tara": 7500,
      "capacidade_kg": 14000,
      "tipo_rodado": "02",
      "tipo_carroceria": "02",
      "uf": "SP"
    },
    "condutores": [
      {
        "cpf": "00000000191",
        "nome": "Motorista Exemplo",
        "telefone": "+55 11 90000-0000"
      }
    ],
    "contratantes": [
      {
        "cpf_cnpj": "00000000000272",
        "nome": "Contratante Exemplo Ltda"
      }
    ],
    "seguros": [
      {
        "responsavel": 1,
        "seguradora": "Seguradora Exemplo",
        "cnpj_seguradora": "00000000000353",
        "apolice": "0000000001",
        "averbacoes": [
          "0000000000000001"
        ]
      }
    ],
    "produto_predominante": {
      "tipo_carga": "05",
      "descricao": "Eletrônicos",
      "ncm": "84713012"
    },
    "totais": {
      "valor_carga": 85000,
      "unidade": "01",
      "quantidade_carga": 1200
    },
    "cep_carregamento": "01001000",
    "cep_descarregamento": "20010000"
  }
}'
2. consultar até autorizar
curl -s "https://painel.meurastreio.app/api/v1/mdfes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
3. baixar o DAMDFE
curl -s "https://painel.meurastreio.app/api/v1/mdfes/pdf?external_reference=0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN" \
  -o damdfe.pdf
4. encerrar ao fim da viagem
curl -s -X POST "https://painel.meurastreio.app/api/v1/mdfes/close" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "ibge_encerramento": "3304557"
}'

Em JavaScript, emitindo e consultando até o status deixar de ser transitório, respeitando o 429:

JavaScript (Node 20+)
const BASE_URL = "https://painel.meurastreio.app/api/v1";
const TOKEN = process.env.MEU_RASTREIO_TOKEN;
const IN_PROGRESS = ["PENDING", "PROCESSING"];
const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function call(path, options = {}) {
  while (true) {
    const response = await fetch(`${BASE_URL}${path}`, {
      ...options,
      headers: { "x-api-token": TOKEN, "Content-Type": "application/json" },
    });

    if (response.status === 429) {
      await wait(Number(response.headers.get("Retry-After") ?? 5));
      continue;
    }

    const body = await response.json();

    if (!response.ok) throw new Error(`${response.status} ${body.code ?? ""} ${body.message}`);

    return body;
  }
}

async function emit(externalReference, mdfe) {
  // 201 means queued: the final status comes from the GET (or from the webhooks)
  await call("/mdfes", {
    method: "POST",
    body: JSON.stringify({ external_reference: externalReference, mdfe }),
  });

  for (let attempt = 0; attempt < 60; attempt++) {
    await wait(5);

    const document = await call(`/mdfes/${externalReference}`);

    if (!IN_PROGRESS.includes(document.status)) return document;
  }

  throw new Error("Ainda em processamento: consulte de novo mais tarde");
}

// mdfe: the object described in "Emissão"
const document = await emit(crypto.randomUUID(), mdfe);

console.log(document.status, document.status_reason);

Suporte

Ativação do módulo, configuração fiscal e certificado, permissão da integração, webhooks ou dúvidas sobre uma rejeição: [email protected]. Para contratar: [email protected].