Cotação de frete via API das transportadoras: preço e prazo em tempo real

O que é uma cotação de frete integrada

É o processo em que o sistema da empresa envia os dados de uma entrega para uma ou mais transportadoras e recebe de volta as opções disponíveis, com valor, prazo e tipo de serviço. A cotação pode acontecer no checkout do e-commerce, na proposta do vendedor, no portal B2B ou automaticamente quando um pedido é aprovado.

O sistema envia	A transportadora devolve
CEP de origem e de destino	Valor total do frete
Peso real e dimensões de cada volume	Prazo estimado de entrega
Valor da mercadoria (base para seguro e GRIS)	Tipo de serviço (expresso, econômico, dedicado)
CNPJ ou CPF do destinatário	Taxas adicionais aplicadas
Tipo de produto e restrições	Disponibilidade para a região
Data prevista de coleta	Validade da cotação e mensagens de alerta

Por que não depender apenas de tabela fixa

Tabelas de frete ainda têm seu lugar, mas raramente acompanham todas as variáveis do contrato. Basta uma taxa de restrição de trânsito em uma cidade, uma mudança na faixa de peso ou um reajuste de pedágio para o valor da tabela se afastar do que vem na fatura. No transporte rodoviário, o preço final costuma ser a soma de vários componentes:

Componente	O que representa
Frete peso	Valor pela faixa de peso, considerando o maior entre peso real e peso cubado
Frete valor (ad valorem)	Percentual sobre o valor da mercadoria transportada
GRIS	Percentual para cobrir o gerenciamento de risco da carga
Pedágio	Cobrado por fração de peso ou por documento, conforme o contrato
TDE e TRT	Taxas de dificuldade de entrega e de restrição de trânsito em determinadas regiões
Taxa de despacho	Valor fixo por documento ou embarque
ICMS	Imposto sobre o serviço de transporte, conforme as UFs envolvidas

Quando a cotação é feita pela API, quem calcula é a própria transportadora, com as regras do contrato vigente. A diferença entre o cotado e o cobrado diminui, e a equipe para de refazer contas em planilha.

Cubagem: o detalhe que mais gera divergência

Volumes leves e grandes são cobrados pelo peso cubado, e não pelo peso da balança. No rodoviário fracionado, um fator comum é 300 kg por metro cúbico, mas ele varia por transportadora e por contrato.

Caixa: 0,50 m x 0,40 m x 0,40 m = 0,08 m³
Peso cubado: 0,08 m³ x 300 kg/m³ = 24 kg
Peso real: 10 kg
Peso considerado no frete: 24 kg (o maior dos dois)

Por isso o cadastro de dimensões no ERP precisa ser confiável. Sem medidas corretas por produto ou por embalagem, nenhuma integração consegue cotar com precisão.

Como funciona o fluxo técnico

1. O sistema recebe os dados do pedido ou da simulação.
2. Valida CEPs, peso, dimensões, quantidade de volumes e valor declarado.
3. Seleciona as transportadoras elegíveis para aquela origem, destino e tipo de carga.
4. Envia as requisições em paralelo, cada uma com seu tempo limite.
5. Trata erros e retornos incompletos de cada transportadora, sem derrubar as demais.
6. Normaliza as respostas em um formato único.
7. Aplica as regras comerciais da empresa.
8. Exibe as melhores opções e grava a cotação para auditoria.

A normalização é o coração do processo. Cada transportadora usa nomes, unidades e estruturas diferentes. Antes de comparar qualquer coisa, tudo precisa virar o mesmo formato:

{
  "cotacao_id": "COT-2026-000431",
  "transportadora": "transportadora-a",
  "servico": "rodoviario-economico",
  "valor_frete": 187.40,
  "prazo_dias_uteis": 4,
  "componentes": { "frete_peso": 121.00, "ad_valorem": 18.90, "gris": 9.45, "pedagio": 12.80, "outros": 25.25 },
  "peso_considerado_kg": 24.0,
  "valido_ate": "2026-10-08T23:59:00-03:00",
  "retorno_original_id": "log-98f1c2"
}

Consultas em paralelo e tempo de resposta

No checkout, cada segundo conta. Consultar cinco transportadoras uma depois da outra pode levar mais tempo do que o cliente está disposto a esperar. Algumas práticas resolvem a maior parte dos casos:

• Consultar as transportadoras em paralelo, com tempo limite individual de poucos segundos.
• Exibir as opções que responderam a tempo, em vez de esperar a mais lenta.
• Usar cache de curta duração para combinações repetidas de CEP, peso e valor.
• Pré-filtrar transportadoras que não atendem a região ou o tipo de carga.
• Registrar o tempo de resposta de cada API para identificar gargalos.

Critérios para escolher a melhor opção

Nem sempre o menor preço é a melhor escolha. A regra de decisão precisa refletir a estratégia da empresa, e pode combinar vários critérios com pesos diferentes:

Critério	Quando pesa mais
Menor custo	Produtos de margem apertada e clientes sensíveis a preço
Menor prazo	Reposição urgente, perecíveis, clientes estratégicos
Histórico de pontualidade	Regiões onde a transportadora mais barata costuma atrasar
Transportadora preferencial	Contratos negociados, clientes que exigem determinado parceiro
Restrições de carga	Peso, volume, produtos frágeis ou controlados
Margem mínima da venda	Quando o frete subsidiado pode tornar a venda deficitária

Em operações mais maduras, a cotação em tempo real é cruzada com o histórico de entregas. Uma transportadora barata, mas com alto índice de atraso em determinada região, recebe uma pontuação menor e deixa de ser a escolha automática.

Onde a cotação aparece na empresa

• E-commerce: no carrinho e no checkout, influenciando diretamente a conversão.
• Comercial: o vendedor monta a proposta com o custo logístico real, sem pedir cotação por e-mail.
• Portal B2B: o próprio cliente simula condições antes de fechar o pedido.
• ERP e expedição: o pedido aprovado é cotado automaticamente e segue para a transportadora escolhida.

Tratamento de falhas e indisponibilidade

APIs externas falham. O que diferencia uma integração profissional é o comportamento previsível quando isso acontece.

• Tempo limite por consulta e retentativa controlada apenas quando faz sentido.
• Falha de uma transportadora nunca derruba a cotação inteira.
• Tabela interna como alternativa, quando o contrato permitir.
• Mensagem clara ao usuário quando uma opção não está disponível.
• Log de requisição e resposta para o suporte diagnosticar o problema.
• Alerta para falhas recorrentes da mesma transportadora.

Regras comerciais e auditoria

Depois que a API devolve o valor, a empresa ainda pode aplicar suas regras: frete grátis acima de determinado valor, subsídio parcial, bloqueio de transportadoras por região ou contratos diferentes por filial. Para que isso não vire confusão, o sistema deve guardar três valores separados:

Valor	Origem	Para que serve
Frete cotado	Retorno da API da transportadora	Base de custo e auditoria
Frete apresentado	Cotado + regras comerciais	O que o cliente viu e aceitou
Frete faturado	CT-e e fatura da transportadora	Conferência de cobrança

Indicadores que a cotação libera

• Transportadoras mais competitivas por região e faixa de peso.
• Diferença média entre frete cotado e frete faturado.
• Percentual de falhas e tempo médio de resposta de cada API.
• Regiões sem cobertura adequada ou com prazos fora do padrão.
• Impacto do valor do frete na conversão do checkout.
• Margem consumida por subsídio de frete.

Esses números sustentam a negociação de contratos e a definição de estratégias comerciais por região.

Perguntas frequentes

Cotação por API substitui completamente a tabela de frete?

Não necessariamente. Muitas empresas usam a API como fonte principal e mantêm a tabela como alternativa quando uma transportadora fica indisponível ou não oferece API.

Quantas transportadoras dá para consultar ao mesmo tempo?

Não há um limite fixo. Com consultas em paralelo e tempo limite individual, o tempo total fica próximo ao da transportadora mais lenta que ainda responde dentro do prazo.

Por que o frete faturado vem diferente do cotado?

Os motivos mais comuns são dimensões erradas no cadastro, taxas regionais não previstas, reajuste de contrato e diferença entre o peso informado e o peso aferido na transportadora. Guardar o cotado e conciliar com o CT-e mostra exatamente onde está a diferença.

Preciso de uma plataforma intermediária de fretes?

Ela ajuda a começar rápido, principalmente no e-commerce. Em operações com contratos próprios, a integração direta costuma dar mais controle sobre regras, custos e dados.