# Meu Rastreio — API de MDF-e (referência para modelos de IA)

> Documento em Markdown para agentes e modelos de IA. Versão para pessoas: https://meurastreio.app/pt-BR/api-de-mdfe

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 URL: `https://painel.meurastreio.app/api/v1`

## 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é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:

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:

```http
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:

```bash
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:

```json
{
  "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:

```bash
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. |

> Cada seguro precisa de ao menos uma identificação: `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. |

corpo de exemplo:

```json
{
  "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:

```json
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "mdfe": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PENDING"
  }
}
```

> **Atenção:** 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 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`, `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-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_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.

> **Atenção:** 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 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_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:

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

resposta 200:

```json
{
  "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:

```bash
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. |

> 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`)

| 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. |

encerrar:

```bash
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:

```json
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "mdfe": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "event": {
      "type": "CLOSING",
      "sequence": 1,
      "status": "PENDING"
    }
  }
}
```

cancelar:

```bash
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:

```bash
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": "financeiro@transportador-exemplo.com.br"
      }
    }
  ]
}'
```

> 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â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. |

requisição:

```bash
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

| 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. |

> 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

| 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 suporte@meurastreio.app 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 `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`)

| 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`. |

corpo recebido:

```json
{
  "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
}
```

> **Atenção:** 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

| 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:

resposta 429:

```http
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:

```json
{
  "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 `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:

```bash
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:

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

3. baixar o DAMDFE:

```bash
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:

```bash
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+):

```javascript
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: suporte@meurastreio.app. Para contratar: oi@meurastreio.app.
