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

Listar e consultar áreas

Lista as áreas de tarifa do seller ou devolve uma delas, com zonas e formas desenhadas.

Listar áreas

Devolve as áreas do seller, ordenadas por nome, sem paginação. Cada área já traz as zonas e as formas desenhadas.

GET/api/v1/vendor/rate-areasSeller

Lista as áreas de tarifa do seller

Parâmetros de consulta

statusstringpadrão: A

ADallactivedisabled

A (ou active) só ativas, D (ou disabled) só desativadas, all todas.

typestring

shippingtax

Filtra por tipo: shipping ou tax. Sem o parâmetro, vêm todos.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/rate-areas?status=all" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Lista de áreas

json

{
  "rate_areas": [
    {
      "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"
    }
  ],
  "total": 1
}

Campos da resposta

rate_areasarray

Áreas do seller (campos abaixo).

iduuid

Id da área.

namestring

Nome da área.

descriptionstring

Descrição livre.

typestring

shippingtax

shipping (frete) ou tax (imposto).

statusstring

AD

A ativa ou D desativada. Área desativada não casa com nenhum endereço.

vendor_iduuid

Seller dono. Nas rotas de seller é sempre o seu.

min_order_amountinteger

Pedido mínimo, em centavos, para entregar nesta área. 0 = sem mínimo.

shipping_rate_amountinteger

Tarifa fixa de frete da área, em centavos. 0 = a área só delimita região.

zip_codesstring

Padrões de CEP, um por linha (01310-*).

citiesstring

Padrões de cidade, um por linha.

addressesstring

Padrões de endereço, um por linha.

zonesarray

Zonas geográficas da área. Ausente quando não há.

iduuid

Id da zona.

rate_area_iduuid

Área dona da zona.

country_codestring

País, ex.: BR.

state_codestring

UF, ex.: SP. Vazio = qualquer estado.

city_iduuid

Cidade do cadastro de localidades da loja. Ausente quando não usada.

district_iduuid

Bairro do cadastro de localidades. Ausente quando não usado.

cep_fromstring

Início da faixa de CEP, 8 dígitos. Vazio quando a zona não usa faixa.

cep_tostring

Fim da faixa de CEP, 8 dígitos.

min_order_amountinteger

Pedido mínimo desta zona, em centavos.

geofencesarray

Áreas desenhadas no mapa. Ausente quando não há.

iduuid

Id da geometria.

shapestring

polygoncircle

polygon ou circle.

geojsonobject

Só em polygon: GeoJSON Polygon ou MultiPolygon, coordenadas [longitude, latitude].

centerobject

Só em circle: lat e lng do centro.

radius_minteger

Só em circle: raio em metros.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

totalinteger

Quantidade de áreas devolvidas.

Erros: listar

Status	Quando	Corpo de exemplo
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"}`
500	Falha ao consultar.	`{"error":"failed to list rate areas"}`

Consultar uma área

Devolve uma área sua, sem envelope, com os mesmos campos de cada item de rate_areas.

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

Mostra uma área de tarifa do seller

Parâmetros de caminho

iduuidobrigatório

Id da área de tarifa.

Exemplo de requisição: consultar

bash

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

Resposta: consultar

200Área encontrada

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

Mesmos campos da lista.

Erros: consultar

Status	Quando	Corpo de exemplo
400	O `id` é `0` ou um inteiro negativo.	`{"error":"invalid id parameter"}`
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	A área existe, mas é da plataforma ou de outro seller.	`{"error":"forbidden","detail":"rate area does not belong to this vendor"}`
404	Não existe área com esse id.	`{"error":"rate area not found"}`
500	O `id` não é um UUID. Esta rota não valida o formato: o `detail` vem em português.	`{"error":"failed to get rate area","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Veja também

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

Listar e consultar áreas

Lista as áreas de tarifa do seller ou devolve uma delas, com zonas e formas desenhadas.

Listar áreas

Devolve as áreas do seller, ordenadas por nome, sem paginação. Cada área já traz as zonas e as formas desenhadas.

GET/api/v1/vendor/rate-areasSeller

Lista as áreas de tarifa do seller

Parâmetros de consulta

statusstringpadrão: A

ADallactivedisabled

A (ou active) só ativas, D (ou disabled) só desativadas, all todas.

typestring

shippingtax

Filtra por tipo: shipping ou tax. Sem o parâmetro, vêm todos.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/rate-areas?status=all" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Lista de áreas

json

{
  "rate_areas": [
    {
      "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"
    }
  ],
  "total": 1
}

Campos da resposta

rate_areasarray

Áreas do seller (campos abaixo).

iduuid

Id da área.

namestring

Nome da área.

descriptionstring

Descrição livre.

typestring

shippingtax

shipping (frete) ou tax (imposto).

statusstring

AD

A ativa ou D desativada. Área desativada não casa com nenhum endereço.

vendor_iduuid

Seller dono. Nas rotas de seller é sempre o seu.

min_order_amountinteger

Pedido mínimo, em centavos, para entregar nesta área. 0 = sem mínimo.

shipping_rate_amountinteger

Tarifa fixa de frete da área, em centavos. 0 = a área só delimita região.

zip_codesstring

Padrões de CEP, um por linha (01310-*).

citiesstring

Padrões de cidade, um por linha.

addressesstring

Padrões de endereço, um por linha.

zonesarray

Zonas geográficas da área. Ausente quando não há.

iduuid

Id da zona.

rate_area_iduuid

Área dona da zona.

country_codestring

País, ex.: BR.

state_codestring

UF, ex.: SP. Vazio = qualquer estado.

city_iduuid

Cidade do cadastro de localidades da loja. Ausente quando não usada.

district_iduuid

Bairro do cadastro de localidades. Ausente quando não usado.

cep_fromstring

Início da faixa de CEP, 8 dígitos. Vazio quando a zona não usa faixa.

cep_tostring

Fim da faixa de CEP, 8 dígitos.

min_order_amountinteger

Pedido mínimo desta zona, em centavos.

geofencesarray

Áreas desenhadas no mapa. Ausente quando não há.

iduuid

Id da geometria.

shapestring

polygoncircle

polygon ou circle.

geojsonobject

Só em polygon: GeoJSON Polygon ou MultiPolygon, coordenadas [longitude, latitude].

centerobject

Só em circle: lat e lng do centro.

radius_minteger

Só em circle: raio em metros.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

totalinteger

Quantidade de áreas devolvidas.

Erros: listar

Status	Quando	Corpo de exemplo
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"}`
500	Falha ao consultar.	`{"error":"failed to list rate areas"}`

Consultar uma área

Devolve uma área sua, sem envelope, com os mesmos campos de cada item de rate_areas.

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

Mostra uma área de tarifa do seller

Parâmetros de caminho

iduuidobrigatório

Id da área de tarifa.

Exemplo de requisição: consultar

bash

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

Resposta: consultar

200Área encontrada

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

Mesmos campos da lista.

Erros: consultar

Status	Quando	Corpo de exemplo
400	O `id` é `0` ou um inteiro negativo.	`{"error":"invalid id parameter"}`
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	A área existe, mas é da plataforma ou de outro seller.	`{"error":"forbidden","detail":"rate area does not belong to this vendor"}`
404	Não existe área com esse id.	`{"error":"rate area not found"}`
500	O `id` não é um UUID. Esta rota não valida o formato: o `detail` vem em português.	`{"error":"failed to get rate area","detail":"o valor \"abc\" não é um uuid válido. ..."}`