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

Resposta

200Carrinho com um item

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.

200Resumo do carrinho

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.

200Carrinho esvaziado

Erros

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

Veja também

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.

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

Resposta

200Carrinho com um item

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.

200Resumo do carrinho

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

subtotalinteger

Como em GET /cart: valores gravados, sem promoções nem frete.

Esvaziar o carrinho

DELETE/api/v1/storefront/cartAutenticada

Esvazia o carrinho

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

200Carrinho esvaziado

Erros

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