Abbiamo DocsCotação de Frete
Cálculo de valor e prazo antes da emissão do envio, via API ou na criação do pedido
A Cotação de Frete é o cálculo do valor e prazo de entrega antes de o envio ser criado. O sistema consulta as tabelas de frete das integrações de transportadora ativas da filial e retorna as opções de envio disponíveis.
Quando acontece
A cotação pode ser realizada em diferentes momentos:
- Via API — para simular frete antes de criar o pedido. O endpoint Quote orders V2 permite cotar com ponto de coleta em uma loja e um ponto de entrega.
- Na solicitação de coleta — na página de Pedidos, ao clicar em "Solicitar coleta". O sidepanel exibe as cotações, o operador escolhe uma opção e o envio é criado. Veja Solicitação de Coleta.
- Em algumas integrações de pedido — integrações específicas (ex.: VTEX) podem disparar a cotação no fluxo de criação ou exibição de opções de frete.
- Automaticamente — quando uma automação de envio com ação mais barato ou mais rápido é acionada.
Como funciona
- O sistema identifica todas as integrações de transportadora ativas da filial.
- Para cada integração, consulta a tabela de frete vinculada — que pode ser do tipo CEP ou do tipo raio.
- Se os dados de latitude/longitude e distância dirigida ainda não existirem (por exemplo, quando vêm da API), o sistema calcula novamente a partir do endereço.
- Para cada prazo da tabela (ex.: D1, D3, EXP60):
- Verifica se o destino está coberto pela tabela.
- Calcula o preço com base na faixa de destino (CEP ou km) e na faixa de peso do pedido.
- Calcula a data de entrega esperada para cada prazo, considerando:
- O número de dias ou minutos do prazo (D1 = 1 dia útil, EXP60 = 60 minutos)
- O horário de corte da integração
- Aplica as regras de cotação configuradas, que podem ajustar preço ou prazo.
- Retorna todas as opções disponíveis com: transportadora, modalidade, prazo, preço e data de entrega esperada.
Cotação V2
Atualmente, apenas a cotação V2 é suportada. Ela aceita endereço completo com latitude/longitude ou apenas CEP (zipcode).
Diferença entre tabela de CEP e tabela de raio na cotação
| Tabela de CEP | Tabela de Raio | |
|---|---|---|
| Dado usado | CEP de destino do pedido | Distância entre origem e destino |
| Como encontra o preço | Busca em qual faixa de CEP o destino se encaixa | Calcula a distância (via geolocalização) e busca a faixa de km |
| Faixas de preço | Por faixa de peso, dentro de cada faixa de CEP | Por faixa de peso, dentro de cada faixa de km |
| Dado adicional necessário | Apenas o CEP de destino | Endereço completo (para calcular coordenadas e distância) |
Como o prazo gera a data de entrega esperada
O prazo da tabela de frete (ex.: D1, D3, EXP120) é transformado em uma data de entrega esperada no momento da cotação:
- Prazos em dias úteis (D0, D1, D3, D7...): o sistema conta os dias úteis a partir da data do pedido, considerando o horário de corte.
- Prazos expressos (EXP60, EXP120...): o sistema soma os minutos ao horário atual, respeitando a janela de operação.
Horário de corte
Se o pedido é criado depois do horário de corte da integração, a contagem de dias úteis começa no próximo dia de operação. Isso pode fazer com que um prazo D1 resulte em 2 dias na prática. Veja mais em Tabela de Frete — Horário de corte.
Regras de cotação
Após o cálculo base (preço + prazo), o sistema pode aplicar regras de cotação que alteram o resultado:
- Alterar o preço — definir um preço fixo ou adicionar/subtrair do preço calculado.
- Alterar a data de entrega — definir uma data fixa ou adicionar tempo à data calculada.
- Excluir opções — remover prazos ou transportadoras específicas do resultado.
As regras de cotação são configuradas separadamente e permitem ajustar o resultado sem alterar a tabela de frete em si.
O que a cotação retorna
Para cada opção disponível, a cotação retorna:
| Informação | Descrição |
|---|---|
| Transportadora | Nome da transportadora |
| Modalidade | Modalidade (ex.: CARRO, MOTO, PAC) |
| Prazo | Código do prazo (ex.: D1, D3, EXP60) |
| Preço | Valor do frete calculado |
| Data de entrega esperada | Data estimada de entrega ao destinatário |
Links relacionados
- Cotação de Frete (ação) — onde e quando a cotação acontece
- Solicitação de Coleta — fluxo no sidepanel de pedidos
- Tabela de Frete — onde os preços e prazos são definidos
- Quote orders V2 — endpoint da API para cotação
- Prazos de Entrega — códigos de prazo e como interpretá-los
- Integração de Transportadora — integrações consultadas na cotação
- Automação de Envio — automações que usam a cotação para escolher a melhor opção