VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Métodos de envio

Políticas de frete

Cria regras que ajustam o frete cotado: somam ou descontam valores, zeram o frete acima de um subtotal, escondem métodos ou limitam as opções.

Uma política de frete muda a lista de opções que o cliente vê depois que os métodos foram cotados, sem editar os métodos. É a ferramenta para campanhas e contingências: "frete grátis acima de R$ 300", "Expressa 10% mais cara no Nordeste", "esconder o SEDEX por uma semana". As políticas ativas rodam em ordem de priority (menor primeiro) e cada uma enxerga o resultado da anterior.

Uma política pode ser restrita a uma área de tarifa (rate_area_id) e a um método (method_code). Sem restrição, vale para todos.

rule_typeO que fazCampos de params
free_aboveZera o frete (e marca free_shipping) se o subtotal do carrinho for maior ou igual ao mínimo.min_subtotal_cents (obrigatório, maior que 0)
markupSoma um valor ao frete.value_type (F centavos ou P pontos-base) e value (maior que 0)
discountSubtrai um valor do frete, sem passar de zero.value_type e value, como em markup
hide_methodRemove o método das opções.Exige method_code (coluna ou em params)
limit_optionsLimita e ordena as opções: remove as mais lentas que max_transit_days, ordena por sort e mantém só as max primeiras.max, max_transit_days, sort (price ou transit); ao menos um deles

Em markup e discount com value_type: "P", value é em pontos-base (1000 = 10%). Com F, é em centavos.

Listar políticas

GET/api/v1/admin/shipping/policiesAdmin

Lista as políticas de frete

Devolve as políticas ativas e desativadas, ordenadas por prioridade. As apagadas não aparecem.

Exemplo de requisição

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

Resposta

200Políticas retornadas
json
{
  "policies": [
    {
      "id": "605bfa9e-3307-488e-94e5-910561ce03d8",
      "name": "Frete grátis acima de R$ 300",
      "rule_type": "free_above",
      "priority": 100,
      "status": "active",
      "params": {
        "min_subtotal_cents": 30000
      }
    }
  ]
}

Campos da resposta

policiesarray

Políticas.

iduuid
Id da política.
namestring
Nome.
rule_typestring
Tipo da regra.
priorityinteger
Prioridade (menor primeiro).
statusstring
active ou disabled.
rate_area_iduuid
Área restrita. Ausente = todas.
method_codestring
Método alvo. Ausente = todos.
paramsobject
Parâmetros da regra.

Criar uma política

Uma política disabled é um rascunho: pode ser salva incompleta e não altera nenhuma cotação. Uma política active precisa estar completa.

POST/api/v1/admin/shipping/policiesAdmin

Cria uma política de frete

Exige manage_shipping.

Corpo da requisição

namestringobrigatório
Nome da política.
rule_typestringobrigatório
limit_optionsmarkupdiscountfree_abovehide_method
Tipo da regra.
priorityinteger
Ordem de aplicação: menor primeiro. Na criação, vazio ou 0 vira 100. Na alteração, o valor enviado é gravado como está.
statusstring
activedisabled
active ou disabled. Qualquer outro texto vira active.
rate_area_iduuid
Restringe a regra a uma área de tarifa. Omita para valer em todo lugar.
method_codestring
code do método alvo. Omita (ou *) para valer em todos os métodos.
paramsobject
Parâmetros da regra, conforme o tipo (veja a tabela abaixo).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/shipping/policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frete grátis acima de R$ 300",
    "rule_type": "free_above",
    "params": {
      "min_subtotal_cents": 30000
    }
  }'

Resposta

201Política criada
json
{
  "id": "605bfa9e-3307-488e-94e5-910561ce03d8",
  "name": "Frete grátis acima de R$ 300",
  "rule_type": "free_above",
  "priority": 100,
  "status": "active",
  "params": {
    "min_subtotal_cents": 30000
  }
}

Alterar uma política

Substitui a política inteira: envie todos os campos. O retorno é só uma confirmação.

PUT/api/v1/admin/shipping/policies/{id}Admin

Altera uma política de frete

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório
Id da política.

Corpo da requisição

namestringobrigatório
Nome da política.
rule_typestringobrigatório
limit_optionsmarkupdiscountfree_abovehide_method
Tipo da regra.
priorityinteger
Ordem de aplicação: menor primeiro. Na criação, vazio ou 0 vira 100. Na alteração, o valor enviado é gravado como está.
statusstring
activedisabled
active ou disabled. Qualquer outro texto vira active.
rate_area_iduuid
Restringe a regra a uma área de tarifa. Omita para valer em todo lugar.
method_codestring
code do método alvo. Omita (ou *) para valer em todos os métodos.
paramsobject
Parâmetros da regra, conforme o tipo (veja a tabela abaixo).

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/shipping/policies/$POLICY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frete grátis acima de R$ 300",
    "rule_type": "free_above",
    "params": {
      "min_subtotal_cents": 30000
    },
    "priority": 50,
    "status": "disabled"
  }'

Resposta

200Política alterada
json
{
  "message": "updated"
}

Apagar uma política

DELETE/api/v1/admin/shipping/policies/{id}Admin

Apaga uma política de frete

Exige manage_shipping. Exclusão lógica.

Parâmetros de caminho

iduuidobrigatório
Id da política.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/shipping/policies/$POLICY_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Política apagada
json
{
  "message": "deleted"
}

Simular as políticas

Mostra o efeito das políticas ativas sobre os métodos ativos da loja, antes e depois, para um CEP e um subtotal. Não grava nada. O "antes" usa o preço fixo (flat_rate) de cada método: métodos cobrados por faixa ou por transportadora aparecem com custo 0. Se a loja não tem nenhum método ativo, a simulação usa métodos de demonstração.

POST/api/v1/admin/shipping/policies/simulateAdmin

Simula as políticas de frete

Exige manage_shipping, mesmo sendo só leitura.

Corpo da requisição

postal_codestring
CEP de destino, para as políticas restritas a uma área.
subtotal_centsinteger
Subtotal do carrinho em centavos, usado por free_above.
weight_gramsinteger
Aceito, mas hoje não influencia o resultado.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/shipping/policies/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postal_code": "01310-100",
    "subtotal_cents": 35000
  }'

Resposta

200Antes e depois
json
{
  "before": [
    {
      "method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "method_name": "Entrega Padrão",
      "method_code": "entrega_padrao",
      "cost": 1500,
      "estimated_days": 0,
      "min_delivery_days": 0,
      "max_delivery_days": 0,
      "free_shipping": false,
      "is_pickup": false,
      "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "shipping": "Entrega Padrão",
      "rate_str": "15.00"
    }
  ],
  "after": [
    {
      "method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "method_name": "Entrega Padrão",
      "method_code": "entrega_padrao",
      "cost": 0,
      "estimated_days": 0,
      "min_delivery_days": 0,
      "max_delivery_days": 0,
      "free_shipping": true,
      "is_pickup": false,
      "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "shipping": "Entrega Padrão",
      "rate_str": "0.00"
    }
  ]
}

Campos da resposta

beforearray

Opções sem as políticas.

method_iduuid
Id do método.
method_namestring
Nome.
method_codestring
Código.
costinteger
Frete em centavos.
estimated_daysinteger
Prazo em dias (descontinuado).
min_delivery_daysinteger
Prazo mínimo.
max_delivery_daysinteger
Prazo máximo.
free_shippingboolean
Se a opção ficou gratuita.
is_pickupboolean
Se é retirada.
rate_strstring
cost em string decimal (campo duplicado). shipping_id e shipping também são aliases.
afterarray
Opções depois das políticas, no mesmo formato. Pode ter menos itens, outra ordem ou outros custos.

Erros

StatusQuandoCorpo
401Sem token, token inválido ou expirado{"error":"invalid or expired token"}
403Usuário sem o privilégio manage_shipping{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}
400Corpo que não é JSON; name vazio; rule_type desconhecido; params que não é JSON válido; parâmetros incompletos numa política ativa; política que não existe (alterar e apagar){"error":"invalid rule_type: nope"} / {"error":"min_subtotal_cents must be greater than zero"} / {"error":"policy not found"}
500Falha ao simular{"error":"failed to simulate","detail":"..."}

Mensagens de validação por tipo: free_above: min_subtotal_cents must be greater than zero. markup e discount: value_type must be F or P e value must be greater than zero. hide_method: method_code is required. limit_options: max and max_transit_days cannot be negative, sort must be price or transit e limit_options needs max, max_transit_days or sort.

Só a palavra disabled desativa

Qualquer status diferente de disabled (inclusive D, inactive ou vazio) grava a política como ativa. Para pausar, envie exatamente disabled.

Prioridade na alteração

Na criação, priority vazio vira 100; na alteração, um priority ausente grava 0, e a política passa a rodar antes de todas as outras. Reenvie sempre a prioridade que quer.

Regras incompletas não fazem nada

free_above sem valor e hide_method sem método são ignoradas na cotação em vez de agir sobre todos os métodos. É por isso que a API recusa salvá-las ativas.

Veja também

  • Criar um método
  • Monitoramento de entregas
  • Caixas de embalagem
Anterior
Caixas de embalagem
Próxima
Impostos de importação
Nesta página
  • Listar políticas
  • Exemplo de requisição
  • Resposta
  • Criar uma política
  • Exemplo de requisição
  • Resposta
  • Alterar uma política
  • Exemplo de requisição
  • Resposta
  • Apagar uma política
  • Exemplo de requisição
  • Resposta
  • Simular as políticas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também