API atual/Referência completa/Frete e entrega

Pedido mínimo e frete grátis

Calcula o pedido mínimo efetivo do carrinho e o progresso do cliente rumo ao frete grátis.

Duas rotas do carrinho: uma diz o mínimo que o cliente precisa comprar, a outra diz quanto falta para o frete grátis.

Pedido mínimo efetivo

POST/api/v1/storefront/shipping/effective-min-orderPública

Pedido mínimo efetivo do carrinho

Calcula o pedido mínimo que o cliente precisa atingir, juntando as regras da loja, dos sellers do carrinho e do destino. Corpo vazio é aceito (vira "sem endereço e sem sellers").

Corpo da requisição

postal_codestring

CEP do destino. Habilita as regras por destino e o desbloqueio de frete.

state_codestring

UF do destino. Deduzida do CEP quando omitida.

country_codestringpadrão: BR

País do destino.

vendor_idsuuid[]

Sellers presentes no carrinho. Repetidos e vazios são descartados.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/shipping/effective-min-order" \
  -H "Content-Type: application/json" \
  -d '{
  "postal_code": "01310-100",
  "vendor_ids": [
    "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
  ]
}'

Resposta

200Mínimo efetivo

json

{
  "min_order_amount": 15000,
  "global_min": 10000,
  "vendor_min": 15000,
  "shipping_min": 0,
  "destination_min": 0,
  "vendor_effective": { "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36": 15000 }
}

Campos da resposta

min_order_amountinteger

O mínimo que o cliente precisa atingir, em centavos: o maior entre os mínimos efetivos dos sellers do carrinho.

global_mininteger

Mínimo configurado para a loja toda, em centavos.

vendor_mininteger

O maior mínimo entre os sellers do carrinho, em centavos. 0 sem sellers.

shipping_mininteger

Menor valor de carrinho em que todos os sellers conseguem ter ao menos um método de frete para o destino. 0 quando não se sabe ou quando valor nenhum resolve. É informativo: não aumenta o min_order_amount.

destination_mininteger

Mínimo da área de tarifa em que o destino cai, em centavos. 0 quando desconhecido. Quando maior que zero, vale para o seller mesmo que seja menor que o mínimo dele ou o da loja.

region_unavailableboolean

Presente (true) quando a região do destino não pôde ser lida; então min_order_amount é o mais rigoroso entre seller e loja.

vendor_effectiveobject

Por seller (chave: id), o mínimo efetivo em centavos. Ausente sem sellers.

vendor_minsobject

Por seller, o mínimo cadastrado por ele. Ausente quando não há.

Erros

Status	Quando	Corpo
500	Falha ao resolver o mínimo.	`{"error":"failed to resolve effective min order","detail":"..."}`

Progresso do frete grátis

GET/api/v1/storefront/shipping/free-shipping-statusPública

Progresso do cliente rumo ao frete grátis

Alimenta a barra "faltam R$ X para o frete grátis". O servidor encontra o limite de frete grátis que vale para o CEP (regional ou nacional) e compara com o subtotal informado.

Parâmetros de consulta

postal_codestring

CEP do visitante. Sem ele vale o limite nacional, quando existe.

subtotal_centsinteger

Subtotal elegível do carrinho em centavos, depois dos descontos de produto e antes do frete. Valor ausente ou inválido vale 0.

coupon_codestring

Cupom aplicado. Se ele (ou qualquer promoção) já dá frete grátis, a barra marca como atingida.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/shipping/free-shipping-status?postal_code=01310100&subtotal_cents=5000"

Resposta

200Faltam R$ 50,00

json

{
  "eligible": true,
  "threshold_cents": 10000,
  "remaining_cents": 5000,
  "achieved": false,
  "promotion_name": "Frete grátis São Paulo"
}

200Sem frete grátis configurado

json

{ "eligible": false, "threshold_cents": 0, "remaining_cents": 0, "achieved": false }

Campos da resposta

eligibleboolean

true quando existe um limite de frete grátis para este visitante. Com false, esconda a barra.

threshold_centsinteger

O limite, em centavos. 0 quando não elegível.

remaining_centsinteger

Quanto falta, em centavos (nunca negativo).

achievedboolean

true quando o subtotal já alcança o limite, ou quando uma promoção ou cupom já dá frete grátis.

promotion_namestring

Nome da regra de frete grátis aplicada. Ausente no limite nacional.

Erros

Status	Quando	Corpo
500	Falha ao ler a regra de frete grátis.	`{"error":"failed to resolve free-shipping status","detail":"..."}`

Veja também

Pedido mínimo e frete grátis

Calcula o pedido mínimo efetivo do carrinho e o progresso do cliente rumo ao frete grátis.

Duas rotas do carrinho: uma diz o mínimo que o cliente precisa comprar, a outra diz quanto falta para o frete grátis.

Pedido mínimo efetivo

POST/api/v1/storefront/shipping/effective-min-orderPública

Pedido mínimo efetivo do carrinho

Calcula o pedido mínimo que o cliente precisa atingir, juntando as regras da loja, dos sellers do carrinho e do destino. Corpo vazio é aceito (vira "sem endereço e sem sellers").

Corpo da requisição

postal_codestring

CEP do destino. Habilita as regras por destino e o desbloqueio de frete.

state_codestring

UF do destino. Deduzida do CEP quando omitida.

country_codestringpadrão: BR

País do destino.

vendor_idsuuid[]

Sellers presentes no carrinho. Repetidos e vazios são descartados.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/shipping/effective-min-order" \
  -H "Content-Type: application/json" \
  -d '{
  "postal_code": "01310-100",
  "vendor_ids": [
    "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
  ]
}'

Resposta

200Mínimo efetivo

json

{
  "min_order_amount": 15000,
  "global_min": 10000,
  "vendor_min": 15000,
  "shipping_min": 0,
  "destination_min": 0,
  "vendor_effective": { "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36": 15000 }
}

Campos da resposta

min_order_amountinteger

O mínimo que o cliente precisa atingir, em centavos: o maior entre os mínimos efetivos dos sellers do carrinho.

global_mininteger

Mínimo configurado para a loja toda, em centavos.

vendor_mininteger

O maior mínimo entre os sellers do carrinho, em centavos. 0 sem sellers.

shipping_mininteger

destination_mininteger

Mínimo da área de tarifa em que o destino cai, em centavos. 0 quando desconhecido. Quando maior que zero, vale para o seller mesmo que seja menor que o mínimo dele ou o da loja.

region_unavailableboolean

Presente (true) quando a região do destino não pôde ser lida; então min_order_amount é o mais rigoroso entre seller e loja.

vendor_effectiveobject

Por seller (chave: id), o mínimo efetivo em centavos. Ausente sem sellers.

vendor_minsobject

Por seller, o mínimo cadastrado por ele. Ausente quando não há.

Erros

Status	Quando	Corpo
500	Falha ao resolver o mínimo.	`{"error":"failed to resolve effective min order","detail":"..."}`

Progresso do frete grátis

GET/api/v1/storefront/shipping/free-shipping-statusPública

Progresso do cliente rumo ao frete grátis

Alimenta a barra "faltam R$ X para o frete grátis". O servidor encontra o limite de frete grátis que vale para o CEP (regional ou nacional) e compara com o subtotal informado.

Parâmetros de consulta

postal_codestring

CEP do visitante. Sem ele vale o limite nacional, quando existe.

subtotal_centsinteger

Subtotal elegível do carrinho em centavos, depois dos descontos de produto e antes do frete. Valor ausente ou inválido vale 0.

coupon_codestring

Cupom aplicado. Se ele (ou qualquer promoção) já dá frete grátis, a barra marca como atingida.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/shipping/free-shipping-status?postal_code=01310100&subtotal_cents=5000"

Resposta

200Faltam R$ 50,00

json

{
  "eligible": true,
  "threshold_cents": 10000,
  "remaining_cents": 5000,
  "achieved": false,
  "promotion_name": "Frete grátis São Paulo"
}

200Sem frete grátis configurado

json

{ "eligible": false, "threshold_cents": 0, "remaining_cents": 0, "achieved": false }

Campos da resposta

eligibleboolean

true quando existe um limite de frete grátis para este visitante. Com false, esconda a barra.

threshold_centsinteger

O limite, em centavos. 0 quando não elegível.

remaining_centsinteger

Quanto falta, em centavos (nunca negativo).

achievedboolean

true quando o subtotal já alcança o limite, ou quando uma promoção ou cupom já dá frete grátis.

promotion_namestring

Nome da regra de frete grátis aplicada. Ausente no limite nacional.

Erros

Status	Quando	Corpo
500	Falha ao ler a regra de frete grátis.	`{"error":"failed to resolve free-shipping status","detail":"..."}`