Skip to main content

Descrição

Este webhook permite que você implemente seu próprio sistema de cálculo de frete personalizado. Quando um cliente solicita uma cotação de frete no checkout, o Olist ERP enviará os dados do carrinho para sua URL e aguardará o retorno com as opções e valores de frete.

Quando é Acionado

  • Cliente solicita cálculo de frete no checkout
  • Alteração de CEP de entrega
  • Modificação de produtos no carrinho
  • Recálculo de frete solicitado manualmente

Diferença dos Outros Webhooks

Este webhook funciona de forma síncrona e bidirecional:
  • O sistema aguarda sua resposta em tempo real (timeout: 10 segundos)
  • Você deve retornar as opções de frete calculadas
  • O cliente vê as opções que você retornou

Estrutura da Requisição Recebida

O Olist ERP enviará via POST:

Estrutura da Resposta Esperada

Você deve retornar em até 10 segundos:

Campos da Requisição Recebida

Campos da Resposta Obrigatórios

Campos da Resposta Opcionais

Exemplo de Implementação

PHP

Python

Node.js

Configuração

Para ativar este webhook:
  1. Acesse Configurações > Integrações > Webhooks
  2. Clique em Novo Webhook
  3. Selecione o evento Cotação de Fretes
  4. Informe a URL do seu endpoint
  5. Configure o timeout (padrão: 10 segundos)
  6. Salve as configurações

Casos de Uso

  • Integração com transportadoras: Consulte APIs de múltiplas transportadoras
  • Regras personalizadas: Implemente frete grátis, progressivo, etc.
  • Tabelas próprias: Use suas próprias tabelas de frete
  • Frete dinâmico: Calcule baseado em promoções e regras de negócio
  • Multi-transportadora: Ofereça múltiplas opções ao cliente
  • Frete inteligente: Escolha a melhor opção automaticamente

Boas Práticas

  • Performance: Responda em menos de 5 segundos (timeout: 10s)
  • Cache: Use cache para CEPs consultados recentemente
  • Fallback: Tenha uma opção padrão se APIs externas falharem
  • Múltiplas opções: Ofereça pelo menos 2-3 opções de frete
  • Valores claros: Seja transparente com prazos e valores
  • Tratamento de erro: Sempre retorne uma resposta válida
  • Log de cotações: Registre todas as cotações para análise

Tratamento de Erros

Se não conseguir calcular o frete:
O sistema então usará as regras de frete padrão configuradas no Olist ERP.

Timeout

  • Timeout máximo: 10 segundos
  • Recomendado: Responder em até 5 segundos
  • Se exceder: Sistema usa cálculo padrão do Olist ERP

Observações

  • Este é o único webhook síncrono da API v2
  • O cliente aguarda a resposta para ver as opções de frete
  • Performance é crítica - otimize consultas e use cache
  • Sempre retorne pelo menos uma opção de frete válida
  • Valores devem ser positivos (use 0.00 para frete grátis)
  • Prazos são sempre em dias úteis (exceto se especificado nas observações)
  • O cotacao_id deve ser retornado exatamente como recebido