VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Áreas de tarifa e entrega

Alterar e apagar área

Altera parcialmente uma área de tarifa do seller ou a apaga junto com suas zonas.

Alterar uma área

A alteração é parcial para os campos simples: só o que você envia muda. Já zones e geofences substituem o conjunto inteiro quando presentes: omitidos, ficam como estão; [], apagam todos.

PUT/api/v1/vendor/rate-areas/{id}Seller

Altera uma área de tarifa do seller

Parâmetros de caminho

iduuidobrigatório
Id da área de tarifa.

Corpo da requisição

namestring
Nome da área.
descriptionstring
Descrição livre.
typestring
shippingtax
shipping ou tax.
statusstring
AD
A ativa ou D desativada. Também aceita active e disabled.
min_order_amountinteger
Pedido mínimo da área, em centavos.
shipping_rate_amountinteger
Tarifa fixa de frete, em centavos. Acima de zero, a área vira uma forma de envio automática. Veja o aviso.
zip_codesstring | array
Padrões de CEP: texto com um por linha, ou uma lista. * = qualquer sequência de dígitos, ? = exatamente um dígito (01310-*, 0?3*). Hífens são ignorados.
citiesstring | array
Padrões de cidade, um por linha ou em lista.
addressesstring | array
Padrões de endereço, um por linha ou em lista.
zonesarray

Zonas geográficas (estado, cidade, bairro ou faixa de CEP).

country_codestring
País, ex.: BR.
state_codestring
UF, ex.: SP.
city_iduuid
Cidade do cadastro de localidades da loja.
district_iduuid
Bairro do cadastro de localidades da loja.
cep_fromstring
Início da faixa de CEP. Com ou sem hífen; é gravado só com os 8 dígitos. Exige cep_to.
cep_tostring
Fim da faixa de CEP. Precisa ser maior ou igual a cep_from.
min_order_amountintegerpadrão: 0
Pedido mínimo desta zona, em centavos. Uma zona acima do valor do carrinho é ignorada, e as outras da área ainda podem casar.
geofencesarray

Áreas desenhadas no mapa, até 20. Exige o módulo delivery-geofence ligado na loja.

shapestringobrigatório
polygoncircle
polygon ou circle.
geojsonobject
Obrigatório em polygon: GeoJSON Polygon ou MultiPolygon (também aceita Feature), coordenadas [longitude, latitude] dentro do Brasil, sem auto-interseção, mínimo de 0,01 km² por polígono.
centerobject
Obrigatório em circle: {"lat": -23.56, "lng": -46.65}, dentro do Brasil.
radius_mnumber
Obrigatório em circle: raio em metros, de 100 a 100000. Frações são arredondadas.

Exemplo de requisição: alterar

bash
curl -X PUT "$BASE_URL/api/v1/vendor/rate-areas/7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_rate_amount": 1800,
    "min_order_amount": 5000
  }'

Resposta: alterar

200Área atualizada
json
{
  "id": "7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54",
  "name": "Centro de São Paulo",
  "description": "Entrega de motoboy no centro",
  "type": "shipping",
  "status": "A",
  "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "min_order_amount": 5000,
  "shipping_rate_amount": 1800,
  "zip_codes": "01310-*\n01311-*",
  "cities": "",
  "addresses": "",
  "zones": [
    {
      "id": "258257fb-0790-49d9-b981-6acae95891af",
      "rate_area_id": "7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54",
      "country_code": "BR",
      "state_code": "SP",
      "cep_from": "01000000",
      "cep_to": "01999999",
      "min_order_amount": 0
    }
  ],
  "geofences": [
    {
      "id": "0e1d2c3b-4a59-4687-b6a5-948372615049",
      "shape": "circle",
      "center": {
        "lat": -23.5614,
        "lng": -46.6559
      },
      "radius_m": 8000
    }
  ],
  "created_at": "2026-10-01T14:20:11Z",
  "updated_at": "2026-10-01T14:20:11Z"
}

Campos da resposta

(campos)object
A área completa, igual a Consultar uma área.

Erros: alterar

StatusQuandoCorpo de exemplo
400O id é 0 ou um inteiro negativo.{"error":"invalid id parameter"}
400Corpo que não é JSON.{"error":"invalid request body"}
400Faixa de CEP malformada: só um dos dois extremos, fora de 8 dígitos, ou cep_from maior que cep_to.{"error":"invalid CEP range: cep_from must be <= cep_to"}
400Geometria inválida (fora do Brasil, raio fora de 100 a 100000 m, polígono que se cruza, mais de 20 geometrias...). A mensagem vem em português.{"error":"geofence inválido: geofences[0]: raio deve ficar entre 100 m e 100 km (recebido 50 m)"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403A área existe, mas é da plataforma ou de outro seller.{"error":"forbidden","detail":"rate area does not belong to this vendor"}
403Há geofences no corpo, mas o módulo delivery-geofence está desligado na loja.{"error":"module_disabled","module":"delivery-geofence"}
404Não existe área com esse id.{"error":"rate area not found"}
500Falha ao gravar, ou id que não é UUID.{"error":"failed to update rate area"}
Tarifa gera uma forma de envio sozinha

Quando type é shipping, status é A e shipping_rate_amount é maior que zero, a plataforma cria (e depois mantém sincronizada) uma forma de envio de código rate_area_ + id da área, com o nome da área e esse valor fixo, limitada ao endereço da área. É ela que o cliente vê no checkout. Zerar a tarifa ou desativar a área desativa essa forma; apagar a área a apaga.

Apagar uma área

Remove a área, suas zonas, suas formas desenhadas e a forma de envio automática que ela gerou. A exclusão é definitiva.

DELETE/api/v1/vendor/rate-areas/{id}Seller

Apaga uma área de tarifa do seller

Parâmetros de caminho

iduuidobrigatório
Id da área de tarifa.

Exemplo de requisição: apagar

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/rate-areas/7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54" \
  -H "Authorization: Bearer $TOKEN"

Resposta: apagar

200Área apagada
json
{
  "message": "rate area deleted"
}

Campos da resposta

messagestring
Texto fixo de confirmação.

Erros: apagar

StatusQuandoCorpo de exemplo
400O id é 0 ou um inteiro negativo.{"error":"invalid id parameter"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403A área existe, mas é da plataforma ou de outro seller.{"error":"forbidden","detail":"rate area does not belong to this vendor"}
404Não existe área com esse id.{"error":"rate area not found"}
500Falha ao apagar.{"error":"failed to delete rate area"}
Formas que usam a área ficam sem restrição

Formas de envio criadas por você com rate_area_id apontando para esta área não são apagadas: passam a apontar para uma área que não existe e deixam de casar com os endereços. Troque o rate_area_id delas antes. Para só parar de usar a área, mude status para D.

Veja também

  • Listar e consultar
  • Formas de envio
Anterior
Criar área de tarifa
Próxima
Testar um endereço
Nesta página
  • Alterar uma área
  • Exemplo de requisição: alterar
  • Resposta: alterar
  • Erros: alterar
  • Apagar uma área
  • Exemplo de requisição: apagar
  • Resposta: apagar
  • Erros: apagar
  • Veja também