# Meu Rastreio — API de CIOT (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-ciot

Declare a operação de transporte e gere o CIOT a partir do seu sistema pela API do Meu Rastreio: emissão na ANTT, consulta, encerramento, cancelamento, escolha de rota, status e webhooks.

Base URL: `https://painel.meurastreio.app/api/v1`

## Visão geral

A API de CIOT declara o **Código Identificador da Operação de Transporte** na ANTT a partir do seu sistema (ERP, TMS ou outro), em nome de **uma filial**. Com ela você emite, consulta, cancela e encerra o CIOT e escolhe a rota da viagem.

- A emissão é **assíncrona**: o `POST` responde na hora dizendo que o CIOT entrou na fila, e o número chega depois, pela consulta ou por webhook.
- A `external_reference` é a chave do CIOT para o seu sistema: é com ela que você consulta, reenvia, cancela e encerra.
- Cancelar, encerrar e escolher rota são chamadas à parte, que já devolvem o CIOT atualizado.
- Veículos e motoristas são os do cadastro da filial no Meu Rastreio; a API valida o cadastro antes de enviar à ANTT.

| método | caminho | o que faz |
|---|---|---|
| `POST` | `/ciots` | Emite um CIOT, ou reenvia o da mesma `external_reference`. |
| `GET` | `/ciots/{external_reference}` | Consulta um CIOT. |
| `GET` | `/ciots?external_reference=` | A mesma consulta, pela query string. |
| `GET` | `/ciots?date_from=&date_to=` | Lista os CIOTs criados no período. |
| `POST` | `/ciots/cancel` | Cancela. |
| `POST` | `/ciots/close` | Encerra. |
| `POST` | `/ciots/route` | Escolhe a rota da viagem. |

## 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 **CIOT**. 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 **CIOT** ligada. Sem a permissão, a API responde `401`.
4. Os veículos da viagem estão cadastrados na filial, com proprietário (CPF/CNPJ), RNTRC do transportador, número de eixos e, quando o corpo não trouxer `pagamentos`, a forma de pagamento do frete.
5. Para o TAC-agregado, o RNTRC da filial está preenchido na configuração da empresa.

> O CIOT não depende do módulo de documentos fiscais: quem emite só CIOT não precisa de certificado digital.

## 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 **CIOT**.
- 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 CIOT de lotação. Gere um UUID para a `external_reference` e guarde-o: é a sua chave para tudo o que vem depois.

requisição:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ciots" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "ciot": {
    "tipo_operacao": "LOTACAO",
    "inicio_viagem": "2026-11-20T08:00:00-03:00",
    "fim_viagem": "2026-11-22T18:00:00-03:00",
    "valor_frete": 4800,
    "veiculo": {
      "placa": "ABC1D23"
    },
    "reboques": [
      {
        "placa": "XYZ9A88"
      }
    ],
    "motorista": {
      "cpf": "00000000191",
      "nome": "Motorista Exemplo",
      "telefone": "+55 11 90000-0000"
    },
    "destinatario": {
      "cpf_cnpj": "00000000000272",
      "nome": "Destinatário Exemplo Ltda"
    },
    "origem": {
      "nome": "CD São Paulo",
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01001000"
    },
    "paradas": [],
    "destino": {
      "nome": "Cliente Rio",
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ",
      "cep": "20010000"
    },
    "distancia_km": 430,
    "carga": {
      "ncm": "84713012",
      "peso_kg": 12000,
      "tipo": "CARGA_GERAL"
    },
    "pagamentos": [
      {
        "tipo": "PIX",
        "chave_pix": "financeiro@transportador-exemplo.com.br",
        "cpf_cnpj_titular": "00000000191"
      }
    ],
    "indicadores": {
      "alto_desempenho": false,
      "retorno_vazio": false
    }
  }
}'
```

resposta 201:

```json
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "ciot": {
    "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/ciots/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
```

Quando `status` for `AUTHORIZED`, o CIOT está aberto e `ciot` traz o número com o código verificador.

## Emissão

`POST /ciots` recebe um JSON com a referência e o objeto `ciot`.

### Corpo (`raiz`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `external_reference` | string (UUID) | não | A sua chave para o CIOT. Sem ela, o Meu Rastreio gera uma e devolve na resposta. Enviar de novo a mesma referência reenvia o documento (ver Reenvio). |
| `ciot` | object | sim | Os dados da operação de transporte. |

### CIOT (`ciot`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `tipo_operacao` | string | sim | `LOTACAO`, `FRACIONADA` ou `TAC_AGREGADO`. |
| `inicio_viagem` | datetime | sim | ISO 8601 **com fuso** (`2026-11-20T08:00:00-03:00`). No máximo 30 dias à frente. |
| `fim_viagem` | datetime | sim | Com fuso e posterior ao início. Período de até 90 dias em lotação e fracionada; de 10 a 30 dias no TAC-agregado. |
| `valor_frete` | number | sim | Maior que zero. |
| `veiculo` | object | sim | Veículo de tração: `{ "placa": "ABC1D23" }`. A placa precisa existir no cadastro da filial. |
| `reboques` | array | não | Até 4 reboques, cada um `{ "placa": "..." }`, sem placa repetida. Cavalo mecânico exige ao menos um. |
| `motorista` | object | sim | Motorista da viagem (ver tabela). |
| `contratante` | object | não | Quem contrata o transporte. Omitido, é a própria filial. No TAC-agregado só pode ser a filial. |
| `contratantes_carga_fracionada` | array | não | Os demais contratantes da carga na operação fracionada, cada um com `cpf_cnpj` e `nome`. |
| `destinatario` | object | lotação e fracionada | Destinatário da carga, com `cpf_cnpj` e `nome`. |
| `origem` | object | sim | Ponto de origem (ver tabela). |
| `paradas` | array | não | Paradas intermediárias, no mesmo formato de `origem`. |
| `destino` | object | sim | Ponto de destino (ver tabela). |
| `distancia_km` | number | não | Distância da viagem em km, maior que zero. |
| `carga` | object | não | Dados da carga (ver tabela). `ncm` e `peso_kg` são obrigatórios em lotação e fracionada. |
| `pagamentos` | array | não | Como o frete é pago. Omitido, vale o pagamento do cadastro do veículo. Se enviado, ao menos um item. |
| `indicadores` | object | não | Indicadores da operação (ver tabela). |
| `shipment_external_reference` | string (UUID) | não | Referência de um romaneio da filial, para vincular o CIOT a ele. |

### Motorista (`ciot.motorista`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `cpf` | string | sim | CPF de um motorista já cadastrado na filial, ou de um 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. |

### Contratante e destinatário (`ciot.contratante, ciot.destinatario, ciot.contratantes_carga_fracionada[]`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `cpf_cnpj` | string | sim | CPF (11 dígitos) ou CNPJ (14 posições). A pontuação é removida. |
| `nome` | string | sim | Até 120 caracteres. |

### Origem, paradas e destino (`ciot.origem, ciot.paradas[], ciot.destino`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `nome` | string | não | Nome do local, até 100 caracteres. |
| `ibge` | string | sim | Código IBGE do município, com 7 dígitos. |
| `cidade` | string | sim | Nome do município. |
| `uf` | string | sim | Sigla da UF, com 2 letras. |
| `cep` | string | não | CEP com 8 dígitos. A pontuação é removida. |
| `latitude` | number | não | De -90 a 90. |
| `longitude` | number | não | De -180 a 180. |

### Carga (`ciot.carga`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `ncm` | string | lotação e fracionada | NCM da carga, de 4 a 8 dígitos. |
| `peso_kg` | number | lotação e fracionada | Peso em kg, maior que zero. |
| `tipo` | string | não | Padrão `CARGA_GERAL`. Aceita `GRANEL_SOLIDO`, `GRANEL_LIQUIDO`, `FRIGORIFICADA_OU_AQUECIDA`, `CONTEINERIZADA`, `CARGA_GERAL`, `NEOGRANEL`, `PERIGOSA_GRANEL_SOLIDO`, `PERIGOSA_GRANEL_LIQUIDO`, `PERIGOSA_FRIGORIFICADA_OU_AQUECIDA`, `PERIGOSA_CONTEINERIZADA`, `PERIGOSA_CARGA_GERAL` e `CARGA_GRANEL_PRESSURIZADA`. |

### Pagamento (`ciot.pagamentos[]`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `tipo` | string | sim | `PIX`, `CONTA_CORRENTE`, `CONTA_POUPANCA`, `CONTA_PAGAMENTO`, `IPEF` ou `OUTROS`. `OUTROS` não é aceito para todo tipo de transportador (`PAYMENT_TYPE_NOT_ALLOWED`). |
| `cpf_cnpj_titular` | string | não | CPF ou CNPJ do titular da conta ou da chave. |
| `chave_pix` | string | no tipo PIX | Até 77 caracteres. |
| `end_to_end` | string | não | Identificador da transação PIX, até 32 caracteres. |
| `banco` | string | nos tipos de conta | Código do banco, até 5 caracteres. |
| `agencia` | string | nos tipos de conta | Até 10 caracteres. |
| `conta` | string | nos tipos de conta | Até 20 caracteres. |
| `parcela` | integer | não | Número da parcela, a partir de 1. Com ela, `vencimento` e `valor` passam a ser obrigatórios. |
| `vencimento` | datetime | com parcela | ISO 8601 com fuso. |
| `valor` | number | com parcela | Maior que zero. |

### Indicadores (`ciot.indicadores`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `alto_desempenho` | boolean | não | Padrão `false`. |
| `retorno_vazio` | boolean | não | Padrão `false`. |
| `composicao_veicular` | boolean | não | Omitido, vale `true` quando há reboque. |

corpo completo:

```json
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "ciot": {
    "tipo_operacao": "LOTACAO",
    "inicio_viagem": "2026-11-20T08:00:00-03:00",
    "fim_viagem": "2026-11-22T18:00:00-03:00",
    "valor_frete": 4800,
    "veiculo": {
      "placa": "ABC1D23"
    },
    "reboques": [
      {
        "placa": "XYZ9A88"
      }
    ],
    "motorista": {
      "cpf": "00000000191",
      "nome": "Motorista Exemplo",
      "telefone": "+55 11 90000-0000"
    },
    "destinatario": {
      "cpf_cnpj": "00000000000272",
      "nome": "Destinatário Exemplo Ltda"
    },
    "origem": {
      "nome": "CD São Paulo",
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01001000"
    },
    "paradas": [],
    "destino": {
      "nome": "Cliente Rio",
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ",
      "cep": "20010000"
    },
    "distancia_km": 430,
    "carga": {
      "ncm": "84713012",
      "peso_kg": 12000,
      "tipo": "CARGA_GERAL"
    },
    "pagamentos": [
      {
        "tipo": "PIX",
        "chave_pix": "financeiro@transportador-exemplo.com.br",
        "cpf_cnpj_titular": "00000000191"
      }
    ],
    "indicadores": {
      "alto_desempenho": false,
      "retorno_vazio": false
    }
  }
}
```

resposta 201:

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

### Regras que a API confere antes de enfileirar

- A mesma placa, o mesmo motorista ou o mesmo transportador autônomo não pode ter dois CIOTs vivos ao mesmo tempo: `409 CIOT_CONFLICT`. Cancele ou encerre o anterior.
- A tração aceita de 2 a 4 eixos e o reboque, de 1 a 4 (`VEHICLE_AXLES_INVALID`).
- O TAC-agregado exige transportador autônomo (CPF) proprietário do veículo de tração e dispensa `destinatario` e `carga`.
- Quando a operação não exige CIOT emitido pela filial, a resposta é `422 CIOT_NOT_REQUIRED`, com o motivo em `message`.
- Se o veículo de tração ainda não foi consultado na ANTT, o CIOT é aceito e fica `PENDING` com `awaiting_transporter_check: true` até a consulta terminar.

### Reenvio

O `POST` com uma `external_reference` que já existe **substitui os dados e volta o CIOT para a fila**, desde que ele ainda possa mudar:

| situação do CIOT | o que o reenvio faz |
|---|---|
| `PENDING` que ainda não foi enviado, `REJECTED` ou `ERROR` | Substitui os dados e enfileira de novo. |
| `PENDING` ou `PROCESSING` já em andamento na ANTT | `409 CIOT_IN_PROGRESS`: aguarde o retorno. |
| `AUTHORIZED`, `CONTINGENCY`, `CANCELED` ou `CLOSED` | `409 DOCUMENT_ALREADY_PROCESSED`: cancele e emita outro, com outra referência. |

## Consulta e listagem

| chamada | devolve |
|---|---|
| `GET /ciots/{external_reference}` | O CIOT dessa referência. |
| `GET /ciots?external_reference=` | O mesmo CIOT, pela query string. |
| `GET /ciots?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`, `CONTINGENCY`, `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 criação do CIOT.
- 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/ciots/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
```

resposta 200:

```json
{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "status": "AUTHORIZED",
  "status_reason": null,
  "environment": "PRODUCTION",
  "transporter_notice": null,
  "operation_type": "LOTACAO",
  "ciot": "123456789012/3456",
  "number": "123456789012",
  "verification_code": "3456",
  "transporter_cpf_cnpj": "00000000191",
  "trip_start_at": "2026-11-20T11:00:00.000Z",
  "trip_end_at": "2026-11-22T21:00:00.000Z",
  "declared_at": "2026-11-19T14:02:11.000Z",
  "canceled_at": null,
  "cancel_reason": null,
  "closed_at": null,
  "freight_value": 4800,
  "awaiting_route": false,
  "awaiting_transporter_check": false,
  "routes": [
    {
      "id": "rota-1",
      "name": "Via Dutra",
      "toll_value": 182.4,
      "map_url": "https://exemplo.com/mapa/rota-1",
      "selected": true,
      "tolls": [
        {
          "name": "Praça Exemplo",
          "concessionaire": "Concessionária Exemplo",
          "highway": "BR-116",
          "state": "SP",
          "city": "Jacareí",
          "value": 15.2
        }
      ]
    }
  ],
  "shipment_external_references": [],
  "mdfe_external_reference": null,
  "history": [
    {
      "type": "SELECT_ROUTE",
      "source": "API",
      "user": null,
      "integration": "ERP",
      "route_name": "Via Dutra",
      "route_mode": "MANUAL",
      "at": "2026-11-19T14:01:58.000Z"
    }
  ]
}
```

lista:

```bash
curl -s "https://painel.meurastreio.app/api/v1/ciots?date_from=2026-11-01T00:00:00-03:00&date_to=2026-11-30T23:59:59-03:00&status=AUTHORIZED&per_page=100" \
  -H "x-api-token: SEU_TOKEN"
```

### CIOT na resposta (`objeto devolvido`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `external_reference` | string | — | A sua referência. |
| `status` | string | — | Ver a seção Status. |
| `status_reason` | string | — | Motivo da recusa, do erro ou da contingência. |
| `environment` | string | — | `PRODUCTION` ou `HOMOLOGATION`. |
| `transporter_notice` | string | — | Aviso sobre o transportador devolvido na emissão, quando houver. |
| `operation_type` | string | — | `LOTACAO`, `FRACIONADA` ou `TAC_AGREGADO`. |
| `ciot` | string | — | Número do CIOT formatado com o código verificador. `null` enquanto não abrir. |
| `number` | string | — | Número do CIOT. |
| `verification_code` | string | — | Código verificador. |
| `transporter_cpf_cnpj` | string | — | CPF/CNPJ do transportador declarado. |
| `trip_start_at, trip_end_at` | datetime | — | Período declarado da viagem. |
| `declared_at` | datetime | — | Quando o CIOT foi declarado. |
| `canceled_at, cancel_reason` | datetime, string | — | Cancelamento e o motivo informado. |
| `closed_at` | datetime | — | Encerramento. |
| `freight_value` | number | — | Valor do frete. |
| `awaiting_route` | boolean | — | `true` enquanto o CIOT espera a escolha da rota. |
| `awaiting_transporter_check` | boolean | — | `true` enquanto espera a consulta do veículo na ANTT. |
| `routes` | array | — | Rotas da viagem: `id`, `name`, `toll_value`, `map_url`, `selected` e `tolls` (`name`, `concessionaire`, `highway`, `state`, `city`, `value`). |
| `shipment_external_references` | array | — | Referências dos romaneios vinculados. |
| `mdfe_external_reference` | string | — | Referência do MDF-e que gerou o CIOT, quando houver. |
| `history` | array | — | Histórico de ações: `type`, `source`, `user`, `integration`, `route_name`, `route_mode`, `at`. |

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

## Cancelar, encerrar e escolher rota

As três ações são `POST` com a `external_reference` do CIOT no corpo. A resposta `201` traz `protocol` e o CIOT já atualizado, no mesmo formato da consulta.

| rota | corpo | quando pode |
|---|---|---|
| `POST /ciots/cancel` | `external_reference` e `motivo` (de 10 a 200 caracteres) | CIOT aberto (`AUTHORIZED` ou `CONTINGENCY`), até 24 horas depois do início da viagem. Fora disso: `409 CIOT_CANCEL_NOT_ALLOWED`. |
| `POST /ciots/close` | `external_reference` | CIOT aberto e depois do início da viagem. Fora disso: `409 CIOT_CLOSE_NOT_ALLOWED`. |
| `POST /ciots/route` | `external_reference` e `rota` (o `id` de um item de `routes`) | Enquanto `awaiting_route` for `true`. Fora disso: `409 CIOT_ROUTE_NOT_ALLOWED`; rota que não é da viagem: `404 CIOT_ROUTE_NOT_FOUND`. |

cancelar:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ciots/cancel" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "motivo": "Viagem cancelada pelo embarcador"
}'
```

encerrar:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ciots/close" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9"
}'
```

resposta 201 (resumida):

```json
{
  "protocol": "7d1c9b52-8e43-4f6a-b2a7-51c0e9d3f4a6",
  "ciot": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "CANCELED",
    "canceled_at": "2026-11-20T15:30:02.000Z",
    "cancel_reason": "Viagem cancelada pelo embarcador"
  }
}
```

- Cancelamento e encerramento podem não ser confirmados na hora. Nesse caso o CIOT volta com `status` `PROCESSING`, e a confirmação chega pela consulta ou pelos webhooks `CIOT_CANCELED` e `CIOT_CLOSED`. Se a ANTT recusar o pedido, o CIOT volta a ficar aberto, com o motivo em `status_reason`.
- Uma segunda chamada enquanto a primeira está em andamento responde `409 CIOT_IN_PROGRESS`.
- Se o serviço de emissão do CIOT estiver indisponível, a resposta é `502 CIOT_PROVIDER_UNAVAILABLE`: o CIOT continua como estava e a chamada pode ser repetida.

### Escolha da rota

Quando a filial está configurada para escolher a rota manualmente, o CIOT para em `PENDING` com `awaiting_route: true` e `routes` traz as opções, com pedágios e valores. Escolha uma para a emissão continuar:

escolher rota:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ciots/route" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "rota": "rota-1"
}'
```

## Status

| status | o que quer dizer |
|---|---|
| `PENDING` | Gravado e aguardando a fila, a escolha da rota (`awaiting_route`) ou a consulta do veículo (`awaiting_transporter_check`). Também é para onde o CIOT volta depois de uma falha técnica, para nova tentativa automática. |
| `PROCESSING` | Em envio à ANTT, ou com cancelamento ou encerramento em andamento. |
| `AUTHORIZED` | **Aberto**: número e código verificador disponíveis. |
| `CONTINGENCY` | **Aberto em contingência**: a ANTT estava indisponível. Já tem número; o código verificador chega quando a ANTT registrar. A justificativa fica em `status_reason`. |
| `REJECTED` | Recusado. O motivo fica em `status_reason`. Corrija e reenvie com a mesma referência. |
| `ERROR` | A emissão terminou em erro. Pode ser reenviado com a mesma referência. |
| `CANCELED` | Cancelado. |
| `CLOSED` | Encerrado. |

> `PENDING` e `PROCESSING` são transitórios: continue acompanhando. Os demais são o resultado de uma etapa.

## Webhooks

O Meu Rastreio tem webhooks para os eventos do CIOT: 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 |
|---|---|
| `CIOT_CREATED` | O CIOT foi gravado. O reenvio da mesma referência não repete o evento. |
| `CIOT_AUTHORIZED` | O CIOT abriu na ANTT. |
| `CIOT_CONTINGENCY` | O CIOT abriu em contingência. |
| `CIOT_REJECTED` | O CIOT terminou em `REJECTED` ou `ERROR`. |
| `CIOT_CANCELED` | O CIOT foi cancelado. |
| `CIOT_CLOSED` | O CIOT foi encerrado. |

- Cada evento habilitado gera uma chamada `POST` para a sua URL, com `Content-Type: application/json`.
- O corpo é o próprio objeto do CIOT, 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.
- CIOTs criados pelo painel ou por romaneio também disparam os eventos; use `origin` se quiser tratar só os da API.

### CIOT no webhook (`corpo do POST`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `id` | integer | — | Identificador do CIOT no Meu Rastreio. |
| `externalReference` | string | — | A sua referência. |
| `companySubsidiaryId` | integer | — | Identificador da filial. |
| `origin` | string | — | De onde o CIOT nasceu: `API`, `SHIPMENT` (romaneio), `MDFE` ou `PANEL` (painel). |
| `environment` | string | — | `PRODUCTION` ou `HOMOLOGATION`. O mesmo evento sai dos dois ambientes. |
| `status` | string | — | Status do CIOT. |
| `statusDescription` | string | — | O status em português. |
| `statusReason` | string | — | Motivo da recusa, do erro ou da contingência. |
| `transporterNotice` | string | — | Aviso sobre o transportador, quando houver. |
| `operationType` | string | — | `LOTACAO`, `FRACIONADA` ou `TAC_AGREGADO`. |
| `number, verificationCode` | string | — | Número do CIOT e código verificador. |
| `transporterCpfCnpj` | string | — | CPF/CNPJ do transportador. |
| `tripStartAt, tripEndAt` | datetime | — | Período da viagem. |
| `declaredAt, canceledAt, closedAt` | datetime | — | Declaração, cancelamento e encerramento. |
| `cancelReason` | string | — | Motivo do cancelamento. |
| `freightValue` | number | — | Valor do frete. |
| `mdfeId` | integer | — | Identificador do MDF-e ligado, quando houver. |
| `shipmentIds` | array | — | Identificadores dos romaneios vinculados. |

corpo recebido:

```json
{
  "id": 1842,
  "externalReference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "companySubsidiaryId": 12,
  "origin": "API",
  "environment": "PRODUCTION",
  "status": "AUTHORIZED",
  "statusReason": null,
  "transporterNotice": null,
  "operationType": "LOTACAO",
  "number": "123456789012",
  "verificationCode": "3456",
  "transporterCpfCnpj": "00000000191",
  "tripStartAt": "2026-11-20T11:00:00.000Z",
  "tripEndAt": "2026-11-22T21:00:00.000Z",
  "declaredAt": "2026-11-19T14:02:11.000Z",
  "canceledAt": null,
  "cancelReason": null,
  "closedAt": null,
  "freightValue": 4800,
  "mdfeId": null,
  "statusDescription": "Aberto",
  "shipmentIds": []
}
```

> **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. |
| Reboques | até 4 | Por CIOT. |
| Início da viagem | até 30 dias à frente | Campo `inicio_viagem`. |
| Período da viagem | 90 dias; TAC-agregado de 10 a 30 | Entre `inicio_viagem` e `fim_viagem`. |
| Cancelamento | até 24 horas após o início | Depois disso o CIOT só pode ser encerrado. |

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 | `CIOT_NOT_ALLOWED` | A integração não tem a permissão CIOT. |
| 402 | `PLAN_WITHOUT_CIOT` | O plano da empresa não inclui o módulo CIOT. |
| 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. |
| 404 | `SHIPMENT_NOT_FOUND` | O romaneio de `shipment_external_reference` não existe na filial. |
| 404 | `CIOT_ROUTE_NOT_FOUND` | A rota informada não pertence à viagem. |
| 409 | `CIOT_CONFLICT` | Já existe CIOT vivo para a mesma placa, motorista ou transportador autônomo. |
| 409 | `CIOT_IN_PROGRESS` | O CIOT está em processamento. Aguarde e tente de novo. |
| 409 | `DOCUMENT_ALREADY_PROCESSED` | CIOT aberto, cancelado ou encerrado não aceita reenvio. |
| 409 | `DOCUMENT_FROM_ANOTHER_SUBSIDIARY` | A referência externa já pertence a um CIOT de outra filial. |
| 409 | `CIOT_CANCEL_NOT_ALLOWED` | Só é possível cancelar CIOT aberto e até 24 horas depois do início da viagem. |
| 409 | `CIOT_CLOSE_NOT_ALLOWED` | Só é possível encerrar CIOT aberto e depois do início da viagem. |
| 409 | `CIOT_ROUTE_NOT_ALLOWED` | A rota só pode ser escolhida enquanto o CIOT aguarda a escolha. |
| 409 | `DRIVER_PHONE_IN_USE` | O telefone do motorista já pertence a outro usuário. |
| 422 | `DRIVER_REQUIRED` | Faltou `motorista`. |
| 422 | `DRIVER_NOT_FOUND` | CPF sem cadastro na filial. Envie `nome` e `telefone` para cadastrar. |
| 422 | `DRIVER_INVALID_PHONE` | Telefone do motorista inválido. |
| 422 | `VEHICLE_NOT_FOUND` | Placa sem cadastro na filial. |
| 422 | `VEHICLE_AXLES_INVALID` | Número de eixos do veículo fora do permitido. |
| 422 | `VEHICLE_OWNER_REQUIRED` | Falta o CPF/CNPJ do proprietário no cadastro do veículo. |
| 422 | `TRACTOR_WITHOUT_TRAILER` | Cavalo mecânico sem reboque. |
| 422 | `TRANSPORTER_RNTRC_REQUIRED` | Falta o RNTRC do transportador no cadastro do veículo. |
| 422 | `TRANSPORTER_NOT_CHECKED` | A consulta do transportador na ANTT tem pendência; `message` diz qual. |
| 422 | `CIOT_NOT_REQUIRED` | A operação não exige CIOT emitido pela filial. |
| 422 | `AGGREGATE_REQUIRES_TAC` | TAC-agregado exige transportador autônomo (CPF) proprietário do veículo de tração. |
| 422 | `AGGREGATE_CONTRACTOR_MUST_BE_SUBSIDIARY` | No TAC-agregado o contratante é a própria filial. |
| 422 | `CONTRACTOR_RNTRC_REQUIRED` | TAC-agregado exige o RNTRC da filial na configuração da empresa. |
| 422 | `OWNER_PAYMENT_NOT_CONFIGURED` | Sem `pagamentos` no corpo e sem forma de pagamento no cadastro do veículo. |
| 422 | `OWNER_PAYMENT_INCOMPLETE` | O pagamento do cadastro do veículo está sem chave PIX ou sem banco, agência e conta. |
| 422 | `PAYMENT_TYPE_NOT_ALLOWED` | O tipo de pagamento não é aceito para esse transportador. |
| 502 | `CIOT_PROVIDER_UNAVAILABLE` | Serviço de emissão do CIOT indisponível ao cancelar, encerrar ou escolher rota. |

- **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`. `CIOT_IN_PROGRESS` pede espera; os demais pedem uma decisão (cancelar, encerrar ou usar outra referência).
- **502**: tente de novo depois de alguns segundos.

## Exemplos completos

Emitir, acompanhar e encerrar um CIOT com curl:

1. emitir:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ciots" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  "ciot": {
    "tipo_operacao": "LOTACAO",
    "inicio_viagem": "2026-11-20T08:00:00-03:00",
    "fim_viagem": "2026-11-22T18:00:00-03:00",
    "valor_frete": 4800,
    "veiculo": {
      "placa": "ABC1D23"
    },
    "reboques": [
      {
        "placa": "XYZ9A88"
      }
    ],
    "motorista": {
      "cpf": "00000000191",
      "nome": "Motorista Exemplo",
      "telefone": "+55 11 90000-0000"
    },
    "destinatario": {
      "cpf_cnpj": "00000000000272",
      "nome": "Destinatário Exemplo Ltda"
    },
    "origem": {
      "nome": "CD São Paulo",
      "ibge": "3550308",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01001000"
    },
    "paradas": [],
    "destino": {
      "nome": "Cliente Rio",
      "ibge": "3304557",
      "cidade": "Rio de Janeiro",
      "uf": "RJ",
      "cep": "20010000"
    },
    "distancia_km": 430,
    "carga": {
      "ncm": "84713012",
      "peso_kg": 12000,
      "tipo": "CARGA_GERAL"
    },
    "pagamentos": [
      {
        "tipo": "PIX",
        "chave_pix": "financeiro@transportador-exemplo.com.br",
        "cpf_cnpj_titular": "00000000191"
      }
    ],
    "indicadores": {
      "alto_desempenho": false,
      "retorno_vazio": false
    }
  }
}'
```

2. consultar até abrir:

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

3. encerrar depois da viagem:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/ciots/close" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9"
}'
```

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, ciot) {
  // 201 means queued: the final status comes from the GET (or from the webhooks)
  await call("/ciots", {
    method: "POST",
    body: JSON.stringify({ external_reference: externalReference, ciot }),
  });

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

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

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

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

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

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

> **Atenção:** Um CIOT que aguarda a escolha de rota fica em `PENDING` até alguém escolher. Se a sua filial usa rota manual, trate `awaiting_route` no laço de consulta.

## Suporte

Ativação do módulo, permissão da integração, webhooks ou dúvidas sobre uma recusa da ANTT: suporte@meurastreio.app. Para contratar: oi@meurastreio.app.
