API: Frete Mínimo

Receba os parâmetros de uma operação, faça a consulta de frete mínimo e devolva o resultado já normalizado, com cache automático e log completo de cada chamada.

Visão geral

Cada chamada é registrada em /frete-minimo-api com latência, origem (cache ou consulta nova) e payload. Idempotência opcional via request_id: chamadas repetidas com o mesmo identificador nas últimas 24h devolvem o mesmo resultado sem nova consulta.

Autenticação

Use uma API key da empresa (Integrações → API Keys) com escopo read. Toda requisição precisa de X-FreteFlow-Key e X-FreteFlow-Signature (HMAC-SHA256 do corpo, em hex). Veja a página principal da API para o passo a passo da assinatura.

POST/api/public/v1/freight-min/lookupAuth: API key

Body

Campo	Tipo	Descrição
tipo_cargareq	integer	Código do tipo de carga (1–20). Veja /cargo-types.
eixosreq	integer	Quantidade de eixos (2–9).
distanciareq	number	Distância em km (>0, ≤20000).
composicaoreq	boolean	Composição de veículos.
alto_desempenhoreq	boolean	Veículo de alto desempenho.
retorno_vazioreq	boolean	Considerar retorno vazio.
request_id	string	Identificador para idempotência (8–128 chars). Recomendado UUID.

Exemplo

bash

curl -X POST https://freteflow.fr.com.br/api/public/v1/freight-min/lookup \
  -H "Content-Type: application/json" \
  -H "X-FreteFlow-Key: ff_pub_xxx.yyy" \
  -H "X-FreteFlow-Signature: <hmac-sha256-do-body>" \
  -d '{
    "tipo_carga": 5,
    "eixos": 6,
    "distancia": 1200.5,
    "composicao": false,
    "alto_desempenho": true,
    "retorno_vazio": false,
    "request_id": "8f1c7e0c-..."
  }'

Resposta — sucesso

json

{
  "ok": true,
  "request_id": "8f1c7e0c-...",
  "source": "live",
  "consulted_at": "2026-05-15T17:59:00.000Z",
  "valor_frete_total": 4321.00,
  "valor_ida": 4000.00,
  "valor_retorno_vazio": 321.00,
  "ccd": null,
  "cc": null,
  "operacao_transporte": "...",
  "status_consulta": "..."
}

Resposta — erro

Campo	Tipo	Descrição
indisponivel	503	Integração ou credenciais da empresa não configuradas.
upstream_error	502	Falha na consulta ao serviço externo de dados de frete.
invalid_input	422	Body inválido contra o schema.

Mesmo em caso de erro, a chamada é registrada com status: "error" e o error_code correspondente, ficando disponível em /frete-minimo-apipara auditoria.

GET/api/public/v1/freight-min/requestsAuth: API key

Lista paginada das requisições da empresa. Query params:

Campo	Tipo	Descrição
status	ok \| error	Filtra por status.
source	cache \| live \| error	Filtra pela origem do resultado.
from	ISO datetime	Limite inferior de data.
to	ISO datetime	Limite superior de data.
cursor	ISO datetime	Para paginação (passe o valor de next_cursor da resposta anterior).
limit	integer	1–200, padrão 50.

GET/api/public/v1/freight-min/requests/{id}Auth: API key

Detalhe completo de uma requisição: inputs, resultado, latência, IP e User-Agent.

GET/api/public/v1/freight-min/cargo-typesAuth: API key

Lista os códigos de tipo de carga aceitos no campo tipo_carga.