Fretes — API Pública v1

Endpoint único para as operações de frete e endereço de entrega de um carrinho. A operação executada depende dos campos enviados no body. Em todas as variações a resposta é o objeto completo do carrinho (ver Carrinho); erros vêm em messages.

Base URL

https://{sua-loja}/api/v1/public/

Identificação do cliente

Envie o header Authorization: Bearer {access_token} obtido no Login (SSO). As operações de troca de endereço exigem um cliente identificado.

Fluxo típico:

Informar o CEP → a resposta traz as opções em shipping_info.freights[].
Selecionar uma opção pelo service → a resposta traz a escolha em shipping_info.selected e o valor em totalizers.shipping_total.
(Opcional) Agendar a janela de entrega, quando a opção oferece scheduled_deliveries_times.
(Opcional) Trocar o endereço de entrega entre os endereços do cliente.

`POST /order/{uuid}/freights/`

1. Informar o CEP de entrega

{ "zipcode": "01310-100" }

Formatos aceitos: 01310100, 01310-100, 01.310-100. A pontuação é removida e o resultado deve ter 8 dígitos.
Quando o carrinho já tem cliente, o endereço de entrega é associado automaticamente (reaproveita ou cria um endereço do cliente).
Após o CEP, o servidor recalcula shipping_info.freights[].

Mensagem	Causa
`Favor informar o CEP`	Nenhum campo reconhecido no body.
`CEP Inválido`	CEP com tamanho diferente de 8 dígitos.

2. Selecionar a opção de frete

{
  "freight": "PAC",
  "pickup_store": 12
}

Campo	Tipo	Descrição
`freight`	`string`	Valor de `service` de uma das opções em `shipping_info.freights[]` (ex.: `PAC`, `Sedex`, `gratis`, `CLICK_RETIRE`, `MotoBoy`).
`pickup_store`	`int`	Opcional. ID da loja de retirada, para opções com `pickup_store: true`. Deve constar em `pickups[]` da opção escolhida.

Após a seleção, shipping_info.selected traz shipping_type, shipping_name, shipping_delivery_date, delivery_time, time_format, pickup/pickup_store e total.

Mensagem	Causa
`Selecione uma opção de frete validos.`	`freight` não corresponde a nenhuma opção disponível para o CEP atual.

3. Agendar a janela de entrega

Disponível quando a opção selecionada traz scheduled_deliveries_times.

{
  "scheduled_delivery_time": true,
  "date": "2026-04-15",
  "start": "14:00:00",
  "end": "18:00:00"
}

A janela precisa ser exatamente uma das oferecidas pela opção de frete selecionada. Em sucesso, shipping_delivery_date, delivery_time, shipping_total e time_format são atualizados.

Mensagem	Causa
`Selecione um horário correto.`	Janela fora da lista oferecida.
`Selecione um frete válido.`	Não há frete selecionado ou a opção não permite agendamento.

4. Trocar o endereço de entrega

Exige cliente identificado.

{ "address": 504 }

Valor	Efeito
`"P"`	Usa o endereço principal do cadastro do cliente.
`<int>`	ID de um endereço do cliente (ver Endereços).
`"L"`	Usa o endereço da lista de presentes vinculada ao carrinho.

Mensagem	Causa
`Selecione um endereço correto.`	Endereço inexistente, de outro cliente ou lista de presentes sem endereço.

Observações gerais

Trocar o CEP ou o endereço invalida a opção de frete selecionada; repita o passo 2.
Alterar itens do carrinho pode mudar as opções e os valores de frete. Reconsulte shipping_info.freights[] antes de seguir para o pagamento.
Quando a loja calcula frete por item (fulfillment dividido), cada item traz os próprios shipping_type, shipping_name, shipping_total e delivery_time.