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
POSTresponde 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étodo | caminho | o que faz |
|---|---|---|
POST | /mdfes | Emite 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/cancel | Cancelamento. |
POST | /mdfes/close | Encerramento. |
POST | /mdfes/include-driver | Inclusão de condutor. |
POST | /mdfes/include-documents | Inclusão de documentos (NF-e). |
POST | /mdfes/payment | Pagamento da operação de transporte. |
POST | /mdfes/payment-change | Alteração do pagamento do serviço. |
POST | /mdfes/confirm-service | Confirmação do serviço de transporte. |
GET | /mdfes/pdf | DAMDFE 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:
- O plano da empresa inclui o módulo Documentos fiscais. Sem ele, a API responde
402. - 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.
- A integração está ativa e com a permissão MDF-e ligada. Sem a permissão, a API responde
401. - A filial tem a configuração fiscal preenchida no painel, com certificado digital vinculado. Sem ela, a API responde
422 FISCAL_CONFIG_NOT_FOUND. - Para
tipo_emitente1, o RNTRC do emitente está na configuração fiscal, ou será enviado no camporntrcde cada MDF-e. - 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.
Autenticação
Envie o token da integração no cabeçalho x-api-token de todas as chamadas.
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
401com{"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.
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"
}
}'{
"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:
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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
external_reference | string (UUID) | não | A 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). |
mdfe | object | sim | Os dados do manifesto. |
MDF-e mdfe
| campo | tipo | obrigatório | regras |
|---|---|---|---|
tipo_emitente | integer | sim | 1 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_transportador | integer | não | 1 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_emissao | string | não | NORMAL (padrão) ou CONTINGENCY. |
data_contingencia | datetime | não | Entrada em contingência, em ISO 8601 com fuso. Só é lida com CONTINGENCY; omitida, vale o momento da chamada. |
uf_inicio | string | sim | UF de início da viagem, com 2 letras. |
uf_fim | string | sim | UF de fim da viagem, com 2 letras. |
percurso | array | não | UFs de passagem entre o início e o fim, cada uma com 2 letras. |
carregamentos | array | sim | Municípios de carregamento (ver tabela): de 1 a 50, sem IBGE repetido. |
cep_carregamento | string | não | CEP do local de carregamento, com 8 dígitos. |
descarregamentos | array | sim | Municípios de descarregamento com os documentos de cada um (ver tabela). Ao menos um. |
cep_descarregamento | string | não | CEP do local de descarregamento, com 8 dígitos. |
inicio_viagem | datetime | não | Previsão de início da viagem, em ISO 8601 com fuso (2026-11-20T08:00:00-03:00). Data sem fuso é recusada. |
veiculo | object | sim | Veículo de tração (ver tabela). |
reboques | array | não | Até 3 reboques, no mesmo formato de veiculo. Sem placa repetida entre tração e reboques. |
condutores | array | sim | Ao menos um condutor (ver tabela), sem CPF repetido. |
rntrc | string | não | RNTRC 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. |
ciots | array | não | CIOTs já declarados da viagem: ciot (12 dígitos) e cpf_cnpj do responsável. Sem CIOT repetido. Exige a permissão CIOT. |
gerar_ciot | object | não | Gera o CIOT junto com o MDF-e (ver CIOT gerado junto). Exige a permissão CIOT. |
vale_pedagio | array | não | Vales-pedágio da viagem (ver tabela). Exige a permissão de vale-pedágio. |
categoria_combinacao_veicular | string | não | Categoria 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. |
lacres | array | não | Números dos lacres, até 20 caracteres cada, sem repetição. |
autorizados | array | não | Até 10 CPFs/CNPJs autorizados a baixar o XML, sem repetição. |
canal_verde | boolean | não | Padrão false. |
carregamento_posterior | boolean | não | Padrã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. |
seguros | array | não | Seguros da carga (ver tabela). |
contratantes | array | com tipo_emitente 1 | Contratantes 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_predominante | object | não | Produto predominante da carga (ver tabela). |
totais | object | sim | Totais da carga (ver tabela). |
observacao | string | não | Observações gerais, até 5000 caracteres. |
observacao_fisco | string | não | Informações de interesse do fisco, até 2000 caracteres. |
shipment_external_reference | string (UUID) | não | Referência de um romaneio da filial, para vincular o MDF-e a ele. |
Carregamento mdfe.carregamentos[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
ibge | string | sim | Código IBGE do município, com 7 dígitos. |
cidade | string | sim | Nome do município. |
Descarregamento mdfe.descarregamentos[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
ibge | string | sim | Código IBGE do município, com 7 dígitos. |
cidade | string | sim | Nome do município. |
documentos | array | não | Documentos descarregados neste município (ver tabela). Sem chave repetida no MDF-e inteiro. |
Documento mdfe.descarregamentos[].documentos[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
tipo | string | sim | CTE com tipo_emitente 1; NFE com tipo_emitente 2 ou 3. Misturar responde 422 VALIDATION_ERROR. |
chave | string | sim | Chave 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_perigosos | array | não | Produtos 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[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
placa | string | sim | Placa do veículo. Sem cadastro na filial e sem nenhum outro dado: 422 VEHICLE_NOT_FOUND. |
renavam | string | não | Até 11 caracteres. |
tara | number | para completar o cadastro | Tara em kg, maior que zero. |
capacidade_kg | number | não | Capacidade em kg, zero ou mais. |
capacidade_m3 | number | não | Capacidade em m³, zero ou mais. |
tipo_rodado | string | na tração, para completar o cadastro | 01 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_carroceria | string | para completar o cadastro | 00 não aplicável, 01 aberta, 02 fechada/baú, 03 granelera, 04 porta container ou 05 sider. |
uf | string | para completar o cadastro | UF de licenciamento, com 2 letras. |
tipo_veiculo | string | não | Tipo do veículo no cadastro do painel, por nome, até 60 caracteres. Nome novo vira uma opção da filial. |
carroceria | string | não | Carroceria no cadastro do painel, por nome, até 60 caracteres. Não confundir com tipo_carroceria, que é o código da SEFAZ. |
proprietario | object | veículo de terceiro | Proprietá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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
tipo | integer | sim | 0 agregado, 1 independente ou 2 outros. |
cpf_cnpj | string | sim | CPF ou CNPJ do proprietário. |
nome | string | sim | Até 60 caracteres. |
ie | string | não | Inscrição estadual, até 14 caracteres. |
uf | string | sim | UF do proprietário, com 2 letras. |
rntrc | string | sim | RNTRC do proprietário, com 8 dígitos. |
Condutor mdfe.condutores[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
cpf | string | sim | CPF de um usuário da filial, ou de um condutor novo (com nome e telefone). |
nome | string | não | Até 60 caracteres. Atualiza o nome do motorista já cadastrado. |
telefone | string | não | Com 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[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
cnpj_fornecedor | string | sim | CNPJ da fornecedora do vale-pedágio. |
cnpj_pagador | string | não | CNPJ de quem pagou. |
numero_compra | string | sim | Número da compra, só dígitos, até 20. |
valor | number | sim | Maior que zero. |
tipo | string | não | Tipo do vale-pedágio, até 2 caracteres. |
Seguro mdfe.seguros[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
responsavel | integer | sim | 1 emitente ou 2 contratante. |
cpf_cnpj_responsavel | string | não | CPF ou CNPJ do responsável pelo seguro. |
seguradora | string | com tipo_emitente 1 e 3 | Nome da seguradora, até 30 caracteres. |
cnpj_seguradora | string | com tipo_emitente 1 e 3 | CNPJ da seguradora. |
apolice | string | não | Número da apólice, até 20 caracteres. |
averbacoes | array | não | Números de averbação, até 40 caracteres cada. |
apolice, seguradora ou averbacoes.Contratante mdfe.contratantes[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
cpf_cnpj | string | não | CPF ou CNPJ do contratante. |
id_estrangeiro | string | não | Identificação de contratante estrangeiro. |
nome | string | sim | Até 60 caracteres. |
pagamento | object | com TAC | Pagamento 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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
tipo_carga | string | sim | Có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. |
descricao | string | sim | Até 120 caracteres. |
ncm | string | não | NCM do produto. |
ean | string | não | Código de barras (GTIN) do produto. |
Totais mdfe.totais
| campo | tipo | obrigatório | regras |
|---|---|---|---|
valor_carga | number | sim | Valor total da carga, zero ou mais. |
unidade | string | sim | 01 kg ou 02 toneladas. |
quantidade_carga | number | sim | Peso bruto total, maior que zero. |
{
"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"
}
}{
"protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
"mdfe": {
"external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"status": "PENDING"
}
}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_emitente1manifesta só CT-e;2e3, só NF-e.- Cavalo mecânico (
tipo_rodado03, 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_emitente1e3exigemseguradoraecnpj_seguradoraem cada seguro.- Cada município de
descarregamentosentra 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 traz | o que acontece |
|---|---|
só a placa | Usa o veículo já cadastrado. Sem cadastro: 422 VEHICLE_NOT_FOUND. |
| a placa com outros dados | Cria o veículo, ou atualiza só os campos enviados. |
só o cpf | Usa o usuário da filial com esse CPF. Sem cadastro: 422 DRIVER_NOT_FOUND. |
o CPF com nome | Atualiza o nome do condutor já cadastrado. |
o CPF com nome e telefone, sem cadastro | Cria 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,ufetipo_carroceria, e a tração tambémtipo_rodado. Veículo de terceiro precisa ainda decpf_cnpj,nome,rntrceufdo proprietário. Faltando algo:422 VEHICLE_INCOMPLETE, complatee a listafieldscom os nomes da API (tara,uf,tipo_rodado,tipo_carroceria,proprietario.cpf_cnpj,proprietario.nome,proprietario.rntrc,proprietario.uf). - Veículo novo sem
proprietarionasce 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, envieproprietariocomtipo2e o CNPJ da filial. - O tipo de transportador enviado à SEFAZ é derivado da tração: veículo próprio da filial, ou
tipo_emitente2, vai sem tipo; proprietário com CPF vira TAC (e os contratantes precisam depagamento); com CNPJ, ETC, ou CTC setipo_transportadorfor3. - 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-e | vai 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_ERRORcom os itens deerrorscomeçando porgerar_ciot:; as demais recusas usam os códigos daquela API (por exemplo409 CIOT_CONFLICT). Quando a recusa acontece depois de o MDF-e ser criado, o erro traz tambémmdfe: { 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
REJECTEDcomstatus_reasoncomeçando porCIOT: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 doinicio_viagem:409 CIOT_AGGREGATE_PERIOD_OPEN; envie o MDF-e a partir do fim do período.
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 documento | o que o reenvio faz |
|---|---|
PENDING, PROCESSING, REJECTED ou ERROR | Substitui os dados e enfileira de novo, mantendo série e número. |
DENIED | Substitui e enfileira com numeração nova: a denegação inutiliza o número anterior na SEFAZ. |
AUTHORIZED, CANCELED ou CLOSED | 409 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
| chamada | devolve |
|---|---|
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 lista | obrigatório | como usar |
|---|---|---|
date_from | sim | Iní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_to | sim | Fim do período, com fuso. Igual ou posterior a date_from. |
status | não | Filtra por um ou mais status: status=AUTHORIZED,CANCELED ou o parâmetro repetido. Valores aceitos: PENDING, PROCESSING, AUTHORIZED, DENIED, REJECTED, CANCELED, CLOSED, ERROR. |
page | não | Página, a partir de 1. Padrão: 1. |
per_page | não | Itens 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_fromedate_to, ou com um status que não existe, a resposta é422 VALIDATION_ERROR. - O
+do fuso precisa ir codificado como%2Bna URL.Ze-03:00não precisam. - A resposta da lista é
{ data, pagination: { page, per_page, total, total_pages } }.
curl -s "https://painel.meurastreio.app/api/v1/mdfes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
-H "x-api-token: SEU_TOKEN"{
"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
}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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
external_reference | string | — | A sua referência. |
status | string | — | Ver a seção Status. |
emission_type | string | — | Forma de emissão. |
serie, number | integer | — | Série e número. null até a numeração ser atribuída. |
access_key | string | — | Chave de acesso, com 44 posições. |
protocol | string | — | Protocolo de autorização na SEFAZ. |
c_stat | integer | — | Código de retorno da SEFAZ. |
status_reason | string | — | Motivo devolvido pela SEFAZ, ou a descrição do erro. |
issued_at | datetime | — | Emissão. |
authorized_at | datetime | — | Autorização. |
canceled_at | datetime | — | Cancelamento. |
closed_at | datetime | — | Encerramento. |
xml_url | string | — | Link do XML do documento. null enquanto não houver XML. |
pdf_url | string | — | Endereço do DAMDFE na rota /pdf. null enquanto o PDF não estiver disponível. |
events | array | — | Eventos do documento (ver tabela). |
Evento na resposta events[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
type | string | — | Tipo do evento. |
sequence | integer | — | Sequência do evento dentro do tipo, a partir de 1. |
status | string | — | PENDING, PROCESSING, REGISTERED, REJECTED ou ERROR. |
justification | string | — | Justificativa enviada, quando o evento tem. |
protocol | string | — | Protocolo de registro do evento na SEFAZ. |
c_stat | integer | — | Código de retorno da SEFAZ para o evento. |
status_reason | string | — | Motivo devolvido pela SEFAZ. |
registered_at | datetime | — | Quando o evento foi registrado. |
xml_url | string | — | Link do XML do evento. |
pdf_url | string | — | Endereço do PDF do evento na rota /pdf. null enquanto o evento não estiver registrado. |
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_referenceouaccess_key, enviados no corpo junto com os campos do evento. - A resposta é
201com{ protocol, mdfe: { external_reference, event: { type, sequence, status } } }. Como na emissão, 201 quer dizer enfileirado: o registro na SEFAZ vem depois, emeventsda 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 aceitamAUTHORIZEDouCLOSED. Fora disso:409 DOCUMENT_NOT_CANCELABLEno cancelamento,409 DOCUMENT_NOT_CLOSABLEno encerramento e409 DOCUMENT_NOT_CHANGEABLEnos 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óximasequence. - Com um evento do mesmo tipo ainda em
PENDINGouPROCESSING, um novo pedido responde409(EVENT_ALREADY_PENDING). - Evento que terminou em
REJECTEDouERRORpode ser pedido de novo: ele reaproveita a mesmasequence, com os dados novos. - Documento emitido por terceiro e importado é só leitura:
409 IMPORTED_DOCUMENT_READ_ONLY.
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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
external_reference | string (UUID) | um dos dois | A referência do documento. |
access_key | string | um dos dois | A chave de acesso, com 44 posições. |
Cancelamento POST /mdfes/cancel
| campo | tipo | obrigatório | regras |
|---|---|---|---|
justificativa | string | sim | De 15 a 255 caracteres. |
Encerramento POST /mdfes/close
| campo | tipo | obrigatório | regras |
|---|---|---|---|
ibge_encerramento | string | sim | Código IBGE do município onde a viagem terminou, com 7 dígitos. |
Inclusão de condutor POST /mdfes/include-driver
| campo | tipo | obrigatório | regras |
|---|---|---|---|
cpf | string | sim | CPF do condutor incluído: um usuário da filial, ou um novo (com nome e telefone), com as mesmas regras da emissão. |
nome | string | não | Até 60 caracteres. Atualiza o nome do motorista já cadastrado. |
telefone | string | não | Com 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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
descarregamentos | array | sim | Ao menos um município: ibge (7 dígitos), cidade e documentos (ao menos um). Sem chave repetida. |
descarregamentos[].documentos[].tipo | string | sim | Só NFE, qualquer que seja o tipo de emitente. Outro tipo: 422 DOCUMENT_TYPE_NOT_ALLOWED. |
descarregamentos[].documentos[].chave | string | sim | Chave 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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
quantidade_viagens | integer | sim | Quantidade de viagens da operação, a partir de 1. |
numero_viagem | integer | sim | Número desta viagem, a partir de 1. |
pagamentos | array | sim | Ao menos um pagamento (ver tabela). |
Alteração do pagamento POST /mdfes/payment-change
| campo | tipo | obrigatório | regras |
|---|---|---|---|
pagamentos | array | sim | Ao menos um pagamento (ver tabela). |
Pagamento pagamentos[]
| campo | tipo | obrigatório | regras |
|---|---|---|---|
nome | string | não | Nome de quem recebe, até 60 caracteres. |
cpf_cnpj | string | um dos dois | CPF ou CNPJ de quem recebe, até 14 caracteres. |
id_estrangeiro | string | um dos dois | Identificação de estrangeiro, até 20 caracteres. |
componentes | array | sim | Ao 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_contrato | number | sim | Valor total do contrato, zero ou mais. |
indicador_pagamento | integer | sim | 0 à vista ou 1 a prazo. |
valor_adiantamento | number | não | Zero ou mais. |
permite_antecipacao | integer | não | 0 ou 1. |
parcelas | array | a prazo | Obrigató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). |
banco | object | sim | Onde 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
| campo | tipo | obrigatório | regras |
|---|---|---|---|
— | — | — | Só a identificação do MDF-e. Por enquanto, só MDF-e emitido pela própria filial do token. |
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"
}'{
"protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
"mdfe": {
"external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"event": {
"type": "CLOSING",
"sequence": 1,
"status": "PENDING"
}
}
}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"
}'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]"
}
}
]
}'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.
O DAMDFE e os comprovantes dos eventos saem da rota de PDF, com o mesmo token:
| parâmetro | obrigatório | como usar |
|---|---|---|
external_reference ou access_key | um dos dois | Identifica o MDF-e. |
event_type | não | Com ele, a rota devolve o PDF do evento em vez do documento. É o type do evento em events. |
event_sequence | não | Sequência do evento. Padrão: 1. |
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:
200comContent-Type: application/pdf. - O PDF do documento existe quando o MDF-e tem XML e está
AUTHORIZED,CANCELEDouCLOSED; o do evento, quando o evento estáREGISTERED. Fora disso a resposta é409com{"message":"PDF_NOT_AVAILABLE"}. - Evento que não existe no documento:
404 EVENT_NOT_FOUND. - Falha ao gerar o arquivo:
502com{"message":"FISCAL_PDF_NOT_GENERATED"}. Tente de novo. - O
pdf_urlda consulta já aponta para esta rota com os parâmetros certos; envie o cabeçalhox-api-tokenao chamá-lo.
Status
| status | o que quer dizer |
|---|---|
PENDING | Gravado e aguardando a fila. |
PROCESSING | Em envio à SEFAZ, ou emitido em contingência aguardando a transmissão. |
AUTHORIZED | Autorizado. Chave, protocolo, XML e PDF disponíveis. |
REJECTED | Rejeitado. O motivo fica em c_stat e status_reason. Corrija e reenvie com a mesma referência. |
DENIED | Denegado pela SEFAZ. O número é perdido; o reenvio usa numeração nova. |
CANCELED | Cancelado: o evento de cancelamento foi registrado. |
CLOSED | Encerrado: o evento de encerramento foi registrado. |
ERROR | Falha no processamento. O motivo fica em status_reason. Pode ser reenviado com a mesma referência. |
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
| status | o que quer dizer |
|---|---|
PENDING | Pedido gravado, aguardando a fila. |
PROCESSING | Em envio à SEFAZ. |
REGISTERED | Registrado na SEFAZ. protocol e registered_at preenchidos. |
REJECTED | Recusado pela SEFAZ. O motivo fica em c_stat e status_reason. |
ERROR | Falha 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.
| evento | quando é enviado |
|---|---|
MDFE_CREATED | O POST da API criou o MDF-e. O reenvio da mesma referência não repete o evento. |
MDFE_AUTHORIZED | A SEFAZ autorizou. |
MDFE_REJECTED | Terminou sem autorização: REJECTED, DENIED ou ERROR. |
MDFE_CANCELED | O cancelamento foi registrado. |
MDFE_CLOSED | O encerramento foi registrado. |
MDFE_EVENT_REGISTERED | Qualquer evento foi registrado na SEFAZ, cancelamento inclusive. |
MDFE_EVENT_REJECTED | Um evento foi recusado pela SEFAZ ou terminou em erro. |
- Cada evento habilitado gera uma chamada
POSTpara a sua URL, comContent-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.
PENDINGePROCESSINGnão geram aviso.- Encerrar também gera dois avisos:
MDFE_CLOSEDeMDFE_EVENT_REGISTERED. - MDF-e recusado porque o CIOT gerado junto foi recusado também dispara
MDFE_REJECTED.
MDF-e no webhook corpo do POST
| campo | tipo | obrigatório | regras |
|---|---|---|---|
id | integer | — | Identificador do MDF-e no Meu Rastreio. |
externalReference | string | — | A sua referência. |
companySubsidiaryId | integer | — | Identificador da filial. |
status | string | — | Status do documento. |
statusDescription | string | — | O status em português. |
environment | string | — | Ambiente em que o documento foi emitido (produção ou homologação). |
emissionType | string | — | Forma de emissão. |
emitterCnpj | string | — | CNPJ do emitente. |
serie, number | integer | — | Série e número. |
accessKey | string | — | Chave de acesso. |
protocol | string | — | Protocolo de autorização. |
cStat | integer | — | Código de retorno da SEFAZ. |
statusReason | string | — | Motivo devolvido pela SEFAZ. |
issuedAt, authorizedAt, canceledAt | datetime | — | Emissão, autorização e cancelamento. |
closedAt | datetime | — | Encerramento. |
shipmentId | integer | — | Identificador do romaneio vinculado, quando houver. |
event | object | — | null nos eventos do documento. Nos webhooks de evento traz type, typeDescription, status, statusDescription, protocol, statusReason e justification. |
{
"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
}x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.externalReference e status para decidir o que fazer e, na dúvida, consulte o documento pela API.Limites de uso
| limite | valor | como funciona |
|---|---|---|
| Requisições por minuto | 120 por IP | Vale para todas as rotas da API somadas, contadas pelo IP de origem. |
| Itens por página | 10 (padrão), até 100 | Parâmetro per_page das listas. |
| Período da lista | obrigatório | date_from e date_to sempre informados: não existe listagem sem período. |
| Municípios de carregamento | de 1 a 50 | Campo carregamentos, sem IBGE repetido. |
| Reboques | até 3 | Por MDF-e. |
| Autorizados a baixar o XML | até 10 | Campo autorizados. |
Passou do limite de requisições, a resposta é 429 e o cabeçalho Retry-After diz quantos segundos esperar:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
{ "message": "TOO_MANY_REQUESTS" }- Respeite o
Retry-Afterantes 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=100para 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.
{
"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"
]
}| status | code | quando acontece |
|---|---|---|
| 401 | — | Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code. |
| 401 | INTEGRATION_DISABLED | A integração do token foi desativada pelo administrador. |
| 401 | MDFE_NOT_ALLOWED | A integração não tem a permissão MDF-e. |
| 402 | PLAN_WITHOUT_FISCAL_DOCUMENTS | O plano da empresa não inclui o módulo de documentos fiscais. |
| 422 | FISCAL_CONFIG_NOT_FOUND | Filial sem configuração fiscal ou sem certificado digital vinculado. |
| 404 | DOCUMENT_NOT_FOUND | Documento não encontrado na filial do token. |
| 405 | METHOD_NOT_ALLOWED | Método HTTP não aceito pela rota. Em algumas rotas o identificador vem só em message. |
| 422 | VALIDATION_ERROR | Corpo 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. |
| 500 | INTERNAL_ERROR | Falha inesperada. Tente de novo; se persistir, fale com o suporte informando o protocol ou o horário da chamada. |
| 409 | DOCUMENT_ALREADY_PROCESSED | Documento autorizado, cancelado ou encerrado não aceita reenvio. |
| 409 | DOCUMENT_FROM_ANOTHER_SUBSIDIARY | A referência externa já pertence a um documento de outra filial. |
| 409 | DOCUMENT_ENVIRONMENT_CHANGED | A filial mudou de ambiente desde a emissão; emita um documento novo. |
| 401 | CIOT_NOT_ALLOWED | O corpo tem ciots ou gerar_ciot e o plano ou a integração não têm CIOT. |
| 401 | VPO_NOT_ALLOWED | O corpo tem vale_pedagio e o plano ou a integração não têm vale-pedágio. |
| 404 | SHIPMENT_NOT_FOUND | O romaneio de shipment_external_reference não existe na filial. |
| 409 | CTE_NOT_AUTHORIZED | Um CT-e do manifesto existe no Meu Rastreio mas não está autorizado nesta filial e ambiente. |
| 409 | CTE_IMPORTED_NOT_MANIFESTABLE | Um CT-e do manifesto foi emitido por terceiro e importado. |
| 409 | DRIVER_PHONE_IN_USE | O telefone do condutor já pertence a outro usuário. |
| 409 | CIOT_IN_PROGRESS | Com gerar_ciot: o CIOT agregado do veículo ainda está em processamento. |
| 409 | CIOT_AGGREGATE_PERIOD_OPEN | Com gerar_ciot: o inicio_viagem é depois do fim do CIOT agregado vigente. |
| 422 | RNTRC_REQUIRED | RNTRC ausente no MDF-e e na configuração fiscal da filial, com tipo_emitente 1. |
| 422 | VEHICLE_NOT_FOUND | Placa sem cadastro na filial e sem dados para cadastrar. |
| 422 | VEHICLE_INCOMPLETE | Cadastro do veículo incompleto para o MDF-e; fields diz o que falta. |
| 422 | TAC_PAYMENT_REQUIRED | O transportador é TAC e algum contratante está sem pagamento. |
| 422 | TRACTOR_WITHOUT_TRAILER | Cavalo mecânico sem reboque. |
| 422 | CONTRACTOR_MUST_BE_EMITTER | Com proprietário na tração, o contratante precisa ser a própria filial. |
| 422 | DRIVER_NOT_FOUND | CPF sem cadastro na filial. Envie nome e telefone para cadastrar. |
| 422 | DRIVER_INVALID_PHONE | Telefone do condutor inválido. |
| 404 | EVENT_NOT_FOUND | Rota de PDF: o evento pedido não existe no documento. |
| 409 | DOCUMENT_NOT_CANCELABLE | O status do documento não permite cancelamento (só AUTHORIZED). |
| 409 | DOCUMENT_NOT_CHANGEABLE | O status do documento não aceita o evento pedido. |
| 409 | DOCUMENT_WITHOUT_PROTOCOL | O evento exige o protocolo de autorização e o documento não tem. |
| 409 | IMPORTED_DOCUMENT_READ_ONLY | Documento emitido por terceiro e importado não aceita eventos. |
| 409 | EVENT_ALREADY_PENDING | Já existe um evento do mesmo tipo aguardando processamento. |
| 409 | EVENT_ALREADY_REGISTERED | O evento só acontece uma vez e já foi registrado. |
| 409 | DOCUMENT_NOT_CLOSABLE | O status do MDF-e não permite encerramento (só AUTHORIZED). |
| 409 | CLOSING_ALREADY_PENDING | Já existe um encerramento aguardando processamento. |
| 409 | CLOSING_ALREADY_REGISTERED | O MDF-e já foi encerrado. |
| 422 | DOCUMENT_TYPE_NOT_ALLOWED | A 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
messagee envie de novo com a mesmaexternal_reference. - 429: espere o
Retry-After. - 409: leia o
code.EVENT_ALREADY_PENDINGpede 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
201e a rejeição aparece depois, nostatus,c_statestatus_reasondo documento ou do evento.
Exemplos completos
Emitir, acompanhar, baixar o DAMDFE e encerrar um MDF-e com curl:
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"
}
}'curl -s "https://painel.meurastreio.app/api/v1/mdfes/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
-H "x-api-token: SEU_TOKEN"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.pdfcurl -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:
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].