Calcular o carrinho

Calcula subtotal, descontos de promoção e cupom, frete, impostos e total do carrinho, com o detalhe por item e por seller.

Esta é a rota que responde "quanto vai custar?". Ela roda o mesmo cálculo que o checkout e o pedido usam: aplica promoções de catálogo e de carrinho, cupons, kits, vale-presente, frete e impostos sobre as linhas do carrinho e devolve os valores prontos para exibir. Chame depois de cada mudança no carrinho, quando o CEP for digitado e quando o comprador escolher uma forma de entrega.

A rota não altera o carrinho nem grava nada: é uma simulação. O carrinho é sempre o do próprio comprador (token ou X-Session-ID); o corpo não aceita cart_id, justamente para ninguém calcular o carrinho de outra pessoa.

POST/api/v1/storefront/cart/calculateAutenticada

Calcula os totais, descontos e frete do carrinho

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado. Com token, grupos de cliente e preços B2B entram no cálculo.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

shipping_method_iduuid

Forma de entrega escolhida, para incluir o frete no total.

shipping_selectionsarray

Uma forma de entrega por seller, para carrinhos com vários sellers. Quando enviada, tem prioridade sobre shipping_method_id.

shipping_selections[].vendor_iduuidobrigatório

Seller (lojista) da seleção.

shipping_selections[].shipping_method_iduuidobrigatório

Forma de entrega desse seller.

shipping_selections[].service_codestring

Serviço específico da transportadora (por exemplo PAC ou SEDEX), quando o método agrega vários.

coupon_codestring

Um cupom ou voucher para simular. Pode ser omitido: se o carrinho já tem cupom gravado (veja Cupons), ele é usado.

coupon_codesarray

Vários cupons. Uma lista não vazia substitui os gravados no carrinho; vazia ou omitida, valem os gravados.

destination_postal_codestring

CEP de entrega, 8 dígitos, com ou sem hífen. Um CEP inválido devolve 400 invalid_postal_code.

destination_statestring

UF de entrega (SP). Entra em regras de preço e imposto por estado.

destination_city_codestring

Código IBGE de 7 dígitos do município, usado no ISS municipal. Mantenha como texto, os zeros à esquerda importam.

destination_address_iduuid

Endereço salvo do cliente. Usado só para áreas de entrega desenhadas no mapa.

destination_streetstring

Rua de entrega. Mesmo uso do campo anterior.

destination_numberstring

Número de entrega. Mesmo uso.

destination_districtstring

Bairro de entrega. Mesmo uso.

destination_citystring

Cidade de entrega. Mesmo uso.

gift_cert_codestring

Código de vale-presente. Um código inválido ou vencido não gera erro: o motivo volta em gift_cert_warning.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/calculate" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "destination_postal_code": "01310-100",
  "destination_state": "SP"
}'

Resposta

200Cálculo do carrinho

json

{
  "subtotal": 23000,
  "discount": 5750,
  "shipping": 0,
  "tax": 0,
  "total": 17250,
  "items": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Notebook Slim Rosa 02373",
      "quantity": 2,
      "unit_price": 11500,
      "subtotal": 23000,
      "discount": 5750,
      "tax": 0,
      "total": 17250
    }
  ],
  "promotions": [
    { "promotion_id": "", "name": "Promoções de catálogo", "discount": 4600, "type": "catalog" },
    { "promotion_id": "c19df8c2-279f-46c3-81e4-d1e52aec733c", "name": "Progressiva 5% acima de R$ 100", "discount": 1150, "type": "percentage" },
    { "promotion_id": "", "name": "Frete grátis", "discount": 0, "type": "free_shipping" }
  ],
  "vendors": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "shipping": 0, "weight": 600, "item_count": 1 }
  ],
  "item_discount": 5750,
  "order_discount": 0,
  "tax_amount": 0,
  "shipping_cost": 0,
  "free_shipping": true
}

Campos da resposta

subtotalinteger

Soma de preço unitário vezes quantidade, em centavos. Já reflete preços B2B e de faixa de quantidade.

discountinteger

Desconto total em centavos: promoções de item, promoções de carrinho, cupom e vale-presente somados.

item_discountinteger

Parte de discount vinda de promoções de catálogo e de item.

order_discountinteger

Parte de discount vinda de cupom.

b2b_discountinteger

Redução de preço por contrato ou faixa B2B. É informativa: já está dentro de subtotal e não é subtraída outra vez. Ausente quando é zero.

shippinginteger

Frete total em centavos, somando todos os sellers. Também aparece como shipping_cost.

taxinteger

Impostos em centavos. Também aparece como tax_amount.

totalinteger

Total final em centavos: subtotal - discount + shipping + tax, nunca negativo.

free_shippingboolean

true quando alguma promoção ou cupom concede frete grátis.

itemsarray

Detalhe por linha. O desconto do carrinho é distribuído entre as linhas na proporção do subtotal de cada uma, e o resto da divisão fica na linha mais cara.

items[].product_iduuid

Produto.

items[].variation_idstring

Variação, quando existe.

items[].vendor_iduuid

Seller da linha.

items[].subtotalinteger

unit_price vezes quantity, em centavos.

items[].discountinteger

Parte do desconto atribuída à linha.

items[].taxinteger

Parte dos impostos atribuída à linha.

items[].totalinteger

subtotal - discount + tax da linha.

promotionsarray

Promoções e cupons aplicados, para mostrar ao comprador o que gerou desconto.

promotions[].promotion_idstring

Id da promoção. Vazio nas linhas sintéticas ("Promoções de catálogo", "Frete grátis").

promotions[].namestring

Nome da promoção como o lojista cadastrou.

promotions[].discountinteger

Desconto em centavos dessa promoção.

promotions[].typestring

Tipo: catalog, percentage, fixed, free_shipping, buy_x_get_y. Outros valores (como multi) podem aparecer; trate como texto livre.

promotions[].coupon_codestring

Presente quando a promoção foi ativada por um cupom.

applied_couponobject

Primeiro cupom aplicado: code, discount (centavos) e kind (coupon ou voucher). Ausente sem cupom.

vendorsarray

Frete por seller, para carrinhos de marketplace: vendor_id, shipping (centavos), weight (gramas) e item_count.

removed_itemsarray

Linhas que não entraram no cálculo, por exemplo porque o seller está inativo.

shipping_unavailableboolean

true quando a forma de entrega escolhida não conseguiu cotar. Nesse caso shipping é 0 por falta de preço, não por ser grátis. Ausente quando false.

gift_cert_codestring

Vale-presente aplicado, quando houver.

gift_cert_amountinteger

Valor do vale-presente descontado, em centavos. Já está dentro de discount e total.

gift_cert_warningstring

Motivo, quando o vale-presente enviado era inválido ou vencido.

change_linesarray

Taxas e descontos extras que uma regra própria da loja adicionou. Ausente na maioria das lojas.

change_hooksobject

Resumo do que a regra própria da loja alterou. Ausente na maioria das lojas.

Erros

Status	Quando	Corpo
400	Sem token e sem `X-Session-ID`	`{"error":"session_id or authentication required"}`
400	Corpo que não é JSON	`{"error":"invalid request body"}`
400	CEP que não tem 8 dígitos válidos	`{"error":"invalid_postal_code","detail":"..."}`
409	A forma de entrega escolhida deixou de cotar para este carrinho	`{"error":"shipping_requote_required","vendor_id":"...","detail":"..."}`
500	Falha interna no cálculo	`{"error":"failed to calculate cart","detail":"..."}`

Veja também

Calcular o carrinho

Calcula subtotal, descontos de promoção e cupom, frete, impostos e total do carrinho, com o detalhe por item e por seller.

POST/api/v1/storefront/cart/calculateAutenticada

Calcula os totais, descontos e frete do carrinho

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado. Com token, grupos de cliente e preços B2B entram no cálculo.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

shipping_method_iduuid

Forma de entrega escolhida, para incluir o frete no total.

shipping_selectionsarray

Uma forma de entrega por seller, para carrinhos com vários sellers. Quando enviada, tem prioridade sobre shipping_method_id.

shipping_selections[].vendor_iduuidobrigatório

Seller (lojista) da seleção.

shipping_selections[].shipping_method_iduuidobrigatório

Forma de entrega desse seller.

shipping_selections[].service_codestring

Serviço específico da transportadora (por exemplo PAC ou SEDEX), quando o método agrega vários.

coupon_codestring

Um cupom ou voucher para simular. Pode ser omitido: se o carrinho já tem cupom gravado (veja Cupons), ele é usado.

coupon_codesarray

Vários cupons. Uma lista não vazia substitui os gravados no carrinho; vazia ou omitida, valem os gravados.

destination_postal_codestring

CEP de entrega, 8 dígitos, com ou sem hífen. Um CEP inválido devolve 400 invalid_postal_code.

destination_statestring

UF de entrega (SP). Entra em regras de preço e imposto por estado.

destination_city_codestring

Código IBGE de 7 dígitos do município, usado no ISS municipal. Mantenha como texto, os zeros à esquerda importam.

destination_address_iduuid

Endereço salvo do cliente. Usado só para áreas de entrega desenhadas no mapa.

destination_streetstring

Rua de entrega. Mesmo uso do campo anterior.

destination_numberstring

Número de entrega. Mesmo uso.

destination_districtstring

Bairro de entrega. Mesmo uso.

destination_citystring

Cidade de entrega. Mesmo uso.

gift_cert_codestring

Código de vale-presente. Um código inválido ou vencido não gera erro: o motivo volta em gift_cert_warning.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/cart/calculate" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "destination_postal_code": "01310-100",
  "destination_state": "SP"
}'

Resposta

200Cálculo do carrinho

json

{
  "subtotal": 23000,
  "discount": 5750,
  "shipping": 0,
  "tax": 0,
  "total": 17250,
  "items": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Notebook Slim Rosa 02373",
      "quantity": 2,
      "unit_price": 11500,
      "subtotal": 23000,
      "discount": 5750,
      "tax": 0,
      "total": 17250
    }
  ],
  "promotions": [
    { "promotion_id": "", "name": "Promoções de catálogo", "discount": 4600, "type": "catalog" },
    { "promotion_id": "c19df8c2-279f-46c3-81e4-d1e52aec733c", "name": "Progressiva 5% acima de R$ 100", "discount": 1150, "type": "percentage" },
    { "promotion_id": "", "name": "Frete grátis", "discount": 0, "type": "free_shipping" }
  ],
  "vendors": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "shipping": 0, "weight": 600, "item_count": 1 }
  ],
  "item_discount": 5750,
  "order_discount": 0,
  "tax_amount": 0,
  "shipping_cost": 0,
  "free_shipping": true
}

Campos da resposta

subtotalinteger

Soma de preço unitário vezes quantidade, em centavos. Já reflete preços B2B e de faixa de quantidade.

discountinteger

Desconto total em centavos: promoções de item, promoções de carrinho, cupom e vale-presente somados.

item_discountinteger

Parte de discount vinda de promoções de catálogo e de item.

order_discountinteger

Parte de discount vinda de cupom.

b2b_discountinteger

Redução de preço por contrato ou faixa B2B. É informativa: já está dentro de subtotal e não é subtraída outra vez. Ausente quando é zero.

shippinginteger

Frete total em centavos, somando todos os sellers. Também aparece como shipping_cost.

taxinteger

Impostos em centavos. Também aparece como tax_amount.

totalinteger

Total final em centavos: subtotal - discount + shipping + tax, nunca negativo.

free_shippingboolean

true quando alguma promoção ou cupom concede frete grátis.

itemsarray

Detalhe por linha. O desconto do carrinho é distribuído entre as linhas na proporção do subtotal de cada uma, e o resto da divisão fica na linha mais cara.

items[].product_iduuid

Produto.

items[].variation_idstring

Variação, quando existe.

items[].vendor_iduuid

Seller da linha.

items[].subtotalinteger

unit_price vezes quantity, em centavos.

items[].discountinteger

Parte do desconto atribuída à linha.

items[].taxinteger

Parte dos impostos atribuída à linha.

items[].totalinteger

subtotal - discount + tax da linha.

promotionsarray

Promoções e cupons aplicados, para mostrar ao comprador o que gerou desconto.

promotions[].promotion_idstring

Id da promoção. Vazio nas linhas sintéticas ("Promoções de catálogo", "Frete grátis").

promotions[].namestring

Nome da promoção como o lojista cadastrou.

promotions[].discountinteger

Desconto em centavos dessa promoção.

promotions[].typestring

Tipo: catalog, percentage, fixed, free_shipping, buy_x_get_y. Outros valores (como multi) podem aparecer; trate como texto livre.

promotions[].coupon_codestring

Presente quando a promoção foi ativada por um cupom.

applied_couponobject

Primeiro cupom aplicado: code, discount (centavos) e kind (coupon ou voucher). Ausente sem cupom.

vendorsarray

Frete por seller, para carrinhos de marketplace: vendor_id, shipping (centavos), weight (gramas) e item_count.

removed_itemsarray

Linhas que não entraram no cálculo, por exemplo porque o seller está inativo.

shipping_unavailableboolean

true quando a forma de entrega escolhida não conseguiu cotar. Nesse caso shipping é 0 por falta de preço, não por ser grátis. Ausente quando false.

gift_cert_codestring

Vale-presente aplicado, quando houver.

gift_cert_amountinteger

Valor do vale-presente descontado, em centavos. Já está dentro de discount e total.

gift_cert_warningstring

Motivo, quando o vale-presente enviado era inválido ou vencido.

change_linesarray

Taxas e descontos extras que uma regra própria da loja adicionou. Ausente na maioria das lojas.

change_hooksobject

Resumo do que a regra própria da loja alterou. Ausente na maioria das lojas.

Erros

Status	Quando	Corpo
400	Sem token e sem `X-Session-ID`	`{"error":"session_id or authentication required"}`
400	Corpo que não é JSON	`{"error":"invalid request body"}`
400	CEP que não tem 8 dígitos válidos	`{"error":"invalid_postal_code","detail":"..."}`
409	A forma de entrega escolhida deixou de cotar para este carrinho	`{"error":"shipping_requote_required","vendor_id":"...","detail":"..."}`
500	Falha interna no cálculo	`{"error":"failed to calculate cart","detail":"..."}`