VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Promoções e cupons

Frete grátis regional

Define o valor mínimo de compra para frete grátis em cada região de frete da loja.

Uma loja costuma oferecer frete grátis acima de um valor, e esse valor muda com a região: perto do centro de distribuição o frete é barato, no Norte é caro. Cada regra liga uma região de frete (rate area) a um subtotal mínimo. Por trás, a plataforma cria e mantém uma promoção free_shipping por regra (ela aparece na lista de promoções com o nome "Frete grátis <região>"). Estas rotas pedem o privilégio de frete (view_shipping para ler, manage_shipping para gravar), não o de promoções.

Listar as regras

GET/api/v1/admin/promotions/free-shipping-regionalAdmin

Lista as regras de frete grátis por região

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/admin/promotions/free-shipping-regional" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Regras
json
{
  "rules": [
    {
      "id": "e26c1bc3-624e-41f5-bffe-fd88a665abe3",
      "rate_area_id": "fefe4673-f01b-47d6-a6c5-52bdf30f9bdf",
      "area_name": "São Paulo",
      "promotion_id": "612a7a7a-c2cf-4080-a6f8-328f1327c7bf",
      "threshold_cents": 10000,
      "is_default": true
    }
  ]
}

Campos da resposta

rulesarray

Regras, a padrão primeiro e depois por valor mínimo crescente. Lista vazia vem como [].

iduuid
Id da regra.
rate_area_iduuid | null
Região de frete da regra. null é a regra nacional.
area_namestring | omitted
Nome da região.
promotion_iduuid
Promoção de frete grátis que a plataforma mantém para esta regra.
threshold_centsinteger
Subtotal mínimo do carrinho para ganhar frete grátis, em centavos.
is_defaultboolean
Se é a regra padrão (só uma pode ser).

Erros: listar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403Sem privilégio de frete.{"error":"insufficient privileges","required":"..."}

Substituir as regras

PUT/api/v1/admin/promotions/free-shipping-regionalAdmin

Substitui o conjunto de regras de frete grátis por região

Corpo da requisição

rulesarrayobrigatório

O conjunto completo de regras desejado.

rate_area_iduuid | null
Região de frete. null ou omitido é a regra nacional.
threshold_centsintegerobrigatório
Subtotal mínimo em centavos, maior que zero.
is_defaultbooleanpadrão: false
Marca como regra padrão. Só uma regra fica padrão; a última marcada vence.

Exemplo de requisição: substituir

bash
curl -X PUT "$BASE_URL/api/v1/admin/promotions/free-shipping-regional" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "rate_area_id": null,
        "threshold_cents": 29900,
        "is_default": true
      },
      {
        "rate_area_id": "fefe4673-f01b-47d6-a6c5-52bdf30f9bdf",
        "threshold_cents": 15900
      }
    ]
  }'

Resposta: substituir

200Regras gravadas
json
{
  "rules": [
    {
      "id": "0b7d6a0e-6a4b-4a3e-8d5c-3c2a1f9e7b11",
      "rate_area_id": null,
      "promotion_id": "5a9b4e22-1c7d-4f6a-b3e8-2d1c0a9f8e77",
      "threshold_cents": 29900,
      "is_default": true
    }
  ]
}

Campos da resposta

rulesarray
As regras resultantes, no mesmo formato da listagem.

Erros: substituir

StatusQuandoCorpo de exemplo
400Corpo inválido, ou threshold_cents menor ou igual a zero. A mensagem vem direto no campo error.{"error":"threshold_cents must be > 0"}
401Token ausente ou inválido.{"error":"authentication required"}
403Sem o privilégio manage_shipping.{"error":"insufficient privileges","required":"manage_shipping"}

Sugestões de valor mínimo

GET/api/v1/admin/promotions/free-shipping-regional/suggestionsAdmin

Sugere o valor mínimo de frete grátis por região

Exemplo de requisição: sugestões

bash
curl "$BASE_URL/api/v1/admin/promotions/free-shipping-regional/suggestions" \
  -H "Authorization: Bearer $TOKEN"

Resposta: sugestões

200Sugestões
json
{
  "suggestions": [
    {
      "rate_area_id": "32ffd693-895b-47a7-832a-ae6794de249e",
      "area_name": "Centro-Oeste",
      "avg_shipping_cost_cents": 4250,
      "suggested_threshold_cents": 20990,
      "sample_count": 38
    }
  ]
}

Campos da resposta

suggestionsarray

Uma sugestão por região de frete cadastrada, em ordem alfabética.

rate_area_iduuid
Região de frete.
area_namestring
Nome da região.
avg_shipping_cost_centsinteger
Custo médio das cotações de frete dos últimos 90 dias, em centavos. 0 sem amostras.
suggested_threshold_centsinteger
Sugestão: o maior entre 4 vezes o custo médio e o ticket médio dos últimos 30 dias mais 20%, arredondado para cima até o próximo R$ X9,90.
sample_countinteger
Quantas cotações entraram na média.

Erros: sugestões

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403Sem privilégio de frete.{"error":"insufficient privileges","required":"..."}
O PUT é substituição total

Regras existentes que não estiverem na lista enviada são apagadas, junto com a promoção de frete grátis que a plataforma mantinha para elas. Para alterar uma região, leia a lista, mude o item e reenvie todas as regras. A regra é identificada pela região (rate_area_id); reenviar a mesma região atualiza em vez de duplicar.

Sem amostras, a sugestão é só ticket médio

Em regiões sem cotações recentes (sample_count 0) o valor sugerido vem do ticket médio dos pedidos, não do custo do frete.

Veja também

  • Promoções: visão geral
  • Listar e detalhar
Anterior
Estatísticas e projeção
Próxima
Orçamentos e grupos de promoções
Nesta página
  • Listar as regras
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Substituir as regras
  • Exemplo de requisição: substituir
  • Resposta: substituir
  • Erros: substituir
  • Sugestões de valor mínimo
  • Exemplo de requisição: sugestões
  • Resposta: sugestões
  • Erros: sugestões
  • Veja também