Frete e entrega

Do carrinho à porta do cliente, a loja precisa responder perguntas diferentes: "quanto custa o frete?", "quando chega?", "posso retirar na loja?", "onde está meu pacote?". Esta seção documenta as rotas públicas da vitrine que respondem a essas perguntas. Elas servem à página do produto, ao carrinho e ao checkout, e também a integrações que montam o próprio checkout.

Como funciona

1. Na página do produto

   Mostre o prazo com Data de entrega e, para vários produtos de uma listagem, a promessa em lote. A estimativa rápida de frete por CEP está em Estimativa de frete.

2. No carrinho

   Barra de frete grátis e pedido mínimo com Pedido mínimo e frete grátis. A cotação completa do carrinho está em Cotar frete.

3. No checkout

   O cliente escolhe um método da cotação, ou retirar em loja, ou ainda agendar uma janela de entrega.

4. Depois da compra

   O cliente acompanha o pacote por Rastreio público, e a loja mostra o link da transportadora com Transportadoras.

Conceitos-chave

Método de envio

Um método de envio é uma forma de entregar ("Entrega Padrão", "Motoboy", "Correios SEDEX"). Tem nome, prazo, regra de preço e pode ser da loja inteira ou de um seller só. O preço pode ser manual (tabela por área e faixa) ou em tempo real (consultado à transportadora). Veja Métodos de envio.

Área de tarifa e CEP

A área de tarifa liga um conjunto de destinos (faixas de CEP, estados, cidades, bairros) ao preço e prazo de um método. É por ela que o mesmo método custa diferente em São Paulo e no Amazonas, ou nem é oferecido.

Cotação por seller

Num marketplace, cada seller entrega os próprios itens. A cotação é feita por seller e depois consolidada: em Cotar frete o carrinho recebe só os métodos que todos os sellers oferecem, com o custo somado; a variante por seller devolve cada grupo separado.

Retirada em loja (BOPIS)

Buy online, pick up in store: o cliente compra pela internet e retira num ponto da loja. Veja Pontos de retirada.

Endpoints

Erros comuns

1. Mandar peso e medidas esperando que a cotação os use. Em calculate e calculate-by-vendor eles são ignorados; vale o cadastro do produto. Só estimate aceita os valores enviados.
2. CEP inválido. 00000000, 99999999, letras ou menos de 8 dígitos respondem 400 invalid_postal_code.
3. Produto sem UUID válido. product_id que não é UUID ou que não existe no catálogo responde 500, não 400.
4. Esperar o mesmo método para todos os sellers. No carrinho com dois sellers, um método que só um deles oferece não aparece na cotação consolidada.
5. Mostrar a data de entrega sem checar o módulo. delivery-estimate e delivery-promise exigem o módulo delivery-window.
6. Tratar rastreio não encontrado como erro HTTP. A rota pública responde 200 com found: false.

Próximos passos