Carrinho

Visão Geral

O carrinho de compras é um dos principais componentes de um e-commerce.

Ele permite que o cliente adicione e gerencie múltiplos produtos em um único pedido, armazenando temporariamente os itens selecionados.

Além disso, o carrinho pode oferecer recursos como aplicação de cupons de desconto, promoções, cálculo de frete, atualização de quantidades e visualização do valor total da compra.

Autenticação

Os endpoints de carrinho não exigem autenticação na maioria dos casos.

A exceção ocorre em funcionalidades promocionais relacionadas ao sistema de pontos e à carteira do cliente, que exigem vínculo com o usuário para validação.

Token

O carrinho pode ser criado a partir de quase todos os endpoints, retornando um token no header da resposta, que deve ser armazenado e reutilizado nas requisições seguintes.

Esse token representa o carrinho atual e permite a utilização sem autenticação.

Caso ele seja perdido, ao realizar qualquer nova solicitação, um novo carrinho e token serão gerados automaticamente.

Embora o token seja retornado inicialmente via header, nas requisições subsequentes ele será enviado por meio de cookie.

Entidades relacionadas

Promocional Cupom

No contexto do carrinho, o cupom permite a aplicação de descontos por meio de um hash que representa um cupom específico.

Essa aplicação envolve regras e período de validade, sendo uma forma simples para o lojista oferecer descontos à loja ou a clientes específicos.

Em geral, apenas quem gera o cupom conhece seu hash e define para quem ele será distribuído.

Promocional Carteira

A carteira do cliente é uma entidade que armazena valores disponíveis, provenientes de cartões-presente, vouchers ou outras ações promocionais.

Em alguns casos, pode conter valores de estornos de compras que não foram concluídas corretamente.

Esse saldo pode ser utilizado no carrinho como forma de pagamento ou desconto.

Promocional Sistema de Pontos

O sistema de pontos premia o cliente após cada compra, permitindo o acúmulo de pontos que podem ser convertidos em descontos para compras futuras.

No carrinho, esses pontos podem ser aplicados para redução do valor total ou, caso o saldo seja suficiente, para pagamento integral de um produto ou serviço.

Produtos de Upsell

Os produtos de upsell são sugestões exibidas, geralmente, no checkout, oferecendo algum desconto adicional com base nos itens presentes no carrinho.

Cada item pode atender a regras específicas de segmentação, fazendo com que determinados produtos sejam exibidos como oferta.

Compre Junto

Produtos de compre junto são sugestões complementares ao produto principal.

Quando o item sugerido é adicionado ao carrinho, pode ser aplicado um desconto, conforme a configuração definida pelo lojista.

Notas e Considerações

O carrinho é recalculado constantemente e passa repetidamente pelos mesmos processos a cada endpoint acionado.

Por esse motivo, alguns erros podem se repetir em diferentes operações.

Nesta documentação, foram priorizados os erros mais relevantes dentro do contexto específico de cada endpoint.

Cotar frete para um carrinho

POST /cart/quote

Possibilita o cliente de cotar o frete para um carrinho

Descrição

Endpoint responsável por possibilitar ao cliente visualizar o valor do frete para sua localidade 🚚.

A exibição ocorre com base no contexto do carrinho, podendo variar conforme itens adicionados e localização do cliente.

Ao realizar a cotação, a opção de frete mais econômica é automaticamente pré-selecionada no carrinho, facilitando a experiência e agilizando a continuidade do checkout.

Parâmetros de query

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`targetCountryCode`	string	✅	Código alfa 3 do país, como por exemplo "BRA" (min: 3, max: 3)
`targetZipCode`	string	✅	CEP do local onde os itens devem ser entregues

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/cart/quote \
3  --cookie "CartToken" \
4  --data '{
5    "targetCountryCode": "BRA",
6    "targetZipCode": "12345678"
7  }'
curl --request POST \
  --url {{MAIN_URL}}/cart/quote \
  --cookie "CartToken" \
  --data '{
    "targetCountryCode": "BRA",
    "targetZipCode": "12345678"
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": "abc123456789098753",
5		"countryCode": "BRA",
6		"quoteZipcode": "12345678",
7		"subtotalValue": 300,
8		"shippingValue": 0,
9		"discountValue": 0,
10		"additionValue": 0,
11		"totalValue": 300,
12		"discountPreview": {
13			"cashDiscount": {
14				"discountPercentage": 0,
15				"discountValue": 0,
16				"valueWithDiscount": 300
17			},
18			"pointSystem": null
19		},
20		"installments": [],
21		"requestedProductMap": [
22			{
23				"productId": 1,
24				"quantity": 1,
25				"code": null,
26				"upsellId": null,
27				"productPairOfferId": null
28			}
29		],
30		"discountMap": {
31			"promotion": [],
32			"coupon": null,
33			"customer-wallet": null,
34			"point-system": null
35		},
36		"customer": null,
37		"addresses": [],
38		"orders": [
39			{
40				"orderId": 0,
41				"quoteId": "abc1234566543",
42				"distance": 0,
43				"subtotalValue": 300,
44				"shippingValue": 0,
45				"discountValue": 0,
46				"additionValue": 0,
47				"totalValue": 300,
48				"service": true,
49				"storage": null,
50				"items": [
51					{
52						"itemId": 0,
53						"productCategoryId": 0,
54						"upsellId": null,
55						"productPairOfferId": null,
56						"productPriceRuleId": 0,
57						"productPriceRuleName": "Original",
58						"quantity": 1,
59						"code": null,
60						"unitValue": 300,
61						"unitAdditionValue": 0,
62						"unitDiscountValue": 0,
63						"subtotalValue": 300,
64						"subtotalAdditionValue": 0,
65						"subtotalDiscountValue": 0,
66						"totalValue": 300,
67						"product": {
68							"productId": 1,
69							"brandId": 1,
70							"brandName": "TechBrand",
71							"mainCategoryId": 0,
72							"mainCategoryName": "",
73							"type": "product",
74							"sku": "SKUABC123",
75							"name": "Produto legal",
76							"active": true,
77							"url": "/tech-brand.html",
78							"comparisonPrice": 400,
79							"stock": 20,
80							"medias": [],
81							"combination": [],
82							"currentAttributes": []
83						},
84						"discounts": [],
85						"additions": []
86					}
87				],
88				"additions": [],
89				"discounts": [],
90				"shippingOptions": []
91			}
92		],
93		"errors": [],
94		"isMerged": false,
95		"createdAt": "2026-01-23 17:54:20",
96		"updatedAt": "2026-01-23 17:57:43"
97	}
98}
{
	"status": true,
	"data": {
		"id": "abc123456789098753",
		"countryCode": "BRA",
		"quoteZipcode": "12345678",
		"subtotalValue": 300,
		"shippingValue": 0,
		"discountValue": 0,
		"additionValue": 0,
		"totalValue": 300,
		"discountPreview": {
			"cashDiscount": {
				"discountPercentage": 0,
				"discountValue": 0,
				"valueWithDiscount": 300
			},
			"pointSystem": null
		},
		"installments": [],
		"requestedProductMap": [
			{
				"productId": 1,
				"quantity": 1,
				"code": null,
				"upsellId": null,
				"productPairOfferId": null
			}
		],
		"discountMap": {
			"promotion": [],
			"coupon": null,
			"customer-wallet": null,
			"point-system": null
		},
		"customer": null,
		"addresses": [],
		"orders": [
			{
				"orderId": 0,
				"quoteId": "abc1234566543",
				"distance": 0,
				"subtotalValue": 300,
				"shippingValue": 0,
				"discountValue": 0,
				"additionValue": 0,
				"totalValue": 300,
				"service": true,
				"storage": null,
				"items": [
					{
						"itemId": 0,
						"productCategoryId": 0,
						"upsellId": null,
						"productPairOfferId": null,
						"productPriceRuleId": 0,
						"productPriceRuleName": "Original",
						"quantity": 1,
						"code": null,
						"unitValue": 300,
						"unitAdditionValue": 0,
						"unitDiscountValue": 0,
						"subtotalValue": 300,
						"subtotalAdditionValue": 0,
						"subtotalDiscountValue": 0,
						"totalValue": 300,
						"product": {
							"productId": 1,
							"brandId": 1,
							"brandName": "TechBrand",
							"mainCategoryId": 0,
							"mainCategoryName": "",
							"type": "product",
							"sku": "SKUABC123",
							"name": "Produto legal",
							"active": true,
							"url": "/tech-brand.html",
							"comparisonPrice": 400,
							"stock": 20,
							"medias": [],
							"combination": [],
							"currentAttributes": []
						},
						"discounts": [],
						"additions": []
					}
				],
				"additions": [],
				"discounts": [],
				"shippingOptions": []
			}
		],
		"errors": [],
		"isMerged": false,
		"createdAt": "2026-01-23 17:54:20",
		"updatedAt": "2026-01-23 17:57:43"
	}
}

⚠️ Erros genéricos de carrinho:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_NOT_FOUND	404	O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED	401	O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED	409	O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH	500	Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	A tentativa de cotação para o grupo de cotação falhou.
UAPPI_STORE_ZIPCODE_RANGE_NO_COVERAGE	409	Não há entrega disponível para o CEP informado.

Seleção de ferete para o carrinho

PUT /cart/shipping

Permite que o cliente selecione um frete para o seu carrinho

Descrição

Endpoint responsável por possibilitar ao cliente selecionar uma das opções de frete disponíveis para o carrinho atual 🚚.

A escolha do frete é limitada e condicionada aos produtos presentes no carrinho e à distância do cliente para o local de entrega, garantindo que apenas opções viáveis sejam apresentadas e aplicadas.

Parâmetros de query

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`orders`	array	✅	lista de opções de frete escolhidas por pedido
`orders.*.cartOrderId`	integer	✅	Identificador do pedido no carrinho
`orders.*.shippingTableId`	integer	✅	Identificador da tabela de envio (o frete selecionado)
`orders.*.shippingPickupPointId`	integer	❌	Identificador do ponto de retirada em casos de busca

Observação importante ℹ️: ao adicionar itens ao carrinho, é gerado um id de pedido, responsável por agrupar todo o conjunto de itens adicionados.

Ao informar esse id de pedido neste endpoint, a seleção de frete passa a considerar todos os itens presentes no carrinho, garantindo uma cotação coerente com o volume, peso e regras aplicáveis ao pedido como um todo.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/cart/shipping \
3  --cookie "cartToken" \
4  --data '{
5	"orders": [
6		{
7			"cartOrderId": 0,
8			"shippingTableId": 1,
9			"shippingPickupPointId": 1
10		}
11	]
12}'
curl --request PUT \
  --url {{MAIN_URL}}/cart/shipping \
  --cookie "cartToken" \
  --data '{
	"orders": [
		{
			"cartOrderId": 0,
			"shippingTableId": 1,
			"shippingPickupPointId": 1
		}
	]
}'

✅ Resposta de Sucesso

Observação importante ℹ️: para validar a efetividade do endpoint, deve-se analisar a lista ShippingOptions.

Dentro dessa lista, o campo selected indica se a opção de frete está selecionada ou não, permitindo identificar qual alternativa foi aplicada ao carrinho no momento da consulta.

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": "abc1234567890987664552",
5		"countryCode": "BRA",
6		"quoteZipcode": "12345678",
7		"subtotalValue": 300,
8		"shippingValue": 0,
9		"discountValue": 0,
10		"additionValue": 0,
11		"totalValue": 300,
12		"discountPreview": {
13			"cashDiscount": {
14				"discountPercentage": -10,
15				"discountValue": 0,
16				"valueWithDiscount": 300
17			},
18			"pointSystem": null
19		},
20		"installments": [],
21		"requestedProductMap": [
22			{
23				"productId": 1,
24				"quantity": 1,
25				"code": null,
26				"upsellId": null,
27				"productPairOfferId": null
28			}
29		],
30		"discountMap": {
31			"promotion": [],
32			"coupon": null,
33			"customer-wallet": null,
34			"point-system": null
35		},
36		"customer": null,
37		"addresses": [],
38		"orders": [
39			{
40				"orderId": 0,
41				"quoteId": "abc1234567421",
42				"distance": 1000,
43				"subtotalValue": 300,
44				"shippingValue": 0,
45				"discountValue": 0,
46				"additionValue": 0,
47				"totalValue": 300,
48				"service": false,
49				"storage": null,
50				"items": [
51					{
52						"itemId": 0,
53						"productCategoryId": 1,
54						"upsellId": null,
55						"productPairOfferId": null,
56						"productPriceRuleId": 0,
57						"productPriceRuleName": "Original",
58						"quantity": 1,
59						"code": null,
60						"unitValue": 300,
61						"unitAdditionValue": 0,
62						"unitDiscountValue": 0,
63						"subtotalValue": 300,
64						"subtotalAdditionValue": 0,
65						"subtotalDiscountValue": 0,
66						"totalValue": 300,
67						"product": {
68							"productId": 1,
69							"brandId": 1,
70							"brandName": "TechBrand",
71							"mainCategoryId": 1,
72							"mainCategoryName": "tech",
73							"type": "product",
74							"sku": "TCB1234",
75							"name": "Produto tecnológico",
76							"active": true,
77							"url": "/tech-brand.html",
78							"comparisonPrice": 400,
79							"stock": 20,
80							"medias": [],
81							"combination": [],
82							"currentAttributes": []
83						},
84						"discounts": [],
85						"additions": []
86					}
87				],
88				"additions": [],
89				"discounts": [],
90				"shippingOptions": [
91					{
92						"shippingTableId": 1,
93						"shippingPickupPointId": null,
94						"label": "Frete grátis",
95						"shippingValue": 0,
96						"beginShippingTime": 2,
97						"endShippingTime": 7,
98						"shippingTimeType": "",
99						"selected": true,
100						"details": {
101							"shippingTableId": 1,
102							"integrationCode": "",
103							"externalShippingCode": "",
104							"carrierId": 1,
105							"carrierName": "Correios",
106							"label": "Frete grátis",
107							"value": 0,
108							"beginShippingTime": 2,
109							"endShippingTime": 7,
110							"trackingUrl": null,
111							"row": {
112								"id": 1,
113								"initialZipcode": "1000",
114								"finalZipcode": "9999",
115								"initialWeight": 2,
116								"finalWeight": 1,
117								"initialPrice": 0,
118								"finalPrice": 100,
119								"beginShippingTime": 2,
120								"endShippingTime": 7,
121								"shippingValue": 0,
122								"variables": []
123							},
124							"pickups": null,
125							"error": null
126						}
127					}
128				]
129			}
130		],
131		"errors": [],
132		"isMerged": false,
133		"createdAt": "2026-01-26 08:23:28",
134		"updatedAt": "2026-01-26 08:25:00"
135	}
136}
{
	"status": true,
	"data": {
		"id": "abc1234567890987664552",
		"countryCode": "BRA",
		"quoteZipcode": "12345678",
		"subtotalValue": 300,
		"shippingValue": 0,
		"discountValue": 0,
		"additionValue": 0,
		"totalValue": 300,
		"discountPreview": {
			"cashDiscount": {
				"discountPercentage": -10,
				"discountValue": 0,
				"valueWithDiscount": 300
			},
			"pointSystem": null
		},
		"installments": [],
		"requestedProductMap": [
			{
				"productId": 1,
				"quantity": 1,
				"code": null,
				"upsellId": null,
				"productPairOfferId": null
			}
		],
		"discountMap": {
			"promotion": [],
			"coupon": null,
			"customer-wallet": null,
			"point-system": null
		},
		"customer": null,
		"addresses": [],
		"orders": [
			{
				"orderId": 0,
				"quoteId": "abc1234567421",
				"distance": 1000,
				"subtotalValue": 300,
				"shippingValue": 0,
				"discountValue": 0,
				"additionValue": 0,
				"totalValue": 300,
				"service": false,
				"storage": null,
				"items": [
					{
						"itemId": 0,
						"productCategoryId": 1,
						"upsellId": null,
						"productPairOfferId": null,
						"productPriceRuleId": 0,
						"productPriceRuleName": "Original",
						"quantity": 1,
						"code": null,
						"unitValue": 300,
						"unitAdditionValue": 0,
						"unitDiscountValue": 0,
						"subtotalValue": 300,
						"subtotalAdditionValue": 0,
						"subtotalDiscountValue": 0,
						"totalValue": 300,
						"product": {
							"productId": 1,
							"brandId": 1,
							"brandName": "TechBrand",
							"mainCategoryId": 1,
							"mainCategoryName": "tech",
							"type": "product",
							"sku": "TCB1234",
							"name": "Produto tecnológico",
							"active": true,
							"url": "/tech-brand.html",
							"comparisonPrice": 400,
							"stock": 20,
							"medias": [],
							"combination": [],
							"currentAttributes": []
						},
						"discounts": [],
						"additions": []
					}
				],
				"additions": [],
				"discounts": [],
				"shippingOptions": [
					{
						"shippingTableId": 1,
						"shippingPickupPointId": null,
						"label": "Frete grátis",
						"shippingValue": 0,
						"beginShippingTime": 2,
						"endShippingTime": 7,
						"shippingTimeType": "",
						"selected": true,
						"details": {
							"shippingTableId": 1,
							"integrationCode": "",
							"externalShippingCode": "",
							"carrierId": 1,
							"carrierName": "Correios",
							"label": "Frete grátis",
							"value": 0,
							"beginShippingTime": 2,
							"endShippingTime": 7,
							"trackingUrl": null,
							"row": {
								"id": 1,
								"initialZipcode": "1000",
								"finalZipcode": "9999",
								"initialWeight": 2,
								"finalWeight": 1,
								"initialPrice": 0,
								"finalPrice": 100,
								"beginShippingTime": 2,
								"endShippingTime": 7,
								"shippingValue": 0,
								"variables": []
							},
							"pickups": null,
							"error": null
						}
					}
				]
			}
		],
		"errors": [],
		"isMerged": false,
		"createdAt": "2026-01-26 08:23:28",
		"updatedAt": "2026-01-26 08:25:00"
	}
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_INVALID_ORDER_ID	400	O id do pedido solicitado é inválido.
UAPPI_STORE_CART_INVALID_SHIPPING_OPTION	400	O id da opção de frete solicitada é inválido.
UAPPI_STORE_CART_PICKUP_POINT_ID_IS_REQUIRED	400	O id do ponto de retirada é obrigatório.
UAPPI_STORE_CART_INVALID_PICKUP_POINT_OPTION	400	O id do ponto de retirada é inválido.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Carrinho

Visão Geral

Autenticação

Token

Entidades relacionadas

Promocional Cupom

Promocional Carteira

Promocional Sistema de Pontos

Produtos de Upsell

Compre Junto

Notas e Considerações

Cotar frete para um carrinho

Descrição

Parâmetros de query

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Erros genéricos de carrinho:

Seleção de ferete para o carrinho

Descrição

Parâmetros de query

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Nesta página

Institucional