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
POSTresponde 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:
- O plano da empresa inclui o módulo CIOT. Sem ele, a API responde
402. - Existe uma integração com o canal API na filial que vai emitir. Ela é criada no painel, em Integrações → nova integração, por um usuário administrador.
- A integração está ativa e com a permissão CIOT ligada. Sem a permissão, a API responde
401. - 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. - Para o TAC-agregado, o RNTRC da filial está preenchido na configuração da empresa.
Autenticação
Envie o token da integração no cabeçalho x-api-token de todas as chamadas.
x-api-token: 0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9- O token é um UUID e pertence a uma integração de uma filial: tudo o que você emite e consulta com ele é dessa filial. Empresa com várias filiais usa um token por filial.
- Ele aparece na tela da integração, no painel, e não tem validade.
- Para revogar, desative ou exclua a integração, ou substitua o token. O token antigo deixa de funcionar.
- O mesmo token pode ter outras permissões. Esta API exige a permissão CIOT.
- Só HTTPS. Nunca envie o token na URL e guarde-o como senha, em cofre de segredos.
- Token ausente ou desconhecido responde
401com{"message":"Acesso negado"}.
Primeira chamada
Emita um CIOT de lotação. Gere um UUID para a external_reference e guarde-o: é a sua chave para tudo o que vem depois.
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
}
}
}'{
"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:
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. |
{
"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
}
}
}{
"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
destinatarioecarga. - Quando a operação não exige CIOT emitido pela filial, a resposta é
422 CIOT_NOT_REQUIRED, com o motivo emmessage. - Se o veículo de tração ainda não foi consultado na ANTT, o CIOT é aceito e fica
PENDINGcomawaiting_transporter_check: trueaté 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_fromedate_to, ou com um status que não existe, a resposta é422 VALIDATION_ERROR. - O
+do fuso precisa ir codificado como%2Bna URL.Ze-03:00não precisam. - A resposta da lista é
{ data, pagination: { page, per_page, total, total_pages } }.
curl -s "https://painel.meurastreio.app/api/v1/ciots/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
-H "x-api-token: SEU_TOKEN"{
"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"
}
]
}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. |
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. |
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"
}'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"
}'{
"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
statusPROCESSING, e a confirmação chega pela consulta ou pelos webhooksCIOT_CANCELEDeCIOT_CLOSED. Se a ANTT recusar o pedido, o CIOT volta a ficar aberto, com o motivo emstatus_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:
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 [email protected] 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
POSTpara a sua URL, comContent-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
originse 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. |
{
"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": []
}x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.externalReference e status para decidir o que fazer e, na dúvida, consulte o documento pela API.Limites de uso
| limite | valor | como funciona |
|---|---|---|
| Requisições por minuto | 120 por IP | Vale para todas as rotas da API somadas, contadas pelo IP de origem. |
| Itens por página | 10 (padrão), até 100 | Parâmetro per_page das listas. |
| Período da lista | obrigatório | date_from e date_to sempre informados: não existe listagem sem período. |
| 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:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
{ "message": "TOO_MANY_REQUESTS" }- Respeite o
Retry-Afterantes de tentar de novo. - Para acompanhar o resultado de uma emissão, prefira os webhooks. Se for consultar, espere alguns segundos entre uma consulta e outra.
- Na lista, use
per_page=100para fazer menos chamadas.
Erros
O corpo de erro traz code, para o seu código decidir o que fazer, e message, para leitura de pessoas. Alguns erros trazem campos extras, como errors na validação.
{
"code": "VALIDATION_ERROR",
"message": "2 errors occurred",
"errors": [
"external_reference must be a valid UUID",
"deve ser uma data ISO 8601 com fuso, como 2026-10-10T09:00:00-03:00"
]
}| status | code | quando acontece |
|---|---|---|
| 401 | — | Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code. |
| 401 | INTEGRATION_DISABLED | A integração do token foi desativada pelo administrador. |
| 401 | 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
messagee envie de novo com a mesmaexternal_reference. - 429: espere o
Retry-After. - 409: leia o
code.CIOT_IN_PROGRESSpede 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:
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
}
}
}'curl -s "https://painel.meurastreio.app/api/v1/ciots/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
-H "x-api-token: SEU_TOKEN"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:
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);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].