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

Documentação

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 URLhttps://painel.meurastreio.app/api/v1
Requisitos e ativação
Nesta página

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étodocaminhoo que faz
POST/ciotsEmite 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/cancelCancela.
POST/ciots/closeEncerra.
POST/ciots/routeEscolhe 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
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
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": "[email protected]",
        "cpf_cnpj_titular": "00000000191"
      }
    ],
    "indicadores": {
      "alto_desempenho": false,
      "retorno_vazio": false
    }
  }
}'
resposta 201
{
  "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
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
campotipoobrigatórioregras
external_referencestring (UUID)nãoA 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).
ciotobjectsimOs dados da operação de transporte.
CIOT ciot
campotipoobrigatórioregras
tipo_operacaostringsimLOTACAO, FRACIONADA ou TAC_AGREGADO.
inicio_viagemdatetimesimISO 8601 com fuso (2026-11-20T08:00:00-03:00). No máximo 30 dias à frente.
fim_viagemdatetimesimCom 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_fretenumbersimMaior que zero.
veiculoobjectsimVeículo de tração: { "placa": "ABC1D23" }. A placa precisa existir no cadastro da filial.
reboquesarraynãoAté 4 reboques, cada um { "placa": "..." }, sem placa repetida. Cavalo mecânico exige ao menos um.
motoristaobjectsimMotorista da viagem (ver tabela).
contratanteobjectnãoQuem contrata o transporte. Omitido, é a própria filial. No TAC-agregado só pode ser a filial.
contratantes_carga_fracionadaarraynãoOs demais contratantes da carga na operação fracionada, cada um com cpf_cnpj e nome.
destinatarioobjectlotação e fracionadaDestinatário da carga, com cpf_cnpj e nome.
origemobjectsimPonto de origem (ver tabela).
paradasarraynãoParadas intermediárias, no mesmo formato de origem.
destinoobjectsimPonto de destino (ver tabela).
distancia_kmnumbernãoDistância da viagem em km, maior que zero.
cargaobjectnãoDados da carga (ver tabela). ncm e peso_kg são obrigatórios em lotação e fracionada.
pagamentosarraynãoComo o frete é pago. Omitido, vale o pagamento do cadastro do veículo. Se enviado, ao menos um item.
indicadoresobjectnãoIndicadores da operação (ver tabela).
shipment_external_referencestring (UUID)nãoReferência de um romaneio da filial, para vincular o CIOT a ele.
Motorista ciot.motorista
campotipoobrigatórioregras
cpfstringsimCPF de um motorista já cadastrado na filial, ou de um novo (com nome e telefone).
nomestringnãoAté 60 caracteres. Atualiza o nome do motorista já cadastrado.
telefonestringnãoCom nome, cadastra o motorista na filial quando o CPF ainda não existe. O telefone é o login do motorista no aplicativo.
Contratante e destinatário ciot.contratante, ciot.destinatario, ciot.contratantes_carga_fracionada[]
campotipoobrigatórioregras
cpf_cnpjstringsimCPF (11 dígitos) ou CNPJ (14 posições). A pontuação é removida.
nomestringsimAté 120 caracteres.
Origem, paradas e destino ciot.origem, ciot.paradas[], ciot.destino
campotipoobrigatórioregras
nomestringnãoNome do local, até 100 caracteres.
ibgestringsimCódigo IBGE do município, com 7 dígitos.
cidadestringsimNome do município.
ufstringsimSigla da UF, com 2 letras.
cepstringnãoCEP com 8 dígitos. A pontuação é removida.
latitudenumbernãoDe -90 a 90.
longitudenumbernãoDe -180 a 180.
Carga ciot.carga
campotipoobrigatórioregras
ncmstringlotação e fracionadaNCM da carga, de 4 a 8 dígitos.
peso_kgnumberlotação e fracionadaPeso em kg, maior que zero.
tipostringnãoPadrã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[]
campotipoobrigatórioregras
tipostringsimPIX, CONTA_CORRENTE, CONTA_POUPANCA, CONTA_PAGAMENTO, IPEF ou OUTROS. OUTROS não é aceito para todo tipo de transportador (PAYMENT_TYPE_NOT_ALLOWED).
cpf_cnpj_titularstringnãoCPF ou CNPJ do titular da conta ou da chave.
chave_pixstringno tipo PIXAté 77 caracteres.
end_to_endstringnãoIdentificador da transação PIX, até 32 caracteres.
bancostringnos tipos de contaCódigo do banco, até 5 caracteres.
agenciastringnos tipos de contaAté 10 caracteres.
contastringnos tipos de contaAté 20 caracteres.
parcelaintegernãoNúmero da parcela, a partir de 1. Com ela, vencimento e valor passam a ser obrigatórios.
vencimentodatetimecom parcelaISO 8601 com fuso.
valornumbercom parcelaMaior que zero.
Indicadores ciot.indicadores
campotipoobrigatórioregras
alto_desempenhobooleannãoPadrão false.
retorno_vaziobooleannãoPadrão false.
composicao_veicularbooleannãoOmitido, vale true quando há reboque.
corpo completo
{
  "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": "[email protected]",
        "cpf_cnpj_titular": "00000000191"
      }
    ],
    "indicadores": {
      "alto_desempenho": false,
      "retorno_vazio": false
    }
  }
}
resposta 201
{
  "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 CIOTo que o reenvio faz
PENDING que ainda não foi enviado, REJECTED ou ERRORSubstitui os dados e enfileira de novo.
PENDING ou PROCESSING já em andamento na ANTT409 CIOT_IN_PROGRESS: aguarde o retorno.
AUTHORIZED, CONTINGENCY, CANCELED ou CLOSED409 DOCUMENT_ALREADY_PROCESSED: cancele e emita outro, com outra referência.

Consulta e listagem

chamadadevolve
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 listaobrigatóriocomo usar
date_fromsimInício do período, em ISO 8601 com fuso: 2026-11-01T00:00:00-03:00 ou 2026-11-01T03:00:00Z. Data sem fuso é recusada.
date_tosimFim do período, com fuso. Igual ou posterior a date_from.
statusnãoFiltra por um ou mais status: status=AUTHORIZED,CANCELED ou o parâmetro repetido. Valores aceitos: PENDING, PROCESSING, AUTHORIZED, CONTINGENCY, REJECTED, CANCELED, CLOSED, ERROR.
pagenãoPágina, a partir de 1. Padrão: 1.
per_pagenãoItens por página, de 1 a 100. Padrão: 10.
  • O período filtra por data de 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
curl -s "https://painel.meurastreio.app/api/v1/ciots/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
resposta 200
{
  "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
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
campotipoobrigatórioregras
external_referencestring—A sua referência.
statusstring—Ver a seção Status.
status_reasonstring—Motivo da recusa, do erro ou da contingência.
environmentstring—PRODUCTION ou HOMOLOGATION.
transporter_noticestring—Aviso sobre o transportador devolvido na emissão, quando houver.
operation_typestring—LOTACAO, FRACIONADA ou TAC_AGREGADO.
ciotstring—Número do CIOT formatado com o código verificador. null enquanto não abrir.
numberstring—Número do CIOT.
verification_codestring—Código verificador.
transporter_cpf_cnpjstring—CPF/CNPJ do transportador declarado.
trip_start_at, trip_end_atdatetime—Período declarado da viagem.
declared_atdatetime—Quando o CIOT foi declarado.
canceled_at, cancel_reasondatetime, string—Cancelamento e o motivo informado.
closed_atdatetime—Encerramento.
freight_valuenumber—Valor do frete.
awaiting_routeboolean—true enquanto o CIOT espera a escolha da rota.
awaiting_transporter_checkboolean—true enquanto espera a consulta do veículo na ANTT.
routesarray—Rotas da viagem: id, name, toll_value, map_url, selected e tolls (name, concessionaire, highway, state, city, value).
shipment_external_referencesarray—Referências dos romaneios vinculados.
mdfe_external_referencestring—Referência do MDF-e que gerou o CIOT, quando houver.
historyarray—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.

rotacorpoquando pode
POST /ciots/cancelexternal_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/closeexternal_referenceCIOT aberto e depois do início da viagem. Fora disso: 409 CIOT_CLOSE_NOT_ALLOWED.
POST /ciots/routeexternal_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
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
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)
{
  "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
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

statuso que quer dizer
PENDINGGravado 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.
PROCESSINGEm envio à ANTT, ou com cancelamento ou encerramento em andamento.
AUTHORIZEDAberto: número e código verificador disponíveis.
CONTINGENCYAberto 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.
REJECTEDRecusado. O motivo fica em status_reason. Corrija e reenvie com a mesma referência.
ERRORA emissão terminou em erro. Pode ser reenviado com a mesma referência.
CANCELEDCancelado.
CLOSEDEncerrado.
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 [email protected] informando a filial, a URL que vai receber as chamadas e quais eventos você quer.

eventoquando é enviado
CIOT_CREATEDO CIOT foi gravado. O reenvio da mesma referência não repete o evento.
CIOT_AUTHORIZEDO CIOT abriu na ANTT.
CIOT_CONTINGENCYO CIOT abriu em contingência.
CIOT_REJECTEDO CIOT terminou em REJECTED ou ERROR.
CIOT_CANCELEDO CIOT foi cancelado.
CIOT_CLOSEDO 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
campotipoobrigatórioregras
idinteger—Identificador do CIOT no Meu Rastreio.
externalReferencestring—A sua referência.
companySubsidiaryIdinteger—Identificador da filial.
originstring—De onde o CIOT nasceu: API, SHIPMENT (romaneio), MDFE ou PANEL (painel).
environmentstring—PRODUCTION ou HOMOLOGATION. O mesmo evento sai dos dois ambientes.
statusstring—Status do CIOT.
statusDescriptionstring—O status em português.
statusReasonstring—Motivo da recusa, do erro ou da contingência.
transporterNoticestring—Aviso sobre o transportador, quando houver.
operationTypestring—LOTACAO, FRACIONADA ou TAC_AGREGADO.
number, verificationCodestring—Número do CIOT e código verificador.
transporterCpfCnpjstring—CPF/CNPJ do transportador.
tripStartAt, tripEndAtdatetime—Período da viagem.
declaredAt, canceledAt, closedAtdatetime—Declaração, cancelamento e encerramento.
cancelReasonstring—Motivo do cancelamento.
freightValuenumber—Valor do frete.
mdfeIdinteger—Identificador do MDF-e ligado, quando houver.
shipmentIdsarray—Identificadores dos romaneios vinculados.
corpo recebido
{
  "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": []
}
As chamadas não têm cabeçalho de assinatura. Para confirmar que a chamada veio do Meu Rastreio, peça ao suporte para configurar um cabeçalho personalizado com um segredo seu (por exemplo x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.
Trate o webhook como aviso: o mesmo evento pode chegar mais de uma vez. Use externalReference e status para decidir o que fazer e, na dúvida, consulte o documento pela API.

Limites de uso

limitevalorcomo funciona
Requisições por minuto120 por IPVale para todas as rotas da API somadas, contadas pelo IP de origem.
Itens por página10 (padrão), até 100Parâmetro per_page das listas.
Período da listaobrigatóriodate_from e date_to sempre informados: não existe listagem sem período.
Reboquesaté 4Por CIOT.
Início da viagematé 30 dias à frenteCampo inicio_viagem.
Período da viagem90 dias; TAC-agregado de 10 a 30Entre inicio_viagem e fim_viagem.
Cancelamentoaté 24 horas após o inícioDepois 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/1.1 429 Too Many Requests
Retry-After: 12

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

Erros

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

resposta 422
{
  "code": "VALIDATION_ERROR",
  "message": "2 errors occurred",
  "errors": [
    "external_reference must be a valid UUID",
    "deve ser uma data ISO 8601 com fuso, como 2026-10-10T09:00:00-03:00"
  ]
}
statuscodequando acontece
401—Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code.
401INTEGRATION_DISABLEDA integração do token foi desativada pelo administrador.
401CIOT_NOT_ALLOWEDA integração não tem a permissão CIOT.
402PLAN_WITHOUT_CIOTO plano da empresa não inclui o módulo CIOT.
404DOCUMENT_NOT_FOUNDDocumento não encontrado na filial do token.
405METHOD_NOT_ALLOWEDMétodo HTTP não aceito pela rota. Em algumas rotas o identificador vem só em message.
422VALIDATION_ERRORCorpo ou query fora do formato. errors lista cada problema encontrado.
429—Limite de requisições. O corpo é {"message":"TOO_MANY_REQUESTS"}, com o cabeçalho Retry-After.
500INTERNAL_ERRORFalha inesperada. Tente de novo; se persistir, fale com o suporte informando o protocol ou o horário da chamada.
404SHIPMENT_NOT_FOUNDO romaneio de shipment_external_reference não existe na filial.
404CIOT_ROUTE_NOT_FOUNDA rota informada não pertence à viagem.
409CIOT_CONFLICTJá existe CIOT vivo para a mesma placa, motorista ou transportador autônomo.
409CIOT_IN_PROGRESSO CIOT está em processamento. Aguarde e tente de novo.
409DOCUMENT_ALREADY_PROCESSEDCIOT aberto, cancelado ou encerrado não aceita reenvio.
409DOCUMENT_FROM_ANOTHER_SUBSIDIARYA referência externa já pertence a um CIOT de outra filial.
409CIOT_CANCEL_NOT_ALLOWEDSó é possível cancelar CIOT aberto e até 24 horas depois do início da viagem.
409CIOT_CLOSE_NOT_ALLOWEDSó é possível encerrar CIOT aberto e depois do início da viagem.
409CIOT_ROUTE_NOT_ALLOWEDA rota só pode ser escolhida enquanto o CIOT aguarda a escolha.
409DRIVER_PHONE_IN_USEO telefone do motorista já pertence a outro usuário.
422DRIVER_REQUIREDFaltou motorista.
422DRIVER_NOT_FOUNDCPF sem cadastro na filial. Envie nome e telefone para cadastrar.
422DRIVER_INVALID_PHONETelefone do motorista inválido.
422VEHICLE_NOT_FOUNDPlaca sem cadastro na filial.
422VEHICLE_AXLES_INVALIDNúmero de eixos do veículo fora do permitido.
422VEHICLE_OWNER_REQUIREDFalta o CPF/CNPJ do proprietário no cadastro do veículo.
422TRACTOR_WITHOUT_TRAILERCavalo mecânico sem reboque.
422TRANSPORTER_RNTRC_REQUIREDFalta o RNTRC do transportador no cadastro do veículo.
422TRANSPORTER_NOT_CHECKEDA consulta do transportador na ANTT tem pendência; message diz qual.
422CIOT_NOT_REQUIREDA operação não exige CIOT emitido pela filial.
422AGGREGATE_REQUIRES_TACTAC-agregado exige transportador autônomo (CPF) proprietário do veículo de tração.
422AGGREGATE_CONTRACTOR_MUST_BE_SUBSIDIARYNo TAC-agregado o contratante é a própria filial.
422CONTRACTOR_RNTRC_REQUIREDTAC-agregado exige o RNTRC da filial na configuração da empresa.
422OWNER_PAYMENT_NOT_CONFIGUREDSem pagamentos no corpo e sem forma de pagamento no cadastro do veículo.
422OWNER_PAYMENT_INCOMPLETEO pagamento do cadastro do veículo está sem chave PIX ou sem banco, agência e conta.
422PAYMENT_TYPE_NOT_ALLOWEDO tipo de pagamento não é aceito para esse transportador.
502CIOT_PROVIDER_UNAVAILABLEServiç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
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": "[email protected]",
        "cpf_cnpj_titular": "00000000191"
      }
    ],
    "indicadores": {
      "alto_desempenho": false,
      "retorno_vazio": false
    }
  }
}'
2. consultar até abrir
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
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+)
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);
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: [email protected]. Para contratar: [email protected].