Formas de envio do seller

Uma forma de envio é uma opção de entrega que o cliente escolhe no checkout: "Motoboy", "PAC", "Retirada na loja". Cada seller (lojista) cadastra as próprias formas, decide quanto elas cobram (valor fixo, faixas por peso, por valor do carrinho ou por número de itens, ou consulta à transportadora) e em quais regiões elas valem. Estas rotas só enxergam e só alteram as formas do seller dono do token. As formas que valem para a loja inteira são do administrador.

Como funciona

O cliente informa o CEP no carrinho. A plataforma percorre as formas ativas do seller dos itens e mantém só as que servem para aquele carrinho e destino. Depois calcula o preço de cada uma.

Uma forma entra na cotação quando: está ativa (A); o peso do carrinho está entre min_weight e max_weight (quando definidos); o endereço cai na área de tarifa, se houver rate_area_id; e o cliente pertence a um dos usergroup_ids, se houver. O preço sai, nesta ordem, de:

1. Frete grátis: free_shipping ligado, ou subtotal do carrinho maior ou igual a free_shipping_threshold.
2. Faixas cadastradas em /rates.
3. Consulta à transportadora, nas formas em tempo real ou de agregador.
4. Peso, se config tiver per_kg_rate.
5. Valor fixo flat_rate.

No fim, surcharge e surcharge_percent são somados ao valor, exceto no frete grátis.

Fluxo típico de integração:

1. Crie a área (opcional)
   Se a forma só vale para uma região, crie antes a área de tarifa.
2. Crie a forma
   POST /api/v1/vendor/shipping-methods com nome, código e valor.
3. Defina faixas (opcional)
   PUT /api/v1/vendor/shipping-methods/{id}/rates quando o preço varia com peso, valor ou itens.
4. Confira
   GET /api/v1/vendor/shipping-methods e simule um CEP na vitrine.

Conceitos-chave

Status

A API aceita também as palavras active e disabled, mas sempre devolve a letra. Outros valores não são validados e acabam em 500.

Retirada na loja

Uma forma é tratada como retirada quando o nome ou o código contém "retirada", "retirar" ou "pickup". Só essas formas aceitam um endereço de retirada; nas demais, essas rotas respondem 400.

Autorização

Basta um token de seller (veja Atores e APIs). Não há privilégio extra para estas rotas: o dono da conta e os usuários da equipe do seller podem usá-las.

Endpoints

Erros comuns

1. Reaproveitar um code. O código é único na loja inteira, inclusive entre sellers: 409 code already exists.
2. Tentar mudar o code com PUT. O campo não existe na alteração; crie outra forma.
3. Enviar reais em vez de centavos. 15.00 em flat_rate é recusado; envie 1500.
4. Confundir peso em kg com gramas. min_weight e max_weight da forma são kg; amount das faixas de peso é grama.
5. Mandar PUT /rates com só a faixa nova. A rota substitui tudo: reenvie as faixas que quer manter.
6. Esperar que uma forma sem rate_area_id valha só em uma região. Sem área, ela vale para o país todo.
7. Usar status com outras palavras. Fora de A, D, active e disabled a resposta é um 500 genérico.

Próximos passos