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

Tarifas por degrau

Lê, substitui e apaga a tabela de tarifas por degrau de um método, com degraus por valor do pedido, peso ou itens.

As tarifas por degrau são uma tabela de preços simples: uma lista de degraus, cada um com uma dimension (o que se mede), um limiar amount ("acima de X") e um valor value (quanto cobrar). Elas servem a quem cobra por um único critério de cada vez. Quando precisar combinar limites de valor, peso e itens, prefira as faixas de preço, que têm limites mínimo e máximo explícitos.

Unidades
  • dimension: "C": amount é o valor do pedido em centavos.
  • dimension: "W": amount é o peso em gramas.
  • dimension: "I": amount é a quantidade de itens.
  • value_type: "F": value é um valor fixo em centavos. value_type: "P": value é um percentual em pontos-base (1000 = 10,00%).

Listar tarifas

GET/api/v1/admin/shipping-methods/{id}/ratesAdmin

Lista as tarifas por degrau de um método

Parâmetros de caminho

iduuidobrigatório
Id do método.

Exemplo de requisição

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

Resposta

200Tarifas retornadas
json
{
  "rate_tiers": [
    {
      "id": "ab5e484a-9ffa-4b7d-bbfa-165450c01b45",
      "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "dimension": "C",
      "amount": 10000,
      "value": 1200,
      "value_type": "F",
      "per_unit": false,
      "position": 0
    }
  ],
  "total": 1
}

Campos da resposta

rate_tiersarray
Degraus do método (o nome do campo é rate_tiers). null quando não há nenhum.
totalinteger
Quantidade de degraus.
rate_tiers[].iduuid
Id do degrau.
rate_tiers[].shipping_iduuid
Método dono.
rate_tiers[].rate_area_iduuid
Área de tarifa do degrau. Ausente = vale para qualquer área.
rate_tiers[].dimensionstring
CWI
O que se mede.
rate_tiers[].amountinteger
Limiar "acima de" na unidade da dimensão.
rate_tiers[].valueinteger
Valor a cobrar: centavos (F) ou pontos-base (P).
rate_tiers[].value_typestring
FP
Tipo do valor.
rate_tiers[].per_unitboolean
Se o valor é multiplicado pelo peso ou pela quantidade de itens.
rate_tiers[].positioninteger
Ordem do degrau na lista.

Substituir a tabela

Apaga todos os degraus do método e grava os enviados, na mesma transação, na ordem do vetor (position é preenchido pela posição, o que você enviar é ignorado). Enviar rate_tiers: [] esvazia a tabela.

PUT/api/v1/admin/shipping-methods/{id}/ratesAdmin

Substitui as tarifas por degrau de um método

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório
Id do método.

Corpo da requisição

rate_tiersarrayobrigatório

Lista completa de degraus.

dimensionstringobrigatório
CWI
O que se mede.
amountinteger
Limiar "acima de".
valueinteger
Valor a cobrar.
value_typestringobrigatório
FP
Tipo do valor.
per_unitbooleanpadrão: false
Multiplica por peso ou itens.
rate_area_iduuid
Área de tarifa do degrau. Omita para qualquer área.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_tiers": [
      {
        "dimension": "C",
        "amount": 10000,
        "value": 1200,
        "value_type": "F"
      },
      {
        "dimension": "C",
        "amount": 20000,
        "value": 0,
        "value_type": "F"
      }
    ]
  }'

Resposta

200Tabela substituída
json
{
  "rate_tiers": [
    {
      "id": "b51823d3-924f-406e-888d-a6020746655a",
      "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "dimension": "C",
      "amount": 10000,
      "value": 1200,
      "value_type": "F",
      "per_unit": false,
      "position": 0
    },
    {
      "id": "c1e3d6a2-0b6e-4a55-8f43-6a5c3d3b1e11",
      "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "dimension": "C",
      "amount": 20000,
      "value": 0,
      "value_type": "F",
      "per_unit": false,
      "position": 1
    }
  ],
  "total": 2
}

Apagar um degrau

DELETE/api/v1/admin/shipping-methods/{id}/rates/{tierId}Admin

Apaga um degrau de tarifa por degrau

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório
Id do método.
tierIduuidobrigatório
Id do degrau.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/rates/$STEP_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Degrau apagado
json
{
  "message": "rate tier deleted"
}

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, ou tierId que não é UUID{"error":"invalid request body","detail":"..."}
500dimension ou value_type fora dos valores aceitos (a gravação inteira é desfeita), método inexistente, ou degrau que não existe{"error":"failed to set rate tiers","detail":"..."} / {"error":"failed to delete rate tier","detail":"rate tier not found: ..."}
O DELETE ignora o método do caminho

DELETE .../rates/{tierId} apaga o degrau pelo tierId, sem conferir se ele pertence ao método do caminho. Use sempre o id lido da listagem do método certo.

Gravação atômica

Se algum degrau do PUT for inválido, nada é gravado e a tabela anterior continua intacta.

Veja também

  • Faixas de preço
  • Apagar e duplicar
  • Criar um método
Anterior
Faixas de preço
Próxima
Áreas do método
Nesta página
  • Listar tarifas
  • Exemplo de requisição
  • Resposta
  • Substituir a tabela
  • Exemplo de requisição
  • Resposta
  • Apagar um degrau
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também