Métodos de envio

Um método de envio é uma opção de entrega que o cliente vê no checkout: "Entrega Padrão", "SEDEX", "Retirada na loja". Cada método diz quanto custa, em quanto tempo chega, para onde vale e, se for o caso, qual transportadora cotou o preço. Esta seção mostra como criar e manter esses métodos pela API de administração, e as peças que os cercam: faixas de preço, prazo por região, caixas de embalagem e regras que ajustam o frete na hora da cotação.

As rotas servem a um integrador que sincroniza o cadastro de frete de um ERP, a uma ferramenta de configuração em lote ou a um painel próprio. O painel da Venddor usa exatamente as mesmas rotas.

Como funciona

O que o checkout faz com um método

1. Filtra os métodos

   Considera só métodos ativos (status: "A"), do seller do carrinho (ou da loja inteira, quando use_for_all_vendors é verdadeiro), dentro da faixa de peso do método e visíveis ao grupo do cliente (usergroup_ids).

2. Acha a área do endereço

   Cada método pode ser vinculado a uma ou mais áreas de tarifa (regiões por estado, cidade ou faixa de CEP). O vínculo sem área vale para os destinos que nenhuma área cobre.

3. Calcula o preço e o prazo

   Em métodos manuais, usa a faixa que casa com o peso, o valor do pedido e a quantidade de itens naquela área. Em métodos em tempo real, pergunta à transportadora. O prazo vem do vínculo método/área.

4. Aplica as políticas de frete

   As políticas ajustam a lista já cotada: somam ou descontam valores, zeram o frete acima de um subtotal, escondem métodos ou limitam quantas opções aparecem.

Estados de um método

Na escrita, status aceita a letra ou a palavra (active, disabled). Na leitura, vem sempre a letra.

Conceitos-chave

Faixas de preço (tiers) e tarifas por degrau (rates)

Uma faixa diz: "para pedidos entre X e Y gramas, entre A e B reais e entre M e N itens, o frete é R". Todas as medidas são inteiros (gramas, centavos, itens) e 0 em um limite significa "sem limite". As tarifas por degrau são outra forma de cobrar: uma lista de degraus por dimension (C valor do pedido, W peso, I itens), com valor fixo ou percentual. As duas listas são independentes: gravar em uma não altera a outra.

Áreas e prazo

Uma área de tarifa é uma região geográfica cadastrada à parte. O vínculo método/área guarda o prazo daquela região (min_delivery_days a max_delivery_days, em dias úteis) e é a âncora das faixas: uma faixa com rate_area_id só vale para aquela área. Sem rate_area_id, vale para o padrão.

Seller dono do método

company_id vazio é um método da loja, que atende a todos os sellers quando use_for_all_vendors é verdadeiro. Com company_id, o método pertence a um seller (lojista) e só aparece nos carrinhos dele. Ao criar sem enviar use_for_all_vendors, o valor padrão é verdadeiro.

Políticas de frete

Regras opcionais, por prioridade, que alteram a cotação sem mexer nos métodos. Ficam em Políticas de frete.

Endpoints

Erros comuns

1. Misturar unidades de peso. min_weight e max_weight do método são em kg; os das faixas são em gramas.
2. Esperar 400 na validação. Dias negativos em um vínculo, day_of_week inválido e ids inexistentes voltam como 500 com a causa em detail.
3. Criar dois vínculos padrão. Cada método aceita um único vínculo sem rate_area_id; o segundo falha.
4. Gravar /rates achando que acrescenta. PUT /rates substitui a lista inteira.
5. Duplicar e esquecer o prazo. A cópia leva as faixas, mas não os vínculos método/área; recrie os prazos.
6. Apagar em vez de desativar. DELETE não tem volta.
7. Reutilizar o code. O código é único por loja; repetir devolve 409.

Próximos passos