Áreas de tarifa e entrega

Delimite regiões de entrega do seller por CEP, estado, cidade ou desenho no mapa, e teste se um endereço é atendido.

Uma área de tarifa é uma região geográfica nomeada: "Centro de São Paulo", "Raio de 8 km da loja", "Grande BH". O seller usa a área para dizer onde entrega e, opcionalmente, quanto cobra por lá e qual pedido mínimo aceita. A mesma região pode ser descrita por padrões de CEP, por zonas (estado, cidade, bairro, faixa de CEP) ou por formas desenhadas no mapa (polígono ou círculo).

Como funciona

Há duas maneiras de usar uma área. Na primeira, a área é só um filtro: você a liga a uma forma de envio pelo campo rate_area_id, e a forma só vale para endereços dentro dela. Na segunda, a área tem sua própria tarifa (shipping_rate_amount) e já vira uma opção de frete no checkout, sem criar a forma manualmente.

Descreva a região
Crie a área com POST /api/v1/vendor/rate-areas: padrões de CEP, zonas ou formas no mapa.
Defina a tarifa (opcional)
Com shipping_rate_amount a área já vira uma opção de frete.
Ligue a uma forma (opcional)
Passe o id em rate_area_id de uma forma de envio.
Teste
Use Testar um endereço para ver o que o checkout diria.

Conceitos-chave

Três jeitos de descrever a região

Campo	Como casa um endereço
`zip_codes`	Padrões de CEP com `` e `?`. `01310-` casa 01310-000 a 01310-999.
`zones`	Estado (`state_code`), cidade, bairro, ou faixa de CEP (`cep_from` a `cep_to`).
`geofences`	Polígono ou círculo no mapa. O endereço precisa ser localizado no mapa (CEP sozinho não basta).

Você pode combinar os três na mesma área; basta casar com um. cities e addresses guardam padrões de texto para compatibilidade, e o CEP continua sendo o jeito mais confiável.

Pedido mínimo

min_order_amount existe na área e em cada zona. Se o subtotal do carrinho é menor que o da área, o endereço é recusado. Se é menor que o de uma zona, só aquela zona é ignorada.

Tipo

shipping delimita frete; tax delimita regra de imposto. A lista usa type=shipping ou type=tax como filtro.

Endpoints

Método	Caminho	Para que serve	Autenticação
GET	`/api/v1/vendor/rate-areas`	Lista as áreas do seller.	vendor
GET	`/api/v1/vendor/rate-areas/{id}`	Mostra uma área.	vendor
POST	`/api/v1/vendor/rate-areas`	Cria uma área.	vendor
PUT	`/api/v1/vendor/rate-areas/{id}`	Altera uma área.	vendor
DELETE	`/api/v1/vendor/rate-areas/{id}`	Apaga uma área.	vendor
POST	`/api/v1/vendor/delivery-areas/test-address`	Testa um endereço contra as áreas desenhadas.	vendor

Erros comuns

Achar que a lista está vazia. Sem status, só vêm as ativas. Use status=all.
Esquecer que PUT com zones troca todas as zonas. Enviar zones substitui a lista inteira; omitir mantém.
Enviar só um extremo da faixa de CEP. cep_from e cep_to vão juntos.
Mandar geofences com o módulo desligado. Resposta 403 module_disabled. Reenviar a mesma geometria já salva não conta como escrita.
Apagar a área e esperar que as formas que a usam continuem restritas. Elas ficam apontando para uma área que não existe e deixam de casar. Revise rate_area_id antes.
Usar reais no lugar de centavos em min_order_amount e shipping_rate_amount.
Passar um id que não é UUID. Dá 500, não 400.

Próximos passos

Criar área de tarifa

Padrões, zonas e mapa.

Testar um endereço

Veja o veredito do checkout.

Formas de envio

Ligue a área a uma forma.