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

POSTTestar um endereço

Verifica se um endereço ou ponto do mapa cai nas áreas desenhadas do seller e mostra o frete que o checkout cotaria.

Use para conferir uma área desenhada antes de divulgá-la: informe um endereço em texto, um CEP ou um ponto clicado no mapa e veja, área por área, se ele está dentro, e quais fretes o cliente veria. A rota só lê: nada é gravado. Ela usa o mesmo caminho do checkout, então o veredito é o que o cliente receberia. Requer o módulo delivery-geofence.

POST/api/v1/vendor/delivery-areas/test-addressSeller

Testa um endereço contra as áreas desenhadas do seller

Corpo da requisição

querystring

Endereço em texto livre, de 3 a 300 caracteres (Rua X, 200, Bairro, Cidade). Precisa localizar a casa; o centro de uma rua ou de um CEP não conta como localizado.

latnumber

Latitude de um ponto clicado no mapa. Vai junto com lng e dispensa query.

lngnumber

Longitude do ponto.

postal_codestring

CEP, 8 dígitos. Ajuda a cotar as formas que não são áreas desenhadas. Também pode ser enviado sozinho, com 8 dígitos.

state_codestring

UF, 2 letras. Preenchida a partir do endereço quando omitida.

product_iduuid

Produto seu e ativo usado na cotação. Se omitido ou inválido, usa o primeiro produto ativo do seller.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/delivery-areas/test-address" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Avenida Paulista, 1000, Bela Vista, São Paulo",
    "postal_code": "01310-100"
  }'

Resposta

200Veredito

json

{
  "located": true,
  "point": {
    "lat": -23.5632,
    "lng": -46.6544
  },
  "precision": "address",
  "postal_code": "01310100",
  "state_code": "SP",
  "areas": [
    {
      "rate_area_id": "7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54",
      "name": "Raio 8 km do centro",
      "inside": true
    }
  ],
  "rates": [
    {
      "method_id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
      "method_name": "Motoboy centro",
      "method_code": "motoboy_centro",
      "cost": 1500,
      "estimated_days": 0,
      "min_delivery_days": 0,
      "max_delivery_days": 0,
      "delivery_time": "2 horas",
      "free_shipping": false,
      "is_pickup": false
    }
  ],
  "unavailable": []
}

Campos da resposta

locatedboolean

true quando o ponto foi localizado com precisão suficiente para decidir as áreas.

pointobject

lat e lng usados. Ausente se não localizado.

precisionstring

pinaddress

pin (ponto clicado) ou address (endereço exato).

approxobject

Só quando não localizado: onde o texto caiu (por exemplo o centro da rua). Informativo, não decide nada.

postal_codestring

CEP usado na cotação, 8 dígitos.

state_codestring

UF usada.

areasarray

Uma entrada por área ativa sua que tem forma desenhada.

rate_area_iduuid

Id da área.

namestring

Nome da área.

insideboolean

Se o ponto está dentro de alguma forma da área.

reasonstring

Quando inside é falso: outside_delivery_area ou address_not_located.

ratesarray

Fretes que o checkout ofereceria deste seller. Cada item tem, entre outros, method_id, method_name, method_code, cost (centavos), min_delivery_days, max_delivery_days, delivery_time, free_shipping e is_pickup.

unavailablearray

Formas que existem mas não valem para este endereço, com method_id, method_name, code (por exemplo outside_delivery_area), message (português) e, às vezes, reason e params.

no_productboolean

true quando o seller não tem produto ativo para cotar: areas continua valendo, mas rates vem vazio.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	Nem `query` (3+ caracteres), nem `lat`/`lng`, nem CEP de 8 dígitos.	`{"error":"query, postal_code or lat/lng is required"}`
400	`query` com mais de 300 caracteres.	`{"error":"query is too long"}`
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	O módulo `delivery-geofence` está desligado na loja.	`{"error":"module_disabled","module":"delivery-geofence"}`
500	Falha ao localizar ou cotar.	`{"error":"failed to test the address"}`

Veja também

POSTTestar um endereço

Verifica se um endereço ou ponto do mapa cai nas áreas desenhadas do seller e mostra o frete que o checkout cotaria.

POST/api/v1/vendor/delivery-areas/test-addressSeller

Testa um endereço contra as áreas desenhadas do seller

Corpo da requisição

querystring

Endereço em texto livre, de 3 a 300 caracteres (Rua X, 200, Bairro, Cidade). Precisa localizar a casa; o centro de uma rua ou de um CEP não conta como localizado.

latnumber

Latitude de um ponto clicado no mapa. Vai junto com lng e dispensa query.

lngnumber

Longitude do ponto.

postal_codestring

CEP, 8 dígitos. Ajuda a cotar as formas que não são áreas desenhadas. Também pode ser enviado sozinho, com 8 dígitos.

state_codestring

UF, 2 letras. Preenchida a partir do endereço quando omitida.

product_iduuid

Produto seu e ativo usado na cotação. Se omitido ou inválido, usa o primeiro produto ativo do seller.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/delivery-areas/test-address" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Avenida Paulista, 1000, Bela Vista, São Paulo",
    "postal_code": "01310-100"
  }'

Resposta

200Veredito

json

{
  "located": true,
  "point": {
    "lat": -23.5632,
    "lng": -46.6544
  },
  "precision": "address",
  "postal_code": "01310100",
  "state_code": "SP",
  "areas": [
    {
      "rate_area_id": "7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54",
      "name": "Raio 8 km do centro",
      "inside": true
    }
  ],
  "rates": [
    {
      "method_id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
      "method_name": "Motoboy centro",
      "method_code": "motoboy_centro",
      "cost": 1500,
      "estimated_days": 0,
      "min_delivery_days": 0,
      "max_delivery_days": 0,
      "delivery_time": "2 horas",
      "free_shipping": false,
      "is_pickup": false
    }
  ],
  "unavailable": []
}

Campos da resposta

locatedboolean

true quando o ponto foi localizado com precisão suficiente para decidir as áreas.

pointobject

lat e lng usados. Ausente se não localizado.

precisionstring

pinaddress

pin (ponto clicado) ou address (endereço exato).

approxobject

Só quando não localizado: onde o texto caiu (por exemplo o centro da rua). Informativo, não decide nada.

postal_codestring

CEP usado na cotação, 8 dígitos.

state_codestring

UF usada.

areasarray

Uma entrada por área ativa sua que tem forma desenhada.

rate_area_iduuid

Id da área.

namestring

Nome da área.

insideboolean

Se o ponto está dentro de alguma forma da área.

reasonstring

Quando inside é falso: outside_delivery_area ou address_not_located.

ratesarray

unavailablearray

Formas que existem mas não valem para este endereço, com method_id, method_name, code (por exemplo outside_delivery_area), message (português) e, às vezes, reason e params.

no_productboolean

true quando o seller não tem produto ativo para cotar: areas continua valendo, mas rates vem vazio.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	Nem `query` (3+ caracteres), nem `lat`/`lng`, nem CEP de 8 dígitos.	`{"error":"query, postal_code or lat/lng is required"}`
400	`query` com mais de 300 caracteres.	`{"error":"query is too long"}`
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	O módulo `delivery-geofence` está desligado na loja.	`{"error":"module_disabled","module":"delivery-geofence"}`
500	Falha ao localizar ou cotar.	`{"error":"failed to test the address"}`