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

Faixas de preço

Lê, substitui ou apaga as faixas que fazem o frete variar com o peso, o valor do carrinho ou o número de itens.

Uma faixa diz: "a partir de X, cobre Y". A plataforma ordena as faixas por dimensão (C, I, W) e, dentro de cada uma, do maior amount para o menor, e usa a primeira que o carrinho alcança. Se a forma tem rate_area_id nas faixas e o destino cai nessa área, só as faixas dessa área são consideradas; senão valem as faixas sem área (e, se não houver nenhuma, todas as faixas do método).

Listar faixas

GET/api/v1/vendor/shipping-methods/{id}/ratesSeller

Lista as faixas de preço de uma forma

Parâmetros de caminho

iduuidobrigatório
Id da forma de envio.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21/rates" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Faixas da forma
json
{
  "rate_tiers": [
    {
      "id": "9b8a7c6d-5e4f-4321-a0b9-c8d7e6f5a4b3",
      "shipping_id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
      "dimension": "W",
      "amount": 1000,
      "value": 2500,
      "value_type": "F",
      "per_unit": false,
      "position": 0
    }
  ],
  "total": 1
}

Campos da resposta

rate_tiersarray | null

Faixas, ordenadas por dimensão, posição e limiar. É null (não []) quando a forma não tem faixas.

iduuid
Id da faixa (gerado pela plataforma).
shipping_iduuid
Id da forma dona da faixa.
rate_area_iduuid | null
Área de tarifa à qual a faixa se limita. Ausente = vale para qualquer destino.
dimensionstring
O que a faixa mede: C valor do carrinho, W peso, I número de itens.
amountinteger
Limiar da faixa: vale a partir deste valor (maior ou igual). C em centavos, W em gramas, I em unidades.
valueinteger
Preço da faixa. Com value_type F, centavos; com P, pontos-base do valor do carrinho (1000 = 10%).
value_typestring
F valor fixo ou P percentual.
per_unitboolean
Multiplica o preço pelos kg (arredondados para cima, mínimo 1) em W, ou pelo número de itens em I. Não tem efeito em C.
positioninteger
Posição na lista, definida pela ordem em que você enviou.
totalinteger
Quantidade de faixas.

Erros: listar

StatusQuandoCorpo de exemplo
400O id não é um UUID válido.{"error":"invalid id","detail":"id must be a valid UUID"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403A forma existe, mas pertence a outro seller ou à loja inteira.{"error":"forbidden","detail":"shipping method does not belong to this vendor"}
404Não existe forma com esse id.{"error":"shipping method not found"}

Substituir todas as faixas

Apaga as faixas atuais e grava as enviadas, na mesma transação: se uma falhar, nada muda. A posição de cada faixa é a ordem do vetor. Mande {"rate_tiers": []} para remover todas.

PUT/api/v1/vendor/shipping-methods/{id}/ratesSeller

Substitui todas as faixas de preço de uma forma

Parâmetros de caminho

iduuidobrigatório
Id da forma de envio.

Corpo da requisição

rate_tiersarrayobrigatório

Lista completa de faixas desejadas.

dimensionstringobrigatório
CWI
C valor do carrinho, W peso ou I itens.
amountintegerpadrão: 0
Limiar: a faixa vale quando o carrinho é maior ou igual a ele. C em centavos, W em gramas, I em unidades.
valueintegerpadrão: 0
Preço: centavos (F) ou pontos-base (P).
value_typestringobrigatório
FP
F valor fixo ou P percentual do carrinho.
per_unitbooleanpadrão: false
Multiplica por kg (W) ou por item (I).
rate_area_iduuid
Limita a faixa a uma área de tarifa. Vazio = qualquer destino.

Exemplo de requisição: substituir

bash
curl -X PUT "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21/rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_tiers": [
      {
        "dimension": "W",
        "amount": 0,
        "value": 1500,
        "value_type": "F",
        "per_unit": false
      },
      {
        "dimension": "W",
        "amount": 5000,
        "value": 2500,
        "value_type": "F",
        "per_unit": false
      }
    ]
  }'

Resposta: substituir

200Faixas gravadas
json
{
  "rate_tiers": [
    {
      "id": "9b8a7c6d-5e4f-4321-a0b9-c8d7e6f5a4b3",
      "shipping_id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
      "dimension": "W",
      "amount": 5000,
      "value": 2500,
      "value_type": "F",
      "per_unit": false,
      "position": 1
    },
    {
      "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
      "shipping_id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
      "dimension": "W",
      "amount": 0,
      "value": 1500,
      "value_type": "F",
      "per_unit": false,
      "position": 0
    }
  ],
  "total": 2
}

Campos da resposta

rate_tiersarray
Faixas gravadas (mesmos campos de "Listar faixas").
totalinteger
Quantidade.

Erros: substituir

StatusQuandoCorpo de exemplo
400O id não é um UUID válido.{"error":"invalid id","detail":"id must be a valid UUID"}
400Corpo que não é JSON.{"error":"invalid request body"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403A forma existe, mas pertence a outro seller ou à loja inteira.{"error":"forbidden","detail":"shipping method does not belong to this vendor"}
404Não existe forma com esse id.{"error":"shipping method not found"}
500Faixa inválida (por exemplo dimension fora de C, W, I). A transação inteira é desfeita.{"error":"failed to set rate tiers"}
É substituição, não acréscimo

Reenvie as faixas que quer manter. Os ids das faixas mudam a cada PUT; não guarde ids antigos. As faixas não são validadas na entrada: um valor inválido só aparece como 500.

Apagar uma faixa

DELETE/api/v1/vendor/shipping-methods/{id}/rates/{tierId}Seller

Apaga uma faixa de preço

Parâmetros de caminho

iduuidobrigatório
Id da forma de envio.
tierIduuidobrigatório
Id da faixa (campo id de "Listar faixas").

Exemplo de requisição: apagar

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21/rates/9b8a7c6d-5e4f-4321-a0b9-c8d7e6f5a4b3" \
  -H "Authorization: Bearer $TOKEN"

Resposta: apagar

200Faixa apagada
json
{
  "message": "rate tier deleted"
}

Campos da resposta

messagestring
Texto fixo de confirmação.

Erros: apagar

StatusQuandoCorpo de exemplo
400O id não é um UUID válido.{"error":"invalid id","detail":"id must be a valid UUID"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403A forma existe, mas pertence a outro seller ou à loja inteira.{"error":"forbidden","detail":"shipping method does not belong to this vendor"}
404Não existe forma com esse id.{"error":"shipping method not found"}
500A faixa não existe.{"error":"failed to delete rate tier"}
Faixa inexistente dá 500

A rota confere que a forma é sua, mas não que a faixa pertence a ela. Um tierId que não existe responde 500, e não 404. Use sempre ids que acabou de listar.

Veja também

  • Criar forma de envio
  • Áreas de tarifa
  • Visão geral
Anterior
Alterar e apagar forma
Próxima
Endereço de retirada
Nesta página
  • Listar faixas
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Substituir todas as faixas
  • Exemplo de requisição: substituir
  • Resposta: substituir
  • Erros: substituir
  • Apagar uma faixa
  • Exemplo de requisição: apagar
  • Resposta: apagar
  • Erros: apagar
  • Veja também