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

Ler e esvaziar o carrinho

Devolve o carrinho completo, um resumo leve para o mini-carrinho, e permite esvaziar o carrinho de uma vez.

Use estas três rotas para desenhar o carrinho na tela. GET /cart traz tudo (linhas completas, ids, campos técnicos). GET /cart/summary traz só o que um ícone de sacola ou um mini-carrinho precisa. DELETE /cart apaga todas as linhas.

Ler o carrinho cria o carrinho se ele ainda não existir, então a primeira chamada de um visitante novo já devolve um carrinho vazio com id. DELETE esvazia as linhas e zera os totais, mas mantém o registro do carrinho (e o mesmo id).

Ler o carrinho

GET/api/v1/storefront/cartAutenticada

Consulta o carrinho

Cabeçalhos

Authorizationstring
Bearer <token> do cliente logado. Se enviado, ele identifica o carrinho.
X-Session-IDstring
Identificador do visitante (UUID). Obrigatório quando não há token.
X-Organization-Branch-Iduuid
Opcional. Seleciona o carrinho da filial (compra B2B).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/cart" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Carrinho com um item
json
{
  "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23",
  "session_id": "6f1c3c0e-8f5b-4c3e-9d6a-2b7d0e0f1a11",
  "items": [
    {
      "line_id": "64ddde83-28ce-4bba-86e5-ba9ebf1ba500",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "category_id": "ae6f8f8b-7cbe-4725-84fa-247cce138143",
      "category_ids": ["ae6f8f8b-7cbe-4725-84fa-247cce138143"],
      "name": "Notebook Slim Rosa 02373",
      "sku": "SD-002373",
      "product_slug": "notebook-slim-rosa-02373",
      "image_url": "/uploads/.../notebook.png",
      "unit_price": 11500,
      "base_price": 11500,
      "list_price": 12345,
      "quantity": 2,
      "sale_unit": "un",
      "total": 23000,
      "weight": 0,
      "requires_shipping": true,
      "id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "item_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "amount": 2,
      "price_str": "115.00",
      "subtotal_str": "230.00"
    }
  ],
  "promotions": [],
  "subtotal": 23000,
  "shipping_total": 0,
  "tax_total": 0,
  "discount_total": 0,
  "total": 23000,
  "currency": "BRL",
  "updated_at": "2026-10-11T21:41:27.369493Z",
  "expires_at": "2026-11-10T21:41:22.557382Z",
  "cart_id": "01ff5b45-566b-4b98-94a1-23a648c9ea23",
  "subtotal_str": "230.00",
  "total_str": "230.00",
  "shipping_cost_str": "0.00",
  "tax_subtotal_str": "0.00",
  "discount_str": "0.00",
  "timestamp": 1791754887
}

Campos da resposta

iduuid
Id do carrinho. Você precisa dele para iniciar o checkout (cart_id).
user_iduuid
Dono do carrinho quando é de um cliente logado. Ausente em carrinho de visitante.
session_idstring
O X-Session-ID do visitante. Ausente em carrinho de cliente.
itemsarray
Linhas do carrinho, na ordem em que foram adicionadas.
items[].line_iduuid
Id estável da linha. Aceito no lugar do id do produto em alterar e remover.
items[].product_iduuid
Produto da linha.
items[].variation_iduuid
Variação do produto, quando existe. Ausente em produto simples.
items[].unified_variation_idinteger
Variação unificada (por exemplo tamanho M), quando existe.
items[].variation_labelstring
Texto da variação, como Tamanho: M, Cor: Azul.
items[].vendor_iduuid
Seller (lojista) que vende o produto. Vazio quando o produto é da própria loja.
items[].vendor_namestring
Nome do seller.
items[].namestring
Nome do produto no momento em que entrou no carrinho.
items[].skustring
Código do produto.
items[].image_urlstring
Imagem principal. Caminho relativo à loja.
items[].unit_priceinteger
Preço unitário em centavos já resolvido para este comprador (faixas de quantidade e preço B2B entram aqui).
items[].list_priceinteger
Preço "de" em centavos, para exibir riscado. Ausente quando não há.
items[].quantitynumber
Quantidade. Decimal só em produto vendido por peso ou medida.
items[].sale_unitstring
Unidade de venda (un, kg...).
items[].totalinteger
unit_price vezes quantity, em centavos.
items[].notestring
Observação do comprador sobre a linha. Ausente quando vazia.
items[].is_giftboolean
true quando a linha é um brinde concedido por uma promoção. O preço é zero e a linha some sozinha se o comprador deixa de ter direito a ela.
items[].bundle_iduuid
Presente quando a linha veio de um kit.
items[].mix_iduuid
Presente quando a linha veio de um mix.
items[].boxobject
Presente em produto vendido por caixa. Descreve a caixa escolhida.
promotionsarray
Promoções gravadas no carrinho. Costuma vir vazia; os descontos aplicados vêm de Calcular o carrinho.
subtotalinteger
Soma dos itens, em centavos.
discount_totalinteger
Descontos gravados no carrinho, em centavos. Normalmente 0; veja a home da seção.
shipping_totalinteger
Frete gravado no carrinho, em centavos. Normalmente 0 até o checkout.
tax_totalinteger
Impostos gravados no carrinho, em centavos.
totalinteger
Total gravado no carrinho, em centavos.
currencystring
Moeda ISO 4217 (BRL).
coupon_codestring
Primeiro cupom aplicado. Ausente quando não há cupom.
coupon_codesarray
Todos os cupons aplicados, em maiúsculas.
updated_atstring
Última alteração, RFC 3339 em UTC.
expires_atstring
Quando o carrinho expira, RFC 3339 em UTC.

Resumo para o mini-carrinho

Devolve só o necessário para um ícone ou uma gaveta: contagem, valores e linhas enxutas. Use quando não precisar dos campos técnicos de cada linha.

GET/api/v1/storefront/cart/summaryAutenticada

Resumo do carrinho para o minicarrinho

Cabeçalhos

Authorizationstring
Bearer <token> do cliente logado.
X-Session-IDstring
Identificador do visitante. Obrigatório sem token.
bash
curl "$BASE_URL/api/v1/storefront/cart/summary" \
  -H "X-Session-ID: $SESSION_ID"
200Resumo do carrinho
json
{
  "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23",
  "item_count": 2,
  "subtotal": 23000,
  "shipping_total": 0,
  "tax_total": 0,
  "discount_total": 0,
  "total": 23000,
  "currency": "BRL",
  "items": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "name": "Notebook Slim Rosa 02373",
      "sku": "SD-002373",
      "image_url": "/uploads/.../notebook.png",
      "unit_price": 11500,
      "quantity": 2,
      "sale_unit": "un",
      "total": 23000
    }
  ]
}

Campos da resposta

item_countinteger
Soma das quantidades de todas as linhas (duas unidades de um mesmo produto contam 2), não o número de linhas.
itemsarray
Linhas resumidas: product_id, variation_id, unified_variation_id, variation_label, vendor_id, vendor_name, name, sku, image_url, unit_price, quantity, sale_unit, sale_unit_label, total e note. Os demais campos têm o mesmo significado de GET /cart.
subtotalinteger
Como em GET /cart: valores gravados, sem promoções nem frete.

Esvaziar o carrinho

DELETE/api/v1/storefront/cartAutenticada

Esvazia o carrinho

Remove todas as linhas de uma vez, inclusive brindes, e zera os totais gravados. Se a loja reserva estoque para o carrinho, as reservas são liberadas. Os códigos de cupom já aplicados continuam gravados no carrinho; para limpá-los chame Remover cupom. A ação não pode ser desfeita.

Cabeçalhos

Authorizationstring
Bearer <token> do cliente logado.
X-Session-IDstring
Identificador do visitante. Obrigatório sem token.
bash
curl -X DELETE "$BASE_URL/api/v1/storefront/cart" \
  -H "X-Session-ID: $SESSION_ID"
200Carrinho esvaziado
json
{ "message": "cart cleared" }

Erros

StatusQuandoCorpo
400Sem token e sem X-Session-ID{"error":"session_id or authentication required"}
400X-Organization-Branch-Id que não é UUID{"error":"invalid_branch"}
403Filial que o usuário não pode usar{"error":"branch_forbidden"}
500Falha ao ler ou gravar o carrinho{"error":"failed to get cart","detail":"..."}
Os totais do carrinho não são os totais da compra

subtotal e total aqui são a soma dos itens. Promoções automáticas, cupom e frete só aparecem em Calcular o carrinho. Mostrar total ao comprador como valor final gera divergência no checkout.

Token inválido vira visitante

Nas rotas de carrinho um Authorization: Bearer inválido ou expirado não devolve 401: a chamada é tratada como de visitante e usa o X-Session-ID. Se o cliente aparece "sem itens" depois de o token expirar, renove o token antes de ler o carrinho.

Atualize a tela com a resposta

Toda rota que altera o carrinho devolve o carrinho completo. Use essa resposta para redesenhar a tela em vez de chamar GET /cart de novo.

Veja também

  • Adicionar itens
  • Alterar ou remover uma linha
  • Calcular o carrinho
  • Visão geral do carrinho
Anterior
Carrinho
Próxima
Adicionar itens ao carrinho
Nesta página
  • Ler o carrinho
  • Exemplo de requisição
  • Resposta
  • Resumo para o mini-carrinho
  • Esvaziar o carrinho
  • Erros
  • Veja também