API atual/Referência completa/Áreas de tarifa e entrega

POSTCriar área de tarifa

Cria uma área de entrega do seller por padrões de CEP, zonas ou formas desenhadas no mapa.

Use para delimitar uma região de entrega. A área nasce ativa, pertence ao seller do token (o corpo não pode escolher o dono) e, se tiver tarifa, já cria a forma de envio correspondente. Zonas e formas são gravadas na mesma transação: se uma zona for inválida, nada é criado.

POST/api/v1/vendor/rate-areasSeller

Cria uma área de tarifa do seller

Corpo da requisição

namestringobrigatório

Nome da área.

descriptionstring

Descrição livre.

typestringpadrão: shipping

shippingtax

shipping ou tax.

statusstringpadrão: A

AD

A ativa ou D desativada. Também aceita active e disabled.

min_order_amountintegerpadrão: 0

Pedido mínimo da área, em centavos.

shipping_rate_amountintegerpadrão: 0

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

bash

curl -X POST "$BASE_URL/api/v1/vendor/rate-areas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Raio 8 km do centro",
    "description": "Entrega de motoboy",
    "type": "shipping",
    "min_order_amount": 3000,
    "shipping_rate_amount": 1500,
    "zip_codes": [
      "01310-*",
      "01311-*"
    ],
    "geofences": [
      {
        "shape": "circle",
        "center": {
          "lat": -23.5614,
          "lng": -46.6559
        },
        "radius_m": 8000
      }
    ]
  }'

Resposta

201Área criada

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": 3000,
  "shipping_rate_amount": 1500,
  "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

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`name` vazio.	`{"error":"name is required"}`
400	Faixa 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"}`
400	Geometria 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)"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O seller não tem conta de vendedor vinculada ao usuário.	`{"error":"vendor_profile_required"}`
403	Há `geofences` no corpo, mas o módulo `delivery-geofence` está desligado na loja.	`{"error":"module_disabled","module":"delivery-geofence"}`
500	Falha ao gravar.	`{"error":"..."}`

Veja também

POSTCriar área de tarifa

Cria uma área de entrega do seller por padrões de CEP, zonas ou formas desenhadas no mapa.

POST/api/v1/vendor/rate-areasSeller

Cria uma área de tarifa do seller

Corpo da requisição

namestringobrigatório

Nome da área.

descriptionstring

Descrição livre.

typestringpadrão: shipping

shippingtax

shipping ou tax.

statusstringpadrão: A

AD

A ativa ou D desativada. Também aceita active e disabled.

min_order_amountintegerpadrão: 0

Pedido mínimo da área, em centavos.

shipping_rate_amountintegerpadrão: 0

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

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

bash

curl -X POST "$BASE_URL/api/v1/vendor/rate-areas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Raio 8 km do centro",
    "description": "Entrega de motoboy",
    "type": "shipping",
    "min_order_amount": 3000,
    "shipping_rate_amount": 1500,
    "zip_codes": [
      "01310-*",
      "01311-*"
    ],
    "geofences": [
      {
        "shape": "circle",
        "center": {
          "lat": -23.5614,
          "lng": -46.6559
        },
        "radius_m": 8000
      }
    ]
  }'

Resposta

201Área criada

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": 3000,
  "shipping_rate_amount": 1500,
  "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

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`name` vazio.	`{"error":"name is required"}`
400	Faixa 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"}`
400	Geometria 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)"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O seller não tem conta de vendedor vinculada ao usuário.	`{"error":"vendor_profile_required"}`
403	Há `geofences` no corpo, mas o módulo `delivery-geofence` está desligado na loja.	`{"error":"module_disabled","module":"delivery-geofence"}`
500	Falha ao gravar.	`{"error":"..."}`