API: CIOT (Operações de Transporte)

Crie, valide e emita o CIOT em uma única chamada, ou em etapas.

Visão geral

Toda a tela de CIOT também está disponível por API. Você pode enviar a operação completa (contratantes, veículos, pagamentos e documentos) em uma única requisição e, opcionalmente, rodar a validação e a emissão na ANTT no mesmo passo.

Escopo de operações suportadas

A API atende operações de Lotação e Fracionada nas seguintes modalidades de contratação:

Frota própria — quando a empresa transporta carga com veículos próprios.
TAC autônomo — transportador autônomo de carga.
ETC contratado — empresa de transporte rodoviário de carga contratada.
ETC equiparado a TAC — ETC tratado como TAC para fins de pagamento.

Autenticação

Use os headers X-FreteFlow-Key (formato prefix.secret) e X-FreteFlow-Signature (HMAC-SHA256 do body cru com o segredo da chave). Veja Autenticação para detalhes.

Escopos necessários

read para GET; write para POST/PATCH/DELETE.

URL canônica — sempre use freteflow.log.br

Todos os exemplos usam https://freteflow.log.br. Não envie POST para domínios alternativos que façam redirect 302: a maioria dos clientes HTTP (incluindo curl sem -L --post302, fetch erequests) transforma o POST em GET ao seguir o redirect, e a operação falha silenciosamente devolvendo a lista de operações com status 200.

Ambientes (Homologação × Produção)

Cada operação carrega um campo environment com valores "homolog" (sandbox de testes — não gera CIOT válido na ANTT) ou "producao" (emissão oficial). O ambiente é definido na criação e é imutável: todos os eventos pós-emissão (validar, emitir, cancelar, encerrar, retificar) usam sempre o ambiente registrado na operação, mesmo que o ambiente padrão da empresa mude depois.

Quando environment não é informado no POST /operations, a operação herda o ambiente padrão configurado pelo administrador da empresa. Para operar nos dois ambientes em paralelo (por exemplo, treinar usuários em homologação enquanto outros já operam em produção), basta enviar environment explicitamente em cada criação. As credenciais de cada ambiente são configuradas separadamente pelo administrador.

Credenciais de produção

Ao chamar /emit em uma operação criada em producao sem que a empresa tenha credenciais de produção configuradas, a API responde 422 com mensagem de credencial ausente. Configure ambos os ambientes antes do go-live.

POST/api/public/v1/ciot/operationsAuth: API key

Cria a operação completa. Body principal:

Campo	Tipo	Descrição
external_id	string	Identificador no seu sistema (vai para os logs).
environment	enum	homolog \| producao. Default: ambiente padrão da empresa. Imutável após criação.
tipo_operacaoreq	enum	lotacao \| fracionada
freight_id	uuid	Vincular a um frete já existente no FreteFlow.
contratado_cpf_cnpjreq	string	CNPJ/CPF do transportador.
contratado_rntrcreq	string	RNTRC do transportador.
contratado_tipo	enum	TAC \| ETC \| CTC. Opcional — derivado automaticamente do cadastro do parceiro (categoria RNTRC). Ignorado se houver parceiro cadastrado com categoria definida.
contratado_nome	string	Razão social do transportador (opcional, será buscada na consulta).
origem	object	{tipo, uf, codigo_municipio \| cep \| lat+lng, ...}
destino	object	Mesma estrutura de origem. tipo deve ser igual ao da origem.
distancia_km	number	Calculado automaticamente se omitido (em alguns casos).
codigo_natureza_carga	string	Tabela ANTT de natureza da carga.
codigo_tipo_carga	number	Tabela ANTT de tipo da carga.
peso_carga	number	Em kg.
valor_frete	number	Valor total do frete.
destinatario_cpf_cnpjreq	string	CPF/CNPJ do destinatário da carga. Obrigatório — exigido pela validação DS01. Aceita formatado ou só dígitos.
destinatario_nome	string	Razão social ou nome do destinatário.
bank_code	string	Banco do recebedor (obrigatório para TAC autônomo / ETC equiparado a TAC).
agency	string	Agência do recebedor (obrigatório para TAC / equiparado).
account_number	string	Conta do recebedor (obrigatório para TAC / equiparado).
cpf_cnpj_owner	string	CPF/CNPJ do titular da conta. Para TAC autônomo e ETC equiparado a TAC, deve ser igual ao contratado_cpf_cnpj (regras TR05/PRV03).
data_declaracao	ISO date	Data da declaração (default: hoje).
viagem_inicio	ISO date\|datetime	Data/hora de início da viagem. Obrigatório pela política de alguns provedores de emissão — recomendado sempre informar.
viagem_fim	ISO date\|datetime	Data/hora prevista de conclusão da viagem. Obrigatório pela política de alguns provedores de emissão — recomendado sempre informar.
chave_pix	string	Chave PIX padrão da operação (CPF, CNPJ, e-mail, celular ou aleatória). Aplicada quando os itens de payments[] não trazem codigo_pagamento próprio.
tipo_pagamento	enum	pix \| conta_corrente \| cartao_pre_pago_ip \| conta_poupanca \| conta_pagamento \| outros
indicador_pagamento	enum	vista \| prazo
contingencia	boolean	Se true, exige justificativa_contingencia.
codigo_ciot	string (12 dígitos)	Use APENAS para importar um CIOT já gerado em contingência em outro sistema. Quando informado, a operação é criada como rascunho com contingencia=true e auto_validate/auto_emit são ignorados — você revisa e valida manualmente. Duplicata na mesma empresa retorna 409.
data_emissao_original	ISO date	Data em que o CIOT foi originalmente emitido no sistema externo. Use junto com codigo_ciot.
contratantesreq	array	Mín. 1. Veja estrutura abaixo.
vehiclesreq	array	Mín. 1 veículo. Veja estrutura abaixo.
payments	array	Itens de pagamento (adiantamento/saldo/parcela/pedagio/ajuste).
documents	array	NF-e, CT-e ou MDF-e vinculados.
auto_validate	boolean	Default true. Roda validações após criar.
auto_emit	boolean	Default false. Se true, emite na ANTT após validar.

Origem / Destino

O tipo deve ser igual nos dois lados (municipio, cep ou latlng). Conforme o tipo, envie:

municipio: uf + codigo_municipio (IBGE) + municipio_nome
cep: cep (8 dígitos)
latlng: lat + lng + endereco_descricao

Contratantes

Campo	Tipo	Descrição
cpf_cnpjreq	string	Somente dígitos.
nomereq	string
rntrc	string	Quando contratante é transportador.
papel	enum	principal \| solidario \| intermediario (default: 1º = principal).
valor_frete	number
percentual	number	0–100.
observacoes	string

Veículos

Campo	Tipo	Descrição
platereq	string	Placa Mercosul ou padrão antigo.
vehicle_kindreq	enum	automotor \| implemento \| cavalo_trator
rntrc	string
axles	number
own_fleet	boolean	Frota própria do contratado.

Pagamentos

Campo	Tipo	Descrição
kindreq	enum	adiantamento \| saldo \| parcela \| pedagio \| ajuste
contratante_index	number	Índice 0-based em contratantes[]. Alternativa a contratante_cpf_cnpj.
contratante_cpf_cnpj	string	Resolução pelo CPF/CNPJ do contratante.
tipo_pagamentoreq	enum
indicador_pagamentoreq	enum	vista \| prazo
amountreq	number
due_datereq	ISO date
banco	string	Código do banco (3 dígitos). Obrigatório para TAC autônomo e ETC equiparado a TAC quando tipo_pagamento ≠ pix.
agencia	string	Número da agência (somente dígitos).
conta	string	Número da conta corrente.
titular_cpf_cnpj	string	CPF/CNPJ do titular da conta. Para TAC autônomo e ETC equiparado a TAC, deve ser igual ao contratado_cpf_cnpj (regra PRV03).
codigo_pagamento	string	Chave PIX do recebedor desta parcela (CPF, CNPJ, e-mail, celular ou aleatória) quando tipo_pagamento=pix. Sobrescreve a chave_pix raiz da operação. Para cartão pré-pago, o código do cartão.

PIX: chave_pix (raiz) vs. codigo_pagamento (por parcela)

O campo chave_pix no corpo principal define a chave PIX padrão da operação. Já o codigo_pagamento dentro de cada item de payments[] permite uma chave distinta por parcela (por exemplo, adiantamento numa chave e saldo em outra).

Quando o pagamento for PIX, recomenda-se preencher os dois: a raiz cobre o caso geral e os itens sobrescrevem quando necessário. Sem nenhum dos dois, alguns provedores recusam a emissão.

Alternativa: dados bancários por parcela

Quando bank_code, agency, account_number e cpf_cnpj_owner não vierem na raiz da operação, o serviço usa automaticamente os valores da primeira parcela de payments[] que tiver banco, agencia, conta ou titular_cpf_cnpj preenchidos. Isso permite informar tudo dentro do array de pagamentos, sem repetir na raiz.

A regra PRV03 continua valendo: para TAC autônomo e ETC equiparado a TAC, o titular_cpf_cnpj da parcela deve ser igual ao contratado_cpf_cnpj.

json

{
  "payments": [
    {
      "kind": "saldo",
      "tipo_pagamento": "conta_corrente",
      "indicador_pagamento": "prazo",
      "amount": 5000.00,
      "due_date": "2026-06-05",
      "banco": "237",
      "agencia": "0001",
      "conta": "12345-6",
      "titular_cpf_cnpj": "12345678901"
    }
  ]
}

Documentos fiscais

Campo	Tipo	Descrição
kindreq	enum	nfe \| cte \| mdfe
access_key	string	Chave de 44 dígitos.
number / series	string
emitter_cnpj / emitter_name	string
freight_value	number	Valor do frete vinculado a este documento. Para evitar o warning DC04, use o mesmo valor de valor_frete da operação — este campo representa o frete, não o valor da mercadoria.
cargo_weight_kg	number	Peso bruto declarado no documento.

Exemplo completo

bash

curl -X POST https://freteflow.log.br/api/public/v1/ciot/operations \
  -H "X-FreteFlow-Key: ff_pub_xxx.yyy" \
  -H "X-FreteFlow-Signature: sha256=<hmac-sha256(body, secret)>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "OP-2025-0001",
    "tipo_operacao": "lotacao",
    "contratado_tipo": "ETC",
    "contratado_cpf_cnpj": "12345678000190",
    "contratado_rntrc": "12345678",
    "origem":  { "tipo": "municipio", "uf": "SP", "codigo_municipio": "3550308", "municipio_nome": "São Paulo" },
    "destino": { "tipo": "municipio", "uf": "RJ", "codigo_municipio": "3304557", "municipio_nome": "Rio de Janeiro" },
    "valor_frete": 4500.00,
    "peso_carga": 12000,
    "codigo_natureza_carga": "1001",
    "viagem_inicio": "2026-05-20",
    "viagem_fim": "2026-06-05",
    "destinatario_cpf_cnpj": "11222333000181",
    "destinatario_nome": "Destinatário da Carga Ltda",
    "tipo_pagamento": "pix",
    "indicador_pagamento": "vista",
    "chave_pix": "transportador@email.com",
    "contratantes": [
      { "cpf_cnpj": "98765432000111", "nome": "Embarcador Ltda", "papel": "principal", "valor_frete": 4500.00 }
    ],
    "vehicles": [
      { "plate": "ABC1D23", "vehicle_kind": "cavalo_trator", "axles": 6, "rntrc": "12345678" }
    ],
    "payments": [
      { "kind": "adiantamento", "tipo_pagamento": "pix", "indicador_pagamento": "vista",
        "amount": 1500.00, "due_date": "2026-05-20" },
      { "kind": "saldo", "tipo_pagamento": "pix", "indicador_pagamento": "prazo",
        "amount": 3000.00, "due_date": "2026-06-05" }
    ],
    "documents": [
      { "kind": "cte", "access_key": "35260512345678000190570010000000011000000017",
        "freight_value": 4500.00, "cargo_weight_kg": 12000 }
    ],
    "auto_validate": true,
    "auto_emit": true
  }'

Resposta

json

{
  "data": { "id": "0c3e...", "code": "CIOT-0123", "status": "emitido", "codigo_ciot": "...", "protocolo": "..." },
  "validation": { "items": [...], "summary": { "ok": true, "blockers": 0, "warnings": 0 } },
  "emission":   { "ok": true, "codigo_ciot": "...", "protocolo": "...", "mensagem": "..." }
}

Falha na validação

Se auto_emit=true e a validação não passar, a operação fica em status com_divergencia e emission.ok=false com reason="validation_blocked". Corrija via PATCH e chame /emit de novo.

Importar CIOT já emitido em contingência

Use este fluxo quando o CIOT foi gerado fora do FreteFlow (sistema de contingência interno, outro emissor, etc.) e você só precisa cadastrá-lo aqui para revisão e acompanhamento. Envie o mesmo payload de criação acrescido de codigo_ciot (12 dígitos). Quando esse campo está presente:

A operação é criada com status="rascunho" e contingencia=true.
auto_validate e auto_emit são ignorados — nada é enviado ao órgão emissor.
O número informado é gravado em codigo_ciot para revisão manual posterior.
Se já existir uma operação com o mesmo codigo_ciot nesta empresa, a resposta é 409 Conflict.

Exemplo:

bash

curl -X POST https://freteflow.log.br/api/public/v1/ciot/operations \
  -H "X-API-Key: $FRETEFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "codigo_ciot": "123456789012",
    "data_emissao_original": "2026-05-15",
    "justificativa_contingencia": "Sistema interno fora do ar em 15/05/2026",
    "tipo_operacao": "lotacao",
    "contratado_tipo": "ETC",
    "contratado_cpf_cnpj": "12345678000190",
    "contratado_rntrc": "12345678",
    "contratantes": [
      { "cpf_cnpj": "98765432000100", "nome": "Indústria XYZ", "papel": "principal" }
    ],
    "vehicles": [{ "plate": "ABC1D23", "vehicle_kind": "automotor" }],
    "origem":  { "tipo": "municipio", "uf": "SP", "codigo_municipio": "3550308", "municipio_nome": "São Paulo" },
    "destino": { "tipo": "municipio", "uf": "RJ", "codigo_municipio": "3304557", "municipio_nome": "Rio de Janeiro" },
    "peso_carga": 12000,
    "valor_frete": 8500.00
  }'

json

{
  "mode": "imported",
  "data": { "id": "0c3e...", "status": "rascunho", "contingencia": true, "codigo_ciot": "123456789012" },
  "validation": null,
  "emission": null
}

Depois da importação, o registro fica disponível em /ciot para revisão. Você pode editar campos faltantes via PATCH e, quando estiver pronto, validar manualmente — sem reenviar o CIOT ao órgão emissor, pois ele já existe.

ETC subcontratada (emissão em nome próprio)

Quando o transportador contratado é uma ETC diferente da sua empresa, a regulação exige que o CIOT seja emitido em nome próprio da ETC contratada — a sua empresa figura apenas como contratante. O FreteFlow trata isso automaticamente:

A ETC contratada precisa estar cadastrada como empresa neste sistema (CNPJ + Inscrição Estadual) e ter as credenciais CIOT configuradas para o ambiente da operação em /admin/integrations → CIOT — Por empresa.
Na criação da operação, basta informar contratado_tipo="ETC" e o contratado_cpf_cnpj da ETC contratada. O sistema resolve a empresa emissora pelo CNPJ e usa as credenciais dela na chamada ao órgão emissor.
Se a ETC contratada não estiver cadastrada ou estiver sem credenciais no ambiente da operação, a validação retorna um bloqueador (EMISSOR_ETC_NAO_CADASTRADA ou EMISSOR_ETC_SEM_CREDENCIAIS) antes mesmo de tentar emitir.
O PDF final usa o branding (logo, cores) da ETC emissora, não do contratante.

Frota própria e TAC seguem inalterados

Em Frota Própria e em contratação de TAC (autônomo, agregado ou equiparado), o emissor continua sendo a sua própria empresa — a regulação permite que o contratante emita nesses casos.

Exemplos por modalidade

As regras de Frota Própria, TAC autônomo, ETC contratado e ETC equiparado a TAC são validadas automaticamente pelo FreteFlow antes da emissão. O tipo do contratado (TAC, ETC, CTC ou ETC equiparado) é derivado do cadastro do parceiro em/parceiros (categoria RNTRC) — basta enviar o contratado_cpf_cnpj que o restante é resolvido no servidor. Quando a operação envolve transportador autônomo, os dados bancários do recebedor permanecem obrigatórios.

1) Frota própria

Quando a empresa contratante e o contratado são a mesma pessoa jurídica e o transporte é feito com veículos próprios. Os dados bancários do recebedor são dispensados (não há pagamento a terceiro).

json

{
  "external_id": "OP-FP-0001",
  "tipo_operacao": "lotacao",
  "contratado_tipo": "ETC",
  "contratado_cpf_cnpj": "12345678000190",
  "contratado_rntrc": "12345678",
  "origem":  { "tipo": "municipio", "uf": "SP", "codigo_municipio": "3550308" },
  "destino": { "tipo": "municipio", "uf": "RJ", "codigo_municipio": "3304557" },
  "valor_frete": 6000.00,
  "peso_carga": 18000,
  "codigo_natureza_carga": "1001",
  "viagem_inicio": "2026-05-20",
  "viagem_fim": "2026-06-05",
  "destinatario_cpf_cnpj": "11222333000181",
  "destinatario_nome": "Filial de Destino Ltda",
  "tipo_pagamento": "pix",
  "indicador_pagamento": "vista",
  "contratantes": [
    { "cpf_cnpj": "12345678000190", "nome": "Minha Empresa Ltda", "papel": "principal", "valor_frete": 6000.00 }
  ],
  "vehicles": [
    { "plate": "ABC1D23", "vehicle_kind": "cavalo_trator", "axles": 6, "rntrc": "12345678", "own_fleet": true }
  ]
}

2) TAC autônomo

Contratado pessoa física com RNTRC TAC. Dados bancários do recebedor são obrigatórios e o titular da conta deve ser o próprio contratado. Adiantamento limitado a 30% do frete.

json

{
  "external_id": "OP-TAC-0001",
  "tipo_operacao": "lotacao",
  "contratado_tipo": "TAC",
  "contratado_cpf_cnpj": "12345678901",
  "contratado_rntrc": "87654321",
  "origem":  { "tipo": "municipio", "uf": "SP", "codigo_municipio": "3550308" },
  "destino": { "tipo": "municipio", "uf": "MG", "codigo_municipio": "3106200" },
  "valor_frete": 5000.00,
  "peso_carga": 15000,
  "codigo_natureza_carga": "1001",
  "viagem_inicio": "2026-05-20",
  "viagem_fim": "2026-06-05",
  "destinatario_cpf_cnpj": "11222333000181",
  "destinatario_nome": "Destinatário da Carga Ltda",
  "tipo_pagamento": "pix",
  "indicador_pagamento": "vista",
  "bank_code": "001",
  "agency": "1234",
  "account_number": "56789-0",
  "cpf_cnpj_owner": "12345678901",
  "contratantes": [
    { "cpf_cnpj": "98765432000111", "nome": "Embarcador Ltda", "papel": "principal", "valor_frete": 5000.00 }
  ],
  "vehicles": [
    { "plate": "ABC1D23", "vehicle_kind": "cavalo_trator", "axles": 6, "rntrc": "87654321" }
  ],
  "payments": [
    { "kind": "adiantamento", "tipo_pagamento": "pix", "indicador_pagamento": "vista",
      "amount": 1500.00, "due_date": "2026-05-20" },
    { "kind": "saldo", "tipo_pagamento": "pix", "indicador_pagamento": "prazo",
      "amount": 3500.00, "due_date": "2026-06-05" }
  ]
}

3) ETC Equiparado a TAC

Pessoa jurídica transportadora equiparada a TAC para fins de pagamento. Aplica todas as regras de TAC (banco obrigatório, titular = contratado, adiantamento ≤ 30%), mas mantém o tipo de viagem padrão. Cadastre o parceiro com categoria TAC_EQUIPARADO em /parceiros — não é necessário enviar nenhum flag no payload.

json

{
  "external_id": "OP-ETC-EQ-0001",
  "tipo_operacao": "lotacao",
  "contratado_cpf_cnpj": "12345678000190",
  "contratado_rntrc": "12345678",
  "origem":  { "tipo": "municipio", "uf": "SP", "codigo_municipio": "3550308" },
  "destino": { "tipo": "municipio", "uf": "RJ", "codigo_municipio": "3304557" },
  "valor_frete": 8000.00,
  "peso_carga": 20000,
  "codigo_natureza_carga": "1001",
  "viagem_inicio": "2026-05-20",
  "viagem_fim": "2026-06-05",
  "destinatario_cpf_cnpj": "11222333000181",
  "destinatario_nome": "Destinatário da Carga Ltda",
  "tipo_pagamento": "pix",
  "indicador_pagamento": "vista",
  "bank_code": "237",
  "agency": "0001",
  "account_number": "12345-6",
  "cpf_cnpj_owner": "12345678000190",
  "contratantes": [
    { "cpf_cnpj": "98765432000111", "nome": "Embarcador Ltda", "papel": "principal", "valor_frete": 8000.00 }
  ],
  "vehicles": [
    { "plate": "ABC1D23", "vehicle_kind": "cavalo_trator", "axles": 6, "rntrc": "12345678" }
  ],
  "payments": [
    { "kind": "adiantamento", "tipo_pagamento": "pix", "indicador_pagamento": "vista",
      "amount": 2400.00, "due_date": "2026-05-20" },
    { "kind": "saldo", "tipo_pagamento": "pix", "indicador_pagamento": "prazo",
      "amount": 5600.00, "due_date": "2026-06-05" }
  ]
}

Códigos de validação relevantes

Campo	Tipo	Descrição
TR05	blocker	Titular da conta de pagamento deve ser o próprio contratado (TAC ou equiparado).
TR06	blocker	equiparado_tac=true exige contratado_tipo='ETC'.
PG13	blocker	Pagamento com titular diferente do contratado em TAC ou equiparado.
PG14	blocker	Forma de pagamento 'outros' não permitida para TAC ou equiparado.
PG17	blocker	Adiantamento acima de 30% do valor do frete (TAC ou equiparado).
PRV02	blocker	Para TAC ou ETC equiparado: quando o pagamento for bancário (conta corrente, poupança, conta pagamento ou cartão pré-pago), banco/agência/conta são obrigatórios (na raiz ou em qualquer parcela). Quando for PIX, informe chave_pix na raiz da operação ou codigo_pagamento em cada parcela.
PRV03	blocker	cpf_cnpj_owner deve coincidir com o contratado.
PRV04	blocker	codigo_natureza_carga é obrigatório.

GET/api/public/v1/ciot/operationsAuth: API key

Lista operações da empresa. Query params: status, tipo_operacao, from, to, limit (máx 200).

GET/api/public/v1/ciot/operations/{id}Auth: API key

Retorna a operação completa, incluindo contratantes, veículos, pagamentos, documentos e últimos 50 eventos.

PATCH/api/public/v1/ciot/operations/{id}Auth: API key

Atualiza campos da operação (apenas em status diferente de emitido/encerrado/cancelado). Os campos id, company_id, codigo_ciot, codigo_verificador, protocolo e status são protegidos.

DELETE/api/public/v1/ciot/operations/{id}Auth: API key

Cancela uma operação ainda não emitida (rascunho, validado, com_divergencia, pronto_emissao). Para operações já emitidas, use o endpoint /cancel abaixo.

POST/api/public/v1/ciot/operations/{id}/validateAuth: API key

Roda novamente as validações declarativas. Atualiza status conforme o resultado.

POST/api/public/v1/ciot/operations/{id}/emitAuth: API key

Valida e emite o CIOT. Resposta 200 em sucesso, 422 quando bloqueado por validação ou rejeitado.

Eventos pós-emissão

Após o CIOT ser emitido (status = "emitido") a operação aceita três fluxos de eventos: retificação (corrige dados sem cancelar), cancelamento (anula a operação) e encerramento (fecha após a conclusão da viagem). Todos consomem o codigo_ciot existente e geram um evento na timeline da operação.

POST/api/public/v1/ciot/operations/{id}/retificarAuth: API key

Retifica uma operação já emitida, mantendo o mesmo codigo_ciot. Use antes do encerramento, quando algum dado precisa ser corrigido (valor do frete, datas da viagem, parcelas de pagamento, documentos fiscais etc.) sem cancelar o CIOT.

Disponibilidade restrita por fluxo de integração

A retificação por API hoje está disponível apenas para empresas configuradas no fluxo de integração legacy. Empresas em outros fluxos recebem 422 com reason: "not_supported" — nesses casos o procedimento recomendado é cancelar o CIOT atual e emitir um novo com os dados corrigidos. Consulte o administrador da plataforma para confirmar qual fluxo de integração está ativo na sua empresa.

Campo	Tipo	Descrição
valor_frete	number	Novo valor total do frete.
peso_carga	number	Novo peso da carga (kg).
data_declaracao	ISO date	Nova data da declaração.
viagem_inicio	ISO date\|datetime	Nova data/hora de início da viagem.
viagem_fim	ISO date\|datetime	Nova data/hora prevista de conclusão.
payments	array	Substitui os itens de pagamento (mesma estrutura do POST inicial).
documents	array	Substitui os documentos fiscais (mesma estrutura do POST inicial).
observacoes	string	Justificativa da retificação (até 500 caracteres).

bash

curl -X POST https://freteflow.log.br/api/public/v1/ciot/operations/0c3e.../retificar \
  -H "X-FreteFlow-Key: ff_pub_xxx.yyy" \
  -H "X-FreteFlow-Signature: sha256=<hmac>" \
  -H "Content-Type: application/json" \
  -d '{
    "valor_frete": 4800.00,
    "viagem_fim": "2026-06-10",
    "observacoes": "Ajuste de valor e prazo após renegociação com o embarcador"
  }'

json

{ "ok": true, "mensagem": "Retificação aceita" }

Resposta 200 em sucesso. 422 quando a operação não está em emitido (reason: "invalid_status"), quando foi rejeitada pelo órgão emissor (reason: "rejected") ou quando o fluxo de integração ativo não suporta retificação (reason: "not_supported"). 404 se a operação não pertencer à empresa.

POST/api/public/v1/ciot/operations/{id}/cancelAuth: API key

Cancela uma operação já emitida. Body:

Campo	Tipo	Descrição
motivoreq	string	Justificativa do cancelamento (3 a 500 caracteres). Vai para o registro de eventos e para o órgão emissor.

bash

curl -X POST https://freteflow.log.br/api/public/v1/ciot/operations/0c3e.../cancel \
  -H "X-FreteFlow-Key: ff_pub_xxx.yyy" \
  -H "X-FreteFlow-Signature: sha256=<hmac>" \
  -H "Content-Type: application/json" \
  -d '{ "motivo": "Cliente cancelou a carga antes do embarque" }'

json

{ "ok": true, "mensagem": "Operação cancelada com sucesso" }

Resposta 200 em sucesso. 422 quando a operação não está em status emitido (reason: "invalid_status") ou foi rejeitada (reason: "rejected"). 404 se não pertencer à empresa.

POST/api/public/v1/ciot/operations/{id}/encerrarAuth: API key

Encerra uma operação já emitida após a conclusão da viagem. Body:

Campo	Tipo	Descrição
peso_carga_finalreq	number	Peso efetivamente transportado (kg).
distancia	number	Distância percorrida (km). Se omitido, usa o valor da operação.
quantidade_viagens	number	Quantidade de viagens realizadas. Default: 1.
data_encerramento	ISO date	Data efetiva do encerramento. Default: agora.
observacoes	string	Observações livres (até 500 caracteres).

bash

curl -X POST https://freteflow.log.br/api/public/v1/ciot/operations/0c3e.../encerrar \
  -H "X-FreteFlow-Key: ff_pub_xxx.yyy" \
  -H "X-FreteFlow-Signature: sha256=<hmac>" \
  -H "Content-Type: application/json" \
  -d '{
    "peso_carga_final": 11850,
    "distancia": 432,
    "quantidade_viagens": 1,
    "data_encerramento": "2026-06-12",
    "observacoes": "Entrega confirmada pelo destinatário"
  }'

json

{ "ok": true, "mensagem": "Operação encerrada com sucesso" }

Mesmas regras de status code do /cancel. Após o encerramento a operação fica em status = "encerrado" e não aceita mais alterações.

Ações irreversíveis

Cancelamento e encerramento são finais. Não há endpoint para reabrir uma operação. Em caso de erro, será necessário emitir uma nova operação.

Exportação em PDF

Operações em status emitido, encerrado ou cancelado podem ser exportadas em PDF, individualmente ou em lote (até 50 por chamada). O PDF traz identificação da operação, transportador, contratantes, rota, veículos, documentos fiscais, pagamentos e linha do tempo de eventos. Operações em environment = "homolog" recebem uma marca d'água "HOMOLOGAÇÃO". A identidade visual (logo, cores, razão social, rodapé) é configurável por empresa no painel administrativo.

GET/api/public/v1/ciot/operations/{id}/pdfAuth: API key

Retorna o PDF da operação (Content-Type: application/pdf). Erros:404 quando a operação não pertence à empresa da chave; 409 quando o status não permite exportação.

bash

curl -L https://freteflow.log.br/api/public/v1/ciot/operations/0c3e.../pdf \
  -H "X-FreteFlow-Key: prefix.secret" \
  -H "X-FreteFlow-Signature: <hmac>" \
  -o ciot.pdf

GET/api/public/v1/ciot/operations/pdfAuth: API key

Exporta múltiplas operações em um único application/zip, com um PDF por arquivo. Limite de 50 operações por chamada. Aceita os seguintes filtros (query string):

Campo	Tipo	Descrição
ids	string	Lista de IDs separados por vírgula. Quando informado, ignora os demais filtros.
status	string	Filtra por status (emitido, encerrado, cancelado). Aceita lista separada por vírgula.
environment	string	homolog ou producao. Default: ambos.
from	ISO date	Data inicial (created_at).
to	ISO date	Data final (created_at).

bash

curl -L "https://freteflow.log.br/api/public/v1/ciot/operations/pdf?status=emitido&from=2026-05-01&to=2026-05-31" \
  -H "X-FreteFlow-Key: prefix.secret" \
  -H "X-FreteFlow-Signature: <hmac>" \
  -o ciot-lote.zip

Marca d'água de homologação

PDFs gerados a partir de operações em environment = "homolog" sempre exibem a marca "HOMOLOGAÇÃO" — útil para diferenciar visualmente documentos de teste dos de produção.

Códigos de status

rascunho → recém-criado, ainda não validado
validado / com_divergencia / pronto_emissao → resultado da validação
emitindo → emissão em andamento
emitido → CIOT gerado com sucesso
rejeitado → ANTT rejeitou; veja mensagem_antt
cancelado / encerrado → estados finais